Twistris is a browser-based falling-block puzzle game built around the Pulse, a central mass that the player expands and stabilizes. Tetrominoes attach to the existing structure, the settled stack may twist when it becomes imbalanced, and there are no line clears.
This repository is focused on a public demo: reveal the damaged Pulse, teach the puzzle and crafting loops, repair the Gravity Module, recover one firewall sector from Bugs, and unlock a replayable Endless Feed mode with a small upgrade set.
The intended game is one continuous motherboard world. Puzzle play, the Pulse hub, Craft, Board, harvest, and repair are connected camera views and interaction modes centered on the Pulse rather than separate screens.
Active demo prototype. The playable Phaser runtime at /next/ now carries the first progression loop and one bounded Board view: puzzle play banks a harvest, the Pulse fabricates the first Bit, that Bit repairs the Gravity Module, and Board mode pulls the same World scene outward to the broken firewall and single Bug-held demo sector. The first-sector state is derived outside Phaser. Once discovered, the nearby sector remains mounted so its northbound copper trace stays visible from Pulse-home, and Board mode reveals the rest through camera movement rather than loading a separate area. Desktop drag and wheel input plus touch drag and pinch input navigate within bounded revealed space. The current Pulse artwork remains provisional and will receive a dedicated damaged-machine redesign later. The trusted legacy route and browser harness remain available for comparison. Missions, firewall recovery, Endless Feed, demo upgrades, and the first-run tutorial are planned but not implemented.
Install the development dependencies once:
npm installStart the local development server:
npm run devOpen the URL printed by Vite. The game now uses browser modules and must be served rather than opened through file://.
npm run dev: start the Vite development servernpm run build: create the production build indist/npm test: run the Vitest unit suitenpm run typecheck: check the TypeScript source
While the legacy controller remains, open /tests/smoke.html through the Vite development server for the full browser characterization harness.
The isolated Phaser proof is available at /proofs/phaser.html. It does not replace or modify the playable game.
The accepted Phaser parity runtime is available at /next/. The legacy / route remains the trusted comparison until its later removal is explicitly approved.
A/Dor arrow keys: moveW,X, or Up: rotate the falling pieceSor Down: soft dropSpace: hard dropP: pauseR: restart
- Build outward from the Pulse and complete larger centered squares.
- Earn Pulse charges when the centered square grows.
- Reach capacity and harvest Pulse charges and Dud salvage.
- Bank resources, fabricate the first Bit, and restore the Gravity Module.
- Inspect the compromised first firewall sector from the continuous Board.
- Demo target: secure one firewall sector and unlock Endless Feed.
- Demo target: earn a small set of optional Endless upgrades.
The tracked project stops at one recovered firewall sector and a replayable Endless mode. The remaining Board stays obscured and the full-game campaign is intentionally unspecified here.
Broader ideas may be developed locally under notes/private/, which is ignored by Git. Nothing from that area is public scope until Katherine explicitly promotes it into the tracked project documents.
The browser is the primary target. The approved architecture keeps one portable web game codebase that can later be packaged for PC, Android, and iOS without forking core gameplay or progression logic.
The current foundation uses TypeScript, Vite, Vitest, and Phaser. Phaser powers the accepted proof and /next/ runtime; application, profile, and economy decisions remain engine-independent, and browser storage, audio, haptics, fullscreen, lifecycle, and achievement capabilities sit behind platform adapters. Playwright remains planned for later browser automation.
- Project Outline: product vision and intended end state
- Plan: current execution path and next implementation slices
- Architecture: current technical map and intended boundaries
- Decisions: major product and architecture decisions
- Agent Guide: instructions for coding agents
- TODO: small loose cleanup tasks only
- Data Formats: current profile contract and provisional future data
- Balance Plan: current twist model and tuning targets
- Testing: browser smoke and manual verification guidance