AI-assisted development in YAZE allows developers and ROM hackers to leverage AI agents for code assistance, debugging, and automation. This guide covers how to use these AI-powered features in your daily workflow.
Overview
YAZE includes two primary AI assistance modes:
- Development Assistance - Help with building, testing, and debugging yaze itself
- ROM Debugging Assistance - Help debugging ROM patches, ASM code, and game state
Both modes use the same underlying AI service (Ollama or Gemini) and tool infrastructure, but target different workflows.
Choosing the right agent persona
- Personas live in
.claude/agents/<agent-id>.md; open the matching file as your system prompt before a session (available to all agents, not just Claude).
- ai-infra-architect: AI/agent infra, MCP/gRPC, z3ed tooling, model plumbing.
- backend-infra-engineer: Build/packaging/toolchains, CI reliability, release plumbing.
- imgui-frontend-engineer: ImGui/editor UI, renderer/backends, canvas/docking UX.
- snes-emulator-expert: Emulator core (CPU/APU/PPU), performance/accuracy/debugging.
- zelda3-hacking-expert: Gameplay/ROM logic, data formats, hacking workflows.
- test-infrastructure-expert: Test harnesses, CTest/gMock infra, flake/bloat triage.
- docs-janitor: Docs/process hygiene, onboarding, checklists.
Prerequisites
Build Requirements
AI-assisted features require the AI-enabled build preset:
cmake --preset mac-ai # macOS
cmake --preset lin-ai # Linux
cmake --preset win-ai # Windows
This includes gRPC server support, the z3ed CLI tool, and all agent infrastructure.
AI Provider Configuration
You need at least one AI provider configured:
Option 1: Local AI with Ollama (Recommended for Development)
Ollama provides free local AI models that run offline without API keys:
# Install Ollama
brew install ollama # macOS
# Or download from https://ollama.ai for Linux/Windows
# Start the Ollama server
ollama serve
# In another terminal, pull a recommended model
ollama pull qwen2.5-coder:0.5b # Fast, 0.5B parameter model
Then run z3ed with the model:
export OLLAMA_MODEL=qwen2.5-coder:0.5b
z3ed agent chat --rom zelda3.sfc
Option 2: Cloud AI with Gemini (For Advanced Features)
For more capable AI with vision support (image analysis, ROM visualization):
# Get API key from https://ai.google.com/
export GEMINI_API_KEY=your_api_key_here
z3ed agent chat --rom zelda3.sfc
Build Verification
After configuring your build:
# Verify AI components built correctly
cmake --build --preset mac-ai --target z3ed
./build/bin/z3ed --help | grep -i agent
Quick Start
Example 1: Debug a Build Error
# You encounter a compilation error
cmake --build build_ai
# [ERROR] src/app/gfx/snes_color.cc:45: error: 'Arena' was not declared
# Use z3ed to analyze and suggest fixes
z3ed agent chat --rom zelda3.sfc
> My code has a compilation error on line 45 of snes_color.cc. Can you help?
AI: I can help! Let me examine that file...
[Reads source files automatically using FileSystemTool]
Found the issue! You're missing:
#include "app/gfx/arena.h"
The Arena class is defined in that header. Here's the fix:
[Shows code diff]
Example 2: Debug ROM Crash
# Start z3ed with ROM debugging capabilities
z3ed agent debug-rom --rom=my_hack.sfc --emulator-port=50051
# You interact with the ROM
> My patch crashes when spawning enemies
AI: Let me connect to the emulator and analyze the crash...
[Emulator pauses at crash point]
I see the issue! Your code writes to $7E:A000 which is out of WRAM bounds.
The register X contains $8000 when it should be < $2000.
[Shows register state, memory contents, and suggests root cause]
Example 3: Generate Tests
# Ask the agent to generate tests for your changes
z3ed agent chat --rom zelda3.sfc
> I just added a function Process(int input) that returns input * 2.
> Can you write a test for it?
AI: Based on your description, here's a test:
TEST(MyClass, ProcessDoublesInput) {
MyClass obj;
EXPECT_EQ(obj.Process(5), 10);
EXPECT_EQ(obj.Process(0), 0);
EXPECT_EQ(obj.Process(-3), -6);
}
Mode 1: Development Assistance
Use AI assistance while developing yaze itself.
Build Error Resolution
The agent automatically analyzes compilation failures:
z3ed agent chat --rom zelda3.sfc
> cmake --build build_ai failed with:
> error: 'gfx::Arena' has not been declared in snes_color.cc:45
# AI will:
# 1. Search for the Arena class definition
# 2. Check your include statements
# 3. Suggest the missing header
# 4. Show the exact code change needed
Test Automation
Generate tests or run existing tests through the agent:
z3ed agent chat --rom zelda3.sfc
> Run the stable test suite and tell me if anything failed
# AI will:
# 1. Run ctest with appropriate filters
# 2. Parse test results
# 3. Report pass/fail status
# 4. Analyze any failures
Crash Analysis
Get help understanding segmentation faults and assertions:
z3ed agent chat --rom zelda3.sfc
> My program crashed with segfault in graphics_arena.cc:234
> [Paste stack trace]
# AI will:
# 1. Read the relevant source files
# 2. Analyze the call chain
# 3. Identify likely root causes
# 4. Suggest memory access issues or uninitialized variables
Performance Analysis
Identify performance regressions:
z3ed agent chat --rom zelda3.sfc
> My tile rendering is 3x slower than before. What changed?
# AI will:
# 1. Search for recent changes to tile rendering code
# 2. Identify performance-sensitive operations
# 3. Suggest optimizations (loop unrolling, caching, etc.)
Mode 2: ROM Debugging Assistance
Use AI assistance while debugging ROM patches and modifications.
ASM Patch Analysis
Get explanations of what your assembly code does:
z3ed agent debug-rom --rom=my_hack.sfc
> What does this routine do?
> [LDA #$01]
> [JSL $0A9000]
# AI will:
# 1. Decode each instruction
# 2. Explain register effects
# 3. Describe what the routine accomplishes
# 4. Identify potential issues (stack imbalance, etc.)
Memory State Analysis
Understand memory corruption:
z3ed agent debug-rom --rom=my_hack.sfc
> My sprite data is corrupted at $7E:7000. Help me debug.
# AI will:
# 1. Read memory from the emulator
# 2. Compare against known structures
# 3. Trace what modified this address (via watchpoints)
# 4. Identify the cause and suggest fixes
Breakpoint Analysis
Analyze game state at breakpoints:
z3ed agent debug-rom --rom=my_hack.sfc
> [Breakpoint hit at $0A:8234]
> Can you explain what's happening?
# AI will:
# 1. Disassemble the current instruction
# 2. Show register/memory state
# 3. Display the call stack
# 4. Explain the code's purpose
Routine Reverse Engineering
Document undocumented game routines:
z3ed agent debug-rom --rom=my_hack.sfc
> Trace through this routine and document what it does
> [Set breakpoint at $0A:8000, trace until return]
# AI will:
# 1. Step through instructions
# 2. Document register usage
# 3. Map memory accesses to structures
# 4. Generate routine documentation
Configuration Options
Environment Variables
# Use specific AI model (Ollama)
export OLLAMA_MODEL=qwen2.5-coder:0.5b
export OLLAMA_API_BASE=http://localhost:11434
# Use Gemini instead
export GEMINI_API_KEY=your_key_here
# Configure z3ed behavior
export Z3ED_WORKSPACE=/tmp/z3ed_work # Working directory for proposals
export Z3ED_LOG_LEVEL=debug # Verbose logging
Command-Line Flags
Most z3ed agent commands support these options:
# Logging and debugging
z3ed agent chat --log-file agent.log --debug
# ROM and workspace configuration
z3ed agent chat --rom zelda3.sfc --sandbox
# Model selection (Ollama)
z3ed agent chat --ai_model qwen2.5-coder:1b
# Emulator debugging (ROM Debug Mode)
z3ed agent debug-rom --emulator-port 50051
Configuration File
For persistent settings, create ~/.config/yaze/agent.toml:
[ai]
provider = "ollama" # or "gemini"
ollama_model = "qwen2.5-coder:0.5b"
gemini_api_key = "YOUR_KEY"
[workspace]
proposals_dir = "~/.local/share/yaze/proposals"
sandbox_roms = true
[logging]
level = "info" # debug, info, warn, error
Troubleshooting
Problem: Agent chat hangs after prompt
Cause: AI provider not running or configured
Solution:
# Check Ollama is running
ollama serve &
# Or verify Gemini API key
echo $GEMINI_API_KEY # Should not be empty
# Specify model explicitly
z3ed agent chat --ai_model qwen2.5-coder:0.5b --rom zelda3.sfc
Problem: z3ed command not found
Cause: Using wrong build preset or build directory
Solution:
# Use AI-enabled preset
cmake --preset mac-ai
cmake --build --preset mac-ai --target z3ed
# Try the full path
./build/bin/z3ed --help
Problem: FileSystemTool can't read my source files
Cause: Path outside project directory or binary file
Solution:
# Always use paths relative to project root
z3ed agent chat
> [Give paths like src/app/rom.cc, not /Users/name/Code/yaze/src/...]
# For binary files, ask for analysis instead
> Can you explain what the graphics in assets/graphics.bin contains?
Problem: Emulator won't connect in ROM Debug Mode
Cause: GUI test harness not enabled or wrong port
Solution:
# Enable test harness in GUI
./build/bin/yaze --rom_file zelda3.sfc --enable_test_harness
# Use correct port (default 50051)
z3ed agent debug-rom --rom my_hack.sfc --emulator-port 50051
Problem: Out of memory errors during large batch operations
Cause: Processing too much data at once
Solution:
# Use smaller batches
z3ed agent chat --max_batch_size 100
# Process one ROM at a time
z3ed agent chat --rom hack1.sfc
# ... finish ...
z3ed agent chat --rom hack2.sfc
Advanced Topics
Integration with CI/CD
Use AI assistance in GitHub Actions:
name: AI-Assisted Build Check
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup build
run: |
cmake --preset lin-ai
cmake --build --preset lin-ai --target yaze z3ed
- name: Analyze build
run: |
z3ed agent chat --ci-mode \
--prompt "Check if build succeeded and suggest fixes"
Batch Processing Multiple ROMs
Process multiple ROM hacks automatically:
#!/bin/bash
for rom in hacks/*.sfc; do
z3ed agent chat --rom "$rom" \
--prompt "Run tests and report status"
done
Custom Tool Integration
Extend z3ed with your own tools:
# Call custom analysis tools
z3ed agent chat --rom zelda3.sfc
> Can you run my custom analysis tool on this ROM?
> [Describe your tool]
# AI will integrate with the tool dispatcher
Related Documentation
1.10.0