Files

scawful 61c99ecfcd feat: enhance CMake configuration and CI workflow for AI features

- Added new build options for agent UI and remote automation in CMake presets, improving modularity.
- Updated CI workflow to enable AI runtime and agent UI during builds, ensuring compatibility with new features.
- Adjusted default Ollama model in scripts and documentation to reflect the lightweight version used in CI.
- Enhanced agent test suite script to support model overrides, improving flexibility for testing scenarios.

2025-11-16 21:36:04 -05:00

4.3 KiB

Raw Blame History

z3ed CLI Guide

Last reviewed: November 2025. z3ed ships alongside the main editor in every *-ai preset and runs on Windows, macOS, and Linux.

z3ed exposes the same ROM-editing capabilities as the GUI but in a scriptable form. Use it to apply patches, inspect resources, run batch conversions, or drive the AI-assisted workflows that feed the in-editor proposals.

1. Building & Configuration

# Enable the agent/CLI toolchain
cmake --preset mac-ai
cmake --build --preset mac-ai --target z3ed

# Run the text UI (FTXUI)
./build/bin/z3ed --tui

The AI features require at least one provider:

Ollama (local) – install via brew install ollama, run ollama serve, then set OLLAMA_MODEL=qwen2.5-coder:0.5b (the lightweight default used in CI) or any other supported model. Pass --ai_model "$OLLAMA_MODEL" on the CLI to override per-run.
Gemini (cloud) – export GEMINI_API_KEY before launching z3ed.

If no provider is configured the CLI still works, but agent subcommands will fall back to manual plans.

2. Everyday Commands

Task	Example
Apply an Asar patch	`z3ed asar patch.asm --rom zelda3.sfc`
Export all sprites from a dungeon	`z3ed dungeon list-sprites --dungeon 2 --rom zelda3.sfc --format json`
Inspect an overworld map	`z3ed overworld describe-map --map 80 --rom zelda3.sfc`
Dump palette data	`z3ed palette export --rom zelda3.sfc --output palettes.json`
Validate ROM headers	`z3ed rom info --rom zelda3.sfc`

Pass --help after any command to see its flags. Most resource commands follow the <noun> <verb> convention (overworld set-tile, dungeon import-room, etc.).

3. Agent & Proposal Workflow

3.1 Interactive Chat

z3ed agent chat --rom zelda3.sfc --theme overworld

Maintains conversation history on disk so you can pause/resume.
Supports tool-calling: the agent invokes subcommands (e.g., overworld describe-map) and returns structured diffs.

3.2 Plans & Batches

# Generate a proposal but do not apply it
z3ed agent plan --prompt "Move the eastern palace entrance 3 tiles east" --rom zelda3.sfc

# List pending plans
z3ed agent list

# Apply a plan after review
z3ed agent accept --proposal-id <id> --rom zelda3.sfc

Plans store the command transcript, diffs, and metadata inside $XDG_DATA_HOME/yaze/proposals/ (or %APPDATA%\yaze\proposals\). Review them before applying to non-sandbox ROMs.

3.3 Non-interactive Scripts

# Run prompts from a file
z3ed agent simple-chat --file scripts/queries.txt --rom zelda3.sfc --stdout

# Feed stdin (useful in CI)
cat <<'PROMPTS' | z3ed agent simple-chat --rom zelda3.sfc --stdout
Describe tile 0x3A in map 0x80.
Suggest palette swaps for dungeon 2.
PROMPTS

4. Automation Tips

Sandbox first – point the agent at a copy of your ROM (--sandbox flag) so you can review patches safely.
Log everything – --log-file agent.log captures the provider transcript for auditing.
Structure output – most list/describe commands support --format json or --format yaml for downstream tooling.
Combine with yaze_test – run ./build_ai/bin/yaze_test --unit after batch patches to confirm nothing regressed.
Use TUI filters – in --tui, press : to open the command palette, type part of a command, hit Enter, and the tool auto-fills the available flags.

5. Troubleshooting

Symptom	Fix
`agent chat` hangs after a prompt	Ensure `ollama serve` or the Gemini API key is configured.
`libgrpc` or `absl` missing	Re-run the `*-ai` preset; plain debug presets do not pull the agent stack.
CLI cannot find the ROM	Use absolute paths or set `YAZE_DEFAULT_ROM=/path/to/zelda3.sfc`.
Tool reports "command not found"	Run `z3ed --help` to refresh the command index; stale binaries from older builds lack new verbs.
Proposal diffs are empty	Provide `--rom` plus either `--sandbox` or `--workspace` so the agent knows where to stage files.

docs/public/developer/testing-without-roms.md – ROM-less fixtures for CI.
docs/public/developer/debugging-guide.md – logging and instrumentation tips shared between the GUI and CLI.
docs/internal/agents/ – deep dives into the agent architecture and refactor plans (internal audience only).

4.3 KiB Raw Blame History Unescape Escape