create-eigen-game 0.1.0

package/templates/app-overlay/web/flutter_bootstrap.js.template

@@ -0,0 +1,19 @@
+{{flutter_js}}
+{{flutter_build_config}}
+
+(async () => {
+  if ("serviceWorker" in navigator) {
+    await navigator.serviceWorker
+      .register("firebase-messaging-sw.js", {
+        scope: "/firebase-cloud-messaging-push-scope",
+      })
+      .catch((error) => {
+        console.warn(
+          "Firebase Messaging service worker registration failed",
+          error,
+        );
+      });
+  }
+
+  _flutter.loader.load();
+})();

package/templates/app-overlay/web/index.html.template

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <base href="$FLUTTER_BASE_HREF">
+  <meta charset="UTF-8">
+  <meta content="IE=Edge" http-equiv="X-UA-Compatible">
+  <meta name="description" content="Example Game">
+  <meta name="mobile-web-app-capable" content="yes">
+  <meta name="apple-mobile-web-app-status-bar-style" content="black">
+  <meta name="apple-mobile-web-app-title" content="Example Game">
+  <title>Example Game</title>
+  <link rel="manifest" href="manifest.json">
+</head>
+<body>
+  <script src="flutter_bootstrap.js" async></script>
+</body>
+</html>

package/templates/project/README.md

@@ -0,0 +1,104 @@
+# Example Game
+
+This repository contains the two application-owned halves of an Eigen game.
+The engine itself is consumed from npm and pub.dev; its repositories are not
+part of this project.
+
+## Worker
+
+```sh
+cd server
+{{PACKAGE_MANAGER}} install
+{{PACKAGE_MANAGER}} run dev
+```
+
+The game module is the default export of `server/src/module/index.ts`. Whenever
+a payload schema or shared fixture changes, regenerate the contract and Dart
+payloads together from the repository root:
+
+```sh
+{{PACKAGE_MANAGER}} run contract
+```
+
+The scaffold includes a starter fixture and both language runners. Keep the
+Worker tests watching while editing rules:
+
+```sh
+cd server
+{{PACKAGE_MANAGER}} run test:watch
+```
+
+After changing a schema or fixture, run `{{PACKAGE_MANAGER}} run contract` from
+the repository root, then `flutter test` from `app/`. Use
+`{{PACKAGE_MANAGER}} run contract:check` from the root in CI. The server and
+app commands remain independently usable if the two halves later move to
+separate repositories.
+
+## Flutter app
+
+The initial scaffold already generates Dart payloads from the Worker contract.
+Implement the client-side legality, preview and presentation rules under
+`app/lib/game/`, then configure Firebase and fill the public build-time values
+in `app/app-config.json`. They are Dart compilation environment declarations,
+not secrets; private credentials belong only in the Worker.
+
+See `app/lib/game/README.md` for the regeneration command.
+
+The app targets Android and web. Run the browser on the origin already allowed
+by the Worker template:
+
+```sh
+cd app
+flutter run -d chrome --web-hostname localhost --web-port 7357 \
+  --dart-define-from-file=app-config.json
+```
+
+For production, give the game one canonical custom domain, edit the public
+values in `app/app-config.json`, then deploy both halves together:
+
+```sh
+{{PACKAGE_MANAGER}} run deploy
+```
+
+That builds Flutter into `server/public/` and deploys one Worker containing the
+SPA and API. The app is `/`; invite and game URLs open the installed native app
+or the browser SPA; the native install landing page is `/download`.
+
+Install and authenticate the Firebase and FlutterFire CLIs, then configure
+Android, Flutter Web, and the messaging service worker together:
+
+```sh
+{{PACKAGE_MANAGER}} run firebase:configure
+```
+
+The command uses FlutterFire's selected Web app to generate both
+`lib/firebase_options.dart` and `web/firebase-config.js`; do not copy Firebase
+identifiers by hand. Put the public VAPID key in `app-config.json` separately —
+Firebase's app SDK configuration does not include that Web Push certificate.
+`eigen_flutter` bundles the pinned Cropper.js assets and loads them only when
+avatar editing starts, so the app needs no Cropper.js setup or runtime CDN. The
+complete production checklist is at
+https://eigeninteractive.com/docs/ship-it/deploy-the-web-app.
+
+Android releases use the same configuration file:
+
+```sh
+{{PACKAGE_MANAGER}} run build:android
+```
+
+Required values are intentionally empty in a fresh scaffold. The app reports
+all missing or malformed declarations at startup instead of continuing with
+placeholder endpoints.
+
+The `eigen_flutter` Android plugin enables Firebase's current FID-based
+messaging mode and supplies a Firebase SDK new enough to support it. The
+scaffolder leaves Flutter's generated manifest and `gradle.properties`
+untouched; it adds only the application-level core-library desugaring block
+required by `flutter_local_notifications`. Push registration is engine-owned;
+game code does not request or store an FCM registration token.
+
+The Worker uses that same Firebase project for push and complete account
+deletion. Copy `server/.dev.vars.example` to `server/.dev.vars`, then fill its
+service-account email and private key. The Firebase project ID and web origin
+remain in `server/wrangler.jsonc`. For deployment, store the two credentials
+with `wrangler secret put`; never commit the downloaded JSON or `.dev.vars`.

package/templates/project/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "example-game",
+  "private": true,
+  "scripts": {
+    "build:android": "cd app && flutter build appbundle --release --dart-define-from-file=app-config.json",
+    "build:web": "cd app && flutter build web --release --output ../server/public --dart-define-from-file=app-config.json",
+    "contract": "cd server && {{PACKAGE_MANAGER}} run contract && cd ../app && dart run eigen_flutter:generate_payloads --contract ../server/game-contract.json --output lib/game/generated/payloads.dart --fixtures-output test/fixtures",
+    "contract:check": "cd server && {{PACKAGE_MANAGER}} run contract:check && cd ../app && dart run eigen_flutter:generate_payloads --contract ../server/game-contract.json --output lib/game/generated/payloads.dart --fixtures-output test/fixtures --check",
+    "deploy": "{{PACKAGE_MANAGER}} run build:web && cd server && {{PACKAGE_MANAGER}} run deploy",
+    "firebase:configure": "cd app && dart run eigen_flutter:configure_firebase"
+  }
+}

package/templates/scaffold/project.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+server/node_modules/
+server/.wrangler/
+server/.dev.vars*
+!server/.dev.vars.example
+server/.env*
+server/public/*
+!server/public/.gitkeep
+*.log

package/templates/scaffold/worker.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+.wrangler/
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example
+*.log
+*.tsbuildinfo
+public/*
+!public/.gitkeep

package/templates/worker/.dev.vars.example

@@ -0,0 +1,4 @@
+# Copy to .dev.vars and fill these from the service-account JSON generated at
+# Firebase Console > Project settings > Service accounts. Never commit .dev.vars.
+FIREBASE_CLIENT_EMAIL=
+FIREBASE_PRIVATE_KEY=

package/templates/worker/README.md

@@ -0,0 +1,50 @@
+# Example Game Worker
+
+The authoritative game rules and Cloudflare Worker for an Eigen game.
+
+## Develop
+
+Install dependencies with `npm install` or `pnpm install`, then:
+
+```sh
+npm run cf-typegen
+npm run contract
+npm test
+npm run dev
+```
+
+The `src/module/index.ts` default export is the game contract. Add fixtures
+under `src/module/fixtures/`; `npm run contract` emits the language-neutral
+`game-contract.json` consumed by the Flutter payload generator.
+
+During rules development, keep `npm run test:watch` running. After changing a
+schema or fixture, run `npm run contract`; CI can use
+`npm run contract:check` to reject a stale committed artifact.
+
+## Configure and deploy
+
+`FIREBASE_PROJECT_ID` and `WEB_APP_ORIGIN` under `wrangler.jsonc` → `vars` are
+the Worker's non-secret environment variables in local development and
+production. Copy `.dev.vars.example` to `.dev.vars`, then fill
+`FIREBASE_CLIENT_EMAIL` and `FIREBASE_PRIVATE_KEY` from the same Firebase
+project's service-account JSON. These credentials are required for FCM and
+complete Firebase account deletion; `.dev.vars` is git-ignored.
+
+For deployment, store both values as Wrangler secrets:
+
+```sh
+npx wrangler secret put FIREBASE_CLIENT_EMAIL
+npx wrangler secret put FIREBASE_PRIVATE_KEY
+```
+
+`WEB_APP_ORIGIN` is the exact Flutter web origin the engine automatically
+allows to make browser API and WebSocket requests, and the trusted base for
+absolute notification links. The scaffolded `http://localhost:7357` value
+matches the documented Flutter command; change it to the canonical HTTPS
+origin before production. Configure `clientOrigins` in `createEngine` only
+when you need multiple or non-standard browser origins.
+
+The combined scaffold builds Flutter directly into `public/`. Static assets
+bypass Worker execution; `/api/*`, `/join/*`, `/game/*`, `/download`, legal,
+and verification paths run Worker-first. `npm run deploy` applies the engine
+migrations before deploying the Worker and whatever is already in `public/`.

package/templates/worker/game-contract.json

@@ -0,0 +1,109 @@
+{
+  "formatVersion": 1,
+  "game": "Example Game",
+  "versions": {
+    "1": {
+      "schemas": {
+        "state": {
+          "$schema": "https://json-schema.org/draft/2020-12/schema",
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "count"
+          ],
+          "type": "object"
+        },
+        "observation": {
+          "$schema": "https://json-schema.org/draft/2020-12/schema",
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "maximum": 9007199254740991,
+              "minimum": 0,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "count"
+          ],
+          "type": "object"
+        },
+        "action": {
+          "$schema": "https://json-schema.org/draft/2020-12/schema",
+          "properties": {
+            "amount": {
+              "maximum": 9007199254740991,
+              "minimum": 1,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "amount"
+          ],
+          "type": "object"
+        },
+        "config": {
+          "$schema": "https://json-schema.org/draft/2020-12/schema",
+          "additionalProperties": false,
+          "properties": {
+            "target": {
+              "maximum": 9007199254740991,
+              "minimum": 1,
+              "type": "integer"
+            }
+          },
+          "required": [
+            "target"
+          ],
+          "type": "object"
+        }
+      }
+    }
+  },
+  "fixtures": [
+    {
+      "path": "v1/counter.json",
+      "document": {
+        "cases": [
+          {
+            "action": {
+              "amount": 1
+            },
+            "config": {
+              "target": 10
+            },
+            "expected": {
+              "observation": {
+                "count": 1
+              },
+              "outcome": null,
+              "pending": [
+                1
+              ],
+              "state": {
+                "count": 1
+              },
+              "valid": true
+            },
+            "kind": "action",
+            "name": "increments the counter and passes the turn",
+            "pending": [
+              0
+            ],
+            "playerIndex": 0,
+            "state": {
+              "count": 0
+            }
+          }
+        ],
+        "schemaVersion": 1
+      }
+    }
+  ]
+}

package/templates/worker/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@game/example-game-server",
+  "version": "0.0.0",
+  "private": true,
+  "description": "The authoritative Example Game server on Cloudflare Workers.",
+  "type": "module",
+  "eigen": {
+    "game": "Example Game"
+  },
+  "cloudflare": {
+    "label": "Example Game Worker",
+    "products": [
+      "D1",
+      "Durable Objects"
+    ],
+    "categories": [
+      "starter"
+    ],
+    "bindings": {
+      "GAME_DB": {
+        "description": "The engine-owned D1 database. Wrangler provisions it automatically on first deployment."
+      },
+      "FIREBASE_PROJECT_ID": {
+        "description": "The Firebase project ID used to verify player identity tokens."
+      }
+    }
+  },
+  "scripts": {
+    "cf-typegen": "wrangler types",
+    "contract": "eigen-contract",
+    "contract:check": "eigen-contract --check",
+    "deploy": "wrangler d1 migrations apply GAME_DB --remote && wrangler deploy",
+    "dev": "wrangler dev",
+    "start": "wrangler dev",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "wrangler types && tsc --noEmit"
+  },
+  "dependencies": {
+    "@eigeninteractive/rules": "^0.1.0",
+    "@eigeninteractive/server": "^0.1.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eigeninteractive/testkit": "^0.1.0",
+    "@types/node": "^26.1.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "wrangler": "^4.110.0"
+  }
+}

package/templates/worker/public/.gitkeep

@@ -0,0 +1 @@
+# Flutter's release build is written into this directory by `pnpm build:web`.

package/templates/worker/src/index.ts

@@ -0,0 +1,17 @@
+import { BaseGameDO, createEngine } from "@eigeninteractive/server";
+import gameModule from "./module/index.js";
+
+export class GameDO extends BaseGameDO<Env> {
+  protected readonly gameModule = gameModule;
+
+  protected d1(env: Env): D1Database {
+    return env.GAME_DB;
+  }
+}
+
+export default createEngine({
+  gameModule,
+  appName: "Example Game",
+  d1: (env: Env) => env.GAME_DB,
+  gameDO: (env: Env) => env.GAME_DO,
+});

package/templates/worker/src/module/fixtures/v1/counter.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "cases": [
+    {
+      "kind": "action",
+      "name": "increments the counter and passes the turn",
+      "config": {
+        "target": 10
+      },
+      "state": {
+        "count": 0
+      },
+      "pending": [0],
+      "playerIndex": 0,
+      "action": {
+        "amount": 1
+      },
+      "expected": {
+        "valid": true,
+        "state": {
+          "count": 1
+        },
+        "pending": [1],
+        "outcome": null,
+        "observation": {
+          "count": 1
+        }
+      }
+    }
+  ]
+}

package/templates/worker/src/module/index.ts

@@ -0,0 +1,4 @@
+import type { GameModule } from "@eigeninteractive/rules";
+import { rulesV1 } from "./v1.js";
+
+export default { versions: { 1: rulesV1 } } satisfies GameModule;

package/templates/worker/src/module/v1.ts

@@ -0,0 +1,57 @@
+import type { GameRules } from "@eigeninteractive/rules";
+import { z } from "zod";
+
+const stateSchema = z.object({ count: z.int().min(0) }).meta({ id: "ExampleGameV1State" });
+const observationSchema = z.object({ count: z.int().min(0) }).meta({ id: "ExampleGameV1Observation" });
+const actionSchema = z.object({ amount: z.int().min(1) }).meta({ id: "ExampleGameV1Action" });
+const configSchema = z.object({ target: z.int().min(1) }).meta({ id: "ExampleGameV1Config" });
+
+type State = z.infer<typeof stateSchema>;
+type Observation = z.infer<typeof observationSchema>;
+type Action = z.infer<typeof actionSchema>;
+type Config = z.infer<typeof configSchema>;
+
+const outcome = (winner: number) => [
+  { playerIndex: winner, result: "win" as const, placement: 1, teamIndex: winner },
+  { playerIndex: 1 - winner, result: "loss" as const, placement: 2, teamIndex: 1 - winner },
+];
+
+export const rulesV1: GameRules<State, Observation, Action, Config> = {
+  schemas: {
+    state: stateSchema,
+    observation: observationSchema,
+    action: actionSchema,
+    config: configSchema,
+  },
+
+  initialState: () => ({
+    state: { count: 0 },
+    pendingPlayers: [0],
+  }),
+
+  applyAction: ({ state, data, playerIndex, config }) => {
+    const count = state.count + data.amount;
+    return {
+      state: { count },
+      pendingPlayers: count >= config.target ? [] : [1 - playerIndex],
+      ...(count >= config.target ? { outcome: outcome(playerIndex) } : {}),
+    };
+  },
+
+  applyLifecycle: ({ state, pending, data }) => {
+    const loser = data.type === "timeout" ? (pending[0] ?? 0) : data.playerIndex;
+    return {
+      state,
+      pendingPlayers: [],
+      outcome: outcome(1 - loser),
+    };
+  },
+
+  computeObservation: ({ state, pending }) => ({
+    data: state,
+    pendingPlayers: pending,
+  }),
+
+  ratingPool: () => null,
+  botSeatable: () => true,
+};

package/templates/worker/test/twin.spec.ts

@@ -0,0 +1,4 @@
+import { twinFixtureTests } from "@eigeninteractive/testkit";
+import gameModule from "../src/module/index.js";
+
+twinFixtureTests(gameModule, new URL("../src/module/fixtures/", import.meta.url));

package/templates/worker/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024"],
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "types": ["./worker-configuration.d.ts", "node"]
+  },
+  "include": ["src", "test", "worker-configuration.d.ts"]
+}