# Cabin
Assembles alpineProps' baked structure parts (wall sections, corners, windows, doors, gables, roofs, chimney, foundation, porch, bench, woodpile, trough) into a whole mountain hut. The `Cabin` component calls it; call it yourself to place huts from code or to lay out a single part.
```luau
local Cabin = require("alpineProps.Cabin")
local hut = Cabin.build("logHut", { parent = root, position = { 0, 0, 0 }, yaw = 0.4, season = "winter", snow = true, seed = 7 })
hut:destroy()
```
- `Cabin.STYLES`: `logHut`, `stoneHut`, `aFrame`.
- `Cabin.build(style, opts)` builds temporary child entities, each with a box collider, and returns `{ root, style, parts, colliders, destroy }`. Opts: `parent`, `position`, `yaw`, `season`, `look`, `snow`, `seed`.
- `Cabin.layout(style)` is the list of placements `{ kind, v, p, yaw }` in the hut frame; `Cabin.footprint(style)` its size.
- `Cabin.placePart(parent, kind, variant, position, yaw, opts)` places one part with its colliders.
The front (door side) faces local +Z and the origin is the ground at the centre of the footprint.
# BakedStructures
Generated index of every baked hut part and trail prop mesh (`StructureBake.writeIndex()` writes it from `meshes/structures_manifest.json`; do not edit by hand). `StructureCatalog` reads it to hand out parts; nothing else needs to.
- `meshes[name]` is a literal `asset.ref` for each `<kind>_v<variant>_lod<lod>_<materialKey>` mesh under `meshes/structures`, so publishing and installing see every mesh as a dependency.
- `parts["<kind>_v<v>_lod<l>"]` lists the material keys that stem draws, in order (`snow` last, drawn only when snow is on).
- `tris[name]` is the triangle count of each mesh, used by the budget tests and the package README.
```luau
local Baked = require("alpineProps.BakedStructures")
print(Baked.parts["bench_v1_lod0"][1], Baked.tris["bench_v1_lod0_roughTimber"])
```
# AlpineProps
The alpineProps registry: every alpine kind (58 of them: conifers, dead trees, shrubs, grasses, flowers, rocks, cliffs, huts and trail props) is registered here, and through it also in forestProps' `Props`, so forestKit's `ForestRender` draws and collides alpine props the same way it does forest ones. The `AlpineProp`, `Cabin`, `Signpost` and `PropGallery` components and the catalogs call it, and game code calls it to list kinds or get draws.
```luau
local AP = require("alpineProps.AlpineProps")
for _, k in AP.kinds() do print(k, AP.info(k).category) end
local parts = AP.parts("spruce", { age = "veteran", season = "summer", snow = true, lod = 0 }) -- { { mesh, material, part } }
```
- `AP.kinds()` lists every kind in registration order; `AP.kindsOf(category)` those of one category (`tree`, `deadtree`, `log`, `bush`, `grass`, `flower`, `rock`, `cliff`, `structure`).
- `AP.info(kind)` returns the catalog entry: `category`, `variants`, `radius`, `height`, `collider`, `surface`, and for trees `ages` and `byAge`.
- `AP.parts(kind, opts)` returns the draws. Opts are `age`, `season`, `look`, `variant`, `lod` (0-2), `seed` and `snow`; `snow` defaults to `season == "winter"`, and `age = "old"` reads as `"veteran"`.
- `AP.normalize(kind, opts)` returns forestProps-normalised opts plus `snow`. `AP.register(entry, partsFn)` adds or replaces a kind, which is how the catalogs (`ConiferCatalog`, `FloraCatalog`, `RockCatalog`, `StructureCatalog`) plug in; they load on first use.
- `AP.AGES`, `AP.SEASONS` and `AP.LOOKS` hold the accepted values.
# StructureCatalog
Registers alpineProps' 27 hut parts and trail props with `AlpineProps` (and through it forestProps' `Props`), category `structure`. `AlpineProps` loads it on first use; ask `AlpineProps.parts(kind, opts)` for draws and this module only for colliders and triangle counts.
```luau
local AP = require("alpineProps.AlpineProps")
AP.parts("roofShingle", { lod = 0, season = "winter", look = "painted" }) -- snow on the roof
require("alpineProps.StructureCatalog").colliders("lookout") -- every walkable box
```
- Kinds (`SC.KINDS`): logWallSection, logCorner, stoneWallSection, timberWallSection, wallWindow, wallDoor, gableLog, gableStone, gableTimber, roofShingle, roofSlate, aFrameRoof, chimneyStone, porchDeck, stoneFoundation, bench, woodpile, waterTrough, signpost, signArm, waymarkPost, footbridge, summitCross, lookout, trailSteps, fenceRail, infoBoard.
- Each entry carries forestProps' `collider` (one box), `colliders` (every box of a multi-box kind: decks, rails, piers, steps), `variantColliders[v]`, `surface` (`wood` or `stone`) for footsteps and `variantNames`.
- `SC.parts(kind, o, snow)`, `SC.colliders(kind, variant)`, `SC.tris(kind, variant, lod)`.
- Parts come from `BakedStructures`; a part with no bake yet is built at runtime once per session so a kind always draws. Materials come from `alpineMaterials.AlpineMaterials`.
# Signs
Builds a trail signpost with direction arms and readable destinations: the baked `signpost` post (variant 4, post only) plus one baked `signArm` per arm, lettered on both faces with a mesh laid out from the engine's font glyphs (`font.textMesh`, ArimoBold), so each face reads left to right. The `Signpost` component calls it; call it directly for signs with up to six arms or custom heights.
```luau
local Signs = require("alpineProps.Signs")
local sign = Signs.make(parentEntity, { arms = {
{ text = "Bergsee 20 min", yaw = 0 },
{ text = "Gipfelkreuz 2 h", yawDeg = 140 },
{ text = "Parkplatz 1 h", yaw = math.pi, height = 1.9 },
}, season = "winter", snow = true })
sign:destroy()
```
- `Signs.make(parent, opts)`: opts `arms` (`text`, `yaw` radians or `yawDeg`, optional `height`), `season`, `look`, `snow`. Arms stack top down from 2.32 m, 0.22 m apart. Children are temporary.
- `Signs.textMesh(text)`: the cached lettering mesh for one arm.
- `Signs.MAX_ARMS` = 6.
# StructureGen
Procedural geometry for the alpine huts and trail props: one builder per kind writes a `Geometry` per material key for a given variant and level of detail. `StructureBake` bakes its output, `StructureCatalog` registers it and `Cabin` lays it out using `SG.DIM`. Games do not call it at runtime except through the catalog's fallback for an unbaked part.
```luau
local SG = require("alpineProps.StructureGen")
local geos = SG.build("logWallSection", 1, 0) -- { [materialKey] = Geometry }
local boxes = SG.colliders("lookout", 1)
```
- Material keys map to alpineMaterials surfaces through `SG.SURFACE`: logWall, woodShingles, roughTimber, stoneWall, slateRoof, ironWrought, lichenGranite, deadwoodSilver, mountainLake, `paint` (roughTimber with vertex colours for trail paint) and `snow` (snowLoad, only drawn with snow).
- `SG.ORDER` lists every kind; `SG.KINDS[kind].entry` its catalog entry.
- Units are metres, +Y up; wall parts run along local X with the outside at +Z and the base at y = 0, sized on the 0.5 m grid in `SG.DIM`.
# alpineProps
High-mountain props for walkable alpine worlds: 58 kinds, from 30 cm gentians to 34 m veteran spruces, a dry-stone hut and a footbridge. Each one is placed with a single component and comes in three looks (real, painted, toon), all four seasons, and with or without snow. They have three baked levels of detail, colliders where a player needs them, and footstep surfaces. Every kind also registers with forestProps' `Props`, so forestKit's `Forest` / `ForestRender` can scatter and draw them instanced. Materials come from alpineMaterials. Works installed in any world (it finds its own files, wherever it sits).
## Quick start
```luau
-- an old Norway spruce with snow on its branches
entity.spawn("tree").component.add("alpineProps.AlpineProp", { kind = "spruce", age = "veteran", snow = "on" })
-- a winter A-frame hut (door faces the entity's +Z), and a lettered trail sign
entity.spawn("hut").component.add("alpineProps.CabinHut", { style = "aFrame", season = "winter" })
entity.spawn("sign").component.add("alpineProps.Signpost", { arm1 = "Bergsee 20 min", dir1 = 0, arm2 = "Gipfelkreuz 2 h", dir2 = 150 })
-- every kind side by side, in labelled rows
entity.spawn("gallery").component.add("alpineProps.PropGallery", {})
```
From code: `require("alpineProps.AlpineProps")` lists kinds (`kinds()`, `kindsOf("rock")`), describes one (`info(kind)`) and returns its draws (`parts(kind, { age, season, look, variant, lod, snow })` → `{ { mesh, material } }`). `require("alpineProps.Cabin").build(style, opts)` and `require("alpineProps.Signs").make(parent, opts)` place huts and signs.
## Components
| Component | What it places | Key fields |
|---|---|---|
| `AlpineProp` | any one kind | `kind`, `age` (sapling, young, mature, veteran; "old" = veteran), `season`, `look`, `variant`, `seed` (non-zero picks variant and yaw), `detail` (auto, near, mid, far), `collide`, `snow` (auto, on, off) |
| `Cabin` | a whole hut: `logHut`, `stoneHut`, `aFrame` | `style`, `season`, `look`, `snow`, `seed` |
| `Signpost` | a post with up to four lettered arms | `arm1..4` text, `dir1..4` degrees, `season`, `look`, `snow` |
| `PropGallery` | every kind in labelled rows | `sections`, `look`, `summerSeason`, `detail`, `labels`, `gap` |
All of them build temporary children from synced fields, so every player sees the same prop and a reload rebuilds it.
## Kinds
Triangle counts are read from the `Baked*` tables: real look, snow excluded, the range over variants.
### Conifers (category `tree`, four ages)
| Kind | Variants per age | LOD0 sapling | LOD0 young | LOD0 mature | LOD0 veteran | LOD1 mature | LOD2 mature |
|---|---|---|---|---|---|---|---|
| `spruce` | 3 | 1398-1400 | 4996-5000 | 11499 | 19496-19499 | 3447-3449 | 490 |
| `scotsPine` | 3 | 1396-1398 | 5000 | 11496-11500 | 19496-19498 | 2773-2835 | 490 |
| `fir` | 3 | 1396-1400 | 4996-4998 | 11496 | 19500 | 3447-3448 | 490 |
| `larch` | 3 | 1396-1398 | 4996-4998 | 11497-11500 | 19499-19500 | 3446 | 490 |
| `stonePine` | 3 | 1400 | 4998 | 11496 | 19496-19500 | 3444-3446 | 490 |
| `mugoPine` | 3 | 1122-1196 | 2910-3056 | 6616-7262 | 10652-10998 | 1806-1860 | 490 |
Norway spruce, Scots pine, silver fir, European larch (gold in autumn, bare in winter), Swiss stone pine and mugo (dwarf mountain) pine. Sizes run from about 1.4 m saplings to 34 m veterans (mugo: 0.6-3 m).
### Dead and odd trees, shrubs, grasses, flowers
| Kind | Category | Variants | LOD0 | LOD1 | LOD2 |
|---|---|---|---|---|---|
| `deadSpruce` | deadtree | 3 | 3190-3198 | 1020 | 488 |
| `krummholz` | deadtree | 2 | 7304-7996 | 2100-2377 | 489-490 |
| `windbentPine` | deadtree | 2 | 7068-8040 | 1944-2013 | 490 |
| `fallenSpruce` | log | 2 | 1421-1468 | 450-462 | 322-367 |
| `arnica` | flower | 3 | 60 | 12 | - |
| `alpenrose` | bush | 3 | 1444-1636 | 438-510 | 24 |
| `edelweiss` | flower | 3 | 48-84 | 8-16 | - |
| `juniper` | bush | 3 | 1144-1336 | 312-368 | 16 |
| `alpineAster` | flower | 3 | 72-84 | 12-16 | - |
| `greenAlder` | bush | 3 | 2388-2708 | 594-686 | 104-122 |
| `gentian` | flower | 3 | 96-120 | 16-20 | - |
| `dwarfWillow` | bush | 3 | 784-1084 | 282-398 | 14 |
| `saxifrage` | flower | 3 | 102-114 | 20 | - |
| `campanula` | flower | 3 | 60-96 | 12-16 | - |
| `globeflower` | flower | 3 | 54-72 | 12 | - |
| `cottonGrass` | grass | 3 | 156-204 | 36-48 | - |
| `alpineTussock` | grass | 4 | 84-90 | 24-28 | - |
Flowers and grasses have no LOD2 (-): they drop out at distance.
### Rocks and cliffs
| Kind | Category | Variants | LOD0 | LOD1 | LOD2 |
|---|---|---|---|---|---|
| `cliffSpire` | cliff | 3 | 3864-4512 | 988-1112 | 168-196 |
| `cliffFace` | cliff | 3 | 4176-4584 | 980-1112 | 280-292 |
| `graniteBoulder` | rock | 4 | 1440-1944 | 360-456 | 44-96 |
| `rockOutcrop` | rock | 3 | 1368-2280 | 488-556 | 144-148 |
| `screeStone` | rock | 3 | 240-288 | 36-44 | 28-32 |
| `screePatch` | rock | 3 | 2564-2652 | 608-636 | 236-272 |
| `flatSlab` | rock | 3 | 336-1152 | 240-336 | 32-36 |
| `cairn` | rock | 3 | 1852-1984 | 572-872 | 272-292 |
### Trail props
| Kind | Category | Variants | LOD0 | LOD1 | LOD2 |
|---|---|---|---|---|---|
| `bench` | structure | 1 | 168 | 126 | 120 |
| `woodpile` | structure | 1 | 3224 | 2320 | 72 |
| `waterTrough` | structure | 1 | 234 | 137 | 122 |
| `signpost` | structure | 4 | 324-5836 | 86-198 | 16-128 |
| `signArm` | structure | 1 | 64 | 28 | 28 |
| `waymarkPost` | structure | 1 | 260 | 90 | 40 |
| `footbridge` | structure | 1 | 11780 | 3122 | 776 |
| `summitCross` | structure | 1 | 3924 | 1812 | 58 |
| `lookout` | structure | 1 | 1732 | 866 | 722 |
| `trailSteps` | structure | 1 | 840 | 144 | 144 |
| `fenceRail` | structure | 2 | 175-210 | 49-74 | 52-72 |
| `infoBoard` | structure | 1 | 5085 | 391 | 146 |
The footbridge deck, lookout stairs and platform and trail-step treads carry walkable box colliders.
### Hut parts (what `Cabin` assembles; usable alone)
| Kind | Category | Variants | LOD0 | LOD1 | LOD2 |
|---|---|---|---|---|---|
| `logWallSection` | structure | 2 | 756-812 | 132-144 | 12 |
| `logCorner` | structure | 2 | 1306 | 378 | 24 |
| `stoneWallSection` | structure | 3 | 892-1640 | 212-402 | 24 |
| `timberWallSection` | structure | 1 | 144 | 96 | 24 |
| `wallWindow` | structure | 4 | 628-1808 | 364-522 | 124-172 |
| `wallDoor` | structure | 4 | 502-1078 | 228-500 | 128-164 |
| `gableLog` | structure | 1 | 1348 | 248 | 8 |
| `gableStone` | structure | 1 | 2298 | 460 | 16 |
| `gableTimber` | structure | 2 | 492-616 | 492-616 | 10 |
| `roofShingle` | structure | 1 | 7078 | 338 | 60 |
| `roofSlate` | structure | 1 | 3298 | 310 | 60 |
| `aFrameRoof` | structure | 1 | 9970 | 394 | 60 |
| `chimneyStone` | structure | 2 | 218-5700 | 140-1284 | 88-96 |
| `porchDeck` | structure | 5 | 224-488 | 190-262 | 190-262 |
| `stoneFoundation` | structure | 1 | 1068 | 222 | 24 |
Wall parts sit on a 0.5 m grid (`StructureGen.DIM`), run along local X with the outside at +Z.
## Looks, seasons and snow
- **Looks**: `real` (photoreal PBR), `painted` (hand-painted stylised), `toon` (cartoon; conifers swap to dedicated toon needle meshes up close).
- **Seasons**: `spring`, `summer`, `autumn`, `winter`. Larch turns gold in autumn and is bare in winter; grasses go to straw; materials follow alpineMaterials' seasonal variants.
- **Snow**: `snow = "auto"` draws snow loads on branches, roofs, rails and rocks in winter only. Use `"on"` or `"off"` to force it in any season.
## Gallery
`PropGallery.component` lays out every kind: each conifer species at all four ages without and with snow, then dead and odd trees, shrubs, grasses and flowers (as small patches), rocks and cairn, cliffs, the three hut styles, trail props and hut parts. A last row catches any kind added later. `PropGallery.scene` frames it with a meadow ground, a sun and ambient light, a procedural sky and a camera. Check shots: `design/checks/props/gallery_overview.jpg` and `gallery_conifers.jpg` in the Snowline Pass world.
## Known limits
- Flowers are true to scale (10-40 cm), so they read only up close or in drifts; scatter them in numbers.
- Destroying an entity whose AlpineProp parts carry `MeshLod` logs one harmless "component this proxy names was removed" error per part from the engine's MeshLod `onDestroy` (reported upstream). Changing fields to rebuild does not.
- A structure part with no bake falls back to building its mesh at runtime once per session.
- `AlpineProp` places one prop per entity. For forests and boulder fields use forestKit's `Forest`/`ForestRender` (instanced) with these kinds.
- Bakers (`ConiferBake`, `FloraBake`, `StructureBake`) are authoring tools. Re-baking writes hundreds of meshes, so run one kind at a time.
## Tests
`tests/conifers`, `tests/flora` and `tests/structures` (`tools.use("tests", "run", { suite = "conifers" })`) cover registration, every kind × age × season × look × variant × LOD resolving to baked meshes, snow switching, triangle budgets, colliders a player walks on, and the components.