# Blockhaven
The `Blockhaven` module defines the core constants and rules for the game world, including its color palette, city layout, outfit prices, and obstacle course parameters. It is read by every other module in the game to ensure consistency across the city, shop, and HUD, and is not meant to be modified by them.
# coins
The `coins` module manages all collectible coins scattered throughout the Blockhaven world. It uses the `pickupsKit` for pickup mechanics, making coins spin, pop on collection, respawn after a delay, and handle simultaneous grabs. It also sets up the coin counter HUD. Other modules call it to populate the game world with interactive currency.
# screen
Blockhaven's two screens, authored as widget trees:
- **the title** — BLOCKHAVEN in chunky block lettering (one styled label per
letter, so the word cascades in) over the jumping toy avatar and a shower of
gold coins, with the tagline pill and one gold PLAY button over the live city;
- **the HUD** — the coin count from the pickupsKit ledger and the three outfits
of FITZ & CO., each with its price until it is bought and a tick after.
`game/screen.module` builds the trees and nothing else:
`Screen.titleTree({ W, H })` and `Screen.hudTree({ W, H, coins, delta,
ownedCount, owned, outfits })`. Every size is worked out from the width the UI
lays out on, so the same tree reads at a desktop window and at a phone-sized
one.
`Screen.build(env)` is what `scenes/main.scene/build.luau` calls. It spawns the
`ScreenHost` entity and attaches `game.ScreenHost`, the component that
registers both screens, polls the ledger and the wardrobe, and answers the PLAY
callback — so the engine takes the screens down with that entity.
Coin counts come from `require("pickupsKit.api").get(player, "coins")`. Outfits
owned come from `require("game.avatar")`: the ids found in its `worn` table,
plus every id that went through its `apply(player, id)` call — which this
component wraps so a purchase shows on the HUD the moment it happens.
# shop
The `shop` module constructs the "FITZ & CO." outfit shop located in Blockhaven's plaza. It builds the storefront, including its yellow facade, striped awning, and open glass entrance. Inside, it places mannequins displaying the unlockable outfits, each priced according to the `Blockhaven` module's outfit list. Other modules call it to generate the physical shop environment.
# city
The `city` module constructs the main environment of Blockhaven, including its streets, houses, trees, plaza, and clock tower. It provides a `build` function that spawns and positions these entities, creating a walkable city with detailed structures like houses with open interiors and windows. Other modules call it to generate the game's physical world.
# audio
The `audio` module is responsible for managing all sound effects and music within the Blockhaven game. It provides a `build` function that spawns an `AudioHost` entity, which serves as the central point for attaching and controlling audio components in the scene. Other modules call it to set up the game's sound environment.
# course
The `course` module builds the obstacle course that floats above Blockhaven's plaza. It constructs a series of stepping platforms, support columns, and a checkered finish deck with a flag, all tuned for the player's jump mechanics. Each platform also carries a coin as a reward for climbing. Other modules call it to generate the game's challenge area.
# avatar
The `avatar` module manages the player's appearance, including their body structure and outfits. It provides functions to compose the blocky avatar on a given player entity and to apply different outfits based on their IDs. Other game modules call `apply` to change a player's look, and `outfitOf` to query what a player is currently wearing.
# game.ScreenHost
Blockhaven's screens in play: the title screen until the player presses PLAY,
then the in-play HUD.
Attach it to one entity (the scene's `ScreenHost`) with no settings:
```lua
host.component.add("game.ScreenHost", {})
```
It registers the two screens `game/screen.module` authors, on layers 600 (the
title) and 40 (the HUD), and swaps between them on the PLAY callback. The
screens belong to this component's instance, so they go when the entity does.
The HUD shows the coins the pickupsKit ledger holds for this peer
(`require("pickupsKit.api").get(player, "coins")`) and the three outfits of
`game.Blockhaven.OUTFITS`, each with its price until it is owned. Ownership is
read from `game/avatar`: the ids in its `worn` table, plus every id passed to
its `apply(player, id)`, which this component wraps.
Siblings it expects: the pickupsKit ledger (its `PickupHUD` is hidden while
this HUD is up, so there is one coin counter in the corner, not two) and
`game/avatar` for the wardrobe.