Patch Notes

Patch Notes is a browser-first game prototype workspace built with Vite, TypeScript, Three.js, and a small ECS-based engine. The main playable project is Patch Notes, a game about moving through the inside of a machine while game systems unlock as installable patches.

The workspace currently includes:

• a reusable ECS and Three.js engine package
• a root prototype launcher for older playable slices and tools
• a visual Level Editor for authoring Patch Notes rooms and level JSON
• the final @game/patch-notes game shell with three prototype campaign levels
• 2D side-scroller and 3D top-down modes
• authored upgrades for Jump, Dimension, Sprite Driver, Overclock, and Debugger
• generated 2D sprites, backgrounds, sound effects, and looping music
• player-mode menus, options, credits, fullscreen controls, and debug tooling

Quick Start

Install dependencies:

npm install

Run Patch Notes:

npm run dev --workspace=@game/patch-notes

Open the Vite URL shown in the terminal, usually http://localhost:5174. Debug mode is the default. For the player-facing view, open:

http://localhost:5174/?mode=player

Run the Level Editor:

npm run dev

Then open:

http://localhost:5173/?tool=level-editor

Run the legacy prototype launcher:

npm run dev

Then open the Vite URL shown in the terminal, usually http://localhost:5173.

Repository Layout

.
|-- docs/
|-- packages/
|   |-- engine/
|   |-- game/
|   |-- level-editor/
|   |-- patch-notes/
|   `-- prototypes/
|-- skills/
`-- README.md

• packages/engine contains the reusable ECS core, shared types, systems, and Three.js integration.
• packages/game contains the root launcher, prototype runtime, preview adapters, and the browser entry point used by the Level Editor.
• packages/level-editor contains the current visual authoring tool, schemas, migrations, commands, validation, and editor viewports.
• packages/patch-notes contains the current Patch Notes game shell, authored levels, assets, audio, menus, and release build path.
• packages/prototypes contains legacy playable prototype documents and compiler helpers.
• docs contains engine, game, prototype, and tooling documentation.

Patch Notes

Patch Notes is the current game. The player begins inside a broken boot sequence and installs patch upgrades that change the controls, presentation, and available ways to solve rooms.

Current campaign levels:

• Level 1, Boot Sector - First Compile: introduces Jump, Sprite Driver, Dimension, and Overclock.
• Level 2, Memory Bus - Route Conflict: expands routing with Debugger receivers, enemies, channels, switches, lasers, and patch-station compatibility moments.
• Level 3, Kernel Core - Final Handshake: combines the main mechanics into a shorter finale and closes with a prototype thank-you message.

Useful Patch Notes URLs:

http://localhost:5174
http://localhost:5174/?mode=player
http://localhost:5174/?mode=debug

Debug mode includes development controls for unlocking upgrades, moving between states, and testing local level files. Player mode is the default export-style presentation.

Patch Notes Controls

Core controls:

• WASD or arrow keys: move
• E: interact
• Esc: pause
• / or ?: open controls/help
• mouse wheel: zoom
• backtick: toggle FPS overlay

Patch controls appear after the relevant upgrade is installed:

• Space: Jump
• K: Dimension
• V: Sprite Driver
• Shift: Overclock
• F: Debugger

The in-game Options menu includes music and sound volume controls. Menu music plays on menus and story interstitials, while each campaign level has its own looping track.

Level Editor

The Level Editor creates structured JSON that the Patch Notes runtime can load. Use it for room layout, floor and gap placement, doors, switches, barriers, lasers, moving platforms, enemies, receivers, goals, atmosphere metadata, and asset bindings.

Launch it with:

http://localhost:5173/?tool=level-editor

Typical workflow:

1. Create or select a room.
2. Add floors, blockers, hazards, pickups, and goals.
3. Connect rooms with authored doors.
4. Use channels for switches, receivers, barriers, lasers, and platforms.
5. Export the level JSON.
6. Load that JSON in the Patch Notes debug shell with the local level loader.

See the Level Editor Quickstart for the full authoring guide.

Useful Commands

Build all workspaces:

npm run build

Run all tests:

npm test

Typecheck all workspaces:

npm run typecheck

Patch Notes checks:

npm test --workspace=@game/patch-notes
npm run smoke:level1 --workspace=@game/patch-notes
npm run smoke:campaign --workspace=@game/patch-notes

Create an itch.io browser upload zip:

npm run package:patch-notes:itch

The zip is written to:

output/patch-notes/patch-notes-itch.zip

Level Editor checks:

npm test --workspace=@game/level-editor
npm run typecheck --workspace=@game/level-editor

Docs

• Patch Notes Game Guide
• Patch Notes Design
• Patch Notes Progress
• Level Editor Quickstart
• Level Editor Design
• Level Editor V2 QA Notes
• Tooling Docs Index
• Prototype Docs Index
• Engine Overview

Current Limits

Patch Notes is still a prototype. The current build is good for playtesting, feedback, and editor experimentation, but it does not yet include save slots, keyboard rebinding, desktop packaging, or a fully polished asset pipeline. The Level Editor is also still growing: exported JSON is usable today, while prefab libraries, richer transform gizmos, and production asset browser workflows are future work.