Type Alias Expr

Type Declaration

• { kind: "constF32"; value: number }
• { kind: "constVec2"; value: [number, number] }
• { kind: "constVec3"; value: [number, number, number] }
• { kind: "constVec4"; value: [number, number, number, number] }
• { kind: "attribute"; attr: ParticleAttribute }

  Reads a particle attribute. Type matches the attribute (see ParticleAttribute).

• { kind: "time" }

  Reads the engine time uniform (uniforms.time, seconds since pass start).

• { kind: "deltaTime" }

  Reads the per-frame delta-time uniform (uniforms.dt, seconds).

• { kind: "particleId" }

  Reads the particle's slot index as an f32 (handy as a per-particle constant).

• { kind: "emitterOrigin" }

  Reads the emitter origin (world-space, after the GameObject transform). vec3.

• { kind: "random"; mode: RandomMode; min: number; max: number; seed: number }

  Uniform random float in [min, max]. Seed source depends on RandomMode.

• { kind: "variable"; name: string }

  Reference to a local variable declared in the same graph.

• { kind: "unary"; op: UnaryOp; arg: Expr }
• { kind: "binary"; op: BinaryOp; lhs: Expr; rhs: Expr }
• { kind: "clamp"; value: Expr; min: Expr; max: Expr }
• { kind: "mix"; a: Expr; b: Expr; t: Expr }
• { kind: "smoothstep"; edge0: Expr; edge1: Expr; x: Expr }
• { kind: "select"; cond: Expr; whenTrue: Expr; whenFalse: Expr }

  Branchless selection: returns whenTrue if cond is true, else whenFalse. Both branches are evaluated; for control-flow use action.if_.

• { kind: "vec2"; x: Expr; y: Expr }
• { kind: "vec3"; x: Expr; y: Expr; z: Expr }
• { kind: "vec4"; x: Expr; y: Expr; z: Expr; w: Expr }
• { kind: "swizzle"; arg: Expr; channels: string }

  WGSL swizzle: swizzle(v, 'xz'), swizzle(c, 'rgb'), etc. channels must be 1–4 of [xyzwrgba].

• {
      kind: "patchSample";
      field: number;
      coord: Expr;
      filter: "nearest" | "bilinear";
  }

  Reads a patch (grid) field value at the world-space point coord (xz used as the ground plane). Returns f32. Only valid when the surrounding ParticleGraphConfig declares patchFields — used by the agent-modeling layer (turtles sensing a pheromone/diffusion grid). field indexes config.patchFields. filter picks nearest-cell vs bilinear sampling.

• { kind: "patchCell"; field: number; dx: number; dz: number }

  Reads a patch field value at a CELL offset (dx, dz) from the current cell. Only valid in the PATCH (cellular-automaton) context — the per-field update program of a PatchFieldDef, which runs once per grid cell. dx/dz are integer cell offsets (0,0 = this cell); they read the pre-step half so a CA sees a consistent snapshot of its neighborhood.

• {
      kind: "patchReduce";
      field: number;
      op: "mooreSum" | "mooreCountGt" | "vonNeumannSum";
      threshold: number;
  }

  Neighborhood reduction over the current cell's grid neighbors, for the PATCH (CA) context. mooreSum / vonNeumannSum sum the 8 / 4 surrounding cells of field; mooreCountGt counts how many of the 8 Moore neighbors exceed threshold (the building block for "live neighbors" / "burning neighbors").

• {
      kind: "neighbor";
      query: "count" | "meanPos" | "meanVel" | "sep" | "nearest" | "coneCount";
      radius: number;
      coneHalfAngle?: number;
      breed?: number;
  }

  Generic neighbor reduction over the agents within radius (the AgentScript inRadius family), evaluated against the spatial hash. query picks the reduction: count (f32 number of neighbors), meanPos (vec3 center of mass — cohesion; self position when none), meanVel (vec3 average velocity — alignment), sep (vec3 sum of normalized away-vectors — separation). Only valid in the UPDATE context when the surrounding ParticleGraphConfig declares spatialHash. XZ ground plane.

  nearest returns the offset vec3 to the closest neighbor within radius (zero when none). coneCount counts neighbors within radius AND inside a forward vision cone of half-angle coneHalfAngle (radians, about the heading) — the AgentScript in-cone.

  • kind: "neighbor"

  • query: "count" | "meanPos" | "meanVel" | "sep" | "nearest" | "coneCount"

  • radius: number

  • OptionalconeHalfAngle?: number

  • Optionalbreed?: number

    When set, restrict the reduction to neighbors of this breed id (color.a) — the AgentScript breed neighbor query. Only valid with count / nearest.

• {
      kind: "linkReduce";
      op: "min" | "max" | "sum" | "mean" | "count";
      attr: LinkAttr;
  }

  Reduction over THIS agent's link-neighbors (the AgentScript link-neighbors family) — read a scalar attribute of every agent this one is linked to and fold it. count is the degree (number of live link-neighbors); min/max/ sum/mean fold the chosen scalar attr (rotation/alpha/size, the free per-agent scalar channels). Empty-neighborhood defaults: min +1e30, max -1e30, sum/mean 0, count 0. UPDATE context only; requires config.links. The graph-relaxation building block: label propagation / connected components = min(self, linkReduceMin(label)); Bellman-Ford = min(self, linkReduceMin(dist) + edgeCost).

• { kind: "agentAttr"; idx: Expr; attr: ParticleAttribute }

  Random-access read of ANOTHER agent's attribute by index (idx is an f32 agent index, rounded + clamped to the live range). Reads the particles storage buffer directly, so it works for any attribute (position is a vec3, scalars f32). UPDATE context only. The building block for agents that reference other agents by id — e.g. a traveler reading the world position of the graph node it's walking toward (linktravel/roads). Reads the live buffer; point it at agents that don't mutate the read field mid-step (static graph nodes) to stay race-free.

• { kind: "linkSlot"; idx: Expr; slot: Expr }

  Read agent idx's link slot slot — the linked agent's index as f32, or -1 for an empty slot (idx/slot rounded + clamped). Lets an agent read the adjacency of ANOTHER node (not just its own links), so a traveler can pick the next node to walk to: linkSlot(node, floor(random*k)). UPDATE context only; requires config.links.

• { kind: "scratchGet"; slot: Expr }

  Read this agent's own scratch-array slot slot (f32; rounded + clamped to [0, slotsPerAgent)). The per-agent working array declared by config.scratch. UPDATE context only.

• { kind: "scratchAt"; agent: Expr; slot: Expr }

  Read ANOTHER agent's scratch slot — scratch[agent][slot] (both rounded + clamped). Lets an agent read a peer's working array (e.g. copy a better candidate in tournament local search). UPDATE context only; requires config.scratch.