How importantseal/homebrew works
1. Project shape
- This is a browser-only game with a static index.html, modular ES modules, and no runtime backend.
- The main runtime layers are: content/data, game logic, controller, and UI.
2. App entry and startup
- js/app.js is the top-level entry point.
- It validates configured action/effect codes before gameplay starts, then hands off to the setup flow.
- js/setup.js creates players and starts the game controller.
3. Canonical game data
- js/gameData.js is the source of truth for cards, items, penalties, actions, and effects.
- The repo strongly prefers structured fields on cards over text parsing, which keeps card resolution deterministic.
- js/logic/cardSchema.js and js/logic/penaltySchema.js define the shape of those objects.
4. Runtime state boundary
- js/state.js owns the mutable runtime state and reset behavior.
- This is the central state object that the controller, UI, and logic modules read from and update.
- js/navigationGuard.js helps prevent accidental navigation away from an active game.
5. Core game logic
- js/logic/ contains the rule engine: deck behavior, effects, penalties, item logic, randomization, and flow state.
- deck.js, effects.js, penalty.js, items.js, and objectCardCycle.js model the rule primitives.
- flowMachine.js plus flowMachine.state.js, flowMachine.transitions.js, flowMachine.selectors.js, and flowMachine.constants.js manage multi-step interaction state for card resolution.
6. Game controller orchestration
- js/game/controller.js is the main orchestrator for each turn.
- It deals cards, reacts to player input, updates state, and routes the current card into the correct resolution path.
- js/game/controller/helpers.js, effectsPanel.js, itemsController.js, and playerRemoval.js are focused controller-side support modules.
7. Card resolution is split into small flows
- js/game/controller/cardHandlers.js dispatches card clicks into specialized flows.
- The flow modules separate the major outcomes:
- plainCardFlow.js
- objectCardFlow.js
- choiceFlow.js
- penaltyFlow.js
- penaltyFlowGroupQueue.js
- penaltyFlowShare.js
- guards.js protects invalid transitions, so card interactions stay legal across modal steps and turn changes.
8. Special actions and effect registries
- The specialActionRegistry.*.js files organize handlers by category: choice, effects, item, penalty, shared, simple, targeted, and general handlers.
- specialActions.js and specialActionSupport.js provide shared execution logic for action/effect-driven cards.
- This creates a clear boundary between card data and how that card actually behaves.
9. UI layer and modal-driven interaction
- js/ui/ is the rendering and interaction layer.
- It includes dedicated components for cards, modals, dice, effects selection, items board, rules, settings, stats, timer, spin wheel, turn order, and background effects.
- uiFacade.js acts as the UI integration point the controller can call without touching low-level DOM details directly.
- CSS is similarly split by concern: layout, cards, modals, effects, history, responsive, etc.
10. Feedback, history, and stats
- js/cardHistory.js, js/stats.js, and js/statsLeaderboard.js record gameplay outcomes and leaderboard-related data.
- These feed the history/stats UI surfaces and support longer-running game progression across turns.
- Sounds and visual effects live in sounds/, images/, and UI effect modules like animations.js and dvdBouncer.js.
11. Testing and verification
- Tests are Node-based (node:test) and live in tests/.
- tests/domHarness.js provides a lightweight DOM environment for UI-heavy tests.
- The repo also includes repo-level verification scripts: linting, type checking of game-data contracts, import/asset verification, and test execution.
12. Developer card injection path
- js/dev/testCard.js and related dev helpers let the game force a specific card or subcard for manual testing.
- This is a deliberate debug boundary: it bypasses normal deck randomness so one card flow can be exercised repeatedly.
13. Main data flow to diagram
- The clearest runtime path is:
- gameData defines cards and actions
- setup creates players
- state holds the live game
- controller deals turns and routes interactions
- logic/flowMachine and cardHandlers resolve the chosen card
- ui presents modals, choices, and feedback
- stats/history record the result
- That separation is the key architectural pattern in this repo.
Main entry points: controller.js Controller · uiFacade.js UI facade · cardHandlers.js Card handlers · specialActions.js Special actions
Components 23
Bootstrap & data
Entry point, setup, canonical card data, and schema boundaries.
- App · Browser entry point that validates configuration and starts the game.
js/app.js - Setup · Creates players and hands off into the controller.
js/setup.js - Game data · Source of truth for cards, items, penalties, actions, and effects.
js/gameData.js - Card schema · Defines the structured card shape used by the engine.
js/logic/cardSchema.js - Penalty schema · Defines the structured penalty shape used by the engine.
js/logic/penaltySchema.js - Test card · Forces a specific card or subcard for deterministic manual testing.
js/dev/testCard.js
Game logic
Mutable state and rule-engine modules that resolve gameplay.
- State · Central mutable game state and reset behavior.
js/state.js - Nav guard · Prevents accidental navigation away from an active game.
js/navigationGuard.js - Deck · Deck and draw behavior for gameplay flow.
js/logic/deck.js - Effects · Effect resolution and effect-driven game behavior.
js/logic/effects.js - Items · Item logic and item-driven interactions.
js/logic/items.js - Penalties · Penalty resolution and shared penalty behavior.
js/logic/penalty.js - Flow machine · Multi-step interaction state for card resolution.
js/logic/flowMachine.js - Special actions · Runs structured action and effect handlers separate from card data.
js/game/controller/specialActions.js
Orchestration
Turn controller and card-resolution routing.
- Controller · Main per-turn orchestrator that deals cards and routes resolution.
js/game/controller.js - Card handlers · Dispatches card clicks into specialized resolution flows.
js/game/controller/cardHandlers.js
UI & feedback
Rendering, interaction surfaces, history, and stats.
- UI facade · Integration point for controller-driven UI updates.
js/ui/uiFacade.js - Cards UI · Card rendering and card-centric interaction surfaces.
js/ui/cards.js - Card modal · Primary modal used for card choices and resolution steps.
js/ui/cardActionModal.js - Effect picker · UI for selecting effects during gameplay.
js/ui/effectSelectionUi.js - History · Records gameplay outcomes and turn history.
js/cardHistory.js - Stats · Tracks game stats across play sessions.
js/stats.js - Leaderboard · Aggregates leaderboard-oriented stats.
js/statsLeaderboard.js
Connections 29
- App → Game data: validate · App checks configured action/effect codes before play starts.
- App → Setup: start · App hands off startup to setup.
- Setup → State: init · Setup seeds the live game state.
- Setup → Controller: launch · Setup starts the game controller.
- Game data → Card schema: conforms to · Game data uses the canonical card schema.
- Game data → Penalty schema: conforms to · Penalty data follows the penalty schema.
- Test card → Game data: override · Dev injection can bypass normal deck selection.
- Controller → State: read/write · Controller coordinates the authoritative runtime state.
- Controller → Deck: deal · Controller draws and distributes cards.
- Controller → Card handlers: route · Controller delegates card interactions to the handler router.
- Controller → Special actions: execute · Controller runs action/effect-driven behavior.
- Controller → UI facade: render · Controller updates the UI through the facade.
- Controller → History: record · Controller logs outcomes to history.
- Controller → Stats: update · Controller feeds gameplay stats.
- Controller → Nav guard: protect · Controller participates in active-game navigation protection.
- Card handlers → Flow machine: advance · Handlers drive the multi-step resolution machine.
- Card handlers → Effects: apply · Handlers invoke effect-specific logic when needed.
- Card handlers → Penalties: resolve · Handlers route penalty outcomes into penalty logic.
- Card handlers → Items: use · Handlers coordinate item-triggered flows.
- Flow machine → State: track · Flow machine stores interaction state in the runtime boundary.
- Special actions → Effects: dispatch · Special actions fan out into effect behavior.
- Special actions → Items: dispatch · Special actions can trigger item behavior.
- Special actions → Penalties: dispatch · Special actions can trigger penalty behavior.
- UI facade → Cards UI: compose · Facade coordinates card rendering.
- UI facade → Card modal: open · Facade opens modal-driven card interactions.
- UI facade → Effect picker: choose · Facade surfaces effect selection UI.
- UI facade → History: show · Facade feeds history displays.
- UI facade → Stats: show · Facade feeds stats displays.
- Stats → Leaderboard: aggregate · Stats flow into leaderboard summaries.