Gessa Docs
Recipes

Recipe

Pointer click and tap to world cursor interaction

The player clicks a spot to walk there, taps an enemy to target it, or drags to place a building. This is cursor-to-world picking: an input action carries the world pick, and a handler acts on it. There is no getInputRay host op (that is Spawn vocabulary); the resolved pick rides the action value.
engine v1.0.234since script-semantic-patch-ops.v1, action-catalog.v1.0.232, input.v1, physics.v1, mutation.v1, spawn.v1Copy for LLM

Use this for

click or tap the world to move, select, place, or aim; point-and-click and cursor-driven controls; click-to-move; drag-box or click selection; aim at whatever the cursor points at

Not for

fixed key or button bindings with no cursor (see input-mapping-actions-bindings); a turret that auto-aims with no player click (see turrets-and-auto-aim); camera framing (see camera-modes-and-switching)

Pairs with: Input mapping actions bindings keyboard mouse gamepad touch, Turrets auto-aim and target tracking guns, Camera modes top-down isometric side-scroller and switching, Doors buttons levers and press-to-interact

The recipe

Author with project_apply_script_semantic_patch using the ai_safe op pack.

  1. Declare the pick action on the InputProfileComponent (see input-mapping-actions-bindings). Use valueType:"world_target" so the engine resolves the cursor ray to a world point or entity and delivers it in the action payload; bind it to a mouse click or a touch tap.
  2. React: addActionHandler { "actionKey":"pick" }. In the body (whole-body GessaScript via replaceScriptFromGessaScript) read the target world position or entity id from the action value.
  3. Click to move: ctx.entity.patchComponent the player TransformComponent position toward the pick, or set a NavAgentComponent destination (see npc-enemy-navigation) so it paths there.
  4. Click to select: from the pick, resolve the entity and mark it selected with writeTypedStateValue (a selectedId field), and toggle a HighlightComponent on it.
  5. Click to place: spawnEntityFromTemplate { "prefabKey": <building> } at the pick, snapping to ctx.terrain.heightAt for ground alignment.
  6. Manual ray (no world_target): use a valueType:"screen2d" action for raw cursor coordinates and ctx.physics.shapecast from the camera along the view ray, or ctx.physics.overlapTest a small shape at the hit, to find what was clicked.

Pitfalls

  • world_target already does the raycast; do not also shapecast for the same click. Use screen2d plus ctx.physics.shapecast only when you need a custom ray or filter.
  • The pick resolves on the authority; act on it server-side so all players agree on what was clicked or placed.
  • Touch and mouse feed the SAME action; add both a mouse and a touch binding so the pick works on desktop and mobile.
  • A click that must hit only certain things needs a physics filter or a tag check in the handler; the raw pick returns whatever is under the cursor.

Verify

  • simulation_run (qa.run.start) to prove a click moves, selects, or places at the intended world point.
  • project_get_graph_snapshot to confirm the pick action handler landed.
Was this helpful?Report an issueContact support

On this page