Sky Layer

The sky layer is the simplest Hs2d visual base: one cached screen-sized background surface. It is built from a bitmap source and usually sits first in the layer order. The world still clears the screen, but the sky gives the scene a visible background image or solid color before parallax, tiles, sprites, particles, and HUD are composed.

Gameplay should use sky, parallax, tile, sprite, particle, HUD, and cached-surface layers instead of drawing backgrounds manually in the frame loop.

When To Use

Use a sky layer when the background should stay screen-fixed:

Use	Better alternative
Static skybox, starfield, menu backdrop, or flat color base	Direct or surface parallax if the image should move with the camera.
One image that should fit the viewport	Cached surface if the image is a large world-space backdrop that needs camera crop.
A clear visual base behind transparent layers	Custom layer only for special measured effects.

Construction Pattern

Manual worlds use world.addSky:

world.addSky({
  source: skyBitmap,
  clearColor: 0x000000ff,
});

The manual API uses the source at its natural dimensions. Supply viewport-sized art yourself if it must fill the screen.

Tiled worlds use an image layer with hs2d:role=sky. The builder looks up hs2d:asset or falls back to the layer id. It scales the bitmap to the viewport once at build time when needed.

Image layer: sky
hs2d:role = sky
hs2d:asset = space-sky
hs2d:clearColor = #000000

Update, Render, And Compose Behavior

SkyLayer extends CompositorSurfaceLayer.

Phase	Behavior
Attach	Creates a surface and compositor, creates one region for the source, and adds one compositor sprite.
Update	No camera work. The sky stays screen-fixed.
Render	Draws the compositor into its surface while dirty. For normal sky content this is a build-time or first-frame cost.
Compose	Draws the cached surface to the screen.

The sky layer uses zoom settings that keep it fixed at 1x scale by default. It is not a world camera layer.

Performance Notes

• Keep the sky source at the target viewport size when practical.
• Let the builder perform any one-time screen-fit scale instead of scaling during render. Manual addSky calls do not perform that fit.
• Do not redraw the sky in a custom layer each frame.
• Put parallax motion into direct or surface parallax layers, not into the sky.
• Use transparent foreground layers above the sky so only one base layer is needed.

Code Sample

const built = Hs2dWorldBuilder.fromLevel({
  level,
  assets,
  viewportWidth: screenWidth,
  viewportHeight: screenHeight,
  cameraX: 0,
  cameraY: 0,
  clearColor: 0x000000ff,
});

// With a Tiled image layer named "space-sky" and hs2d:role=sky,
// the builder adds the sky before later map layers in file order.
const world = built.world;
world.render(screen);

Source References

Source	Why it matters
../games/hosanna-ui/src/hosanna-game/scene/GameSceneRenderer.ts	SkyLayer, CompositorSurfaceLayer, attach/render/compose behavior, and render-frame order.
../games/hosanna-ui/src/hosanna-game/hosanna2d/Hs2dWorld.ts	addSky world API.
../games/hosanna-ui/src/hosanna-game/hosanna2d/Hs2dWorldBuilder.ts	Tiled hs2d:role=sky, asset lookup, clear color, and build-time screen fitting.
../hosanna-ui-game-samples-public/src/hosanna-game-examples/native-shoot-em-up/VerticalShooterLevelScene.ts	Example world build that relies on map image layers for sky and background composition.