GraphBlender

A Beam’s Color and Transparency are spatial properties. They’re not graphs over time — they’re gradients along the beam’s length, from attachment 0 to attachment 1. Set Color to a red-to-blue ColorSequence and the beam paints red at one end, blue at the other, with a gradient in between. The gradient stays the same for the whole life of the beam.

That’s a problem if you want the colours to change as the beam ages. There’s only one ColorSequence on the Beam instance. There’s no place to put a “second colour gradient” for a later moment.

GraphBlender solves that. Each state is a snapshot of the gradient at one moment in time. State A says “this is the gradient at age 0”. State B says “this is the gradient at age 0.5”. The engine blends between consecutive states as the beam ages, producing a fresh gradient each frame. The Beam’s spatial Color and Transparency get rewritten on the fly.

You author the per-time gradients. The engine handles morphing between them.

Adding states

Open the property panel for a transformed Beam. Scroll to the Blender section near the bottom. There’s a + Add State button. Click it.

A new state appears in the panel. Each state gets its own row with three things:

• Time — a number from 0 to 1 saying when this state is active.
• Color — a colour graph for this state.
• Transparency — a number graph for this state.

Click Color and the standard colour-sequence editor opens; pick stops, pick colours. Same for Transparency and the standard graph editor.

Click + Add State again to add another phase. Most authors end up with two or three states. Many states is supported, but rarely needed.

What Time means

Each state’s Time is a position in the beam’s life:

• Time = 0 — the moment the beam is born.
• Time = 0.5 — exactly halfway through its life.
• Time = 1 — the moment it dies.

A two-state Beam with state A at Time = 0 and state B at Time = 1 blends smoothly from A’s look to B’s look over the full lifetime. Halfway through, the rendered colour is “halfway between A’s colour and B’s colour” — same for transparency.

A three-state Beam with state A at Time = 0, state B at Time = 0.4, state C at Time = 1 does two consecutive blends: A → B over the first 40% of life, then B → C over the remaining 60%. The transition between A→B and B→C lands exactly at age 0.4.

You can put states at any times. Time = 0, 0.3, 0.7, 1 is fine. Times don’t have to be evenly spaced. They have to be sortable — two states with the same Time is undefined behaviour (the engine still works, but the result depends on which one was authored first).

What states do

Each state holds a full gradient along the beam (a ColorSequence and a NumberSequence) plus a Time saying when that gradient is active.

Set up a three-state lightning beam:

• State A (Time = 0): gradient is white-hot core fading to bright tip. Both ends fully opaque.
• State B (Time = 0.5): gradient is pale blue all along the length. Mostly opaque.
• State C (Time = 1): gradient is dark blue at the base fading to nothing at the tip. Fully transparent.

If you froze the beam at age 0, you’d see A’s gradient painted along its length. At age 0.5, B’s gradient. At age 1, C’s.

In between, the gradient itself is the blend of two states. At age 0.25 (halfway between A and B), every point along the beam shows a colour that’s halfway between A’s colour at that point and B’s colour at that point. The whole gradient morphs from A’s shape to B’s shape over the first half of life, then morphs from B’s to C’s over the second half.

Transparency morphs the same way. Each state’s NumberSequence is also a gradient along the beam. The engine blends per-position, exactly like Color.

That’s the whole feature: each state is a spatial gradient at one moment. The engine smoothly morphs from one snapshot’s gradient to the next as the beam ages.

A worked example: a lightning strike

Three states. Times 0, 0.25, 1. Each state’s Color is a ColorSequence painted along the beam.

• State A (Time = 0): gradient is solid white the full length. Fully opaque.
• State B (Time = 0.25): gradient is pale blue the full length. Fully opaque.
• State C (Time = 1): gradient fades from dark blue at the base to nothing at the tip. Fully transparent.

Result over the beam’s life:

• Ages 0 to 0.25 — the gradient morphs from bright-white-everywhere to pale-blue-everywhere. Quick flash, dramatic. The first quarter of the lifetime.
• Ages 0.25 to 1 — the gradient morphs from pale-blue-everywhere to fading-into-nothing. Slow settle, atmospheric. The remaining three-quarters.

Same beam, two visual stages. The Beam’s spatial Color and Transparency are rewritten each frame as the engine produces the in-between gradient.

How the engine blends states

You can stop reading here if “the engine blends smoothly between states” is enough. The rest of this chapter describes what the engine produces visually each frame, in case you’re curious.

When a beam is at age t between two states, the engine produces a gradient that’s somewhere between the two states’ gradients — closer to whichever state is nearer in time. At the exact moment a state’s Time matches the beam’s age, that state’s gradient renders unmodified. Between two adjacent states, the rendered gradient is a smooth blend.

Same idea for transparency: each state holds its own transparency gradient, and the engine produces an in-between version each frame.

Multi-state beams are well optimized but not free. The engine reuses precomputed merged times across blends, but each frame still produces a fresh NumberSequence and ColorSequence per active GraphBlender beam. At ordinary counts the cost is fine; at very high counts the per-frame sequence work shows up as GC pressure. If a single static Color and Transparency covers your effect, prefer that — see Performance for the cross-cutting guidance.

Edge cases worth knowing

A few quirks that match what experience would tell you anyway, but easier to read once than discover by accident.

• Single-state case. Just one state in the folder? No interpolation happens. The engine reads that one state directly. Same effect as a regular Beam with Color and Transparency set.
• Empty folder. Transform always seeds one state, so an empty folder only appears if states were manually deleted or the folder was hand-edited. With zero states the Beam falls back to its native Color/Transparency (whatever you set on the source Beam in Studio’s Properties window). GraphBlender doesn’t override anything.
• Times outside 0–1. If any state’s Time is greater than 1, the engine normalizes the whole list at emit (divides every state’s Time by the maximum) so the timeline still spans 0–1. Useful when you’ve authored states like Time = 1, 2, 3 and want them to land at 0.33, 0.66, 1.0 automatically. For predictable authoring, keep times in [0, 1] directly.
• Two states at the same Time. Don’t. The result depends on which one was authored first, which is hard to reason about.

What’s next

Hidden Depths covered four advanced patterns: nesting, native editing, texture pinning, and GraphBlender. The next section — The Toolbench — covers the bulk-edit tools that operate on a Studio selection: Resize, Retime, Hue, Clipboard, Shifter, plus four utilities (Scan, Insert, Emit Code, Optimization Indicator).