feuerwerk/src/core/graph/lookup.ts

import type { AnimationClip } from '../model/animation';
import type { VectorPoint } from '../model/Asset';
import type { PropertyBag } from '../model/Properties';
import type { DeclaredPort, Graph } from './Graph';

/** What running another behavior's graph in place needs: its nodes, its variable defaults, its name. */
export interface BehaviorProgram {
  name: string;
  graph: Graph;
  defaults: PropertyBag;
  /** The variables a call hands on to the next call from the same site (#229); absent is none. */
  kept?: readonly string[];
}

export interface ShaderFunction {
  name: string;
  graph: Graph;
}

/**
 * A sound FX as a node naming it sees it: the parameters its Input declares (#311). An instrument
 * looks the same from outside, with the parameters of its Parameters node (#331).
 */
export interface SoundFxShape {
  name: string;
  params: readonly DeclaredPort[];
}

/** One state of a machine: the node id is what a port and the runtime hold, the name is the label. */
export interface MachineState {
  id: string;
  name: string;
}

/**
 * An allowed move between two states, both named by state node id, under the name `State
 * transition` asks for. The name is empty until someone gives the transition one.
 */
export interface MachineTransition {
  from: string;
  to: string;
  name: string;
}

export interface StateMachine {
  name: string;
  states: MachineState[];
  transitions: MachineTransition[];
  /** Id of the state every instance begins in, empty when the machine has no start (see #55). */
  start: string;
}

/**
 * What a node may look up in the project around its graph: the behaviors it can run, the state
 * machines it can read, the curves a `Lerp` eases along (#247) and the struct types `Add item`
 * checks (#254), what a variable written by a graph is held to (#271), how long an animation is
 * (#233) and what the collision and render layers are called (#211, #305). One handle, so no caller
 * can resolve a node with half of it.
 */
export interface GraphLookup {
  behavior(assetId: string): BehaviorProgram | null;
  /** A shader function's graph, which a call node takes its ports from and the compiler sets in (#303). */
  shaderFunction(assetId: string): ShaderFunction | null;
  soundFx(assetId: string): SoundFxShape | null;
  machine(assetId: string): StateMachine | null;
  curve(assetId: string): readonly VectorPoint[] | null;
  /** A Struct asset as a run knows it: a name and field names, nothing else travels (#254). */
  structType(assetId: string): StructShape | null;
  /** A texture's, frame's or pixel-art frame's own size in pixels; null for no picture. */
  textureSize(pictureId: string): { w: number; h: number } | null;
  /** An animation's length and playback, for a node that asks where a player stands in it (#233). */
  animation(assetId: string): AnimationClip | null;
  /** The project's collision layers by number, as `Layer of` names them (#211). */
  collisionLayers(): readonly string[];
  /** The project's render layers by number, as `Render layer of` names them (#305). */
  renderLayers(): readonly string[];
  /** The asset whose graph this is, `''` for none. */
  ownerOf(graph: Graph): string;
  /** What a variable of that asset declares about the structs it holds (#271); none for nothing typed. */
  variableTyping(assetId: string, key: string): ValueTyping | undefined;
}

export interface StructShape {
  name: string;
  fields: readonly string[];
  /** What the type's fields declare in turn, for those that declare anything. */
  inner: Readonly<Record<string, ValueTyping>>;
}

/**
 * What a written value is held to (#271): the Struct asset it is, the one every item of it is, and
 * what its fields declare. Only the ids travel; a run asks `structType` for the rest.
 */
export interface ValueTyping {
  structType?: string;
  itemType?: string;
  fields?: Readonly<Record<string, ValueTyping>>;
}

export const NO_LOOKUP: GraphLookup = {
  behavior: () => null,
  shaderFunction: () => null,
  soundFx: () => null,
  machine: () => null,
  curve: () => null,
  structType: () => null,
  textureSize: () => null,
  animation: () => null,
  collisionLayers: () => [],
  renderLayers: () => [],
  ownerOf: () => '',
  variableTyping: () => undefined,
};