Skip to content

tilttek/escape-room-bundle

✅ published

Escape rooms for a Symfony application: the host's console, the hint screen in real time, bookable sessions, and a public leaderboard by the team's consent.

tilttek/escape-room-bundle integrates tilttek/escape-room with Symfony. The rooms — their scenario of puzzles, time, penalties and team sizes — are written in the configuration, or given by the application's own catalog. Each game is kept in Doctrine DBAL as the plain values the library writes, in UTC, with the moment its countdown reaches zero; the results of the teams that escaped and what the hint screen shows are kept beside it, in five tables the bundle adds to the schema the ORM generates. GameDesk plays each move by the game's identifier: it reads the game, moves it, writes it back, records the result of an escape, and tells the screens.

The host drives a game from a console — push a hint, skip a puzzle, send a message, clear the screen, pause, resume, end the game —, each form working without a script and sent in the background by a Stimulus controller. The hint screen in the room shows the countdown, the hint or the message, and celebrates an escape with the Celebration of the PHIL UX kit; it hears of each move through Mercure when a hub is there, or reads the game again at intervals. A schedule for Symfony Scheduler ends the games whose countdown reached zero, once each. The sessions are booked on phil/reservation when it is installed, under one lock per session in the database. The public leaderboard shows a team only once it agrees, and it may change its mind; a member's games, results, screens and bookings are exported and pseudonymised with their account through phil/privacy-bundle.

It is for a Symfony application that runs escape rooms, in a venue or online. The library alone suits an application without Symfony.

It requires tilttek/escape-room, Doctrine DBAL, Twig and Symfony's container, HTTP kernel, routing and CSRF; the ORM, the console, Symfony Scheduler, Mercure, the rate limiter, Twig components, phil/reservation and phil/privacy-bundle are optional, and the bundle registers what uses them only when they are installed.

Status

PartState
Configuration of the rooms, the stores, the access and the integrationsImplemented and tested
GameDesk: the moves of a game by its identifier, the results, the hint screen, the expiries, the leaderboardImplemented and tested
DbalGameStore, DbalResultStore, DbalScreenStore, DbalSeatLedger and the five tables, with the schema listenerImplemented and tested
The memory stores for tests, reset between two requests of a workerImplemented and tested
The reservations on phil/reservation, wired when it is installedImplemented and tested
The schedule tilttek_escape_room on Symfony Scheduler and the command tilttek:escape-room:expireImplemented and tested
The console and the hint screen, built of the kit's recipes, with their Stimulus controllersImplemented and tested
The moves told through Mercure, the hub detectedImplemented and tested
The consent and the public leaderboardImplemented and tested
Export and erasure of a member for phil/privacy-bundleImplemented and tested
A Flex recipePrepared in recipe/0.1

Documentation

DocumentWhat it covers
InstallationRequirements, installing, the routes, the tables and the access.
ConfigurationEvery option, with an example.
GamesGameDesk: starting a game, its moves, the results and the leaderboard.
ScreensThe console, the hint screen, the consent and the leaderboard pages; their controllers and events.
Real timeMercure, the topics, and the screens without a hub.
BookingsThe reservations of the sessions on phil/reservation, or the application's.
SchedulingThe schedule and the command that end the games whose countdown reached zero.
DatabaseThe five tables and what each column holds.
AccessibilityWhat the screens do for every player.
PrivacyWhat is exported and pseudonymised for a member.
Extension pointsWhat an application replaces.
ReferenceThe classes, services, routes and exceptions.
TestingThe bundle's tests, and testing an application.

Quick start

# config/packages/tilttek_escape_room.yaml
tilttek_escape_room:
    access: App\EscapeRoom\Access
    rooms:
        cell:
            title: The cell
            duration: 1800
            scenario: { id: cell, finale: door, puzzles: [{ id: door, title: The door, answers: [key], hints: [{ text: Under the bed }] }] }
    schedule: { enabled: true }
$desk->start('g-01J8', 'cell', ResourceReference::of('team', 'owls'));
// The host opens /escape-room/console/g-01J8; the room shows /escape-room/screen/g-01J8.

Requirements

PHP 8.5 or later, Symfony 8.2, Doctrine DBAL 4.5.

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.