Skip to content

Shaders, Scene3D, and particles

Supported authored schema: 110. Use the structural schema for every variant’s fields and the catalog for exact IDs, ports, defaults, and named kinds.

shaderAssets holds reusable shader patches, while placed shader nodes carry patch configuration in a layer graph. shaderFunctions holds graph or WGSL functions. catalog.shaderGraphNodes describes shader graph nodes and their config defaults and port types. A shader card composes over Previous Pass. Previous Frame reads that card’s retained output from the preceding frame. sharedTextures names cross-card outputs; producers and consumers must agree on IDs and field types. Shared Texture Routing shows a working path.

For custom WGSL, transparent fragColor leaves Previous Pass visible; it does not cut a hole in that input. Use a separate transparent layer for a cutout. Keep fine height fields on a scalar Shared Texture rather than passing them through display color. A held feedback Clear prevents new history from accumulating; release it after resetting or replacing the source.

New Sample Source, Source Info, and Source Audio nodes select Rack Sources directly; an empty inputId means None. Legacy layer inputId, layer-input bindings, and hidden TrackSource nodes retain playback compatibility. Upgrading schemas 101–109 records old implicit shader selections explicitly before the default changes.

scene3DResources contains the scene graph and output resources; layer graph scene cards refer to them. scene3DShaders and scene3DMaterials hold typed surface definitions. Entities, cameras, lights, materials, model assets, environment maps, and output membership have distinct schema variants. catalog.scene3DEntityKinds and catalog.scene3DMaterialTypes list the current discriminants. Models and environments use stable project-asset: IDs. Reflective 3D Skull is a portable example.

particleTemplates contains staged emitter, spawn, initialize, update, event, and render modules plus runtime settings. particleModules carries project-authored custom simulation definitions used by custom-sim. A placed layer graph particle card names a template ID. The catalog lists all current particleModuleTypes; the JSON Schema provides each module’s fields. Particle Drift has a staged template and a visible layer card. Keep a referenced custom module and its template in the same project.

For 2D particles, color-from-texture.sampleTiming chooses birth or continuous sampling; omitted values use birth behavior. Continuous mode refreshes color after motion, then Color By Speed tints that sample; Color Over Life replaces RGB. Custom Spawn, Initialize, or Update modules that write color are overridden by the refresh, so put custom color writes in Event. The last enabled force-texture module supplies luminance at each particle’s current position to Drag, Curl Noise, Attractor, and Turbulence modules that set strengthFromTexture: true. Forces without that flag keep their original strength.

simulationDefinitions and simulationInstances describe portable numerical programs. A definition declares typed state, named parameters and inputs, versioned kernel interfaces, reusable helpers, queries, initialize/step programs and outputs. An instance selects a definition and owns its domain, seed, parameter values, input bindings, fixed clock and quality settings. Duplicated instances evolve independently. These records are available for local experimental authoring; normal production execution and Portal uploads remain disabled.

The catalog’s simulation entry lists capability IDs, value types, contexts and operations. simulationTemplates.surfaceAggregate is a complete definition built from those public operations. The JSON Schema describes each record; local validation also checks references, capacity budgets and supported kernel source. Known-format unsupported versions remain editable and produce activation diagnostics.

Field domain.extent contains positive integer cell counts; spacing contains physical cell size. A 128 × 128 field with spacing [1/128, 1/128] covers one physical unit per axis. Instance domain extents are physical sizes. Definitions support two or three dimensions. A two-dimensional field or field input inside a three-dimensional definition declares plane: {origin,u,v} with orthonormal three-dimensional axes. Kernel cell/sample coordinates retain the resource’s own dimension.

WGSL kernels declare value inputs, logical reads and named result fields. Reads use read_<local name> and the invocation context is ctx: KernelContext; results use KernelResult. Pure helpers use HelperResult. Operations map named outputs to state writes. Only statically bounded for loops are supported; integer loop inputs declare a maximum. Importing or namespacing definitions preserves the authored source body and local aliases.

A particle view stores simulationView2D on a shader card. A field view uses { "kind": "simulation-output", "simulationId": "instance-id", "outputId": "definition-output-id" } as a texture reference and explicitly converts numeric data to display color. Consumers read the last completed tick. Simulation inputs cannot depend on another simulation, directly or through a layer or shared texture; interacting materials share one simulation domain.

Native volume bindings use {kind: "simulation-volume", source: outputRef} in the shader card’s separate simulationVolumes array, with at most four slots. SampleSimulationVolume samples floating scalar/vector volume data directly. SliceSimulationVolume and ProjectSimulationVolume produce an ordinary two-dimensional texture binding with kind: "simulation-volume-image", version: 1, the native source, an explicit physical plane, physicalExtent, pixel size, and nearest/linear sampling. Projection also declares a normal-axis range, max/mean/integral reduction and bounded sample count. Integer solver fields support logical cell reads and report an unsupported native display diagnostic.

Query records 1 and 2 retain the same variable-radius policy: an unordered pair within one set uses the lower logical ID’s radius; a cross-set pair uses the source element’s radius. motionMargin extends that radius. Query 2 adds conservative swept point/line/triangle bounds without changing this saved policy. A symmetric pair support should be authored as a shared radius; importing an older graph does not silently change its neighborhood.

A stream may declare capacityFrom: {kind: "sum" | "max", sources: [{stateId, multiplier}], minimum?: number} with capability feature/derived-capacity/1. Sources use element/stream capacities or a field’s logical cell count. Module expansion resolves these structural sizes after binding ports, including nested calls; Reset still checks the complete allocation budget. Cycles, missing sources and sizes above 16,777,216 are rejected. Field ports normally require matching domain geometry. An explicit fieldDomain: "bound" port with capability feature/bound-field-domain/1 instead uses its owner’s geometry, allowing a recooked field to resize private module scratch without changing shared definitions. These records describe allocation dependencies, never GPU offsets or live snapshots.

A Scene3D simulation-view entity names an output and declares particles, mesh, element vectors, field vectors, field slice or bounded volume/isodensity settings. It uses the scene’s existing transform, material and output membership. Mesh output ABI 2 names a vertex set, a relation set, triangle/line topology and an ordered tuple of generational member attribute IDs. Position and optional normal attributes are explicit. Legacy mesh ABI 1 remains editable with an unsupported activation diagnostic; upgrade does not infer topology. Import and reuse remap these identities while retaining authored source and physical geometry. GPU textures, buffers and borrowed leases are recreated by the runtime.

Begin with a working bundle and keep relationships between IDs, resource collections, and layer cards intact while changing one part at a time. validate checks authoring contracts; open the result in Studio to judge rendering and motion.