procgen.onPresent

Arms a probe that fires the moment a generator presents a frame matching every term given, so an effect can be caught at the instant something happens in it: a burst reaching a count, a time inside a looping cycle, an output appearing. It is a probe on proc.cooks.presented, so probe.list, probe.hits and probe.cancel manage it like any other, and probe.hits lists what each hit reported.

Terms, each optional, all of them held together:

• entity: the generator, by entity id or name.
• output: a frame on which that output presents; minElements with it asks for at least that many elements in it.
• at: a frame at or past that graph time. With every, the time within each repeating cycle of that length: at = 0.4, every = 3 fires on a frame from 0.4 s to 0.4 s + within into any three-second cycle (within defaults to 0.25 s, room for the presents a heavy cook spaces out).
• how: how the frame was made, "cook", "memo", "device" or "held".
• when: a Luau condition of your own over the present in args[1] (time, frame, how, ms, owner and outputs, each output { elements } by name).

What a hit does:

• By default its notice reports the frame's time and frame, how it was made, its milliseconds and each output's element count by output name ({ time, frame, how, ms, sparks = 315 }); run reports what your own code returns instead, and notice replaces the notice's text.
• capture = true takes a picture of each frame it fires on: the generator is held on that frame while the picture is taken, of what it draws alone, framed to fit, over the grey studio backdrop, and the effect plays on. A table states the picture's options: width, height, angle ({ yaw, pitch } in degrees), margin, backdrop ("studio" or "dark") and path (a file to write it to as well).
• freeze = true holds the generator on the frame it fires on and stops the world there, for looking at it from more than one place. generator:play() plays the generator on, and engine.paused = false resumes the session.
• limit (default 1), cooldown, label and silent mean what they mean on probe.onCall.

A frame the picture tools present while holding a generator is never a hit. procgen.frames takes the pictures of several chosen moments in one call.

tools.use("procgen", "onPresent", { entity = "Grow", output = "output", at = 0.5, limit = 1 })

Part of procgen.toolbox, called as tools.use("procgen", "onPresent", ...) (zero procgen onPresent in the engine shell). Returns { probe, source, when }: the probe's id, the function it is attached to, and the condition it was armed with.