Lumenfall

Lumenfall is an original, offline, single-player 2D top-down survivor-like for desktop browsers. You play the Lantern Warden in the drowned Pelagic Orrery, choose one of four starting instruments, assemble a three-weapon build with mutually exclusive evolutions, survive two elite threats, and defeat the Hollow Astronomer in a six-minute run.

Play the public demo: rhdqngo.github.io/lumenfall

Run locally

Requirements: Node.js 22.12 or newer and npm.

npm install
npm run dev

Open the local URL printed by Vite. The minimum supported viewport is 1024×576; 1280×720 or larger is recommended.

Production build:

npm run build
npm run preview

The distributable static build is written to dist/.

Controls

Action	Keyboard / mouse	Gamepad
Move	WASD or arrow keys	Left stick or D-pad
Pause / resume	Escape or P	Start
Navigate menus	Arrow keys or mouse	D-pad / left stick
Confirm	Enter or click	South / A button
Back / resume / invalid-choice feedback	Escape	East / B button
Audio mix	Master/Music/SFX ranges on title or pause	Menu navigation
Motion preference	Motion control on title or pause	Menu navigation

Attacks fire automatically. Move to evade telegraphs and collect dropped Lumen and healing ampoules.

Run structure

• Target clear time: 05:35–06:15; boss at 05:00, enrage at 05:50, hard end at 06:20.
• Regular enemies: Siltling chasers, Glass Moth ranged attackers, and armored Tide Husks.
• Elites: Bellwarden shockwave caster and Rift Skater dash attacker.
• Final boss: the Hollow Astronomer, arriving at 05:00 for a one-minute finale.
• Weapons: Dawncoil, Tideglass Needle, Gloam Bell, and Starward Prism.
• Growth: three weapon slots, unified unlock/weapon/passive/evolution definitions, and eight mutually exclusive weapon evolutions gated by elite materials.
• Outcomes: victory and defeat ledgers with immediate restart or return to title.

Validation

npm test

The release matrix contains 16 Vitest contract checks and 16 Playwright browser scenarios. Coverage includes starting-weapon selection, evolution and stable rack nodes, complete mouse/keyboard/emulated-gamepad victory/defeat/restart flows, three boss phases and safe tells, persistent settings, controller recovery, 1024×576/1280×720/1600×900, 125% zoom, 130% long copy, critical/optional asset recovery, OS reduced motion, natural encounter captures, a 30-second mixed 120-enemy stress case, and relative production serving under /lumenfall/.

Useful focused commands:

npm run test:unit
npm run test:e2e
npm run test:e2e:headed
npm run test:subdir
npm run test:playthrough

The Pages workflow runs all deterministic browser scenarios on GitHub's software-rendered runner. Three real-time pacing gates—the boss damage cadence, natural no-input defeat window, and 120-enemy hardware frame budget—remain in the full local suite and are explicitly skipped in CI because hosted-runner frame timing is not representative of the release machine.

test:playthrough runs eight production-config attempts and may take roughly 25 minutes. The retained result is docs/playtest-v2.json: four wins from eight attempts, boss kills at 05:45.7–06:00.9, and a highest aggregate weapon share of 56.25%. Performance evidence is retained in docs/ui/performance-v2.json; high-volume rendered QA evidence and internal UI working documents remain local to the project and are not published in this repository.

Architecture

• TypeScript 6, Vite 8, Phaser 3.90.
• GameScene coordinates Phaser entities and system calls; WeaponSystem owns weapon runtime/cooldowns/evolution behavior and BossCombatSystem owns boss attack state/telegraphs, while encounter commands, build definitions, arena art, combat effects, settings storage, RNG, audio, and semantic UI live in focused modules.
• Semantic DOM overlays provide the title, HUD, level-up register, pause menu, boss instrument, and results.
• Web Audio synthesizes explore, pressure, and boss layers plus weapon-specific and rate-limited aggregate cues; the project has no downloaded audio files.
• The OS prefers-reduced-motion setting initializes the game preference; synchronized title/pause controls can change it during the session. Reduced mode suppresses camera shake/flash and substitutes stationary, lower-count canvas feedback as well as shortening DOM motion.
• Production artwork is loaded from public/assets/; high-resolution generated masters are retained locally and are not published in this repository.

Art and licensing notes

The setting, names, characters, UI, and visual direction are original to Lumenfall. Included raster art was generated specifically for this project with OpenAI image generation, then locally chroma-keyed, cropped, resized, and inspected. No third-party asset pack, copied game IP, downloaded music, or downloaded sound effect is bundled. See assets/README.md for provenance and processing details. Use and distribution of generated outputs remain subject to the terms applicable to the owner's OpenAI account.

No open-source license is granted for this repository. The source is publicly viewable as part of the Lumenfall demo; all rights are reserved unless the owner gives separate permission.