godotctl-qxzn-shell

name: godotctl-qxzn-shell description: Work on the QXZN Godot Shell runtime project. Use for qxzn-runtime-template, embedded game migration, Shell menu routing, game ids, AI motion correction runtime validation, setup_shell/shutdown handlers, hardware hit segment dispatch, current Qualcomm kiosk deployment, and preserving migrated game gameplay/visuals. license: MIT compatibility: Requires QXZN repo, tools/godotctl, and the Godot Shell project under games/qxzn-runtime-template. metadata: author: QXZN version: "0.3"

Use this skill for QXZN Godot Shell tasks, especially when moving standalone games into games/qxzn-runtime-template.

Paths

cd /home/xwsl/code/qxzn02/tools/godotctl
export GODOT_PROJECT=/home/xwsl/code/qxzn02/games/qxzn-runtime-template
export GODOT_BIN=/home/xwsl/code/qxzn02/godot/bin/godot

Shell project:

/home/xwsl/code/qxzn02/games/qxzn-runtime-template

Current local kiosk target is the Qualcomm board at 172.16.6.7. RK3588 may be used again later, so keep runtime paths profile-based rather than RK-only.

Embedded Game IDs

Current Shell embedded games include:

interstellar_bounce
tracking_challenge
agility_challenge
fruit_slice

The migrated standalone games should be launched through Shell with:

./godotctl run-qcom -- --auto-start --game-id tracking_challenge
./godotctl run-qcom -- --auto-start --game-id agility_challenge
./godotctl run-qcom -- --auto-start --game-id fruit_slice

AI Motion Correction 2.0 Checks

For AI 动作纠正 2.0 in qxzn-runtime-template, the expected production-style flow is ROS2/Go serving control and media metadata, while Godot receives live RTP/H.264 and plays the final replay MP4. Do not validate this page by API calls alone.

Before declaring the Godot page ready, check:

1. ROS2 camera role and frame topic are live, for example /camera/rear_left/shm_frame at the expected resolution/FPS.
2. Skeleton topic is live, for example /skeleton/rear_left_2d.
3. Go session API accepts a session and reaches ready.
4. The replay URL supports HEAD and GET.
5. The exact local RTP/H.264 GStreamer receive pipeline decodes at least one frame.
6. The replay MP4 can be downloaded and played with local filesrc.
7. Godot C# builds after changes to QxznGstVideoPlayer.cs.
8. Godot logs include HTTP code/body-prefix or stream-error details when the UI shows a generic failure.

Useful commands for the 12.8-to-local development topology:

ssh x@172.16.12.8 "bash -lc 'export ROS_DOMAIN_ID=67; source /opt/ros/jazzy/setup.bash; source /home/x/code/qxzn02/ros2_ws/install/setup.bash; source /home/x/code/qxzn02/combat_system_ws/install/setup.bash; timeout 5 ros2 topic hz /camera/rear_left/shm_frame'"

sid="codex-godot-media-$(date +%s)"
curl -sS -X POST http://172.16.12.8:8000/api/v1/ai-motion-correction/sessions \
  -H 'Content-Type: application/json' \
  -d "{\"session_id\":\"$sid\",\"role\":\"rear_left\",\"tutorial_id\":\"ai_motion_correction_v2_main\",\"record_duration_sec\":2,\"client_host\":\"$(hostname -I | awk '{print $1}')\",\"live_rtp_port\":5604}"

timeout 10 bash -lc 'gst-launch-1.0 -q udpsrc port=5604 caps="application/x-rtp,media=video,clock-rate=90000,encoding-name=H264,payload=96" ! rtpjitterbuffer latency=20 drop-on-latency=true ! rtph264depay ! h264parse ! avdec_h264 ! videoconvert ! fakesink sync=false num-buffers=1'

curl -I "http://172.16.12.8:8000/api/v1/ai-motion-correction/sessions/$sid/replay.mp4"
curl -sS -o /tmp/qxzn-replay.mp4 "http://172.16.12.8:8000/api/v1/ai-motion-correction/sessions/$sid/replay.mp4"
gst-launch-1.0 -q filesrc location=/tmp/qxzn-replay.mp4 ! qtdemux ! h264parse ! avdec_h264 ! videoconvert ! fakesink sync=false

When starting local Godot against the 12.8 backend, pass the local machine IP as QXZN_ACTION_CORRECTION_CLIENT_HOST; otherwise ROS2 may push RTP to the wrong host:

QXZN_API_BASE=http://172.16.12.8:8000 \
QXZN_ACTION_CORRECTION_ROLE=rear_left \
QXZN_ACTION_CORRECTION_RTP_PORT=5600 \
QXZN_ACTION_CORRECTION_CLIENT_HOST="$(hostname -I | awk '{print $1}')" \
godot --path /home/x/code/qxzn02/games/qxzn-runtime-template --display-driver x11 --rendering-driver opengl3 --windowed --resolution 1280x720

If the UI says 动作纠正启动响应异常, inspect the Godot log and data-service log before changing ROS2. A 2xx HTML response, unsupported HEAD on replay MP4, bad GStreamer property, or HTTP playback incompatibility can look like a Godot failure while ROS2/session status is healthy.

Migration Checklist

1. Inspect original and migrated scenes with scene-tree and deps.
2. Preserve gameplay, scene structure, visual scale, audio, fonts, and resources.
3. Add the scene under scenes/games/ and scripts under scripts/games/.
4. Register the game id in Shell routing, menu cards, and auto-start handling.
5. Implement embedded lifecycle methods: setup_shell, shutdown, handle_key_event, and handle_segment for GDScript, or PascalCase equivalents for C#.
6. Route exit/back to the Shell menu instead of quitting the whole tree when embedded.
7. Route hardware hit segments through Shell bridge dispatch; do not keep duplicate WebSocket polling inside embedded games unless intentionally standalone.
8. For C# games, run doctor-csharp and build-csharp.
9. Run lint, check, auto-start smoke tests, export, deploy, and board-side GPU checks.
10. Delete old standalone folders only after migrated content,玩法, and visual design are verified.

Useful Checks

./godotctl scene-tree scenes/games/TrackingChallenge.tscn
./godotctl deps scenes/games/TrackingChallenge.tscn
./godotctl scene-tree scenes/games/AgilityChallenge.tscn
./godotctl scene-tree scenes/games/FruitSlice.tscn
./godotctl lint
./godotctl doctor-csharp
./godotctl build-csharp
./godotctl export-report output

For remote validation, use godotctl-runtime guidance and the current Qualcomm profile first. Keep RK3588 checks available for future deployment work.