How bbc/genie works
Project type and purpose
• This is a pure-frontend framework (no custom backend) for building modular children’s games.
• The README calls it “BBC Games – Genie,” a library built with JavaScript/Phaser that provides core services (loader, layout, event bus, accessibility, debug) and pluggable UI components (home, how-to-play, game, narrative, select, shop, results).
• It includes build/CI scripts (webpack, Babel, license checker, JSDoc), unit tests (Jest), end-to-end tests (Cypress), theming assets, and developer documentation.
Top-level directories and their roles
• build-scripts: CI/build toolchain (webpack config, docs generator, license/schema validators, theme generator).
• dev: local development server assets and custom CSS, sample HTML files, helper scripts.
• docs: design/development documentation (Markdown, Sketch).
• lib: third-party libraries bundled in (basisu, lodash, polyfills).
• src: the application code itself
• src/core: core framework services (loader, event bus, accessibility, layout, debug, GMI, background, scaler, music).
• src/components: game screens and UI modules (home, how-to-play, narrative, select, shop, results overlays).
• src/main.js: application entry point.
• test: Jest unit tests mirroring src/core and src/components, plus Cypress fixtures/plugins/e2e suites for end-to-end.
• output (not shown but created by build): compiled bundles + stats.html for visualizer.
Key architectural patterns
• Modular component architecture: core services are decoupled from UI screens via an event bus.
• Build pipeline: Babel + webpack bundle source + lib + polyfills + themes into a single distributable.
• Theme-driven design: static JSON asset packs drive graphics and configuration, loaded at runtime by core/loader.
• Test automation: Jest for unit tests, Cypress for integration/e2e against a local or deployed build.
• Documentation pipeline: JSDoc + markdown → docs/api and docs/**/*.md.
Main components
A. Build & CI Layer
• build-scripts (webpack, Babel, schema-validator, license checker, theme generator)
• npm CLI (scripts: start, build, docs, create-theme2, test, cy:local, etc.)
• output folder (bundled JS/CSS, stats.html)
B. Development Server
• dev static files (index.dev.html / index.main.html)
• webpack-dev-server (npm start)
C. Runtime Frontend
1. Entry Point: src/main.js
2. Core Framework Modules (src/core)
• Loader (JSON5, particles, fonts, basisu, media)
• Event bus
• Layout engine (grid, DOM text, sprite/text/tweens wrappers)
• Accessibility layer
• Debug tools (console output, UI overlay)
• GMI (“game measurement interface”)
• State/config parser (parse-url-params, settings, custom-styles)
3. UI Components (src/components)
• Scenes: home, how-to-play, narrative, game, select, shop, results
• Overlays & sub-components (pause, results-rows, scrollable lists, confirm dialogs)
4. Themes & Assets (themes/default, theme2)
• Config JSON → loader → core services
• Media files (images, audio, videos, spine animations)
5. Third-party libs (lib/basisu, lib/lodash, polyfills)
D. Testing & Documentation
• Jest Runner (unit tests under test/)
• Cypress Runner (e2e tests under cypress/)
• JSDoc generator (outputs docs/api)
• Markdown docs (docs/ and dev/docs/)
Relationships and data flow
• Developer invokes npm script → build-scripts spawn webpack → consumes src/, lib/, themes/ → emits output bundle + stats.
• Browser loads index.html → main.js bootstraps core/startup → loader pulls theme JSON + assets → initializes Phaser game instance.
• Event bus glues core services to UI components: screens register event handlers, dispatch user actions, and forward to core/store.
• UI components import core services (layout, accessibility, debug) and present game screens.
• Tests import modules directly (unit) or drive the built output in a headless browser (Cypress).
• JSDoc parses src/core and src/components comments to build API site.
Architectural patterns/design principles
• Separation of concerns: build pipeline, core services, UI components, themes, tests, docs all live in dedicated directories.
• Inversion of Control: UI screens plug into the core event bus and loader services.
• Configuration-driven: runtime behaviour and assets controlled entirely via JSON theme files.
• Extensibility: new components or themes can be added without altering core logic.