167 lines
4.5 KiB
Markdown
167 lines
4.5 KiB
Markdown
# YAZE Startup Debugging Flags
|
|
|
|
This guide explains how to use command-line flags to quickly open specific editors and panels during development for faster debugging workflows.
|
|
|
|
## Basic Usage
|
|
|
|
```bash
|
|
./yaze [flags]
|
|
```
|
|
|
|
## Available Flags
|
|
|
|
### `--rom_file`
|
|
Load a specific ROM file on startup.
|
|
|
|
```bash
|
|
./yaze --rom_file=/path/to/zelda3.sfc
|
|
```
|
|
|
|
### `--debug`
|
|
Enable debug logging with verbose output.
|
|
|
|
```bash
|
|
./yaze --debug --log_file=yaze_debug.log
|
|
```
|
|
|
|
### `--log_level`, `--log_categories`, `--log_to_console`
|
|
Control verbosity and filter by subsystem. Categories can be allowlisted or blocked by prefixing with `-`:
|
|
|
|
```bash
|
|
./yaze --log_level=debug --log_categories="EditorManager,-Audio" --log_to_console
|
|
```
|
|
|
|
### `--editor`
|
|
Open a specific editor on startup. This saves time by skipping manual navigation through the UI.
|
|
|
|
**Available editors:**
|
|
- `Assembly` - Assembly code editor
|
|
- `Dungeon` - Dungeon/underworld editor
|
|
- `Graphics` - Graphics and tile editor
|
|
- `Music` - Music and sound editor
|
|
- `Overworld` - Overworld map editor
|
|
- `Palette` - Palette editor
|
|
- `Screen` - Screen editor
|
|
- `Sprite` - Sprite editor
|
|
- `Message` - Message/text editor
|
|
- `Hex` - Hex/memory editor
|
|
- `Agent` - AI agent interface
|
|
- `Settings` - Settings editor
|
|
|
|
**Example:**
|
|
```bash
|
|
./yaze --rom_file=zelda3.sfc --editor=Dungeon
|
|
```
|
|
|
|
### `--open_panels`
|
|
Open specific panels within an editor. Matching is case-insensitive and accepts either display names
|
|
or stable panel IDs (e.g., `dungeon.room_list`, `emulator.cpu_debugger`). `Room N` tokens will open
|
|
the corresponding dungeon room card.
|
|
|
|
**Dungeon Editor Panels:**
|
|
- `Rooms List` - Shows the list of all dungeon rooms
|
|
- `Room Matrix` - Shows the dungeon room layout matrix
|
|
- `Entrances List` - Shows dungeon entrance configurations
|
|
- `Room Graphics` - Shows room graphics settings
|
|
- `Object Editor` - Shows the object placement editor
|
|
- `Palette Editor` - Shows the palette editor
|
|
- `Room N` - Opens a specific room by ID (e.g., `Room 0`, `Room 105`)
|
|
|
|
**Example:**
|
|
```bash
|
|
./yaze --rom_file=zelda3.sfc --editor=Dungeon --open_panels="Rooms List,Room 0"
|
|
```
|
|
|
|
### `--startup_welcome`, `--startup_dashboard`, `--startup_sidebar`
|
|
Control startup chrome visibility. Each accepts `auto`, `show`, or `hide`:
|
|
|
|
```bash
|
|
./yaze --rom_file=zelda3.sfc --editor=Overworld \
|
|
--startup_welcome=hide --startup_dashboard=show --startup_sidebar=hide
|
|
```
|
|
|
|
## Common Debugging Scenarios
|
|
|
|
### 1. Quick Dungeon Room Testing
|
|
Open a specific dungeon room for testing:
|
|
|
|
```bash
|
|
./yaze --rom_file=zelda3.sfc --editor=Dungeon --open_panels="Room 0,Room Graphics"
|
|
```
|
|
|
|
### 2. Multiple Room Comparison
|
|
Compare multiple rooms side-by-side:
|
|
|
|
```bash
|
|
./yaze --rom_file=zelda3.sfc --editor=Dungeon --open_panels="Room 0,Room 1,Room 105"
|
|
```
|
|
|
|
### 3. Full Dungeon Editor Workspace
|
|
Open all dungeon editor tools:
|
|
|
|
```bash
|
|
./yaze --rom_file=zelda3.sfc --editor=Dungeon \
|
|
--open_panels="Rooms List,Room Matrix,Room Graphics,Object Editor,Palette Editor"
|
|
```
|
|
|
|
### 4. Debug Mode with Logging
|
|
Enable full debug output while working:
|
|
|
|
```bash
|
|
./yaze --rom_file=zelda3.sfc --debug --log_file=debug.log \
|
|
--editor=Dungeon --open_panels="Room 0"
|
|
```
|
|
|
|
### 5. Quick Overworld Editing
|
|
Jump straight to overworld editing:
|
|
|
|
```bash
|
|
./yaze --rom_file=zelda3.sfc --editor=Overworld
|
|
```
|
|
|
|
## gRPC Test Harness (Developer Feature)
|
|
|
|
If compiled with `YAZE_WITH_GRPC=ON`, you can enable automated GUI testing:
|
|
|
|
```bash
|
|
./yaze --enable_test_harness --test_harness_port=50051
|
|
```
|
|
|
|
This allows remote control via gRPC for automated testing and AI agent interaction.
|
|
|
|
## Combining Flags
|
|
|
|
All flags can be combined for powerful debugging setups:
|
|
|
|
```bash
|
|
# Full debugging setup for room 105
|
|
./yaze \
|
|
--rom_file=/path/to/zelda3.sfc \
|
|
--debug \
|
|
--log_file=room_105_debug.log \
|
|
--editor=Dungeon \
|
|
--open_panels="Room 105,Room Graphics,Palette Editor,Object Editor"
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Panel tokens are matched case-insensitively against IDs and display names
|
|
- Use quotes around comma-separated panel lists
|
|
- Invalid editor or panel names will be logged as warnings but won't crash the application
|
|
- `Room N` shortcuts use the dungeon room ID range (0-319 in vanilla)
|
|
|
|
## Troubleshooting
|
|
|
|
**Editor doesn't open:**
|
|
- Check spelling (case-sensitive)
|
|
- Verify ROM loaded successfully
|
|
- Check log output with `--debug`
|
|
|
|
**Panels don't appear:**
|
|
- Ensure editor is set (e.g., `--editor=Dungeon`)
|
|
- Check panel name spelling
|
|
- Some panels require a loaded ROM
|
|
|
|
**Want to add more panel support?**
|
|
See `EditorManager::OpenEditorAndPanelsFromFlags()` in `src/app/editor/editor_manager.cc`
|