@helixdev/helix-manifest 0.2.1-staging.8 → 0.3.0-staging.11

package/dist/src/index.d.ts

@@ -1,8 +1,9 @@
 export * from './bundle-rules';
 export declare const MANIFEST_FILENAME = "helix.json";
-export declare const MANIFEST_VERSIONS: readonly ["0.1", "0.2"];
+export declare const MANIFEST_VERSIONS: readonly ["0.1", "0.2", "0.3"];
 export declare const PERMISSIONS_V01: readonly ["auth.profile"];
-export type HelixPermission = (typeof PERMISSIONS_V01)[number];
+export declare const PERMISSIONS_V03: readonly ["auth.profile", "multiplayer", "voice.room", "voice.proximity"];
+export type HelixPermission = (typeof PERMISSIONS_V03)[number];
 /**
  * Bundle vocabulary, pinned for main-backend compatibility. A **system** is a
  * versioned runtime framework that hosts abilities (the humanoid character is
@@ -21,18 +22,375 @@ export type HelixBundleKind = (typeof BUNDLE_KINDS)[number];
  */
 export declare const MAIN_BACKEND_PACKAGE_TYPE: Record<HelixBundleKind, string>;
 export type HelixContentRating = 'unrated' | 'everyone' | 'teen' | 'mature';
+/**
+ * A declared custom-state variable's type + constraints (Tier 2 declared state — spec §5). The author
+ * declares names -> HelixVarType under `multiplayer.state`; the room realizes them as @colyseus/schema and
+ * interprets them. Value vocabulary: number | string | boolean | vec3 | ref (the id of a live player/entity).
+ * This is the DECLARATION home; the runtime value union (RoomVarValue) lives in the SDK multiplayer-contract.
+ */
+export type HelixVarType = {
+    type: 'number';
+    default: number;
+    min?: number;
+    max?: number;
+    integer?: boolean;
+} | {
+    type: 'string';
+    default: string;
+    maxLen?: number;
+    enum?: string[];
+} | {
+    type: 'boolean';
+    default: boolean;
+} | {
+    type: 'vec3';
+    default: [number, number, number];
+} | {
+    type: 'ref';
+    of: 'player' | `entity:${string}`;
+    default?: null;
+} | {
+    type: 'list';
+    of: 'number' | 'string' | 'boolean';
+    maxLen: number;
+} | {
+    type: 'counterMap';
+    keys: string[];
+};
+/** A declared bag of custom vars: name -> type. Names are identifiers (see the v0.3 schema pattern). */
+export type HelixVarDecls = Record<string, HelixVarType>;
+/** v0.3 (Tier 2 Phase 1.3): the per-world DECLARED state — room-level + per-player custom vars. */
+export type HelixMultiplayerState = {
+    roomVars?: HelixVarDecls;
+    playerVars?: HelixVarDecls;
+};
+export type HelixRuleEvent = {
+    on: 'tick';
+    everyN?: number;
+} | {
+    on: 'playerJoin';
+} | {
+    on: 'playerLeave';
+} | {
+    on: 'playerDisconnect' | 'playerReconnect';
+} | {
+    on: 'zoneEnter' | 'zoneExit' | 'zoneInside';
+    zone: string;
+} | {
+    on: 'playerContact';
+    radius: number;
+} | {
+    on: 'action';
+    name: string;
+} | {
+    on: 'stateEnter' | 'stateExit';
+    phase: string;
+} | {
+    on: 'timerElapsed';
+    timer: string;
+} | {
+    on: 'entitySpawn' | 'entityDestroy';
+    kind: string;
+} | {
+    on: 'ownershipChanged';
+    kind: string;
+} | {
+    on: 'varReached';
+    scope: 'room' | 'self';
+    var: string;
+    cmp: '==' | '!=' | '<' | '<=' | '>' | '>=';
+    value: number | string | boolean;
+};
+export type HelixExpr = number | string | boolean | {
+    vec3: [number, number, number];
+} | {
+    var: string;
+} | {
+    ref: HelixRef;
+    var: string;
+} | {
+    op: 'distance';
+    a: HelixExpr;
+    b: HelixExpr;
+} | {
+    op: '==' | '!=' | '<' | '<=' | '>' | '>=';
+    a: HelixExpr;
+    b: HelixExpr;
+} | {
+    op: '+' | '-' | '*' | '/';
+    a: HelixExpr;
+    b: HelixExpr;
+} | {
+    op: 'and' | 'or';
+    of: HelixExpr[];
+} | {
+    op: 'not';
+    of: HelixExpr;
+} | {
+    op: 'aggregate';
+    scope: 'players' | `zone:${string}` | `entities:${string}`;
+    agg: 'count' | 'sum' | 'min' | 'max' | 'avg';
+    field?: string;
+    where?: HelixExpr;
+    as?: string;
+} | {
+    op: 'timerRemaining';
+    timer: string;
+    key?: HelixRef;
+} | {
+    op: 'listLength';
+    list: string;
+} | {
+    op: 'listAt';
+    list: string;
+    index: HelixExpr;
+} | {
+    op: 'count';
+    map: string;
+    key: string;
+} | {
+    op: 'randomPoint';
+    min: [number, number, number];
+    max: [number, number, number];
+} | {
+    op: 'playerCount' | 'random' | 'timeInState';
+};
+export type HelixRef = string | {
+    var: string;
+} | {
+    op: 'nearestPlayer';
+    from: HelixExpr;
+} | {
+    op: 'nearestEntity';
+    from: HelixExpr;
+    kind?: string;
+} | {
+    op: 'aggregate';
+    scope: 'players' | `zone:${string}` | `entities:${string}`;
+    agg: 'argmax' | 'argmin';
+    field: string;
+    where?: HelixExpr;
+    as?: string;
+};
+export type HelixLvalue = string | {
+    ref: HelixRef;
+    var: string;
+};
+export type HelixBroadcastTarget = 'all' | HelixRef | {
+    team: string;
+};
+export type HelixRuleEffect = {
+    do: 'add';
+    target: HelixLvalue;
+    by: HelixExpr;
+} | {
+    do: 'set';
+    target: HelixLvalue;
+    to: HelixExpr;
+} | {
+    do: 'setRef';
+    target: HelixLvalue;
+    to: HelixRef | null;
+} | {
+    do: 'teleport' | 'respawn';
+    player: HelixRef;
+    to: HelixExpr;
+} | {
+    do: 'forEachPlayer';
+    as: string;
+    where?: HelixExpr;
+    then: HelixRuleEffect[];
+} | {
+    do: 'forEachEntity';
+    kind: string;
+    as: string;
+    where?: HelixExpr;
+    then: HelixRuleEffect[];
+} | {
+    do: 'transitionTo';
+    phase: string;
+} | {
+    do: 'startTimer';
+    timer: string;
+    seconds: number;
+    key?: HelixRef;
+} | {
+    do: 'cancelTimer';
+    timer: string;
+    key?: HelixRef;
+} | {
+    do: 'broadcast';
+    event: string;
+    to: HelixBroadcastTarget;
+    payload?: Record<string, HelixExpr | HelixRef>;
+} | {
+    do: 'spawnEntity';
+    kind: string;
+    at: HelixExpr;
+    vars?: Record<string, HelixExpr | HelixRef>;
+    bind?: 'spawned';
+} | {
+    do: 'destroyEntity';
+    entity: HelixRef;
+} | {
+    do: 'requestOwnership' | 'takeover';
+    entity: HelixRef;
+    to: HelixRef | null;
+} | {
+    do: 'append';
+    target: string;
+    value: HelixExpr;
+} | {
+    do: 'clear';
+    target: string;
+} | {
+    do: 'addCount';
+    target: string;
+    key: string;
+    by: HelixExpr;
+};
+export type HelixRule = {
+    when: HelixRuleEvent;
+    if?: HelixExpr;
+    then: HelixRuleEffect[];
+};
+export type HelixStateMachine = {
+    initial: string;
+    phases: string[];
+    joinPolicy?: Record<string, {
+        joinable?: boolean;
+        onLateJoin?: HelixRuleEffect[];
+    }>;
+};
+export type HelixTimer = {
+    keyed?: 'player' | `entity:${string}`;
+};
+export type HelixFieldType = {
+    type: HelixVarType['type'];
+    of?: 'player' | `entity:${string}`;
+};
+export type HelixEventDecl = {
+    payload?: Record<string, HelixFieldType>;
+};
+export type HelixActionArgType = {
+    type: 'number';
+    min?: number;
+    max?: number;
+    integer?: boolean;
+} | {
+    type: 'string';
+    maxLen?: number;
+    enum?: string[];
+} | {
+    type: 'boolean';
+} | {
+    type: 'vec3';
+} | {
+    type: 'ref';
+    of: 'player' | `entity:${string}`;
+};
+export type HelixActionDecl = {
+    args?: Record<string, HelixActionArgType>;
+};
+export type HelixZone = {
+    id: string;
+    tracks?: 'players' | `entity:${string}`;
+    requireDwell?: number;
+    debounce?: number;
+} & ({
+    shape: 'box';
+    center: [number, number, number];
+    size: [number, number, number];
+} | {
+    shape: 'sphere';
+    center: [number, number, number];
+    radius: number;
+});
+export type HelixEntityMotion = {
+    type: 'static';
+} | {
+    type: 'linear';
+    velocity: [number, number, number];
+} | {
+    type: 'orbit';
+    center: [number, number, number];
+    radius: number;
+    speed: number;
+} | {
+    type: 'waypoints';
+    points: [number, number, number][];
+    speed: number;
+    loop?: boolean;
+} | {
+    type: 'seek';
+    target: string;
+    speed: number;
+};
+export type HelixAttachedZone = {
+    offset?: [number, number, number];
+    tracks?: 'players' | `entity:${string}`;
+    requireDwell?: number;
+    debounce?: number;
+} & ({
+    shape: 'box';
+    size: [number, number, number];
+} | {
+    shape: 'sphere';
+    radius: number;
+});
+export type HelixEntity = {
+    vars?: HelixVarDecls;
+    motion?: HelixEntityMotion;
+    zone?: HelixAttachedZone;
+    authority?: 'server' | 'owner';
+    maxSpeed?: number;
+    shared?: boolean;
+    idleTimeout?: number;
+    ownerLifecycle?: 'despawnWithOwner' | 'persist' | 'migrateToServer' | 'hostMigrate';
+    transferPolicy?: 'fixed' | 'request' | 'takeover';
+};
+export type HelixMultiplayerConfig = {
+    /** Advisory interest radius in meters (drives later StateView interest management; may be ignored in v1). */
+    interestRadius?: number;
+    /**
+     * Minimum players the world needs to be playable (Tier 2 Phase 4.5, spec §14). Default 1 = single-player-safe:
+     * the single-player gate then warns (strict → error) if a phase transition is gated on playerCount ≥ 2, since a
+     * solo player would be soft-locked. Set ≥ 2 to declare a genuinely multiplayer-only world (the gate stands down).
+     */
+    minPlayers?: number;
+    /** Server owns authoritative state + validates inputs (Tier 1). Defaulted to true; leave it true in v1. */
+    authoritative?: boolean;
+    /** Declared per-world custom state (roomVars + per-player vars); the room realizes + interprets it. */
+    state?: HelixMultiplayerState;
+    /** Declared entity archetypes (Tier 2 Phase 4, spec §9): kind name -> { vars }. spawnEntity/destroyEntity reference them; the room realizes per-kind schema + syncs the entities collection. */
+    entities?: Record<string, HelixEntity>;
+    /** Declared room-scoped state machine (Tier 2 Phase 3, spec §8): the phase set + the initial phase. */
+    states?: HelixStateMachine;
+    /** Declared timers (Tier 2 Phase 3, spec §8): name -> {}. startTimer/cancelTimer/timerElapsed/timerRemaining reference them. */
+    timers?: Record<string, HelixTimer>;
+    /** Declared static spatial zones (Tier 2 Phase 2.3, spec §6) — the room tests membership each tick. */
+    zones?: HelixZone[];
+    /** Declared server→client broadcast events (Tier 2 Phase 2.5, spec §10.3): name -> payload schema. */
+    events?: Record<string, HelixEventDecl>;
+    /** Declared client→server actions (Tier 2 Phase 2.5b, spec §11.5): name -> { typed arg schema }. */
+    actions?: Record<string, HelixActionDecl>;
+    /** Declared behavior rules (Tier 2 Phase 2, spec §7) — the room evaluates them in declared order per tick. */
+    rules?: HelixRule[];
+};
 /**
  * contentRating → main-backend ContentRating. 'unrated' has no counterpart there (their enum is
  * Everyone/Teen/Mature) — an unrated bundle cannot federate into the catalog until it is rated.
  */
 export declare const MAIN_BACKEND_CONTENT_RATING: Record<HelixContentRating, 'Everyone' | 'Teen' | 'Mature' | null>;
 export type HelixManifest = {
-    helixVersion: '0.1' | '0.2';
+    helixVersion: '0.1' | '0.2' | '0.3';
     title: string;
     slug: string;
     entry: string;
     maxPlayers?: number;
     permissions?: HelixPermission[];
+    /** v0.3: present only on multiplayer worlds. */
+    multiplayer?: HelixMultiplayerConfig;
     supportsMobile?: boolean;
     requiresAuth?: boolean;
     contentRating?: HelixContentRating;
@@ -45,15 +403,84 @@ export type HelixManifest = {
     /** v0.2: pinned ability dependencies (slug -> semver range), resolved + baked at build. */
     abilities?: Record<string, string>;
 };
-export type NormalizedHelixManifest = Required<Omit<HelixManifest, 'systems' | 'abilities'>> & Pick<HelixManifest, 'systems' | 'abilities'>;
+export type NormalizedHelixManifest = Required<Omit<HelixManifest, 'systems' | 'abilities' | 'multiplayer'>> & Pick<HelixManifest, 'systems' | 'abilities' | 'multiplayer'>;
 export type ManifestValidationResult = {
     valid: true;
     manifest: NormalizedHelixManifest;
+    warnings: string[];
 } | {
     valid: false;
     errors: string[];
 };
-export declare function validateManifest(data: unknown): ManifestValidationResult;
+export declare const PLATFORM_MAX_PLAYERS_PER_ROOM = 24;
+export declare const MULTIPLAYER_CAPS: {
+    /** Declared room-level vars. */
+    readonly roomVars: 64;
+    /** Declared per-player vars (these are realized once PER PLAYER at runtime, so the effective cost scales). */
+    readonly playerVars: 64;
+    /** Ceiling on a string var's declared `maxLen` (bounds a single synced string). */
+    readonly stringMaxLen: 1024;
+    /** Values in a string var's `enum`. */
+    readonly enumValues: 64;
+    /** Ceiling on a `list` collection var's declared `maxLen` (4.5.13 — bounds a single synced array). */
+    readonly listMaxLen: 256;
+    /** Keys in a `counterMap` collection var's declared key enum (4.5.13). */
+    readonly counterKeys: 64;
+    /** Declared behavior rules (Tier 2 Phase 2). */
+    readonly rules: 128;
+    /** Effects in a single rule's `then`. */
+    readonly ruleThen: 16;
+    /** Max nesting depth of a condition expression (`if`). */
+    readonly exprDepth: 8;
+    /** Max total nodes in a single condition expression. */
+    readonly exprNodes: 64;
+    /** Declared state-machine phases (Tier 2 Phase 3, spec §8). One room-scoped machine; this caps its phase set. */
+    readonly phases: 32;
+    /** Declared timers (Tier 2 Phase 3, spec §8). Each active timer (room-scoped, or × live members when keyed in
+     *  3.3) reifies a deadline into synced state — this caps the declared name count. */
+    readonly timers: 32;
+    /** Floor on a `startTimer` duration (seconds) = one sim tick (1/20s). A shorter timer can't resolve below the
+     *  tick rate; rejecting it stops a 0s timer from same-tick start→elapse churn. MUST track the room's SIM_HZ. */
+    readonly timerMinSeconds: 0.05;
+    /** Effects in a single phase's `joinPolicy.onLateJoin` (Tier 2 Phase 3.5). Runs once per late join (≤ player
+     *  cap/tick), so it's bounded like a playerJoin rule's `then`. */
+    readonly joinPolicyEffects: 16;
+    /** §3.6/§11.3 cascade-drain depth — the longest within-tick chain of stateEnter/stateExit → transitionTo →
+     *  stateEnter… Computed statically at publish (a cycle is rejected outright); a config whose chain exceeds
+     *  this fails publish. Bounds the ×(1+maxCascadeDepth) budget term + MUST stay ≤ the room's MAX_CASCADE_DEPTH
+     *  runtime backstop (helix-colyseus-server src/tuning.ts). */
+    readonly maxCascadeDepth: 16;
+    /** Declared zones (Tier 2 Phase 2.3). Membership is O(members × zones)/tick, both capped. */
+    readonly zones: 64;
+    /** Declared broadcast events (Tier 2 Phase 2.5). */
+    readonly events: 64;
+    /** Fields in a single broadcast event's payload. */
+    readonly broadcastFields: 16;
+    /** Declared client→server actions (Tier 2 Phase 2.5b). */
+    readonly actions: 64;
+    /** Args in a single action's schema. */
+    readonly actionArgs: 16;
+    /** Declared entity archetypes (Tier 2 Phase 4, spec §9). */
+    readonly entityKinds: 32;
+    /** Max declared vars per entity kind (realized once PER live entity at runtime, so the effective cost scales). */
+    readonly entityVars: 64;
+    /** Max live entities of a single kind in a room — bounds the synced entities collection + per-tick entity work.
+     *  Enforced at RUNTIME (a spawn over the cap is skipped + counted in the H3 metric, never throws). */
+    readonly entitiesPerKind: 256;
+    /** Ceiling on a zone's extent — any box dimension or a sphere radius, in meters. A sanity bound (a zone
+     *  test is O(1) regardless of size), generous enough for whole-level kill-planes. */
+    readonly zoneMaxExtent: 10000;
+    /** §11.2 per-tick budget — the worst-case node-evaluations across ALL rules in one tick: Σ over rules of
+     *  fireCount(event) × ruleCost, where reductions (aggregate/nearest*) + forEach fanout are weighted by the
+     *  player cap and contact events by playerCap², all ×(1 + maxCascadeDepth) for the Phase-3 cascade drain
+     *  (analyzeCascade computes the cycle-free longest chain). Over this → publish fails. PROVISIONAL: a generous
+     *  bound that catches pathological configs; the precise number wants the S6 load test. */
+    readonly tickNodeBudget: 100000;
+};
+export declare const VAR_TYPES: readonly ["number", "string", "boolean", "vec3", "ref", "list", "counterMap"];
+export declare function validateManifest(data: unknown, opts?: {
+    strict?: boolean;
+}): ManifestValidationResult;
 export declare function parseManifest(json: string): ManifestValidationResult;
 export declare const PACKAGE_ENVELOPE_VERSION: "1";
 export type HelixPackageEnvelope = {