Lantern Run: a Halloween roguelike built with Kiro

Written for Kiroween 2026, Lantern Run is a compact browser-based roguelike game. You assume the role of a pumpkin-shaped lantern, wielding a torch as you navigate four rooms. The torch gradually burns out, while ghosts gradually siphon its energy. Candy restores the torch's power. To finish each room, you must amass the required candy and venture to the exit.

Following the first three rooms, you have the option to select one enhancement. The fourth and final room faces the Pumpkin King. Experience it here: https://hyy12345678.github.io/lantern-run/ View the code on GitHub: https://github.com/hyy12345678/lantern-run A jack-o-lantern serves as the protagonist, already embodying a small, flickering light in the darkness.

This concept finds resonance in the game's mechanics, which emphasize preserving that light rather than engaging in combat. Roguelikes fit this theme perfectly: each session is brief, the rules are uncomplicated, and every decision significantly impacts the unfolding narrative. Kiro, an open-source framework, played a pivotal role in the development process.

Leveraging Kiro's specification, steering, and hook features, I managed all aspects of the project within the .kiro/ directory of the repository. The requirements are documented in specs/requirements.md, with 13 distinct categories and clear acceptance criteria. The architectural design is outlined in design.md, detailing modules, data structures, tuning parameters, and a comprehensive test plan.

The task management system is tracked in tasks.md. Upon transitioning from a three-night structure to a roguelike framework, I meticulously updated all three core files, subsequently reconstructing the task list to accommodate the new game architecture. Steering, a fundamental component, consists of three separate files: one delineating scope constraints, another addressing code guidelines (for instance, prohibiting direct imports from Phaser), and a third file governing visual elements and motion limits.

Hooks, another integral part, automate crucial tasks such as TypeScript validation upon saving each .ts file and executing the test suite after each specification task. Rigorous property-based testing using fast-check ensures the core game mechanics adhere to predefined rules: the torch remains within boundaries, levels remain deterministic given a specific seed, and the blow ability only affects ghosts within its designated radius.

The core game logic resides in src/core/, completely independent of Phaser, enabling seamless testing with Vitest and fast-check in a browser environment. Levels are generated through a seeded random algorithm, guaranteeing identical maps for identical seeds. The generator meticulously crafts a guaranteed path from the starting point to the exit while ensuring all candies and ghosts remain within reach, thanks to breadth-first search optimization.

Every element visible on the screen is meticulously crafted through code, with no reliance on image or audio assets. Sound effects are synthesized using the Web Audio API. The project's success can be attributed to the use of well-defined specifications, steering guidelines, and automated hooks, which streamlined development and minimized manual oversight.

Property-based tests proved invaluable in identifying edge cases that conventional unit tests might overlook, such as boundary conditions in the flame mechanics. However, the roguelike adaptation posed unique challenges. Transitioning the project's structure and revamping the task management files required significant effort. While automated tests confirm the fidelity of the game rules, they do not guarantee an enjoyable gaming experience.

Balancing the game elements through manual playtesting remains essential to ensure an engaging and fair gameplay loop. I invite you to play a session of Lantern Run and share your feedback. Specifically, I am keen to hear your thoughts on whether the available upgrades provide meaningful progression and whether the final boss room presents an appropriately challenging obstacle.

Your insights will greatly contribute to refining the game for future iterations. Thank you for your engagement, and I wish you a delightful Kiroween celebration!