Skip to content

Advanced Movement and Animation

opensim-metaverse2mcp exposes movement and animation tools over MCP HTTP. AI prompts in IM map to these tools.

Core movement, sit, and animation tool set

  • MoveBy
  • WalkTo
  • FlyTo
  • TeleportTo
  • TeleportToRegionHandle
  • RegionUuid
  • Map
  • StopMovement
  • StartMovement
  • LookAt
  • SetCameraHeading
  • GetCameraState
  • Follow
  • MonitorAgent
  • StopFollow
  • Sit
  • SitOnPrim
  • SitOnPrimByName
  • SitOnNearestSittablePrim
  • Stand
  • Fly
  • Jump
  • AnimationStart
  • AnimationStop
  • AnimationsList
  • ActiveAnimations
  • ListScriptDialogs
  • ScriptDialogChoice
  • ScriptDialogTextInput
  • ListScriptAnimationPermissionRequests
  • ScriptAnimationPermissionRespond

Sit semantics and chair workflows

  • Sit performs a ground sit only.
  • SitOnPrim(localId=...) performs object sit handshake (RequestSit -> wait AvatarSitResponse -> Sit).
  • SitOnPrimByName(name=...) resolves nearest name match in current simulator cache, then uses object sit handshake.
  • SitOnNearestSittablePrim(...) searches around the bot, prefers explicit sit targets, and sits on the nearest candidate.

Examples:

SitOnPrim(localId=503191167)
SitOnPrimByName(name="deck chair", exactMatch=false, caseSensitive=false)
SitOnNearestSittablePrim(radiusMeters=12, requireExplicitSitTarget=false)
SitOnNearestSittablePrim(radiusMeters=20, requireExplicitSitTarget=true)

Operational notes:

  • Object sit can fail if the bot is too far away from the target.
  • If no AvatarSitResponse arrives, move closer and retry.
  • Some furniture is sit-enabled by script/poseball rather than ClickAction=Sit; name-based or nearest search is often more reliable than strict explicit sit filtering.

Animation control

Use AnimationsList to discover built-in animation names (e.g. DANCE1, WAVE, CLAP, SIT), then start/stop them by name or raw UUID:

AnimationsList()
AnimationStart(animation="DANCE1")
ActiveAnimations()
AnimationStop(animation="DANCE1")

Object animation permission prompts

When scripted objects request permission to animate the bot (for example after a sit interaction), runtime emits:

  • channel: general
  • event type: script.permission.animation.requested
  • key attribute: pendingPermissionHandle

Use this response pattern:

  1. Poll for script.permission.animation.requested.
  2. Inspect pending requests with ListScriptAnimationPermissionRequests.
  3. Approve or deny with ScriptAnimationPermissionRespond.

Example calls:

ListScriptAnimationPermissionRequests(pendingPermissionHandle="all")
ScriptAnimationPermissionRespond(pendingPermissionHandle="<handle>", allow=true)
ScriptAnimationPermissionRespond(pendingPermissionHandle="<handle>", allow=false)

Scripted dialog menus and text boxes

Scripted objects can open either button menus (e.g. llDialog) or text entry prompts (e.g. llTextBox). Both are exposed through the same pending dialog handle surfaced by runtime event script.dialog.received.

Recommended response flow:

  1. Poll/inspect pending dialogs with ListScriptDialogs.
  2. Use ScriptDialogChoice when responding by button index.
  3. Use ScriptDialogTextInput when the dialog expects free-form text.

Example calls:

ListScriptDialogs(pendingDialogHandle="all")
ScriptDialogChoice(pendingDialogHandle="<dialog-handle>", buttonIndex=0)
ScriptDialogTextInput(pendingDialogHandle="<dialog-handle>", text="status")

Reliable navigation pattern

For long distances, prefer waypoint-style prompts:

Walk to 140,130,25 first, then fly to 200,200,60, then land.

This aligns with stepped autopilot behavior used by movement tools.

Agent monitoring pattern

Use MonitorAgent when you need continuous presence tracking for another avatar UUID. The tool runs as a background BotTaskHandle and emits change events on runtime channel agentMonitor once per second at most.

Current behavior is intentionally current-region scoped: if the target is not in the bot's current simulator, region, position, velocity, and isFlying are reported as unknown (null). External fallback probing is disabled by default; enable AGENT_MONITOR_EXTERNAL_FALLBACK=true only if you want occasional off-region online checks.

Teleport targeting strategy

  • Use explicit region names plus coordinates when possible.
  • If region name collisions exist, use a region-handle or precise routing command.
  • Confirm location with status before issuing object-edit operations.

Operational checks

Health endpoint for bot runtime:

curl -s http://127.0.0.1:8999/healthz

If your mapped host port is not 8999, adjust the URL.

Failure recovery

  • If movement hangs, send:
*cancel
Stop movement.
  • If login session is stale, restart only the metaverse sidecar:
docker compose restart opensim-metaverse2mcp

Handler-gated control

If handler restrictions are enabled, only the configured handler avatar can issue bot control commands.

For tool-level outfit, wearable, and attachment operations, see Advanced Guide -> Appearance and Wearables.