Hs2d / Hosanna Game

Hs2d is Hosanna's cross-platform 2D game framework. A game owns a stack of scenes, gameplay scenes build a world from ordered renderer layers, one camera projects that world, and the runtime separates input, simulation, render-state synchronization, rendering, and presentation.

Use this page to choose the right starting point. The engine is maintained in games/hosanna-ui; runnable games, hosts, assets, and tests are maintained in hosanna-ui-game-samples-public.

Start Here

For a new world-based game:

1. Extend Hs2dGame or compose an Hs2dSingleSceneGame.
2. Start with a title or menu scene and replace it with a gameplay scene.
3. Extend Hs2dLevelScene for gameplay that renders an Hs2dWorld.
4. Load assets through asset bundles and an Hs2dAssetGate.
5. Build the world once, usually with Hs2dWorldBuilder.fromLevel().
6. Keep game rules in onUpdate() and synchronize stable render objects in updateSceneSprites().
7. Tick one camera and render through Hs2dWorld.render(screen).
8. Use fixed-capacity pools, cached text, and an appropriate layer renderer for steady-state work.

The vertical shooter is the clearest end-to-end example:

Source	Purpose
hosanna-ui-game-samples-public/src/hosanna-game-examples/native-shoot-em-up/VerticalShooterGame.ts	Hs2dGame entrypoint and title-scene installation.
hosanna-ui-game-samples-public/src/hosanna-game-examples/native-shoot-em-up/VerticalShooterMenuScene.ts	Title menu and transition into gameplay.
hosanna-ui-game-samples-public/src/hosanna-game-examples/native-shoot-em-up/VerticalShooterLevelScene.ts	Hs2dLevelScene, Tiled world build, pools, camera, HUD, particles, and telemetry.
hosanna-ui-game-samples-public/src/hosanna-game-examples/native-shoot-em-up/VerticalShooterPauseScene.ts	Pausing overlay, restart and quit actions, and controller-management entrypoints.
hosanna-ui-game-samples-public/asset-bundles/native-shoot-em-up/	Bundle manifest, app config, images, audio, fonts, and prepared levels.

Do not use a diagnostic controller with an ad hoc DrawRect, DrawObject, or DrawScaledObject loop as the template for a production world renderer. Diagnostic controllers are intentionally small probes.

Read In This Order

1. Runtime Frame Loop explains the host-owned tick.
2. Game And Scene Stack explains navigation and overlays.
3. Level Scene Lifecycle covers loading, one-time world construction, and restart.
4. Level Scene Frame Hooks assigns ready-state work to input, simulation, synchronization, telemetry, and render hooks.
5. Worlds, Layers, And Camera explains world composition.
6. Building A New Game turns those pieces into a working skeleton.
7. Performance Covenant defines the device-safe steady-state rules.

Then choose the focused rendering, systems, Tiled, and example pages below.

Source Layout

Path	Owns
games/hosanna-ui/src/hosanna-game	Runtime, scenes, worlds, layers, input, controls, assets, audio, collisions, particles, economy, items, settings, store integration, and core utilities.
hosanna-ui-game-samples-public/src/hosanna-game-examples	Runnable games, diagnostic rigs, shared shell/menu code, registry, and game-level tests.
hosanna-ui-game-samples-public/src/sample-platform/roku-game	Roku host loop, runtime wiring, input adapters, paired-control server, audio, and launch code.
hosanna-ui-game-samples-public/asset-bundles/<game>	Bundle manifests, app config, images, audio, fonts, atlases, and prepared Tiled data.

Shared game code compiled for Roku must remain compatible with the Hosanna compiler. Keep browser-only APIs out of shared engine and gameplay code; isolate them in target-specific adapters.

Run And Validate The Samples

Run these commands from hosanna-ui-game-samples-public:

npm install
npx hst sdk:install
npx hst run web dev browser

Use the repository checks before relying on an example:

npm run lint
npm run build
npm test
npm run roku:game:build

Deploy and follow device logs with:

npm run roku:game:run

The Roku commands require a configured device. The web command runs the same registry through the browser host.

Rendering And Layers

• Sprites And Sprite Pools
• Layers Overview
• Sky Layers
• Direct Parallax Layers
• Surface Parallax Layers
• Parallax Sprite Groups
• Sprite Layers
• Dynamic Tile Layers
• Static Tile Layers
• Cached Chunk Tile Layers
• Particle Layers
• HUD Layers
• Cached Surface Layers
• Custom Layers

Game Systems

• Asset Bundles
• Asset Gates And Bitmap Cache
• Audio Manager
• Game Input
• Controller Pairing
• Controller Pairing Scenes And Presentation
• Collisions
• Particles And Effects
• Text, HUD, And Floating Labels
• Economy, Progression, Drops, And Modifiers
• Items, Inventory, And Persistence
• Settings And Store Fulfillment
• Minimap And Core Utilities
• Telemetry And Debugging
• Performance Covenant

Tiled Worlds

• Tiled Map Requirements
• Tiled Layer Properties
• World Builder And Level Loading
• Entity Bindings, Decor, And Zones
• Tiled Levels And World Builder Overview

Example Walkthroughs

• Vertical Shooter Walkthrough
• Vertical Shooter Quick Reference
• Hosanario Walkthrough
• Diagnostics And Pairing Walkthrough

Current Example Registry

The source of truth is hosanna-ui-game-samples-public/src/hosanna-game-examples/registry.ts.

ID	Demonstrates
vertical-shooter	Canonical Hs2d level scene, Tiled world, pooled combat objects, particles, parallax, upgrades, menu, and pause flow.
police-chase	Single-player and split-screen play, paired-controller role selection, traffic, AI, weapons, and objectives.
hosanario-2	Multi-level platformer, title/level selection, checkpoints, camera, parallax, particles, and pause/settings flow.
hosanaptor	High-density arcade shooter with pooled combat objects, upgrade bay, checkpoints, and persistent settings.
hosanna-blaster	Grid arena, bombs, power-ups, destructible blocks, CPU rivals, and controller presentation.
hosantris-2	Falling-block rules, cached background, audio, and effects.
rampage-city	World composition, parallax skyline, and animated arcade sprites.
mini-golf-2	Cached course rendering, ball physics, moving hazards, course locking, scoring, and particles.
micro-racer	Top-down tile racing, pickups, weapons, ramps, laps, and zoom.
hosanna-run	Pseudo-3D road slices, traffic, scenery, speed HUD, and custom controller presentation.
swing-tennis	Court rendering, directional shots, timing, opponent behavior, and impact effects.
pool	Aiming, power, ball physics, collisions, and table rendering.
sound-rig	Music, SFX, rate controls, and audio stress diagnostics.
diagnostic-particles	Emitter modes, compositor pooling, and particle telemetry.
diagnostic-colliders	Collider shapes, centered sprites, camera zoom, and debug rendering.
controller-rig	Four-player routing, pairing, assignments, and controller-state diagnostics.
diagnostic-text	Direct, cached bitmap, and animated sprite text paths.
h2d-tilemap-static	Bounded cached chunks, camera composition, zoom, and repaint telemetry.
h2d-tilemap-dynamic	Ring-tile scrolling, entering-row/column repaint, zoom, and movement telemetry.