yaze/docs/G1-canvas-guide.md

Canvas System Overview

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)

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)

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

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

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

Automation API

• CanvasAutomationAPI: tile operations (SetTileAt, SelectRect), view control (ScrollToTile, SetZoom), entity manipulation hooks
• Exposed through CLI (z3ed) and gRPC service, matching UI modes

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

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

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