Worldshaper/docs/kb/systems/rendering-viewport.md

Rendering And Viewport

What It Does

This subsystem draws the active world or map, manages Pixi chunk surfaces, keeps chunk visibility in sync with the viewport, and overlays debug and selection information on top of the scene.

Key Files

• src/worldshaperStudio/renderController.ts
• src/worldshaperStudio/pixiTileStageController.ts
• src/worldshaperStudio/pixiSceneRebuildHelpers.ts
• src/worldshaperStudio/pixiChunkSurfaceHelpers.ts
• src/worldshaperStudio/overlayRenderer.ts

Endpoints It Uses

• none directly; it consumes already-loaded document and chunk data

Important Data And Rules

• chunk surfaces are built per layer and per chunk
• viewport movement drives visible chunk culling
• Pixi visibility is separate from data caching
• debug snapshots expose visible chunk counts and renderer state

Invariants And Constraints

• rendering changes must respect layer visibility
• the viewport can hide chunk sprites without unloading their cached data
• background tile behavior is special for base-layer rendering
• performance work needs profiling because rendering cost and fetch cost are different problems

Common Request Themes

• rendering performance
• chunk culling
• animation playback in-world
• background drawing behavior
• viewport glitches on very large worlds

Triage Questions

• Is the request about data load, or only about drawing what is already loaded?
• Is the issue specific to Pixi chunk surfaces?
• Does it reproduce only at certain zoom levels or viewport sizes?