scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Consolidate Canvas Documentation and Update Structure

Browse Source 
- Streamlined the canvas documentation by consolidating multiple guides into a single comprehensive overview.
- Updated the canvas architecture section to reflect new features and interaction modes, enhancing clarity for users.
- Improved API patterns and integration steps for editors, ensuring consistency across documentation.
- Removed outdated content and added new sections on automation and debugging, aligning with recent code changes.
- Adjusted file paths in the documentation to match the current project structure, ensuring accurate references.
This commit is contained in:
scawful
2025-10-10 13:03:43 -04:00
parent d124ab962f
commit c96272296c
6 changed files with 79 additions and 553 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
docs/G1-canvas-guide.md
View File

@@ -1,179 +1,70 @@
# G1 - Canvas System and Automation
# Canvas System Overview
This document provides a comprehensive guide to the Canvas system in yaze, including its architecture, features, and the powerful automation API that enables programmatic control for the `z3ed` CLI, AI agents, and GUI testing.
## Canvas Architecture
- **Canvas States**: track `canvas`, `content`, and `draw` rectangles independently; expose size/scale through `CanvasState` inspection panel
- **Layer Stack**: background ➝ bitmaps ➝ entity overlays ➝ selection/tooltip layers
- **Interaction Modes**: Tile Paint, Tile Select, Rectangle Select, Entity Manipulation, Palette Editing, Diagnostics
- **Context Menu**: persistent menu with material icon sections (Mode, View, Info, Bitmap, Palette, BPP, Performance, Layout, Custom)
## 1. Core Concepts
## Core API Patterns
- Modern usage: `Begin/End` (auto grid/overlay, persistent context menu)
- Legacy helpers still available (`DrawBackground`, `DrawGrid`, `DrawSelectRect`, etc.)
- Unified state snapshot: `CanvasState` exposes geometry, zoom, scroll
- Interaction handler manages mode-specific tools (tile brush, select rect, entity gizmo)
### Canvas Structure
- **Background**: Drawing surface with border and optional scrolling
- **Content Layer**: Bitmaps, tiles, custom graphics
- **Grid Overlay**: Optional grid with hex labels
- **Interaction Layer**: Hover previews, selection rectangles
## Context Menu Sections
- **Mode Selector**: switch modes with icons (Brush, Select, Rect, Bitmap, Palette, BPP, Perf)
- **View & Grid**: reset/zoom, toggle grid/labels, advanced/scaling dialogs
- **Canvas Info**: real-time canvas/content size, scale, scroll, mouse position
- **Bitmap/Palette/BPP**: format conversion, palette analysis, BPP workflows with persistent modals
- **Performance**: profiler metrics, dashboard, usage report
- **Layout**: draggable toggle, auto resize, grid step
- **Custom Actions**: consumer-provided menu items
### Coordinate Systems
- **Screen Space**: ImGui window coordinates
- **Canvas Space**: Relative to canvas origin (0,0)
- **Tile Space**: Grid-aligned tile indices
- **World Space**: Overworld 4096x4096 large map coordinates
## Interaction Modes & Capabilities
- **Tile Painting**: tile16 painter, brush size, finish stroke callbacks
- Operations: finish_paint, reset_view, zoom, grid, scaling
- **Tile Selection**: multi-select rectangle, copy/paste selection
- Operations: select_all, clear_selection, reset_view, zoom, grid, scaling
- **Rectangle Selection**: drag-select area, clear selection
- Operations: clear_selection, reset_view, zoom, grid, scaling
- **Bitmap Editing**: format conversion, bitmap manipulation
- Operations: bitmap_convert, palette_edit, bpp_analysis, reset_view, zoom, grid, scaling
- **Palette Editing**: inline palette editor, ROM palette picker, color analysis
- Operations: palette_edit, palette_analysis, reset_palette, reset_view, zoom, grid, scaling
- **BPP Conversion**: format analysis, conversion workflows
- Operations: bpp_analysis, bpp_conversion, bitmap_convert, reset_view, zoom, grid, scaling
- **Performance Mode**: diagnostics, texture queue, performance overlays
- Operations: performance, usage_report, copy_metrics, reset_view, zoom, grid, scaling
## 2. Canvas API and Usage
## Debug & Diagnostics
- Persistent modals (`View→Advanced`, `View→Scaling`, `Palette`, `BPP`) stay open until closed
- Texture inspector shows current bitmap, VRAM sheet, palette group, usage stats
- State overlay: canvas size, content size, global scale, scroll, highlight entity
- Performance HUD: operation counts, timing graphs, usage recommendations
### Modern Begin/End Pattern
The recommended way to use the canvas is with the `Begin()`/`End()` pattern, which handles setup and teardown automatically.
## Automation API
- CanvasAutomationAPI: tile operations (`SetTileAt`, `SelectRect`), view control (`ScrollToTile`, `SetZoom`), entity manipulation hooks
- Exposed through CLI (`z3ed`) and gRPC service, matching UI modes
```cpp
canvas.Begin(ImVec2(512, 512));
canvas.DrawBitmap(bitmap, 0, 0, 2.0f);
canvas.End(); // Automatic grid + overlay
```
## Integration Steps for Editors
1. Construct `Canvas`, set renderer (optional) and ID
2. Call `InitializePaletteEditor` and `SetUsageMode`
3. Configure available modes: `SetAvailableModes({kTilePainting, kTileSelecting})`
4. Register mode callbacks (tile paint finish, selection clear, etc.)
5. During frame: `canvas.Begin(size)` → draw bitmaps/entities → `canvas.End()`
6. Provide custom menu items via `AddMenuItem`/`AddMenuItem(item, usage)`
7. Use `GetConfig()`/`GetSelection()` for state; respond to context menu commands via callback lambda in `Render`
### Feature: Tile Painting
The canvas provides methods for painting single tiles, painting from a tilemap, and painting with solid colors.
## Migration Checklist
- Replace direct `DrawContextMenu` logic with new render callback signature
- Move palette/BPP helpers into `canvas/` module; update includes
- Ensure persistent modals wired (advanced/scaling/palette/bpp/perf)
- Update usage tracker integrations to record mode switches
- Validate overworld/tile16/dungeon editors in tile paint, select, entity modes
```cpp
if (canvas.DrawTilePainter(current_tile_bitmap, 16, 2.0f)) {
ImVec2 paint_pos = canvas.drawn_tile_position();
ApplyTileToMap(paint_pos, current_tile_id);
}
```
### Feature: Tile Selection
The canvas supports both single-tile and multi-tile rectangle selection.
```cpp
canvas.DrawSelectRect(current_map_id, 16, 1.0f);
if (canvas.select_rect_active()) {
const auto& selected_tiles = canvas.selected_tiles();
// Process selection...
}
```
### Feature: Large Map Support
The canvas can handle large maps with multiple local maps, including boundary clamping to prevent selection wrapping.
```cpp
canvas.SetClampRectToLocalMaps(true); // Default - prevents wrapping
```
### Feature: Context Menu
The canvas has a customizable context menu.
```cpp
canvas.AddContextMenuItem({
"My Action",
[this]() { DoAction(); }
});
```
## 3. Canvas Automation API
The `CanvasAutomationAPI` provides a programmatic interface for controlling canvas operations, enabling scripted editing, AI agent integration, and automated testing.
### Accessing the API
```cpp
auto* api = canvas.GetAutomationAPI();
```
### Tile Operations
```cpp
// Paint a single tile
bool SetTileAt(int x, int y, int tile_id);
// Get the tile ID at a specific location
int GetTileAt(int x, int y) const;
// Paint multiple tiles in a batch
bool SetTiles(const std::vector<std::tuple<int,int,int>>& tiles);
```
### Selection Operations
```cpp
// Select a single tile
void SelectTile(int x, int y);
// Select a rectangular region of tiles
void SelectTileRect(int x1, int y1, int x2, int y2);
// Get the current selection state
SelectionState GetSelection() const;
// Clear the current selection
void ClearSelection();
```
### View Operations
```cpp
// Scroll the canvas to make a tile visible
void ScrollToTile(int x, int y);
// Set the canvas zoom level
void SetZoom(float zoom_level);
// Get the current zoom level
float GetZoom() const;
// Center the canvas view on a specific coordinate
void CenterOn(int x, int y);
```
### Query Operations
```cpp
// Get the dimensions of the canvas in tiles
CanvasDimensions GetDimensions() const;
// Get the currently visible region of the canvas
VisibleRegion GetVisibleRegion() const;
// Check if a tile is currently visible
bool IsTileVisible(int x, int y) const;
// Get the cursor position in logical tile coordinates
ImVec2 GetCursorPosition() const;
```
### Simulation Operations (for GUI Automation)
```cpp
// Simulate a mouse click at a specific tile
void SimulateClick(int x, int y, ImGuiMouseButton button = ImGuiMouseButton_Left);
// Simulate a drag operation between two tiles
void SimulateDrag(int x1, int y1, int x2, int y2);
// Wait for the canvas to finish processing
void WaitForIdle();
```
## 4. `z3ed` CLI Integration
The Canvas Automation API is exposed through the `z3ed` CLI, allowing for scripted overworld editing.
```bash
# Set a tile
z3ed overworld set-tile --map 0 --x 10 --y 10 --tile-id 0x0042 --rom zelda3.sfc
# Get a tile
z3ed overworld get-tile --map 0 --x 10 --y 10 --rom zelda3.sfc
# Select a rectangle
z3ed overworld select-rect --map 0 --x1 5 --y1 5 --x2 15 --y2 15 --rom zelda3.sfc
# Scroll to a tile
z3ed overworld scroll-to --map 0 --x 20 --y 20 --center --rom zelda3.sfc
```
## 5. gRPC Service
The Canvas Automation API is also exposed via a gRPC service, allowing for remote control of the canvas.
**Proto Definition (`protos/canvas_automation.proto`):**
```protobuf
service CanvasAutomation {
rpc SetTileAt(SetTileRequest) returns (SetTileResponse);
rpc GetTileAt(GetTileRequest) returns (GetTileResponse);
rpc SelectTileRect(SelectTileRectRequest) returns (SelectTileRectResponse);
// ... and so on for all API methods
}
```
This service is hosted by the `UnifiedGRPCServer` in the main yaze application, allowing tools like `grpcurl` or custom clients to interact with the canvas remotely.
## Testing Notes
- Manual regression: overworld paint/select, tile16 painter, dungeon entity drag
- Verify context menu persists and modals remain until closed
- Ensure palette/BPP modals populate with correct bitmap/palette data
- Automation: run CanvasAutomation API tests/end-to-end scripts for overworld edits