Static Tile Layer

Hs2dStaticTileLayer paints the entire tile map once into a world-sized surface, then reuses a persistent crop region as the camera, scale, or viewport changes. By default, compose draws that crop directly to the screen. It is built for small maps and board-like scenes where a whole-map cached surface is cheaper than maintaining a visible tile sprite pool.

Use static tile layers or cached surfaces for static terrain. Do not draw all map tiles directly to the screen each frame.

When To Use

Use static tile mode when:

Good fit	Better alternative
The map is small enough for one world surface.	Cached chunk tile for large or sparse maps.
Camera movement is limited or slow.	Dynamic tile when the whole surface would be too large.
You want one cached raster representation of the entire tile layer.	Cached surface for non-tile painting.

The implementation guards against accidental huge surfaces. By default, a static layer rejects a world surface when either dimension exceeds 2048 pixels or the total area exceeds 2048 * 2048 pixels.

Construction Pattern

Manual:

const terrain = world.addTileLayer({
  id: 'board',
  mode: 'static',
  tileWidth: 60,
  tileHeight: 60,
  worldColumns: 32,
  worldRows: 18,
  tileKinds,
  regions: tileRegions,
  clearColor: 0x4cbc5eff,
  viewportClearColor: 0x020617ff,
});

Tiled:

Tile layer: board
hs2d:mode = static
hs2d:clearColor = #4cbc5e
hs2d:viewportClearColor = #020617

Set hs2d:allowLargeWorldSurface=true only after measuring memory and fill rate on the target device.

Update, Render, And Compose Behavior

Phase	Behavior
Attach	Creates one world surface, clears it, and paints every non-empty tile into it.
Update	Creates or reuses one crop region into the world surface. Camera changes move that native region without allocating a new object.
Render	No compositor render step. Static tile work happens in attach and update.
Compose, default	With composition: 'direct-to-screen', performs one crop blit, scaled when required. It clears only when the crop cannot cover the viewport.
Compose, compatibility	With composition: 'viewport-surface', redraws an intermediate viewport surface and then draws that surface to the screen.

The layer sets ownsTargetClear = true. When it is the first renderer layer, GameSceneRenderer skips its normal global clear because this layer either covers the viewport or clears exposed margins itself.

Stats expose the last visible tile count, the world paint count, and crop/viewport update count through the shared tile-layer stats shape.

Performance Notes

• Use only for small maps. A whole-world surface grows by worldWidth * worldHeight.
• Camera and zoom changes update the retained crop; static cameras reuse it.
• Keep the default direct-to-screen composition unless a measured integration requires the compatibility viewport surface.
• Avoid allowLargeWorldSurface unless a measured platform budget says it is safe.
• Transparent overlays and sprites should be separate layers above the static tile layer.
• Use dynamic or cached chunk tile mode for tall scrolling levels.

Code Sample

const world = Hs2dWorld.create({
  x: cameraX,
  y: cameraY,
  viewportWidth: screenWidth,
  viewportHeight: screenHeight,
  worldWidth: mapWidth * tileSize,
  worldHeight: mapHeight * tileSize,
  scale: zoom,
  clearColor: 0x020617ff,
});

world.addTileLayer({
  id: 'small-map',
  mode: 'static',
  tileWidth: tileSize,
  tileHeight: tileSize,
  worldColumns: mapWidth,
  worldRows: mapHeight,
  tileKinds,
  regions,
  clearColor: 0x000000ff,
  viewportClearColor: 0x020617ff,
});

world.addHud(this);

Camera viewport dimensions are screen pixels. The camera and layer derive the visible world extent by dividing those dimensions by scale; do not pre-divide them in the world options.

Source References

Source	Why it matters
../games/hosanna-ui/src/hosanna-game/hosanna2d/Hs2dStaticTileLayer.ts	Static world surface allocation, guard size, world paint, viewport crop/scale, compose, and stats.
../games/hosanna-ui/src/hosanna-game/hosanna2d/Hs2dWorld.ts	addTileLayer static mode.
../games/hosanna-ui/src/hosanna-game/hosanna2d/Hs2dWorldBuilder.ts	Tiled hs2d:mode=static, clear colors, viewport clear color, and large-surface opt-in.
../hosanna-ui-game-samples-public/src/hosanna-game-examples/diagnostics/H2dTilemapModeDemoController.ts	Diagnostic static tilemap construction and stats display.