FantasyMaps Items — Affordances

"Given this object and where we are, what can I do with it?"

A thin Foundry client for the Gaia world server. When you click an object — either a local Foundry token or a live ghost from ofm-shared-world — the module resolves the triple {world, perspective, context} from the scene + your character + the module settings, asks Gaia for the object's description and its influence breakdown, and shows the result as a clickable list of affordances.

Entry points

Trigger	Source
Token HUD button (hand-sparkles icon)	renderTokenHUD hook adds a button in the left column
Ghost click	If ofm-shared-world is active and a ghost has attrs.interactive = true, clicking it opens the same dialog via ofmSharedWorldGhostClick
Macro	game.modules.get("ofm-items").api.open({ world, objectId, perspective, context })

Resolution rules

• world ← scene.flags.ofm.world (or legacy scene.flags.ofmWorld).
• objectId:
  • Token: token.flags.ofm.objectId → actor.flags.ofm.objectId → token.flags.ofm-items.objectId.
  • Ghost: the geomqtt id from the payload.
• perspective: currently-controlled token's actor name → your user's assigned character → the DEFAULT_PERSPECTIVE setting (default "Human adult").
• context: scene.flags.ofm.context → DEFAULT_CONTEXT setting (default "generic").

API calls

On open, the dialog fires two Gaia requests in parallel:

• GET /{world}/inspect?obj=<id>&perspective=<>&context=<> — free-form description.
• POST /{world}/tools/influence_inspector body { target, radius_m } — list of InfluenceItems (one affordance per influence channel).

Each affordance row is clickable and fires the hook:

Hooks.on("ofmItemsAffordanceUse", ({ world, objectId, perspective, context, item }) => {
    // item = InfluenceItem from the Gaia schema
    // do something with it (chat card, automation, further Gaia call, …)
});

This module doesn't implement any effect — other OFM modules (or your macros) pick the hook up and decide how the affordance plays out.

Settings

Setting	Purpose
Gaia Base URL	HTTPS endpoint of the Gaia world server (default https://api.gaia.fantasymaps.org)
Default Perspective	Fallback when no actor is controlled
Default Context	Fallback when the scene has no flags.ofm.context

Public API

game.modules.get("ofm-items").api:

Member
GaiaClient	Class — constructor takes a base URL
getClient()	Returns a GaiaClient bound to the configured base URL
open(params)	Opens the affordance dialog; params = { world, objectId, perspective, context }
resolveFromToken(token) / resolveFromGhost(payload)	Helpers for the two entry points
inspect, influenceInspector, nearby, worldSettings	Thin passthroughs to the Gaia endpoints

Compatibility

• Foundry v11 – v13.
• Optional runtime integration with ofm-shared-world; works standalone without it.