@netforge/template-racer 0.0.0-stage → 0.2.0

package/src/game.ts

@@ -0,0 +1,96 @@
+/**
+ * TORQUEBAY: the racer template (play style "racer").
+ * Up to eight karts race laps around harbour circuits: hold the throttle,
+ * drift through the bends to charge a mini-turbo (release for the boost),
+ * hit the boost pads, collect coins (every coin you hold adds 1% top speed,
+ * up to ten) and keep off the grass. A round is one race; the next round runs
+ * another circuit. Seat bots fill the grid so a race always has a field.
+ *
+ * This file is the whole game as the model writes it: declarations only,
+ * against the typed API in @netforge/engine. Everything else (the kart
+ * physics, netcode, renderer, track streaming, bots, referee) is the
+ * template's machinery.
+ *
+ * Track coordinates are metres on the ground (x right, z down the screen's
+ * map). points is the closed centreline in driving order; boosts and coins
+ * are [lap fraction 0..1, lateral -1..1 of the half width].
+ */
+import { earn, game, store, system, upgrade } from "@netforge/engine";
+
+/** Coins in a row: n coins from lap fraction f, `gap` of a lap apart, at one lateral. */
+const coinRow = (f: number, lateral: number, n: number, gap = 0.006): [number, number][] => Array.from({ length: n }, (_, i) => [f + i * gap, lateral]);
+
+export default game({
+  template: "racer",
+  style: "lowpoly",
+  tickRate: 60,
+  places: { harbour: { chunks: "places/harbour", spawn: [0, 0, 0] } },
+  players: { prefab: "style.lowpoly.kart_a", max: 8, bots: 6 },
+  round: { seconds: 240 },
+  tracks: [
+    {
+      name: "Harbour Loop",
+      laps: 3,
+      width: 14,
+      points: [[0, 0], [90, 0], [150, 15], [175, 65], [150, 120], [90, 135], [50, 175], [-20, 190], [-85, 160], [-110, 100], [-90, 35]],
+      boosts: [[0.12, 0], [0.47, -0.4], [0.78, 0.4]],
+      coins: [...coinRow(0.04, 0.5, 5), ...coinRow(0.3, -0.5, 5), ...coinRow(0.6, 0, 5), ...coinRow(0.88, -0.3, 5)],
+    },
+    {
+      name: "Crane Yard",
+      laps: 3,
+      width: 13,
+      points: [[0, 0], [70, -10], [120, 10], [130, 60], [95, 85], [60, 70], [30, 95], [45, 140], [5, 175], [-55, 160], [-75, 105], [-50, 60], [-75, 20]],
+      boosts: [[0.08, 0], [0.38, 0.3], [0.7, -0.3]],
+      coins: [...coinRow(0.15, 0, 5), ...coinRow(0.45, 0.4, 5), ...coinRow(0.62, -0.4, 5), ...coinRow(0.85, 0, 5)],
+    },
+    {
+      name: "Lighthouse Run",
+      laps: 2,
+      width: 15,
+      points: [[0, 0], [120, -15], [200, 10], [235, 70], [210, 140], [140, 170], [80, 150], [40, 190], [-30, 210], [-95, 175], [-115, 105], [-80, 40]],
+      boosts: [[0.05, 0], [0.25, 0.35], [0.5, -0.35], [0.8, 0]],
+      coins: [...coinRow(0.1, -0.4, 6), ...coinRow(0.35, 0.4, 6), ...coinRow(0.66, 0, 6), ...coinRow(0.9, 0.3, 6)],
+    },
+  ],
+});
+
+// Round upgrades sold in the store (one level each, for the race). Racer upgrades raise speed
+// (top speed), haste (drift charge), might (boost length), armor (grass and wall losses) or magnet (coin reach).
+upgrade("turbo", { stat: "might", step: 0.25, maxLevel: 1 });
+upgrade("tuned_engine", { stat: "speed", step: 0.05, maxLevel: 1 });
+upgrade("soft_tyres", { stat: "haste", step: 0.3, maxLevel: 1 });
+upgrade("bumpers", { stat: "armor", step: 0.3, maxLevel: 1 });
+
+// A clean race: finish without scraping a wall hard.
+system("clean_line", ({ on, emit }) => {
+  const scrapes = new Map<number, number>();
+  on("kart.bumped", (ids) => {
+    for (const id of ids) scrapes.set(id, (scrapes.get(id) ?? 0) + 1);
+  });
+  on("player.finished", (ids) => {
+    const clean = ids.filter((id) => (scrapes.get(id) ?? 0) === 0);
+    if (clean.length > 0) emit("race.clean", clean);
+  });
+  on("run.started", (ids) => {
+    for (const id of ids) scrapes.delete(id);
+  });
+});
+
+// Earn (mandatory). Pays the game's coins (1 coin = 1 token), once per race each.
+// Seat bots never earn, and winning a field of bots pays nothing extra. Values are PLACEHOLDER.
+earn.rule("hot_lap", { when: "drift.boosted", n: 3, pay: 4, oncePer: "run" });
+earn.rule("chequered", { when: "player.finished", n: 1, pay: 10, oncePer: "run" });
+earn.rule("clean_line", { when: "race.clean", n: 1, pay: 12, oncePer: "run" });
+earn.rule("pole_to_flag", { when: "race.won", n: 1, pay: 25, oncePer: "run" });
+// Buy-in run (the mandatory sink loop). PLACEHOLDER.
+earn.stake({ min: 10, max: 100, multiple: 2 });
+
+// Store (the Kit), priced in coins: round upgrades and two paint jobs owned for good.
+store.sku("turbo", { coins: 40 });
+store.sku("tuned_engine", { coins: 40 });
+store.sku("soft_tyres", { coins: 60 });
+store.sku("skin_flame", { coins: 300, grants: { cosmetic: 1 } });
+store.sku("skin_chrome", { coins: 500, grants: { cosmetic: 2 } });
+// Losable gear: bumpers in every staked race, lost when that race makes less than loseBelow of its most earn. PLACEHOLDER.
+store.sku("bumper_kit", { coins: 120, grants: { gear: "bumpers", loseBelow: 0.25 } });

package/src/manifest.ts

@@ -0,0 +1,44 @@
+/**
+ * Loads the game module once per process and compiles it. The room server,
+ * the client, the bots and the tests all start here.
+ */
+import { collectManifest, compileGame, kartAdapter } from "@netforge/engine/game";
+import type { CompiledGame, CompiledRacer, KartRoomWorld, RaceRunnerOptions } from "@netforge/engine/game";
+import type { SimAdapter } from "@netforge/engine/net";
+import type { InputCommand } from "@netforge/engine-sim";
+import "./game.js";
+
+/** Content version: bump with any change to game.ts (hot swap compares it). */
+export const GAME_VERSION = "torquebay-0.1.0";
+export const GAME_NAME = "torquebay";
+/** Room template (as the Net Forge room server names it) and place used by the client and the bots. */
+export const TEMPLATE = "racer";
+export const PLACE = "harbour";
+
+const MANIFEST = collectManifest();
+let compiled: CompiledGame | null = null;
+
+/** The compiled game (tracks, handling, upgrades). */
+export function racerGame(): CompiledGame & { readonly racer: CompiledRacer } {
+  compiled ??= compileGame(MANIFEST);
+  if (!compiled.racer) throw new Error('TORQUEBAY: game.ts must declare template "racer"');
+  return compiled as CompiledGame & { readonly racer: CompiledRacer };
+}
+
+/** The SimAdapter for this game. `runner` options are server-side timing overrides (tests). */
+export function racerAdapter(runner?: RaceRunnerOptions): SimAdapter<KartRoomWorld, InputCommand> {
+  const g = racerGame();
+  return kartAdapter({
+    name: GAME_NAME,
+    version: GAME_VERSION,
+    manifest: g.manifest,
+    compiled: g.racer,
+    tickRate: g.tickRate,
+    bots: g.bots,
+    roundSeconds: g.round?.seconds ?? null,
+    ...(runner ? { runner } : {}),
+  });
+}
+
+/** Cosmetic ids for store SKUs (0 is the kart's own paint). */
+export const COSMETICS: Readonly<Record<string, number>> = { skin_flame: 1, skin_chrome: 2 };

package/src/store.ts

@@ -0,0 +1,109 @@
+/**
+ * Store hooks (the Coins model): every
+ * game has coins, 1 coin = 1 game token, shown under the token's own name,
+ * symbol and logo. TORQUEBAY sells three round upgrades (a store command
+ * named after the upgrade grants one level for the rest of the round) and
+ * two cosmetic finishes (permanent), all priced in coins.
+ *
+ * `KitStoreBridge` is the slice of @netforge/kit's `Kit` this game
+ * calls, with the Kit's own names (`kit.coins.*`, `kit.store.owns/buy`), so
+ * the real Kit drops in unchanged. Until a game's token is live `mockKit()`
+ * stands in, in memory. Earned coins are spent first (off chain, no wallet
+ * prompt), then the wallet, exactly as the Kit does.
+ */
+export interface KitStoreBridge {
+  readonly store: {
+    owns(id: string): boolean;
+    count(id: string): number;
+    buy(id: string, opts?: { pay?: "usdg" | "token" | "coins" }): Promise<unknown>;
+  };
+  readonly coins: {
+    /** The token's own name, symbol and logo (its metadata). Never a generic "COIN". */
+    name(): string;
+    symbol(): string;
+    logo(): string | null;
+    /** Whole coins: earned (unclaimed) plus the wallet. */
+    balance(): number;
+    /** Earned first, then the wallet. `key` proves the paid room command (sent as the command's `proof`). */
+    spend(amount: number, reason: string): Promise<{ key: string | null }>;
+  };
+}
+
+/** Coin prices the client is wired to (they match store.sku(...) in game.ts; the generator's gate keeps them). */
+export const COIN_PRICES = { turbo: 40, tuned_engine: 40, soft_tyres: 60, skin_flame: 300, skin_chrome: 500 } as const;
+export type SkuId = keyof typeof COIN_PRICES;
+/** Round upgrades: spent, applied by the room for the rest of the round. */
+export const UPGRADE_SKUS = ["turbo", "tuned_engine", "soft_tyres"] as const;
+/** Cosmetic finishes: bought once, owned for good. */
+export const COSMETIC_SKUS = ["skin_flame", "skin_chrome"] as const;
+
+/** The template's own coin, as its token metadata names it until a creator renames it. */
+export const TORQ_COIN = {
+  name: "Torq",
+  symbol: "TORQ",
+  logo: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Ccircle cx='16' cy='16' r='15' fill='%23ff5a1f'/%3E%3Ccircle cx='16' cy='16' r='9' fill='none' stroke='%23fff3d6' stroke-width='3'/%3E%3Cpath d='M16 7v6M16 19v6M7 16h6M19 16h6' stroke='%23fff3d6' stroke-width='3'/%3E%3C/svg%3E",
+} as const;
+
+export interface SkuPrice {
+  readonly coins?: number;
+  readonly usdg?: number;
+}
+
+export interface MockKit extends KitStoreBridge {
+  /** Dollars left (mock only). */
+  usdg(): number;
+  /** Earned, unclaimed coins left (mock only). */
+  earned(): number;
+}
+
+/** An in-memory Kit for local play and tests: starting balances, prices from game.ts. */
+export function mockKit(
+  start: { earned: number; wallet: number; usdg: number },
+  prices: Readonly<Record<string, SkuPrice>>,
+  coin: { name: string; symbol: string; logo: string | null } = TORQ_COIN,
+): MockKit {
+  let earned = start.earned;
+  let wallet = start.wallet;
+  let usdg = start.usdg;
+  const owned = new Map<string, number>();
+  let spends = 0;
+  /** Earned first, then the wallet: the Kit's order. */
+  const spend = (amount: number, reason: string) => {
+    if (!Number.isInteger(amount) || amount <= 0 || earned + wallet < amount) throw new Error(`cannot spend ${amount} for ${reason}`);
+    const fromEarned = Math.min(earned, amount);
+    earned -= fromEarned;
+    wallet -= amount - fromEarned;
+    return { fromEarned, onChain: amount - fromEarned, key: `mock-spend-${++spends}` };
+  };
+  return {
+    usdg: () => usdg,
+    earned: () => earned,
+    store: {
+      owns: (id) => (owned.get(id) ?? 0) > 0,
+      count: (id) => owned.get(id) ?? 0,
+      async buy(id, opts) {
+        const p = prices[id];
+        if (!p) throw new Error(`no SKU "${id}"`);
+        const payUsdg = opts?.pay === "usdg" || (opts?.pay === undefined && p.coins === undefined);
+        if (payUsdg) {
+          if (p.usdg === undefined || usdg < p.usdg) throw new Error("not enough USDG");
+          usdg -= p.usdg;
+        } else {
+          if (p.coins === undefined) throw new Error(`"${id}" has no coin price`);
+          spend(p.coins, id);
+        }
+        owned.set(id, (owned.get(id) ?? 0) + 1);
+        return { id };
+      },
+    },
+    coins: {
+      name: () => coin.name,
+      symbol: () => coin.symbol,
+      logo: () => coin.logo,
+      balance: () => earned + wallet,
+      async spend(amount, reason) {
+        return spend(amount, reason);
+      },
+    },
+  };
+}