Plugin Manifest Contract

The funday-plugin.json serves as the source of truth for platform integration. For games utilizing the Genius Engine, the manifest must be extended with a genius metadata block.

1. Full JSON Schema Example

{
  "id": "genius-example",
  "name": "example-game",
  "version": "1.0.0",
  "schemaVersion": "2.1",
  "integrationType": "iframe-themeable",
  "gameType": "web",
  "entryPoint": "build/index.html",
  "metadata": {
    "title": "Example Game",
    "description": "A demo game utilizing the Genius Engine template.",
    "developer": "Funday Studios",
    "genre": ["Strategy"],
    "minPlayers": 1,
    "maxPlayers": 4
  },
  "backend": {
    "type": "nakama-js",
    "authoritative": {
      "matchHandler": "example_match"
    }
  },
  "leaderboards": {
    "enabled": true,
    "default": "example_highscores"
  },
  "genius": {
    "funStackPath": "docs/fun-stack.md",
    "perspectivesPath": "docs/perspectives.md",
    "coreLoop": "select_character -> battle_round -> score_evaluation -> upgrade",
    "onboardingGates": ["getReady", "first_match_tutorial"]
  }
}

2. Field Glossary (Genius Block)

The genius block enables programmatic scraping and validation by autonomous agents.

funStackPath: Relative path to the game’s Fun Stack definition. Used by reviewers to verify “Juice” and “Core Loops”.
perspectivesPath: Relative path to the perspectives tracker. Used to measure accessibility and UX completion.
coreLoop: A stringified state machine representation of the main game flow.
onboardingGates: An array of explicit gates that block the core loop until satisfied. e.g., ["getReady"] ensures the player clicks a “Start” button before physics unfreeze.

3. Acceptance & Verification

Criteria: The manifest is valid against the platform schema and includes valid Genius pointers.
- Verify: Run the platform’s manifest validation script (scripts/validate-game-manifest.mjs). Ensure that the paths in the genius block actually resolve to markdown files.

4. Rationale & Anti-Patterns

Why the Genius Block?

The standard funday-plugin.json specifies runtime configurations—how the server scales the game or how the client should be built. The genius metadata block specifies semantic and structural configurations so that AI tooling (the Genies) can audit and orchestrate the game correctly.

Common Anti-Patterns

Missing or Invalid Paths: Pointing funStackPath to docs/stack.md when the file is actually docs/fun-stack.md. Why it fails: Automated agents will throw HTTP 404s and fail to complete standard audits.
Too Granular Core Loop: Setting the coreLoop to "click -> pointer_down -> dispatch -> move". Why it fails: The coreLoop string should represent the high-level psychological loop of the game, not a code-level event stack.
Missing Onboarding Gates: Omitting ["getReady"] when the game actually does feature a start gate. Why it fails: Autotesting agents won’t know they need to click a start button before testing the game’s physics loop.

5. Maintenance Best Practices

Validate often: Use node scripts/validate-game-manifest.mjs early and often.
Keep Core Loop Concise: The coreLoop parameter is designed for human and high-level AI context. Keep it under 60 characters.
Match Your Actual Gates: The onboardingGates should map exactly to states in your UI layer (e.g. $state('get-ready')).