ucp-runtime-debugging
/ucp-runtime-debugging
Find out what the running Unity project is doing and why with `ucp logs`, `ucp run-tests`, `ucp exec`, `ucp profiler`, `ucp profile`, and `ucp frame capture`: read and follow console logs with filters, run edit-mode or play-mode tests by name pattern, execute registered editor scripts with parameters, hot-reload edited method bodies into a running game with `ucp hot-reload`, profile frames and read hierarchies sorted by self time, and export structured captures. Use for playtesting loops, failure triage, test runs, and performance work. For compile errors and editor state use ucp-editor-lifecy
- Author
- mflrevan ↗
- Repository
- unity-control-protocol ↗
- Licence
- MIT
- Last repository change
- 13.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Find out what the running Unity project is doing and why with `ucp logs`, `ucp run-tests`, `ucp exec`, `ucp profiler`, `ucp profile`, and `ucp frame capture`: read and follow console logs with filters, run edit-mode or play-mode tests by name pattern, execute registered editor scripts with parameters, hot-reload edited method bodies into a running game with `ucp hot-reload`, profile frames and read hierarchies sorted by self time, and export structured captures. Use for playtesting loops, failure triage, test runs, and performance work. For compile errors and editor state use ucp-editor-lifecy
Original author description
Find out what the running Unity project is doing and why with `ucp logs`, `ucp run-tests`, `ucp exec`, `ucp profiler`, `ucp profile`, and `ucp frame capture`: read and follow console logs with filters, run edit-mode or play-mode tests by name pattern, execute registered editor scripts with parameters, hot-reload edited method bodies into a running game with `ucp hot-reload`, profile frames and read hierarchies sorted by self time, and export structured captures. Use for playtesting loops, failure triage, test runs, and performance work. For compile errors and editor state use ucp-editor-lifecy
How it works
- Logs
- Tests
- Editor scripts (IUCPScript)
- Profiler
- Frame export
- Workflows
- Pitfalls
SKILL.md preview
---
name: ucp-runtime-debugging
description: >-
Find out what the running Unity project is doing and why with `ucp logs`, `ucp run-tests`,
`ucp exec`, `ucp profiler`, `ucp profile`, and `ucp frame capture`: read and follow console
logs with filters, run edit-mode or play-mode tests by name pattern, execute registered editor
scripts with parameters, hot-reload edited method bodies into a running game with `ucp
hot-reload`, profile frames and read hierarchies sorted by self time, and export structured
captures. Use for playtesting loops, failure triage, test runs, and performance work. For compile errors and editor state use ucp-editor-lifecycle.
compatibility: Requires the `ucp` CLI (npm `@mflrevan/ucp`) and the UCP bridge package in the target Unity project. Unity 2021.3 or newer.
metadata:
author: mflRevan
version: '0.7.1'
homepage: https://unityctl.dev/skills/ucp-runtime-debugging
---
# Runtime debugging: logs, tests, scripts, profiler
## Logs
```bash
ucp logs status # counts by level, top repeated messages, play-session window
ucp logs --count 20 # newest buffered entries
ucp logs --level error --count 50
ucp logs --pattern 'NullReference|Exception' --count 100
ucp logs --filter 'level>=warning,channel=Shader'
ucp logs --id 1842 # one entry with its full stack trace
ucp logs --after-id 1800 --level error # only what happened since a cursor
ucp logs --follow --level error --count 5 # live; stops after 5 matches
ucp log tail --follow # `log` is an alias
```
- The bridge buffers console history since it loaded and seeds it from the Console window, so
`logs` works for entries that predate the connection.
- `logs status` is the cheap first look: it collapses repeats into categories and reports the
last play session's window separately.
- The `[editor]` line after every command already carries the console's error and warning
counts and how many the command itself produced; use `logs` to read the messages.
## Tests
```bash
ucp run-tests # edit-mode, whole project
ucp run-tests --mode play
ucp run-tests --filter ControllerSmokeTests # regex over Namespace.Fixture.Test, substring fallback
ucp run-tests --filter 'Player.*Jump' --json
```
- Results include per-test status and duration; the exit code is non-zero on any failure.
- A console error or exception logged during the run fails an extra synthetic check, so a
passing suite with a red console still fails. Lines a test declared as expected through
`LogAssert.ignoreFailingMessages` are excluded.
- A filter that matches nothing is an error, not a pass.
- Play-mode tests enter play mode and reload the domain; expect the command to take longer and
instance ids to change afterwards.
## Editor scripts (`IUCPScript`)
```bash
ucp exec list # registered scripts in the project
ucp exec run setup-arena
ucp exec run spawn-wave --params '{"count":12,"radius":8}'
ucp exec run demo-autopilot --record run.mp4 --record-lead 0.5 --record-tail 1
```
A script is an editor class implementing `IUCPScript` (`Name`, `Description`,
`object Execute(string paramsJson)`); the return value comes back as JSON. Scripts run on the main
thread with full editor access, which makes them the tool for anything the command surface does
not cover. Two rules, because scripts bypass the bridge's guards: never call
`EditorUtility.DisplayDialog` or any native file panel, and never `SaveScene()` an untitled
scene; both block the editor on a prompt nobody can answer.
## Profiler
```bash
ucp profile --seconds 5 --mode play # one-shot: start, wait, stop, summary
ucp profiler status # capabilities, frame buffer, current mode
ucp profiler config get
ucp profiler config set --deep-profile true --allocation-callstacks true
ucp profiler session start --mode play --clear-first
ucp play
ucp profiler frames list --limit 5 # take a fresh frame index from here
ucp profiler frames show --frame 1234 --include-threads
ucp profiler hierarchy --frame 1234 --thread 0 --sort self-time --limit 20 --fields name,selfMs,calls,gcMemory
ucp profiler timeline --frame 1234 --thread 0 --limit 100 --max-depth 3
ucp profiler callstacks --frame 1234 --kind hierarchy --item 42 --resolve-methods
ucp profiler summary --first-frame 1200 --last-frame 1300 --limit 10
ucp profiler capture save --output ProfilerCaptures/session.json
ucp profiler capture load --input ProfilerCaptures/session.raw
ucp profiler session stop
ucp stop
```
- Live frame indices churn while the editor runs; list frames immediately before `hierarchy`,
`timeline`, or `callstacks`.
- `--fields` trims the payload to the columns you need; `--limit` and `--max-depth` bound it.
Truncation is reported as "showing N of M", not silently.
- `capture save` writes a structured JSON snapshot for scripts and agents; `.raw`/`.data` files
from the Profiler window can be loaded back with `capture load`.
## Frame export
```bash
ucp frame capture --out frame.json # structured frame/profiler capture
ucp shader errors --errors-only # shader compile problems (see ucp-assets)
```
## Workflows
Autonomous playtest with triage:
```bash
ucp compile # fail fast on CS#### errors
ucp logs status # baseline counts
ucp play --log-file play.log
# drive the game: exec scripts, record, wait
ucp logs --level error --count 20
# fix a method body and keep playing: ~1 s, state kept, no domain reload
ucp hot-reload apply Assets/Scripts/EnemyAI.cs
ucp stop
ucp logs status # the lastPlayWindow block is this session
```
Find the hot path behind a spike:
```bash
ucp profiler session start --mode play --clear-first
ucp play
ucp profiler frames list --limit 3
ucp profiler summary --limit 10
ucp profiler hierarchy --frame <fresh> --sort self-time --limit 15 --fields name,selfMs,calls
ucp profiler callstacks --frame <fresh> --kind hierarchy --item <id> --resolve-methods
ucp profiler session stop && ucp stop
```
Run the tests that matter after a change:
```bash
ucp compile
ucp run-tests --filter 'Inventory' --json
ucp logs --level error --after-id <cursor from logs status>
```
## Pitfalls
- `run-tests --mode play` and `ucp play` both reload the domain; every instance id you hold is
stale afterwards.
- Profiling in edit mode measures the editor; use `--mode play` for gameplay numbers.
- Deep profiling and allocation callstacks are expensive; turn them on for a targeted window,
not a whole session.
Versions
The database has no other skills named ucp-runtime-debugging.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 4c3faf1136d5 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100ucp-editor-lifecycle
Bring a Unity project under control with the `ucp` CLI: install the bridge, open or adopt the editor, read the `[editor]` state line every command prints, recompile or hot-reload method bodies without a domain reload, enter and leave play mode, and recover from modal dialogs.… - 100ucp-assets
Work with a Unity project's assets and files through the editor with `ucp asset`, `ucp files`, `ucp material`, `ucp references`, `ucp shader`, and `ucp script`: search and inspect assets, read and write ScriptableObject and material fields, move or rename assets without breaking… - 100ucp-setup
Set up a UCP project — scaffold a merchant server or platform client with discovery profile, SDK installation, and project structure. Use when starting a new UCP implementation. - 100unity-pipeline
Drive a running Unity Editor or development Player from the command line via the unity-pipeline package — install the package, keep the editor ticking while unfocused, run the edit→recompile→run_tests loop, evaluate C#, and hot-reload files at runtime. Use when an agent needs to… - 100ucp-conformance
Run and write UCP conformance tests — validate a UCP implementation against the official test suite covering checkout lifecycle, orders, fulfillment, payments, idempotency, webhooks, and security. Use when testing or validating a UCP implementation. - 100ucp-agent-ready
Publish or repair a Universal Commerce Protocol (UCP) profile so AI shopping agents can discover, read and transact with a store, verified against UCP Checker's independent validator. Use when asked to \"make this store agent-ready\", \"add UCP\", \"fix our /.well-known/ucp\",…