effect

A set of visuals packaged as one thing: every impact a weapon makes, every stage of an explosion, the muzzle flash, impact and tracer of a gun. Each visual is an entry the effect plays by name. The graphs, the parts they are built from, and the shaders, materials, compute shaders and textures they use all live inside the effect.

The shape on disk

<name>.effect/
  effect.yaml   what it plays: entry name -> one graph, or a list of graphs played together
  graphs/       the graphs its entries play
  parts/        graphs those graphs use as nodes, each one whole piece of the look
  shaders/      shaders and shader modules its materials draw with
  materials/
  compute/      compute shaders its graphs run
  textures/
  README.md     what this effect shows, what each entry plays, what each input changes
  .metadata
  settings.yaml its values for the settings below

effect.yaml, graphs/, README.md and .metadata are required.

plays:
  flare: "~.graphs.flare"
  impact:
    - "~.graphs.impactFlash"
    - "~.graphs.impactDebris"
default: flare

Inside an effect ~.x names the effect's own x: ~.graphs.flare, ~.parts.crack, ~.shaders.lava, wherever the effect sits.

Post-processing it carries

post is the post-processing the effect brings with it: bloom on a fireball, a flash of exposure, a vignette. While an entry plays, it stands as a PostProcess region around the effect, and goes when the play stops or finishes:

post:
  radius: 30        # the region, a sphere around the effect unless `shape` says box or global
  falloff: 5        # the distance outside it over which the stack fades out
  effects:
    - { shader: "@builtin::shaders.post.bloom", priority: 10, values: { threshold: 1.2, intensity: 0.6 } }
    - { shader: "@builtin::shaders.post.vignette", priority: 20, values: { intensity: 0.4 } }

effects is the region's stack and the rest its fields, as the PostProcess component takes them (shape, radius, extents, falloff, priority, display, setsDisplay). The region applies while the camera is in it, so a picture of the effect on the preview stage shows it without; effects.capture of the effect placed (entity) shows it with.

Graphs and parts

A graph under graphs/ composes what one entry shows. A piece worth building and looking at on its own (the crack of a fissure, the spray, the smoke) is a graph under parts/, called as a node:

local crack = g["~/parts/crack"]({ length = length })

A part is a whole graph, so it previews and plays alone: the crack without the smoke in front of it. An operation several effects use (a streak look, a smoke puff) is a .procNode outside the effect, used the way a module is required.

Playing one

local beacons = asset.resolve("beacons", "effect")
local shown = beacons:play("flare", { root = mast, offset = { 0, 0.9, 0 }, inputs = { size = 0.4 } })
shown:set("size", 0.6)
shown:onFinished(function() print("done") end)

root is the entity it plays on and follows; inputs go to every graph of the entry that declares them; the handle answers set, pause, resume, seek, getTime, stop, isFinished and onFinished. A play finishes when every graph of its entry reaches the end of its timeline; a graph that states realTime alone has no end, so a play of it runs until stop(), and a simulation that runs once states its frames (g:timeline({ realTime = true, frames = 120 })). Plays are kept ready, built ahead of time: beacons:warm("flare", 6) keeps six ready for a burst. An Effect component, or a drop into the viewport, places an entry in a scene.

entries() and entry(name) read what it plays; setEntry, removeEntry, renameEntry, setDefault and newGraph change it, keeping every line of effect.yaml they do not touch.

Settings

pool: how many plays of each entry there are, counting the ones playing (default 1). Each costs a whole play's memory, so a burst asks for more with warm where it is expected.

In search

Each asset inside an effect is found on its own and names the effect it belongs to. The effect itself is found by its preview, its README and its entries.