@dxos/plugin-game 0.0.0

package/src/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './meta';
+export * from './types';

package/src/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import config from '../dx.config';
+
+export const meta = Plugin.getMetaFromConfig(config);

package/src/plugin.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const GamePlugin = Plugin.lazy(meta, () => import('#plugin'));

package/src/translations.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Type } from '@dxos/echo';
+import { type Resource } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+import { Game } from '#types';
+
+export const translations = [
+  {
+    'en-US': {
+      [Type.getTypename(Game)]: {
+        'typename.label': 'Game',
+        'typename.label_zero': 'Games',
+        'typename.label_one': 'Game',
+        'typename.label_other': 'Games',
+        'object-name.placeholder': 'New game',
+        'add-object.label': 'Add game',
+        'rename-object.label': 'Rename game',
+        'delete-object.label': 'Delete game',
+        'object-deleted.label': 'Game deleted',
+      },
+      [meta.profile.key]: {
+        'plugin.name': 'Game',
+        'create-panel.variant.label': 'Select variant',
+        'create-panel.variant.placeholder': 'Search variants...',
+        'create-panel.submit.label': 'Create',
+        'unsupported-variant.label': 'Unsupported game variant',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types/Game.ts

@@ -0,0 +1,106 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { AppAnnotation } from '@dxos/app-toolkit';
+import { Annotation, DXN, Obj, Ref, Type } from '@dxos/echo';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/Annotation';
+
+/**
+ * A player in a game.
+ * `role` is variant-defined (e.g. 'white' | 'black' for chess, 'x' | 'o' for tictactoe).
+ * `identity` is the optional DID of a human player; absent for AI or empty seats.
+ * `name` is an optional display label (useful for AI/guest players).
+ */
+export const Player = Schema.Struct({
+  role: Schema.String.annotations({
+    description: 'Variant-defined player role (e.g. "white", "x").',
+  }),
+  identity: Schema.optional(
+    Schema.String.annotations({
+      description: 'DID of the player; absent for AI or empty seats.',
+    }),
+  ),
+  name: Schema.optional(
+    Schema.String.annotations({
+      description: 'Optional display name for the player.',
+    }),
+  ),
+});
+
+export type Player = Schema.Schema.Type<typeof Player>;
+
+/**
+ * Base Game object. Variant-specific state lives in a separate referenced object.
+ * Unifies all game variants (chess, tic-tac-toe, ...) under one typename so they share
+ * graph node, create flow, and shared surface scaffolding.
+ */
+export class Game extends Type.makeObject<Game>(DXN.make('org.dxos.type.game', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.optional(Schema.String),
+    players: Schema.mutable(Schema.Array(Player))
+      .annotations({ description: 'Players in the game.' })
+      .pipe(FormInputAnnotation.set(false), Schema.optional),
+    variant: Ref.Ref(Obj.Unknown)
+      .annotations({ description: 'Reference to variant-specific state object.' })
+      .pipe(FormInputAnnotation.set(false)),
+  }).pipe(
+    LabelAnnotation.set(['name']),
+    Annotation.IconAnnotation.set({ icon: 'ph--sword--regular', hue: 'indigo' }),
+    AppAnnotation.CardAnnotation.set(true),
+    // Delegate the graph-node icon to the referenced variant state's schema. Falls back to
+    // the static `ph--sword--regular` above while the variant ref is still loading.
+    Annotation.IconFromRefAnnotation.set('variant'),
+  ),
+) {}
+
+/**
+ * Variant-narrowed reference to a Game.
+ *
+ * Encodes — at the type level — that the variant ref points to a specific state type.
+ * Runtime narrowing is performed by `loadGame(ref, variantType)` which validates and
+ * returns the resolved Game together with its typed variant state.
+ *
+ * @example
+ * ```ts
+ * input: Schema.Struct({
+ *   game: GameRef(Chess.State),
+ * }),
+ * // handler:
+ * const { game, variant } = yield* loadGame(input.game, Chess.State);
+ * // `variant` is typed as Chess.State.
+ * ```
+ */
+export type GameRef<_V> = Ref.Ref<Game>;
+
+export const GameRef = <S extends Type.AnyObj>(_variantType: S) =>
+  Ref.Ref(Game) as Schema.Schema<GameRef<Type.InstanceType<S>>, any, never>;
+
+/**
+ * Build a base `Game` object referencing the given variant-state ECHO object.
+ *
+ * The variant is stored as a `Ref` so the underlying state (e.g. `Chess.State`,
+ * `TicTacToe.State`) lives as its own ECHO object alongside the Game.
+ *
+ * @param name Optional display name shown in the graph node and Properties form.
+ * @param variant Variant-specific state object (e.g. `Chess.State`, `TicTacToe.State`).
+ * @param players Optional initial players; copied into a mutable array on the Game.
+ * @returns A new `Game` object with `variant` stored as a Ref.
+ */
+export const make = ({
+  name,
+  players,
+  variant,
+}: {
+  name?: string;
+  players?: ReadonlyArray<Player>;
+  variant: Obj.Unknown;
+}): Game => {
+  return Obj.make(Game, {
+    name,
+    players: players ? [...players] : [],
+    variant: Ref.make(variant),
+  });
+};

package/src/types/GameCapabilities.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { Capability } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+import type { GameVariant } from './types';
+
+/**
+ * A game variant contribution. Each variant plugin (chess, tic-tac-toe, ...)
+ * contributes one of these via `Capability.contributes(GameCapabilities.VariantProvider, variant)`.
+ * Consumers iterate via `Capability.getAll(GameCapabilities.VariantProvider)` (Effect) or
+ * `useCapabilities(GameCapabilities.VariantProvider)` (React).
+ */
+export const VariantProvider = Capability.make<GameVariant>(`${meta.profile.key}.capability.variant`);

package/src/types/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { Game, GameRef, Player, make } from './Game';
+export * from './types';
+export { GameVariantMismatchError, loadGame } from '../util/load-game';
+
+export * as GameCapabilities from './GameCapabilities';

package/src/types/types.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Effect from 'effect/Effect';
+import type * as Schema from 'effect/Schema';
+import type { ComponentType } from 'react';
+
+import type { Database, Obj, Type } from '@dxos/echo';
+
+import type { Game } from './Game';
+
+/**
+ * Contribution from a variant plugin (e.g. plugin-chess, plugin-tictactoe).
+ * Defines how a game variant is created, rendered, and the roles its players take.
+ */
+export type GameVariant = {
+  /** Stable id, typically the variant state typename (e.g. 'org.dxos.type.chess.state'). */
+  id: string;
+  /** Human-readable variant name (e.g. 'Chess'). */
+  label: string;
+  /** Optional Phosphor icon name (e.g. 'ph--shield-chevron--regular'). */
+  icon?: string;
+  /** ECHO Type entity of the variant state object referenced by `Game.variant`. */
+  variantType: Type.AnyObj;
+  /**
+   * Optional Effect Schema rendered as a form after the user picks the variant.
+   * To use a `Type.Type` entity, extract its schema first via `Type.getSchema(...)`.
+   */
+  inputSchema?: Schema.Schema.AnyNoContext;
+  /** Roles a player may take in this variant (e.g. ['white', 'black']). */
+  roles: readonly string[];
+  /**
+   * Build the variant state object from the user's form input. May allocate ECHO
+   * objects, run effects, etc. Returned object is added to the database alongside the Game.
+   */
+  createVariant: (input: Record<string, any>) => Effect.Effect<Obj.Any, Error, Database.Service>;
+  /** Optional Card surface component for this variant. */
+  card?: ComponentType<GameVariantSurfaceProps>;
+  /** Optional Article/Section surface component for this variant. */
+  article?: ComponentType<GameVariantSurfaceProps>;
+};
+
+export type GameVariantSurfaceProps = {
+  /** The base Game object (may be a snapshot from useObject/Surface). */
+  game: Obj.Snapshot<Game> | Game;
+  /** The resolved variant state object (may be a snapshot from useObject). */
+  variant: Obj.Snapshot<Obj.Unknown> | Obj.Unknown;
+  /** Surface role passed through from the host. */
+  role?: string;
+  /** Attendable id passed through from the host. */
+  attendableId?: string;
+};

package/src/util/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './load-game';

package/src/util/load-game.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Database, Obj, type Ref, Type } from '@dxos/echo';
+
+import { Game } from '../types/Game';
+
+export class GameVariantMismatchError extends Error {
+  readonly _tag = 'GameVariantMismatchError';
+  constructor(
+    readonly gameId: string,
+    readonly expectedTypename: string,
+    readonly actualTypename: string,
+  ) {
+    super(`Game ${gameId} variant typename mismatch: expected ${expectedTypename}, got ${actualTypename}.`);
+  }
+}
+
+/**
+ * Loads a Game from a Ref and resolves its variant state, asserting the variant matches
+ * the expected type. Returns the typed pair.
+ *
+ * Use in operation handlers that declare `input.game: GameRef<MyVariantState>`.
+ */
+export const loadGame = <S extends Type.AnyObj>(
+  ref: Ref.Ref<Game>,
+  variantType: S,
+): Effect.Effect<{ game: Game; variant: Type.InstanceType<S> }, Error, Database.Service> =>
+  Effect.gen(function* () {
+    const game = yield* Database.load(ref);
+    const variant = yield* Database.load(game.variant);
+    if (!Obj.instanceOf(variantType, variant)) {
+      const expected = Type.getTypename(variantType) ?? 'unknown';
+      const actual = Obj.getTypename(variant as Obj.Any) ?? 'unknown';
+      return yield* Effect.fail(new GameVariantMismatchError(game.id, expected, actual));
+    }
+    return { game, variant: variant as Type.InstanceType<S> };
+  });

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}