dcc-mcp-godot: Instructions file for Codex

AGENTS.md — dcc-mcp-godot

Godot 4 editor adapter for the DCC Model Context Protocol: a GDScript EditorPlugin plus an EngineDebugger runtime peer, exposing on-demand capability tools and a tested 2D arena-roguelike skill. Navigation map for AI agents, not a reference manual. Follow the links; do not read everything up front.

Build & test

There is no justfile or vx.toml in this repo — use the commands CI runs:

python -m pip install -e ".[dev]"   # editable install with dev extras
python -m pytest                    # run the test suite
ruff check src tests tools          # lint
ruff format --check src tests tools # format check (line-length 100, py39 target)
python tools/lint_skills.py         # validate SKILL.md / tools.yaml
python -m build --no-isolation      # build wheel + sdist

Live host smoke (what the godot-latest CI job does):

GODOT=$(python tools/download_latest_godot.py --output .godot-bin)
python tests/live_godot_smoke.py --godot "$GODOT"

Windowed scene-preview lane (same job, after the smoke). live_godot_smoke.py starts every editor with --headless, and the host refuses render_scene_preview under that display driver by design, so the smoke is not coverage of the render path. This lane starts a windowed editor on Xvfb and calls it for real:

GODOT=$(python tools/download_latest_godot.py --output .godot-bin)
xvfb-run -a -s "-screen 0 1920x1080x24 -ac +extension GLX +render -noreset" \
  python tests/probe_windowed_preview.py --godot "$GODOT" --out preview-probe --tier B

Exit codes are the gate: 0 measured and passed, 1 measured and failed the criteria, 2 not measured. 2 skips the assertions instead of faking a green light or blocking every pull request, and the reason is written to preview-probe/summary.md and the job summary. The artifact also carries the noise floor the run measured, which is the evidence needed before tier B can be tightened on that platform — never copy another platform's tolerance.