# GLOWFALL design wiki

The design bible for GLOWFALL. Every page links to the ideas it depends on, so you can start
anywhere and follow the links. When a design decision changes, change it **on the page that owns
it** and let the links carry it everywhere else. Don't copy numbers between pages.

> **One-line pitch:** *Contra* on a bioluminescent jungle moon. Up to four blue-skinned hunters
> fight a mining corporation through eleven stages of giant trees, floating mountains and
> glowing reefs, on foot, on six-legged horses and on dragonback.

> **Resuming work?** Start at [STATUS](STATUS.md): what is done, what is in flight, and what comes next.

## Map of the wiki

### Direction
- [Vision & pillars](vision.md): what we're making, what we're *not* making, the IP stance
- [Roadmap & phases](roadmap.md): Phase 0 → Phase 7, with exit criteria
- [Open questions](open-questions.md): decisions waiting on a human
- [Glossary](glossary.md): every in-world name and what inspired it

### World
- [The world of Veyra](lore/world.md): the moon, its biomes, its day and night
- [Factions](lore/factions.md): the Aeli clans and the Helix Extraction Consortium
- [Heroes](lore/heroes.md): the four playable hunters
- [Story](lore/story.md): the campaign arc, stage by stage, and the endings

### Game design
- [Core gameplay](design/core-gameplay.md): controls, movement, aiming, dying, lives
- [Weapons](design/weapons.md): the bow, the salvage guns, the Weave gifts
- [Perspectives](design/perspectives.md): side-scroll, vertical, 3/4 overhead, ride, flight, swim
- [Mounts](design/mounts.md): loper, skywing, wavewing, glidefin, Stormcrown
- [Day, night & bioluminescence](design/day-night.md): the glow system
- [Co-op](design/coop.md): four players, one camera, shared fate
- [Scoring & difficulty](design/scoring-difficulty.md): points, extends, loops, the code
- [Equipment & vehicles](design/gear.md): hijack Striders and Skids, Aeli tools, door guns
- [Acts](design/acts.md): the 44 acts, in-world title cards, per-act tallies, act select
- [**Stage quality bar**](design/stage-quality-bar.md): the checklist every stage is scrutinised against

### Bestiary
- [Wildlife](bestiary/wildlife.md): the living world; hazards, allies, the collared
- [Consortium forces](bestiary/consortium.md): troopers, Striders, gunships, machines
- [Bosses](bestiary/bosses.md): every mid-boss and boss, with attack phases

### Stages
- [Stage overview](stages/index.md): the eleven-stage table, pacing curve, and palette arc
- [1 Rootfall](stages/01-rootfall.md) · [2 The Wire](stages/02-the-wire.md) ·
  [3 Glowwood](stages/03-glowwood.md) · [4 The Elder Bough](stages/04-elder-bough.md) ·
  [5 Thunder Plains](stages/05-thunder-plains.md) · [6 The Hanging Isles](stages/06-hanging-isles.md) ·
  [7 Skywing Squadron](stages/07-skywing-squadron.md) · [8 Seirran Reef](stages/08-seirran-reef.md) ·
  [9 The Levite Pit](stages/09-levite-pit.md) · [10 Ironhold](stages/10-ironhold.md) ·
  [11 The Whisper Willow](stages/11-whisper-willow.md)

### Art
- [Style guide](art/style-guide.md): resolution, pixel rules, the "NES-plus" contract
- [Palettes](art/palettes.md): the Veyra-64 master palette, sub-palettes, day/night swaps
- [Sprite pipeline](art/sprite-pipeline.md): text-grid sources → PNG sheets + atlas
- [Sprite manifest](art/sprite-manifest.md): every sheet, every animation, every frame count
- [Backgrounds & parallax](art/backgrounds.md): the 12–16-layer depth stacks, raster effects, postcard moments
- [Animation bible](art/animation.md): key poses, timing, physics chains, hit-stop, unique deaths

### Audio
- [Audio engine](audio/engine.md): ChipTune v2, an NES-style evolution of the house sequencer
- [Soundtrack](audio/soundtrack.md): every track, key, tempo, motif; day and night versions
- [Sound effects](audio/sfx.md): the full SFX list with synthesis recipes

### Technology
- [Architecture](tech/architecture.md): client engine, shared simulation, module map
- [Netcode & expedition server](tech/netcode.md): how Drift's server becomes a 4-player co-op host
- [Wire protocol](tech/protocol.md): message table
- [Level format](tech/level-format.md): how stages are authored and validated
- [Deploy & ops](tech/deploy.md): systemd, nginx, installer, AGENT.md
- [Testing](tech/testing.md): smoke tests, determinism checks, playtest scripts
- [**Engineering standards**](tech/engineering-standards.md): code limits, determinism, security, testing, and the rules agents must follow (enforced by hooks)
- [Decision records (ADRs)](tech/decisions/README.md): numbered architecture and tooling decisions
- [Plan review, Sept 2026](tech/plan-review-2026-09.md): pre-code scrutiny; blockers to clear before Phase 1

## Conventions for this wiki
- Links are relative markdown links, so they work on GitHub, in VS Code preview and in any
  markdown viewer. (A tiny in-game `wiki.html` viewer is on the [roadmap](roadmap.md).)
- Each page starts with a one-paragraph **summary**, then **See also** links, then the body.
- Numbers such as speeds, HP and timings are *initial tuning values*. The page that owns a number
  says so, and playtests change it there.
- `TODO:` marks something unresolved; [open-questions](open-questions.md) collects the big ones.