mobile-dev-debug-tool
Provides access to live client state, logs, and GDScript evaluation via a WebSocket debug-hub.
Install
mkdir -p .claude/skills/mobile-dev-debug-tool && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/14430" && unzip -o skill.zip -d .claude/skills/mobile-dev-debug-tool && rm skill.zipInstalls to .claude/skills/mobile-dev-debug-tool
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use when inspecting or reporting the state of the running Decentraland Godot Explorer client — on desktop or on a mobile device (iOS/Android) — over the unified scene-inspector debug-hub (`cargo run -- debug-hub`; device port 9231, consumer port 9230) that the client dials out to. Covers the SCENE_INSPECTOR_CMD JSON protocol, the five trees (`scene`/`entity`, `ui_scene`/`ui_entity`, `avatars`/`avatar`, `app_ui`, `ping`/`scenes`), the `focus` keyboard-focus tracker, the `log`/`network` streams, the shared `filters` dict, the `websocat` helper scripts (`scripts/unified.sh`, `unified-tail.sh`), and the wiring across `godot/src/tool/debug_server/`, `scene_inspector_bridge.gd` and the Rust `SceneManager::debug_*` / `AvatarScene::debug_*` hooks. Also covers the `eval` command for running arbitrary GDScript against the live client (non-production only). Trigger when the user asks what state the running app/client is in (what scenes/realm are loaded, where the avatar is, what the UI is showing — desktop or on-device/mobile/iOS/Android), asks to connect to or host the debug-hub, or mentions the scene-inspector channel, debug-hub, port 9230/9231, `DebugWs`, `debug_collector`, websocat against the client, or running/evaluating GDScript against the running client.Key capabilities
- →Inspect live client state including scenes, entities, UI, and avatars
- →Monitor log, network, and lifecycle streams
- →Execute arbitrary GDScript against the live client
- →Connect to a debug-hub on desktop or mobile devices
- →Tail specific log messages for feature instrumentation
How it works
The client dials out to a desktop debug-hub via a WebSocket channel, exposing live state and streams. Local tools connect to the hub's consumer port to interact with the client.
Inputs & outputs
When to use mobile-dev-debug-tool
- →Inspecting avatar state in a scene
- →Monitoring network logs during runtime
- →Executing GDScript for live client debugging
About this skill
Mobile dev debug tool — scene-inspector debug-hub
A single WebSocket channel exposes live client state (scenes / entities / UI /
avatars / focus), a log/network/lifecycle stream, and typed commands
(state, teleport, screenshot, log_filter) — reachable on any platform, including iOS/Android
devices that can't be dialed into. The client dials out to a desktop
debug-hub; local tools (AI / websocat) connect to the hub's consumer port.
There is one transport: the scene-inspector CMD protocol (the source-of-truth
contract an external inspector app already parses, so additions stay
backward-compatible). The mutating commands (teleport, log_filter) are disabled in production builds.
Bring up the hub
cargo run -- debug-hub # device port 9231, consumer port 9230
# launch the client pointed at the hub's device port (LAN IP shown in the banner):
cargo run -- run -- --scene-inspector=ws://127.0.0.1:9231 # desktop
cargo run -- run --target ios -- --scene-inspector=ws://<this-mac>:9231 # device
On iOS pass the hub address with --scene-inspector=ws://<this-mac>:9231; accept the local-network prompt on first launch. The bridge activates at boot
(SceneInspectorBridge, started by DclGlobal at boot),
so the channel is live from the lobby, before login — no need to enter a world
first. A ?scene-inspector=ws://<lan-ip>:9231 deeplink is honoured only on
non-production builds and only when it points at the local network.
Answering "what state is the app in?" — ONE step
Run the pre-armed connector in the background, read its output, then query:
scripts/hub-connect.sh # Bash tool: run_in_background: true — read its output
hub-connect.sh does the whole cold-start dance in one shot: wires Android
adb reverse, ensures a hub (reuse or start), waits ≤35 s for the device to dial
in, and prints either === CONNECTED === + a ping snapshot or a NO DEVICE
relaunch hint. If it started the hub it keeps the task alive so the hub persists.
Then query with the id-filtered helpers:
scripts/unified.sh scenes
scripts/unified.sh scene '{"scene_id":0,"filters":{"limit":5}}'
scripts/unified.sh state
Why it just works: the client dials out and retries forever (backoff
1s→…→30 s cap, debug_hub/socket.rs), and debug builds default the
target to ws://127.0.0.1:9231 with no arg, so a hub started
after the app is picked up within ≤30 s — no app restart needed. Per platform:
- iOS — pass
--scene-inspector=ws://<LAN-IP>:9231; accept the Local Network prompt once. - Android — NO plugin bakes the arg (the baking plugin is iOS-only, and Android
editor-deploy CLI args don't reach the app). The debug loopback default +
adb reverse tcp:9231(set byhub-connect.sh) carry it instead. A build made before that default won't connect — rebuild+redeploy, or usecargo run -- run --target android. - desktop —
cargo run -- run -- --scene-inspector=ws://127.0.0.1:9231, or an editor F5 also auto-dials loopback.
If hub-connect.sh reports NO DEVICE, the app simply isn't dialing — follow the
hint it prints (usually: relaunch/redeploy the app).
Wiring
- Commands, collectors and the transport:
lib/crates/dcl_engine/src/tools/debug_hub/(commands.rs,collector.rs,socket.rs, theSceneInspectorBridgenode). The hub is thedebug-hubxtask (src/log_server.rs). - Rust
#[func]hooks for state only Rust can reach:SceneManager::debug_*(lib/src/scene_runner/scene_manager.rs) — CRDT enumeration, deserialization, UI control lookup.AvatarScene::debug_*(lib/src/avatars/avatar_scene.rs) — avatar listing, address/alias/entity/local lookup.
Protocol (scene-inspector CMD)
- request:
{"type":"SCENE_INSPECTOR_CMD","cmd":"<verb>","args":{...},"id":"<id>"} - reply:
{"type":"SCENE_INSPECTOR_CMD_ACK","id":"<id>","ok":<bool>,"data":...}(or{"ok":false,"error":"..."}) - streams (push):
{"type":"SCENE_INSPECTOR","payload":{"sessionId":...,"entries":[{type:...}]}}whereentries[].type∈ crdt | op_call_start | op_call_end | scene_lifecycle | perf | log | network | session_start | session_end.
The id is echoed in the ACK — always match replies by it (see the perf-vs-ACK
note below). The helpers (scripts/unified.sh) do this for you.
Five trees, one command surface
| cmd | Tree | Identified by |
|---|---|---|
scene / entity | 3D entity tree (DclSceneNode → DclNodeEntity3d) | (scene_id, entity_id) |
ui_scene / ui_entity | per-scene SDK UI (UiNode.base_control) | (scene_id, entity_id) |
avatars / avatar | global AvatarScene | by ∈ {address,alias,entity,local} |
app_ui | Explorer's own UI | auto-detected (/root/explorer/UI or /root/Menu) |
ping / scenes / focus | — | — |
All four data cmds (scene, ui_scene, avatar, app_ui) share a filters dict:
component: [...]— OR-match SDK component names (cheap, no proto decode)property_is: {component, field, contains}— generic substring filter on any (SDK component, field) paircollect_nodes: {<child_name>: [<property>, ...]}— per-child-node property dump viaObject.get(); values pass through_variant_to_jsoninclude_parents,include_children,limit,offset,depth,class_filter,name_contains— traversal/pagination knobs
Querying — unified.sh
scripts/unified.sh <cmd> [args-json] sends one CMD frame to the hub consumer
port (ws://127.0.0.1:9230) and returns its matching ACK. It bakes in
-B 16777216 so websocat doesn't split large replies, and keeps the socket open
until the ACK's id matches (needed for on-device round-trips). Requires
websocat on $PATH (cargo install websocat or your package manager).
# Confirm the round-trip to the connected client
scripts/unified.sh ping
# All loaded scenes
scripts/unified.sh scenes
# All TextShape entities in scene 0 with their Label3D properties
scripts/unified.sh scene '{"scene_id":0,"filters":{
"component":["TextShape"],
"collect_nodes":{"TextShape":["text","font_size","pixel_size","outline_size","modulate"]}
}}'
# Your own avatar — what it's wearing + what's playing
scripts/unified.sh avatar '{"by":"local","filters":{
"collect_nodes":{"AnimationPlayer":["current_animation","autoplay"],"AnimationTree":["active"]}
}}'
# Explorer's own UI hierarchy (lobby in this state, scene UI when loaded)
scripts/unified.sh app_ui '{"filters":{"depth":2}}'
# Keyboard-focus tracker — current owner + ui_root + change history
scripts/unified.sh focus
Typed commands
There is no eval: the GDScript interpreter is gone with the GDScript. What it was used for has
typed commands (the mutating ones are non-production only):
scripts/unified.sh state # realm, parcel, scenes loaded, fps, memory
scripts/unified.sh teleport '{"x":77,"y":1}' # move the player to a parcel
scripts/unified.sh screenshot '{"inline":true}' # PNG of the viewport (inline = base64)
scripts/unified.sh log_filter '{"filter":"dclgodot::comms=debug,warn"}'
eval itself replies ok:false with a pointer to these. For a query nothing covers, add a typed
command in debug_hub/commands.rs.
focus — keyboard-focus tracker
focus takes no args and returns the viewport's current keyboard-focus owner
plus a timestamped change history (no filters). Reply data:
{"current": "<path> [<class>]", "ui_root_path": "/root/explorer/UI", "history": [{"t_ms", "frame", "from", "to"}, ...]} (last FOCUS_HISTORY_MAX
= 64 changes; "<none>" means focus was released to null).
The bridge polls the viewport's focus owner every frame (in debug builds) so the history captures transient changes — including
release-to-null, which the engine's gui_focus_changed signal misses.
Use it for "input stops working" bugs: mobile walk/jump are gated by
the player body's focus check (ui_root.has_focus()), so movement
silently dies whenever current ≠ ui_root_path. The history shows which
control stole focus and on which frame. (This is how the navbar-toggle
focus-steal bug was found: the gate read true→false when a press landed focus
on the navbar's full-rect Button.)
Streams — unified-tail.sh
scripts/unified-tail.sh # logs only (default)
scripts/unified-tail.sh log,network # logs + HTTP
scripts/unified-tail.sh log,lifecycle # logs + per-tick scene lifecycle
Capture is connection-gated + opt-in. With no consumer connected, the device
captures NOTHING (no buffering) — safe to leave the tool enabled in prod. Classic
streams (crdt/perf) flow once a consumer connects; log/network/lifecycle are
opt-in (the helper subscribes for you). source ∈ rust | godot | native
(Swift/ObjC on iOS).
MCP / AI loop: the hub's consumer port (ws://127.0.0.1:9230) is a stable
local endpoint an MCP server (or the helpers above, called from Bash) can use to
read all logs and issue queries — the same contract the external app uses.
Important notes
- Report state from a request/reply ACK, never from a stray
perfframe. On the hub,perf(andcrdt) are always-on pushes that start the instant a consumer connects — so a naïve read of the socket returns aperfframe, not the answer to your command. Always query with the id-filtered request/reply (unified.sh <cmd>), which matches the ACK by its uniqueid. If a query comes back empty, that's a dropped ACK — do not fall back to inferring app state from aperfpush (it only happens to carryfps/mem/scene_count; it has no realm/avatar/UI, and itsscene_count: 0can mislead you into "everything's fine / in lobby"). On a device the ACK needs a full consumer→hub→device→hub round-trip, so it lands after the first pushedperf: the helper must keep the socket
Content truncated.
When not to use it
- →When inspecting production builds, as `eval` is hard-disabled
- →When the client is not configured to dial out to a debug-hub
- →When only static code analysis is required without live client interaction
Limitations
- →The `eval` command for running GDScript is hard-disabled in production builds
- →GDScript `push_warning`/`push_error` are not captured, only Rust warn/error
- →Mobile's default log filter is `info`, requiring `--rust-log` for `debug!` lines
How it compares
This skill enables real-time inspection and GDScript execution on live mobile and desktop clients by having the client dial out to a hub, which differs from traditional debugging that requires dialing into a device.
Compared to similar skills
mobile-dev-debug-tool side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| mobile-dev-debug-tool (this skill) | 0 | 4mo | Review | Advanced |
| react-native-best-practices | 5 | 6mo | Review | Advanced |
| perf-optimizer | 5 | 4mo | Review | Advanced |
| ios-debugger-agent | 2 | 8mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
react-native-best-practices
callstackincubator
Provides React Native performance optimization guidelines for FPS, TTI, bundle size, memory leaks, re-renders, and animations. Applies to tasks involving Hermes optimization, JS thread blocking, bridge overhead, FlashList, native modules, or debugging jank and frame drops.
perf-optimizer
OneKeyHQ
Systematic performance optimization and regression debugging for OneKey mobile app (iOS). Use when: (1) Fixing performance regressions - when metrics like tokensStartMs, tokensSpanMs, or functionCallCount have regressed and need to be brought back to normal levels, (2) Improving baseline performance - when there's a need to optimize cold start time or reduce function call overhead, (3) User requests performance optimization/improvement/debugging for the app's startup or home screen refresh flow.
ios-debugger-agent
Dimillian
Use XcodeBuildMCP to build, run, launch, and debug the current iOS project on a booted simulator. Trigger when asked to run an iOS app, interact with the simulator UI, inspect on-screen state, capture logs/console output, or diagnose runtime behavior using XcodeBuildMCP tools.
launch-on-device
zly2006
Build, install, and launch the Zhihu++ Android app on a connected device using ADB. Includes comprehensive troubleshooting for common issues like missing devices, installation failures, signature mismatches, and app crashes. Use when deploying debug builds to physical devices or emulators.
debug
woliveiras
>
metravel-android-developer
kelios
Implement and debug Android/native compatibility in the metravel Expo React Native app. Use when Codex needs an Android developer role for native crashes, platform-specific files, Expo native modules, Android navigation, push notifications, SecureStore, permissions, native map behavior, or web-first