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
  preview.png   its default entry at a representative moment

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.

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.