tilttek / escape-room
Run escape rooms built from chained puzzles: a countdown, hints that cost time, a host console, bookable sessions and a leaderboard by consent.
Requires
- php: >=8.5
- ext-mbstring: *
- phil/resource: ^0.1@dev
- psr/clock: ^1.0
- psr/event-dispatcher: ^1.0
- symfony/clock: ^8.2
- tilttek/puzzle-builder: ^0.1@dev
Requires (Dev)
- phil/reservation: ^0.1@dev
- phpunit/phpunit: ^13.4
Suggests
- phil/reservation: For BookableSessionReservations: the sessions of the rooms booked as intervals of a bookable resource, with its opening hours, notice and booking window
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 03:09:02 UTC
README
Escape rooms on chained puzzles: a countdown, hints counted in the final time, a host console, bookable sessions and a leaderboard by consent.
A room is a scenario of puzzles from tilttek/puzzle-builder, chained or opened in any graph the scenario allows, a
time to escape, and what a hint and a skipped puzzle cost. A team starts the countdown; it guesses, asks for hints, and
escapes when it solves the finale. From the console, the host pushes a hint to the hint screen, types a message, clears
the screen, pauses and resumes the countdown, skips a puzzle for a team that is stuck, or ends the game. Every hint,
asked or pushed, adds its penalty to the final time, never to the countdown: the time played plus the penalties ranks a
team.
Sessions are booked through a port the application implements over its reservations, or through the adapter the
library ships over phil/reservation: a private session for one party, which takes the whole room, or seats of a
shared session, up to the room's largest team. The public leaderboard shows a team only once it agrees, and it may change its mind.
It is a plain PHP library and keeps nothing: each move takes the team's game and gives the game to store after it, and every move of the console is an event, for a bundle that pushes them to the hint screen in real time. The countdown is read from a PSR-20 clock, never kept running. Locks, sensors and props are outside the library; its events and API stay open to them.
Status
| Part | State |
|---|---|
Room: a scenario, its duration, the penalties of a hint and of a skip, the size of a team; chained rooms |
Implemented and tested |
EscapeRooms: start, guesses, hints asked and pushed, skips, puzzles opened, pauses, the hint screen, expiry, abandon, consent, results |
Implemented and tested |
Game, Timer, GameOutcome: the state of a game, written and read back; the countdown and the final time |
Implemented and tested |
Booking\SessionBooker, Booking\Session, Booking\SeatBooking: private and shared sessions |
Implemented and tested |
Contract\SessionReservations, with Store\InMemorySessionReservations |
Implemented and tested |
Reservation\BookableSessionReservations over phil/reservation, its Contract\SeatLedger and Store\InMemorySeatLedger |
Implemented and tested |
Leaderboard, RoomResult, Standing: the public leaderboard, by consent only |
Implemented and tested |
| Events of the game, the console and the bookings, dispatched through PSR-14 | Implemented and tested |
Exceptions under one EscapeRoomException interface |
Implemented and tested |
Documentation
| Document | What it covers |
|---|---|
| Installation | Requirements, installing and wiring. |
| Usage | Rooms, games, the countdown, hints and penalties, the host console, storing a game, results and the leaderboard. |
| Bookings | Private and shared sessions, the port to the reservations, and the adapter over phil/reservation. |
| Accessibility | Showing the countdown, the hint screen and the leaderboard. |
| Drives and safeguards | Where the library stands in Tilttek's grid of drives, and the safeguards it carries. |
| Extension points | The ports, the events of the console, and what a bundle adds. |
| Testing | The library's tests, fuzz target and benchmarks. |
| Reference | Every type of the library, with its role, and its exceptions. |
Quick start
use Phil\Resource\ResourceReference; use Tilttek\EscapeRoom\EscapeRooms; use Tilttek\EscapeRoom\Room; use Tilttek\PuzzleBuilder\Answer\AnswerKey; use Tilttek\PuzzleBuilder\Hint; use Tilttek\PuzzleBuilder\Limiter\InMemoryGuessLimiter; use Tilttek\PuzzleBuilder\Puzzle; use Tilttek\PuzzleBuilder\PuzzleEngine; $room = Room::chain('crypt', 'The crypt', [ new Puzzle('candle', 'The candle', new AnswerKey(['wick']), [new Hint('Look at the top')]), new Puzzle('tomb', 'The tomb', new AnswerKey(['1347'])), ], duration: 3_600, hintPenalty: 120); $rooms = new EscapeRooms(new PuzzleEngine(new InMemoryGuessLimiter(10, 60), $eventDispatcher), $eventDispatcher); $host = ResourceReference::of('member', '3'); $game = $rooms->start($room, ResourceReference::of('team', 'owls')); $game = $rooms->pushHint($room, $game, 'candle', $host)->game; // on the hint screen, 2 minutes added $game = $rooms->guess($room, $game, 'candle', 'Wick')->game; $game = $rooms->guess($room, $game, 'tomb', '1347')->game; // escaped $rooms->timer($room, $game)->final(); // the time played plus 120 seconds $game->toArray(); // to store
Requirements
PHP 8.5 or later with mbstring, tilttek/puzzle-builder 0.1, phil/resource 0.1, psr/clock,
psr/event-dispatcher and symfony/clock.
Contributing
Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.
License
MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Tilttek project. See LICENSE.