best-practices: Minigames (register into the host) - #7
Conversation
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Pull request overview
Adds a new “Minigames” section to the best-practices guide, documenting the contract for plugins that register a minigame spec into the bundled minigames host (late binding, lifecycle, teardown/cleanup, and reporting results via the SDK).
Changes:
- Documented the minigame host registration flow (pending queue + ready event) and the
spec.start/spec.stoplifecycle expectations. - Added guidance on teardown/resource cleanup, supersede-safe
start, andusesPlayervs standalone behavior. - Renumbered the Shipping section and added a Minigames checklist block; updated the changelog entry under Unreleased.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| spec/best-practices.md | Adds the “Minigames” best-practices section, renumbers Shipping rules, and adds a Minigames checklist block. |
| CHANGELOG.md | Notes the new Minigames best-practices documentation under [Unreleased]. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
3897901 to
675d076
Compare
Add a "Minigames" section to the best-practices guide, ground-truthed against
the bundled minigames plugin — which is a host + SDK, not a game. A minigame is
a plugin that registers a spec into that host; the host mounts/runs/tears down
and scores it.
Rules (21-26):
- Register into the host and bind late: the host loads after your plugin
(alphabetical), so window.feedBackMinigames may not exist at eval — queue via
window.__feedBackMinigamesPending and/or wait for feedBack-minigames-ready.
- Declare a `minigame` manifest block; spec.id MUST equal the plugin id or runs
misattribute and manifest metadata is dropped.
- Implement start({container, modifiers, sdk})/stop(); release in stop()
everything the game opens (rAF, AudioContext, getUserMedia, timers, listeners)
— the host only cancels its own timers/DOM/summary listener.
- Make start supersede-safe (double-tap / navigate-away mid-start races).
- Standalone by default (torn down on any screen change); set usesPlayer only if
the game drives the highway.
- Report results via the SDK — the host owns runs/profile/XP and persists
atomically; use the SDK audio helpers (desktop grabs the wrong device
otherwise); assume a single active session (no splitscreen concurrency).
Renumber the Shipping section to 27-31 and add a Minigames checklist block.
Docs only.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: K. O. A. <topkoa@gmail.com>
- Rule 26: qualify the run-end call as sdk.end(...) (the sdk from start()).
- Rule 21: add { once: true } to the feedBack-minigames-ready listener so it
doesn't linger after firing.
Signed-off-by: K. O. A. <topkoa@gmail.com>
ed41f2c to
ee7d269
Compare
Summary
Adds a Minigames section to the best-practices guide. Ground-truthed against the bundled
minigamesplugin — which turns out to be a host + SDK, not a game: a minigame is a plugin that registers a spec into that host, and the host mounts, runs, tears down, and scores it. The section is the practical contract + the gotchas for building one.Rules (21–26)
window.feedBackMinigamesusually isn't there when yourscriptruns. Queue viawindow.__feedBackMinigamesPendingand/or wait for thefeedBack-minigames-readyevent; registration is idempotent byspec.id.minigamemanifest block;spec.id=== pluginid. Divergence misattributes runs and drops your manifest metadata.start/stop— release instop()everything you open. The host tears you down on navigation mid-run but only cancels its own timers/stage-DOM/summary-listener; your rAF loops,AudioContext,getUserMediastreams, timers, and listeners are yours to release or they leak past the game.startsupersede-safe (double-tap a tile, or navigate away mid-start): synchronous "starting" flag + a start generation re-checked after everyawait.usesPlayeronly if you drive the highway. Minigames share the guitar input, not song playback, and are torn down on any screen change — except ausesPlayergame that intentionally hops to the player.end({score, durationMs, modifiers, meta})); the host owns runs/profile/XP and writes atomically. Use the SDK's audio helpers (a naivegetUserMediagrabs the wrong device on desktop). Assume a single active session — no splitscreen concurrency.Added a Minigames checklist block; Shipping renumbered to 27–31 (contiguous 1–31).
Scope & stacking
Docs only (
spec/best-practices.md+CHANGELOG.md). No version bump. Framed the API names (feedBackMinigames, theminigameblock,spec.start/stop) as the current Host contract, principles as stable — same treatment as the Visualizations section.Stacked on #6. Full stack: #2 → #4 → #3 → #5 → #6 → #7.
mkdocs build --strictandcheck_versions.pypass.🤖 Generated with Claude Code