---
title: "Pointer click and tap to world cursor interaction"
description: "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."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/knowledge/playbooks/pointer-and-click-interaction/
---

# Pointer click and tap to world cursor interaction

## When to use

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.

## 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.