@gatherround/sdk 0.4.1

package/src/runtime-episode.ts

@@ -0,0 +1,109 @@
+/**
+ * runtime-episode.ts
+ *
+ * Top-level runtime episode type — the root of episode.json.
+ * Produced by the editor's publish pipeline, consumed by the game engine.
+ */
+
+import type { RuntimeNode } from "./runtime-types.js";
+
+// ── Heroes ──────────────────────────────────────────────────────────────────
+
+export interface RuntimeHeroAttribute {
+  /** Stable key (e.g. "essence", "fear_meter"). */
+  id: string;
+  /** Display name (e.g. "Essence", "Fear Meter"). */
+  label: string;
+  /** Narrative descriptor value — always string. */
+  value: string;
+}
+
+export interface RuntimeMeterDefinition {
+  /** Stable key matching variable name (e.g. "alignment"). */
+  id: string;
+  /** Display label (e.g. "Alignment"). */
+  label: string;
+  /** Starting value (e.g. 10). */
+  defaultValue: number;
+  /** Range floor (e.g. 0). */
+  min: number;
+  /** Range ceiling (e.g. 20). */
+  max: number;
+  /** Optional CSS color for bar, null = theme default. */
+  color: string | null;
+}
+
+export interface RuntimeHero {
+  /** Role slot: 0 = TV Host, 1–4 = player heroes. */
+  role: number;
+  name: string;
+  description: string;
+  /** Self-describing attribute array — includes all designer-defined attributes. */
+  attributes: RuntimeHeroAttribute[];
+  /** Meter definitions for this hero's class (numeric bars with min/max range). */
+  meters: RuntimeMeterDefinition[];
+  /** GCS path to hero card image (lobby / character sheet), or null if unset. */
+  cardImg: string | null;
+  /** GCS path to profile image (thumbnail / PiP overlay), or null if unset. */
+  profileImg: string | null;
+}
+
+// ── Variables ───────────────────────────────────────────────────────────────
+
+export interface RuntimeVariable {
+  /** Variable name (the target key used in mutations/conditions). */
+  name: string;
+  /** Data type — determines valid runtime operations. */
+  type: "boolean" | "number" | "string";
+  /** Starting value at episode begin. */
+  defaultValue: boolean | number | string;
+  /**
+   * When set, the engine creates one instance per entity of this type.
+   * null = plain global variable. "hero" = one instance per hero.
+   */
+  expandBy: "hero" | null;
+}
+
+// ── Episode-level assets ────────────────────────────────────────────────────
+
+export interface RuntimeEpisodeAssets {
+  logo: string | null;
+  thumbnail: string | null;
+  /** Full-screen image shown on the start/title screen. */
+  startBg: string | null;
+  /** Background image shown behind the lobby UI. */
+  lobbyBg: string | null;
+}
+
+// ── Runtime Episode (episode.json root) ─────────────────────────────────────
+
+export interface RuntimeEpisode {
+  /** Schema version — bumped on breaking changes to the runtime format. */
+  version: "2.0" | "2.1" | "2.2";
+  /** Firestore episode document ID. */
+  episodeId: string;
+  /** ISO-8601 timestamp of when this artifact was compiled. */
+  compiledAt: string;
+  /** Publish version ID (timestamp-based, e.g. "20260306T120000Z"). */
+  versionId: string;
+
+  // ── Episode metadata ────────────────────────────────────────────────────
+  title: string;
+  genre: string | null;
+  summary: string | null;
+
+  /** Node ID to begin execution from. */
+  startNodeId: string;
+
+  // ── Heroes ──────────────────────────────────────────────────────────────
+  heroes: RuntimeHero[];
+
+  // ── Variables (mutable episode state) ───────────────────────────────────
+  variables: RuntimeVariable[];
+
+  // ── Episode-level assets (GCS paths) ────────────────────────────────────
+  assets: RuntimeEpisodeAssets;
+
+  // ── Flat node array — the entire story graph ────────────────────────────
+  nodes: RuntimeNode[];
+}

package/src/runtime-strings.ts

@@ -0,0 +1,12 @@
+/**
+ * runtime-strings.ts
+ *
+ * String extraction artifact (strings.en.json).
+ * Flat key-value map of all player-facing text, keyed by node + field path.
+ */
+
+/**
+ * Flat key-value map of all player-facing text.
+ * Keys follow the pattern: `{nodeId}.{field}` or `{nodeId}.{field}.{index}`
+ */
+export type RuntimeStrings = Record<string, string>;

package/src/runtime-types.ts

@@ -0,0 +1,84 @@
+/**
+ * runtime-types.ts
+ *
+ * Node-level runtime types: nodes, transitions, conditions, mutations.
+ * These define the structure of individual story graph nodes within a RuntimeEpisode.
+ */
+
+// ── Runtime Node ───────────────────────────────────────────────────────────
+
+export interface RuntimeNode {
+  id: string;
+  kind: string;
+  /** Author's label for this node (debugging / game-log use). */
+  label?: string;
+
+  /**
+   * Kind-specific payload. Shape varies by kind:
+   *   play_video:   { url, loop, pipTarget, onPlay, timeEvents }
+   *   hero_action:  { prompt, choices: { text, mutations? }[], targetRoles, timer? }
+   *   trigger_qte:  { text, timeLimit, targetRoles, qteType, difficulty }
+   *   vote:         { prompt, options, timeLimit, tallyMode, targetRoles }
+   *   explore:      { options: { text, image?, showOnce }[], target_roles, locationLabel?, locationImage? }
+   *   set_variable: absent (uses mutations)
+   *   logic:        absent (uses conditions + mutations)
+   *   end_episode:  absent (terminal node — no payload, no transitions)
+   */
+  payload?: Record<string, unknown>;
+
+  /** Logic-kind conditions — evaluated top-to-bottom, first match wins.
+   *  Each element is a branch: either a single RuntimeCondition (legacy)
+   *  or a RuntimeConditionGroup (compound boolean logic). */
+  conditions?: (RuntimeCondition | RuntimeConditionGroup)[];
+
+  /** Variable mutations — executed on node entry. */
+  mutations?: RuntimeMutation[];
+
+  /** Compiled transitions from graph edges. */
+  transitions: RuntimeTransition[];
+}
+
+// ── Transitions ────────────────────────────────────────────────────────────
+
+export interface RuntimeTransition {
+  /** The event that fires this transition. */
+  on: string;
+  /** For choice-based transitions: index into the choices array. */
+  choiceIndex?: number;
+  /** For condition-based transitions: index into the conditions array. */
+  conditionIndex?: number;
+  /** For cue-based transitions: index into the timeEvents array. */
+  cueIndex?: number;
+  /** For exit-based transitions: index into the exits array (explore node). */
+  exitIndex?: number;
+  /** Destination node ID. */
+  target: string;
+}
+
+// ── Conditions ─────────────────────────────────────────────────────────────
+
+export interface RuntimeCondition {
+  variable: string;
+  operator: "eq" | "neq" | "gt" | "lt" | "gte" | "lte";
+  value: string | number | boolean;
+}
+
+/**
+ * A compound condition branch — multiple atomic conditions combined with
+ * a boolean operator (AND/OR) or an arbitrary formula.
+ */
+export interface RuntimeConditionGroup {
+  conditions: RuntimeCondition[];
+  /** "and" | "or" — uniform inline join. "formula" — uses the `formula` field. */
+  mode: "and" | "or" | "formula";
+  /** Boolean formula string (e.g. "(A & B) | !C"). Only present when mode === "formula". */
+  formula?: string;
+}
+
+// ── Mutations ──────────────────────────────────────────────────────────────
+
+export interface RuntimeMutation {
+  target: string;
+  operation: "set" | "increment" | "decrement";
+  value: string | number | boolean;
+}