@gameable/bundle

Interfaces

BundleFile

A hashed payload. manifest.json describes these files and is not itself a payload.

Example

import type { BundleFile } from 'gameable/bundle';
const file: BundleFile = { path: 'assets/empty.bin', bytes: 0,
  sha256: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
  contentType: 'application/octet-stream' };
console.log(file.path);

Properties

bytes

readonly bytes: number;

contentType

readonly contentType: string;

from?

readonly optional from?: string;

Version in the same game containing this path; schema 3 only.

path

readonly path: string;

sha256

readonly sha256: string;

---

BundleIdentity

Game identity independent of the build payloads.

Example

import type { BundleIdentity } from 'gameable/bundle';
const identity: BundleIdentity = { gameId: 'tiny-game', version: '1.0.0', slug: 'tiny-game' };
console.log(identity.gameId);

Properties

gameId

readonly gameId: string;

slug

readonly slug: string;

version

readonly version: string;

---

EngineComposition

Exact versions of the implementations included in a runtime.

Example

const composition: EngineComposition = { compositionId: '0123456789abcdef', core: '1.0.0', modules: [], guestContract: 'gameable:engine@0.2.0' };
console.log(composition.core);

Properties

compositionId

readonly compositionId: string;

core

readonly core: string;

guestContract

readonly guestContract: string;

modules

readonly modules: readonly object[];

runtimeDigest?

readonly optional runtimeDigest?: string;

SHA-256 of sorted runtime paths and content hashes; absent on legacy runtimes.

---

GameCard

Slim researched card metadata used by deterministic lookup.

Example

const card: GameCard = gameIndex().games[0];
console.log(card.id);

Properties

aliases

aliases: string[];

camera

camera: string;

category

category: string;

id

id: string;

juice?

optional juice?: string[];

movement

movement: string;

name

name: string;

players

players: object;

local_or_online?

optional local_or_online?: string;

max

max: string | number;

min

min: string | number;

mode

mode: string;

routing

routing: object;

genres

genres: string[];

keywords

keywords: string[];

template

template: string;

template_status

template_status: string;

ui_sources?

optional ui_sources?: string[];

ui_style?

optional ui_style?: object;

layout

layout: string;

notes

notes: string;

palette

palette: string[];

screens

screens: string[];

typography

typography: string;

---

GameIndex

Replaceable routing index; full specifications remain in games/<id>.md.

Example

const index: GameIndex = gameIndex();
console.log(index.templates.kart.base);

Properties

ambiguous_aliases

ambiguous_aliases: Record<string, string[]>;

games

games: GameCard[];

templates

templates: Record<string, {
  base: string;
  camera: string;
  status: string;
}>;

---

GameLookup

JSON lookup contract, including evidence and the starting template.

Example

const result: GameLookup = findGames('pacman');
console.log(result.start?.card);

Properties

ambiguous

ambiguous: 
  | {
  alias: string;
  ids: string[];
}
  | null;

matchedBy

matchedBy: "name" | "mechanics" | "none";

matches

matches: Pick<GameCard, "ui_style" | "juice" | "ui_sources"> & object[];

request

request: string;

start

start: 
  | {
  card: string;
  from: "none" | "template" | "base";
  instruction: string;
  template: string | null;
}
  | null;

threshold

threshold: number;

uncovered

uncovered: string[];

unsupported

unsupported: boolean;

weakMatch

weakMatch: boolean;

---

TemplateManifest

Agent routing metadata, independent of a compiled bundle's payload manifest. Empty settings means the legacy template only exposes its TypeScript rules.

Example

const manifest = validateTemplateManifest(await (await fetch('template.json')).json());
console.log(manifest.id);

Properties

camera

readonly camera: readonly ("first-person" | "orbit" | "fixed" | "third-person")[];

description

readonly description: string;

examplePrompts

readonly examplePrompts: readonly string[];

exclude?

readonly optional exclude?: readonly string[];

genres

readonly genres: readonly string[];

id

readonly id: string;

input

readonly input: readonly ("keyboard-mouse" | "touch" | "gamepad" | "pointer")[];

keywords

readonly keywords: readonly string[];

limits

readonly limits: readonly string[];

modules

readonly modules: readonly string[];

multiplayer

readonly multiplayer: object;

maxSeats

readonly maxSeats: number;

minSeats

readonly minSeats: number;

notSupported

readonly notSupported: readonly string[];

schemaVersion

readonly schemaVersion: 1;

settings

readonly settings: object;

file

readonly file: string;

keys

readonly keys: Readonly<Record<string, TemplateSetting>>;

title

readonly title: string;

---

TemplateMatch

Ranked candidate and the evidence behind its score on a 0–1 scale.

Example

const matches = scoreTemplates([], { genres: ['adventure'] });
console.log(matches.length);

Properties

reasons

readonly reasons: readonly string[];

score

readonly score: number;

template

readonly template: TemplateManifest;

weakMatch

readonly weakMatch: boolean;

---

TemplateRequest

Structured brief; multiplayer is the requested number of simultaneous seats.

Example

const request: TemplateRequest = { genres: ['racing'], multiplayer: 12 };
console.log(request.multiplayer);

Properties

camera?

readonly optional camera?: "first-person" | "orbit" | "fixed" | "third-person";

genres?

readonly optional genres?: readonly string[];

keywords?

readonly optional keywords?: readonly string[];

multiplayer?

readonly optional multiplayer?: number;

Type Aliases

BundleManifest

type BundleManifest = BundleIdentity & 
  | {
  engine: {
     guestContract: string;
     version: string;
  };
  modules: readonly object[];
  schemaVersion: 1;
}
  | {
  engine: EngineComposition;
  schemaVersion: 2 | 3;
} & object;

Portable game identity, compatibility requirements and complete payload inventory.

Type Declaration

assets

readonly assets: "assets.json";

files

readonly files: readonly BundleFile[];

guest

readonly guest: object;

guest.entry

readonly entry: string;

settings

readonly settings: "settings.json";

Example

import { validateBundleManifest, type BundleManifest } from 'gameable/bundle';
const value: unknown = JSON.parse(await (await fetch('./manifest.json')).text());
const manifest: BundleManifest = validateBundleManifest(value);
console.log(manifest.gameId);

---

TemplateSetting

type TemplateSetting = 
  | {
  integer?: boolean;
  max: number;
  min: number;
  type: "number";
}
  | {
  maxLength: number;
  type: "string";
}
  | {
  type: "boolean";
}
  | {
  type: "enum";
  values: readonly string[];
};

Bounded scalar settings that an agent may edit in the named JSON document.

Example

const setting: TemplateSetting = { type: 'number', min: 0, max: 10 };
console.log(setting.type);

Functions

canonicalComposition()

function canonicalComposition(composition): string;

Canonical composition JSON: exact core and modules sorted by ASCII id.

Parameters

Parameter	Type	Description
composition	Pick<EngineComposition, "core" | "modules">	Exact runtime versions.

Returns

string

Stable JSON to hash or compare; the guest contract is checked separately.

Example

console.log(canonicalComposition({ core: '1.0.0', modules: [] }));

---

compositionId()

function compositionId(composition): Promise<string>;

Derive the runtime id from canonical versions and the built runtime digest. Legacy compositions without a digest retain their original version-only id.

Parameters

Parameter	Type	Description
composition	Pick<EngineComposition, "core" | "modules" | "runtimeDigest">	Exact runtime versions and build digest.

Returns

Promise<string>

First 16 lowercase hex characters of SHA-256.

Example

console.log(await compositionId({ core: '1.0.0', modules: [], runtimeDigest: 'a'.repeat(64) }));

---

findGames()

function findGames(request, options?): GameLookup;

Look up game names first, then rank mechanics with deterministic weighted evidence. Without a name match, the top match is weak below the score threshold, with fewer than two distinct matched request terms, or when a request with at least two keywords has none covered. Mechanics matches expose this count as matched across genres, keywords, camera, movement and players. Unsupported matches are always weak. Only positive-score mechanics matches are returned, so results may contain fewer entries than the limit.

Parameters

Parameter	Type	Description
request	string	A game name, alias or mechanics description.
options	{ index?: GameIndex; limit?: number; threshold?: number; }	Result count (default 3), weak threshold (default 0.5), or replacement index.
options.index?	GameIndex	Replacement routing catalog.
options.limit?	number	Maximum results, default 3.
options.threshold?	number	Weak-match cutoff, default 0.5.

Returns

GameLookup

JSON-serialisable matches, template instructions and uncovered requirements.

Example

console.log(findGames('make a mario kart').start);

---

gameIndex()

function gameIndex(): GameIndex;

Return the bundled slim research index.

Returns

GameIndex

Routing metadata for the researched cards.

Example

console.log(gameIndex().games.length);

---

isBundleVersion()

function isBundleVersion(value): value is string;

Validate an exact semantic version, including prerelease and build metadata.

Parameters

Parameter	Type	Description
value	unknown	The candidate version.

Returns

value is string

Whether it is valid semver.

Example

import { isBundleVersion } from 'gameable/bundle';
console.log(isBundleVersion('1.2.3-beta.1+build'));

---

scoreTemplates()

function scoreTemplates(
   templates, 
   request, 
   threshold?
): TemplateMatch[];

Rank installed templates by genre (4), camera (3), seats (3), and keywords (2). Only supplied dimensions enter the denominator. Incompatible camera/seats are always weak matches; ties sort by id. No evidence scores zero.

Parameters

Parameter	Type	Default value	Description
templates	readonly TemplateManifest[]	undefined	Validated manifests.
request	TemplateRequest	undefined	Structured brief (keywords may contain phrases).
threshold	number	0.5	Minimum confidence, default 0.5.

Returns

TemplateMatch[]

All candidates, strongest first, with matching and conflicting reasons.

Example

console.log(scoreTemplates([], { genres: ['racing'], multiplayer: 12 }));

---

validateBundleIdentity()

function validateBundleIdentity(value): BundleIdentity;

Validate identity before constructing an output directory or compiling a guest.

Parameters

Parameter	Type	Description
value	unknown	Candidate game identity.

Returns

BundleIdentity

The validated identity.

Example

import { validateBundleIdentity } from 'gameable/bundle';
console.log(validateBundleIdentity({ gameId: 'tiny-game', version: '1.0.0', slug: 'tiny-game' }));

---

validateBundleManifest()

function validateBundleManifest(value): BundleManifest;

Parse and validate a version 1 or 2 manifest, throwing on malformed input.

Parameters

Parameter	Type	Description
value	unknown	Parsed JSON from a bundle manifest.

Returns

BundleManifest

The validated manifest.

Example

import { validateBundleManifest } from 'gameable/bundle';
const value: unknown = await (await fetch('./manifest.json')).json();
console.log(validateBundleManifest(value).guest.entry);

---

validateBundlePath()

function validateBundlePath(value): asserts value is string;

Reject paths that cannot safely be resolved below a bundle directory.

Parameters

Parameter	Type	Description
value	unknown	A bundle-relative file path.

Returns

asserts value is string

Example

import { validateBundlePath } from 'gameable/bundle';
validateBundlePath('guest/game.js');

---

validateEngineComposition()

function validateEngineComposition(value): EngineComposition;

Validate the readable runtime metadata, without hashing it.

Parameters

Parameter	Type	Description
value	unknown	Candidate metadata.

Returns

EngineComposition

Validated metadata.

Example

const composition = validateEngineComposition(await (await fetch('composition.json')).json());
console.log(composition.core);

---

validateTemplateManifest()

function validateTemplateManifest(value): TemplateManifest;

Validate a versioned agent manifest, rejecting unknown fields and unsafe settings paths.

Parameters

Parameter	Type	Description
value	unknown	Parsed template.json.

Returns

TemplateManifest

Validated metadata.

Example

const data: unknown = await (await fetch('template.json')).json();
console.log(validateTemplateManifest(data).title);

---

validateTemplateSettings()

function validateTemplateSettings(manifest, patch): void;

Validate an agent's scalar settings patch against the allowlist before writing JSON.

Parameters

Parameter	Type	Description
manifest	TemplateManifest	Validated template metadata.
patch	Readonly<Record<string, unknown>>	Dotted keys and their proposed values.

Returns

void

Example

validateTemplateSettings(validateTemplateManifest(await (await fetch('template.json')).json()), {});