# Scenery surface caching

`StageRectSurface` renders committed patterned scenery through reusable texture tiles.
Drawing previews use the adaptive lightweight renderer. Paint remains a single rectangle.

## Camera movement

Tiles use a fixed grid in the surface's local coordinates. Texture resolution changes in
powers of two, so adjacent wheel steps reuse existing tiles. Panning requests only newly
exposed tiles. Existing textures stay visible while missing tiles are prepared, with a
lightweight surface motif beneath them to prevent blank areas.

`StageSurfaceCache` keeps queued tiles as metadata. A shared queue creates and renders at
most one tile per process frame across all surfaces. It also retires at most two obsolete
render targets per frame. This avoids large allocations, vector rebuilds, and batches of
GPU resource releases during camera input.

Each tile has a 256 × 128 pixel core and a four pixel gutter. The gutter is cropped during
compositing to prevent seams. Each surface requests at most 192 visible tiles and retains
at most 224 tiles, evicting older unused entries. Half-resolution tiles retain full brick
texture and wood grain. Only quarter-resolution tiles and below omit fine texture, for
distant views. Brick and plank positions remain fixed. Detail can fill in progressively
after movement, including when returning from a distant view to a normal zoom level.

## Invalidation and coverage

Geometry, finish, tint, and motif-origin changes invalidate that surface's tiles. Camera
movement selects tiles without invalidating their artwork. Render targets belong to the
surface node; queued references are weak so deleted surfaces cannot keep jobs alive.

Fully opaque rectangular sibling surfaces can suppress artwork entirely hidden behind
them. Coverage checks account for transforms, draw order, and visibility. Transparent
surfaces, custom materials, differing relative-Z conventions, and Y-sorted parents disable
this optimization conservatively. Revealing a surface resumes its pending tiles.

## Verification

`tests/test_scenery_surface_cache.gd` checks rendered appearance against the direct vector
renderer, tile reuse and invalidation, the shared build limit, allocation and retention
bounds, and covered-surface behavior. Run it with a graphical Godot renderer for pixel
comparisons. The adaptive preview regressions remain in
`tests/test_scenery_surface_preview.gd` and `tests/test_scenery_brick_preview.gd`.