HTMLGameKit
It's dangerous to go alone! Take this.
What is it?
HTMLGameKit is a set of custom elements that give you everything you need to build simple browser-based games with nothing but HTML, CSS, and a pinch of JavaScript. It provides a state machine to manage game flow, difficulty directors to control progression, audio systems to handle music and chimes, UI components for overlays, HUDs, timers, and feedback, a scoring system with leaderboards and histograms, and a context protocol so your game components can reactively subscribe to state changes.
Features
State Machine
<game-shell> manages the entire game lifecycle:
init, demo, ready, playing, between rounds, and result. State is
exposed as TC39 Signals, observable by any descendant component.
Difficulty Directors
Three pluggable strategies: Fixed (linear interpolation), Staircase (adaptive psychophysics), and Tier (promote/demote). Configured declaratively in HTML.
Context Protocol
Components subscribe to game state reactively using the Context Community Protocol. No prop drilling. No global state.
UI Components
Overlays, HUD, round counter, timer, feedback flash, result display, share button, quiz engine, and more. All themeable via CSS custom properties.
Scoring & Leaderboards
Built-in scoring with leaderboards, histograms, and anti-cheat
tokens. Defaults to a free hosted server. Pluggable -- point
score-url at your own API.
Audio System
Declarative sound effects and a BPM-ramping sequencer. Three synth types, auto-triggered by game events. No audio files needed.
Zero Dependencies
No React. No build step. No npm install required. Pure ES modules and standard Web Components. Works in any modern browser.
Themeable
Every visual element respects --game-* CSS custom
properties. Dark theme by default. Swap colours to match your game.
Components
| Element | Purpose |
|---|---|
<game-shell> |
Root state machine, context provider, event hub |
[when-some-scene] |
State-driven visibility for any element |
[data-overlay] |
Overlay styling (fixed position, backdrop) |
<game-round-counter> |
Round progress display |
<game-stat> |
Reactive stat display (time, score, etc.) |
<game-timer> |
Countdown progress bar |
<game-toast> |
Trigger-based feedback messages (ephemeral or persistent) |
<game-flash> |
Full-screen pass/fail colour flash |
<game-between when-some-scene="between"> |
Rich between-rounds interstitial |
<game-challenge> |
Challenge mode opponent score |
<game-share> |
Share result button |
<game-score-form> |
Name input + submit to leaderboard |
<game-leaderboard> |
Leaderboard table + histogram |
<game-result-stat> |
Large result score display |
<game-result-message> |
Score-range conditional result messages |
<game-quiz> |
Declarative quiz/trivia from <fieldset> markup |
<game-tile-input> |
Wordle-style tile input with letter tracking |
<game-icon> |
SVG sprite icon from the global sprite sheet |
<game-trophy> |
Achievement with persistent unlock and optional grid |
<game-preferences> |
Popover-based preferences panel |
<game-preference> |
Individual preference (toggle, range) |
<game-audio> |
Auto-triggering sound effect container |
<game-sample> |
Synthesised sound effect definition |
<game-sequencer> |
BPM-ramping music sequencer |
progression attribute |
Declarative difficulty director config |
<game-signal> |
Live value display (score, round, stat, etc.) |
Tutorials
Click Counter
Build a click-target game from scratch. Learn the core loop: shell, state subscription, and round events.
Reaction Time
Build a reaction time game with FixedProgression for variable delays, retry failures, and post-game result logic.
Capital Quiz
Build an adaptive quiz with TierProgression, countdown timer, and the built-in <game-quiz> component. Two lines of JS.
Word Guess
Build a Wordle-style game with tile input, audio, and flash. Showcases <game-tile-input> and declarative sound.
Scoring & Leaderboards
Add online score submission, leaderboards with histograms, and challenge mode. One attribute to enable.