galaxy-game/client/world/README.md

World rendering package

Deprecated. This package belongs to the deprecated galaxy/client Fyne client. New code must not import it. The active map renderer lives in ui/frontend/src/map/ (TypeScript

• PixiJS), with its specification in ui/docs/renderer.md. The sources here remain for historical context only and are not the reference algorithm for the new renderer.

Purpose

world is the client-side map model and renderer for a 2D world that normally behaves like a torus. It owns:

• primitive storage (Point, Line, Circle)
• world-space indexing for render and hit-test queries
• theme and style resolution
• full-frame and incremental rendering onto an expanded canvas
• no-wrap helpers used by the UI when torus scrolling is disabled

The package does not own UI widgets, event loops, or camera policy beyond the helpers exposed for zoom/clamp calculations.

Symbol Map

• World creation and mutation: NewWorld, AddPoint, AddLine, AddCircle, Remove, Reindex
• Viewport/index lifecycle: IndexOnViewportChange, SetCircleRadiusScaleFp
• Rendering: Render, RenderParams, RenderOptions, PrimitiveDrawer, GGDrawer
• No-wrap camera helpers: CorrectCameraZoom, ClampCameraNoWrapViewport, ClampRenderParamsNoWrap, PivotZoomCameraNoWrap
• Hit testing: HitTest, Hit, PrimitiveKind
• Styling and themes: Style, StyleOverride, StyleTable, StyleTheme, DefaultTheme, ThemeLight, ThemeDark

Coordinate Model

• World geometry is stored in fixed-point integers.
• SCALE == 1000, so 1.0 world units are represented as 1000.
• Primitive coordinates, radii, world dimensions, and camera positions use world-fixed units.
• Viewport and canvas sizes use integer canvas px.
• Rectangles in world space and canvas space are treated as half-open intervals: [minX, maxX) x [minY, maxY).
• RenderParams describes the visible viewport, but rendering happens on the expanded canvas:
  • canvasWidthPx = viewportWidthPx + 2*marginXPx
  • canvasHeightPx = viewportHeightPx + 2*marginYPx
• The camera always points to the center of the visible viewport, not the center of the expanded canvas.

Data Model

• World stores torus dimensions W and H in fixed-point units.
• MapItem is implemented by Point, Line, and Circle.
• PrimitiveID is allocated by World and may be reused after removal.
• Each primitive carries:
  • geometry in fixed-point world coordinates
  • Priority for deterministic draw order inside a tile
  • resolved StyleID
  • theme binding metadata (Base, Override, Class)
  • optional per-primitive hit slop in pixels
• Themes resolve base styles per primitive kind, then optional class overrides, then optional user StyleOverride.
• Explicit StyleID bypasses theme-relative recomputation across theme changes.

Spatial Index Lifecycle

• Rendering and hit testing depend on the grid index stored in World.grid.
• IndexOnViewportChange must be called after viewport size or zoom changes.
• The grid cell size is derived from the current visible world span:
  • start from roughly visibleMin / 8
  • clamp into [16*SCALE, 512*SCALE]
• AddPoint, AddLine, AddCircle, Remove, SetCircleRadiusScaleFp, and Reindex mark the index dirty and rebuild it automatically when the last viewport/zoom state is known.
• Circle indexing uses the effective radius after circleRadiusScaleFp is applied.
• Line indexing uses the torus-shortest representation and indexes its wrapped bounding boxes rather than exact rasterized coverage.

Render Pipeline

Render follows this sequence:

1. Validate RenderParams and resolve background color/theme state.
2. Convert zoom to fixed-point and compute the expanded unwrapped world rect.
3. Split that rect into WorldTile segments:
   • torus mode uses wrapped tiling
   • no-wrap mode intersects against the bounded world once
4. Query the spatial grid per tile and deduplicate candidates per tile by PrimitiveID.
5. Build a RenderPlan containing:
   • tile-to-canvas clip rectangles
   • per-tile candidate lists
6. Draw background before primitives.
7. Draw primitives tile-by-tile in deterministic order:
   • Priority ascending
   • primitive kind as stable tie-breaker
   • PrimitiveID ascending
8. For wrapped rendering:
   • points and circles emit only the torus copies that intersect the current tile
   • lines are split into torus-shortest canonical segments before projection

Incremental Pan Rendering

• Render first tries incremental pan reuse through ComputePanShiftPx and PlanIncrementalPan.
• If only camera pan changed and the shift stays inside the configured margins:
  • existing pixels are moved with PrimitiveDrawer.CopyShift
  • newly exposed strips become dirty rects
  • dirty rects are cleared, background-redrawn, and clipped primitive redraw is applied
• If geometry changed in a way that breaks reuse, rendering falls back to full redraw.
• Theme changes, circle radius scale changes, and explicit ForceFullRedrawNext reset incremental state.

No-Wrap Behavior

When RenderOptions.DisableWrapScroll == true, the world is treated as a bounded plane instead of a torus.

• CorrectCameraZoom prevents the visible viewport from becoming larger than the world.
• ClampCameraNoWrapViewport clamps the camera so the viewport remains inside the world.
• ClampRenderParamsNoWrap applies the same rule directly to RenderParams.
• PivotZoomCameraNoWrap keeps the world point under the cursor stable while zoom changes.

Margins are ignored by viewport clamp on purpose so panning remains usable even when the expanded canvas extends beyond the world bounds.

Hit Testing

• HitTest expects the grid to be built already.
• Cursor coordinates are passed in viewport pixels relative to the viewport top-left.
• The query path is:
  1. convert cursor position into world-fixed coordinates
  2. clamp or wrap based on no-wrap mode
  3. query a conservative grid search box using default hit slop
  4. run exact per-primitive hit checks
• Point hits use disc distance.
• Circle hits distinguish between filled circles and stroke-only rings.
• Line hits use the same torus-shortest segment decomposition as rendering.
• Final ranking is:
  • Priority descending
  • squared distance ascending
  • primitive kind ascending
  • PrimitiveID ascending

UI Integration Checklist

Typical UI flow:

1. Create the world with NewWorld.
2. Add primitives and optional styles/themes.
3. Before each render, compute the current viewport size in pixels.
4. Call CorrectCameraZoom when UI zoom changes.
5. Call IndexOnViewportChange when viewport size or zoom changes.
6. If no-wrap mode is enabled, call ClampRenderParamsNoWrap.
7. Render into a PrimitiveDrawer with Render.
8. Reuse the same RenderParams snapshot for HitTest.

The client package in this repository follows exactly that pattern.

Important Invariants and Limits

• Render and HitTest require the grid to be initialized; otherwise they return errGridNotBuilt.
• The package assumes single-goroutine access to hot render scratch buffers stored in World.
• RenderScheduler is only a coalescing example. It is not a license to call Render on arbitrary background goroutines in real UI code.
• PrimitiveDrawer receives final canvas coordinates only; all torus math stays inside world.
• Background anchoring can be viewport-relative or world-relative, but dirty redraws always use the same anchoring logic as full redraws.