Effects
Particles, textures and per pixel programs
Four ways to make a cart look like something, in rough order of how much thinking each one asks for.
| Reach for | When |
|---|---|
| A ready made component | You want fire, and you want it now |
| Particles | Many small moving pieces: sparks, confetti, smoke, trails |
fx |
A picture built or animated from a chain of operations |
| A shader | The picture is a function of the pixel, and you want to write that function |
For a few shapes with crisp edges, none of these is the answer: draw them with drawing or useDrawing and the Painter, because vector paths beat per pixel maths for anything with an outline.
Ready made
<Flame> is a procedural fire that needs no shader thinking at all:
import { Flame } from "oj"
<Flame style={{ width: 120, height: 200 }} speed={1.2} />It takes colors, speed, threshold, softness, width, taper, topFalloff and gain. It is a preset over <TextureFX>, so anything it does is reachable from <TextureFX> directly when you want to go further.
Particles
A C# owned particle system rendered inside any element. Steady emission costs your JavaScript nothing per frame.
import { useParticles } from "oj"
const ref = useRef(null)
const sparks = useParticles(ref, {
max: 2000,
emitters: [{
rate: 200,
shape: { type: "circle", radius: 12 },
speed: [40, 120],
lifetime: [0.5, 1.5],
sizeOverLife: [1, 0],
colorOverLife: ["#ffd080", "#ff408000"],
glow: 1,
gravity: [0, 240],
}],
})
<View ref={ref} onPointerDown={(e) => sparks.burst({ x: e.localX, y: e.localY, count: 30 })} />A pointer event's x and y are window pixels; localX and localY are relative to the element the handler is on, which is what a burst wants.
Ranges are written as [min, max] or as a single number. glow runs from 0 (normal alpha) to 1 (pure additive). An emitter can also take a texture from your own files, a sheet to play that texture as a flipbook, attract to pull particles to a point by the end of their life, tintPalette for random per particle colour, and edge to bounce or stick against the element's rect.
The full reference covers every option.
fx: building a texture
fx builds and animates a picture from a chain of operations, on the GPU. Reach for it when the thing you want is an image rather than a field of moving pieces.
import { View, mount, fx } from "oj"
const canvas = fx.canvas(512)
const shape = canvas.sdf("egg", { h: 0.6, r: 0.17, bulge: 0.7 }).blur(40)
const mask = shape.multiply(canvas.gradient(["#ffffff", "#000000"], "up").pow(0.68))
const body: fx.NoiseOptions = { type: "turbulence", seed: 1, octaves: 3, scroll: [0, -0.7] }
function Fire() {
const flame = fx.useAnimation(canvas, () => (
canvas.noise(body).multiply(2).multiply(mask).threshold(0, 0.2).ramp(["#400000", "#ffd800", "#ffffff"])
))
return <View style={{ width: canvas.width, height: canvas.height, backgroundImage: flame }} />
}
mount(<Fire />)fx.canvas(w, h) fixes a size and gives you the sources: color, blank, noise, gradient and sdf. Every operation returns another image, so they chain. fx.useTexture(canvas, build, deps) renders one once, and again when deps change; fx.useAnimation(canvas, build) re-renders it each frame, with the seconds so far passed in.
Everything in fx is fragment blits, so all of it works in the browser.
Shaders
Some effects are per pixel: fire, water, plasma, energy fields, animated gradients. fx composes those from a fixed menu of operations. A .sl file lets you write the operation.
// plasma.sl
uniform float warp = 0.5;
uniform float hue = 0.5;
float4 main() {
float2 p = (uv - 0.5) * (warp * 14 + 2);
float v = sin(p.x + time) + sin(p.y - time * 0.8);
float n = saturate(v * 0.22 + 0.5);
return float4(hsv2rgb(float3(frac(hue + n * 0.18), 0.75, n)), 1);
}import { ShaderProgram, View, mount } from "oj"
import plasma from "./plasma.sl"
mount(
<View style={{ flexGrow: 1, alignItems: "center", justifyContent: "center" }}>
<ShaderProgram program={plasma} uniforms={{ warp: 0.3 }}
style={{ width: 300, height: 300 }} />
</View>
)That is a complete animated effect. It is HLSL, so it is a syntax a Unity developer already knows, with the boilerplate gone: no Properties block, no SubShader, no CGPROGRAM, no appdata or v2f, no _Time.y. The file is the fragment function, and uniform declares both the slot and the name React binds against.
The editor knows the language. Errors are underlined as you type, at the character the build would name.
Compiled wherever it runs
The build prints your program as WGSL and as GLSL, and the browser compiles whichever one its graphics backend speaks, on the same device Unity draws with.
Open the cart in Unity and the same file becomes a shader that Unity compiles like any other asset. You change nothing.
That is why this exists rather than letting you write GLSL: GLSL would work beautifully in a browser and could never leave one.
Your program is parsed by the build, not at runtime, so no parser and no .sl source ships to a player.
From GLSL
A Shadertoy or WebGL fragment shader comes in as a .sl file. In the editor, New file has a box to paste one into: give the file a name (left empty, it is shader.sl), paste, and press Add file. A .glsl or .frag file dropped on the sidebar or picked in Upload is converted the same way.
Your comments, layout and names stay as they were. What means the same here is respelled: vec3 becomes float3, mix becomes lerp, iTime becomes time, mainImage becomes float4 main(), and iChannel0 becomes a declared texture, bound as under Textures below. Whatever could not be carried over, or now means something slightly different, is listed in comments at the top of the new file, each naming its line in the GLSL you pasted. Anything that still does not compile is underlined like any other error, and the console says how many are left.
Types and values
float, float2, float3, float4, int, uint, bool, and texture2D to declare a sampler.
Every local is declared with its type, and the declaration is checked against what you assigned:
float2 p = uv - 0.5; // fine
float3 c = uv; // error: c is declared float3 and this is a float2
float3 g = 0.5; // fine: one number fills every component
float3 t = #ff8040; // fine: a float4 into a float3 drops its alpha
float h; // fine: zero until something is assignedArithmetic is component wise with a scalar broadcasting on either side. Swizzles read and write with xyzw or rgba: p.x *= aspect; changes one component and keeps the rest. A colour is written as it is anywhere else: #ff8040, #rgb, or #rrggbbaa. It is a float4, or a float3 wherever a float3 is wanted (returned, passed, declared, or beside one), with its alpha dropped. A hex colour is sRGB as written and converted for you, while plain numbers are linear light, the space a program works in: float3(0.5, 0.5, 0.5) shows lighter than #808080.
A local or a uniform may take a builtin's name, such as circle or turbulence. Where the value is visible, the builtin is hidden, and calling it says so.
An int is a whole number, and two of them divide as whole numbers, toward zero: int a = 7 / 2; is 3 and int b = -7 / 2; is -3. % keeps the sign of the number divided, and dividing by zero gives 0. A number written without a point stays a float until it meets an int, so float c = 7 / 2; is 3.5 and 1 / 2 is still 0.5. An int goes into a float by itself; a float goes into an int as int(x), which drops the fraction.
A uint is for hashing: 5u writes one, and &, |, ^, ~, << and >> work on it, wrapping at 32 bits. A bool holds a comparison, combined with &&, || and !, and it is 0 or 1 where a float is wanted.
What a program is given
uv |
float2, 0 to 1 across the element, at the centre of this pixel |
time |
float, seconds since it started |
resolution |
float2, the element's size in pixels |
fragCoord |
float2, the centre of this pixel in pixels, so the first column is 0.5 |
aspect |
float, the element's width over its height |
texel |
float2, one pixel in uv (1 / resolution), the step to a neighbouring pixel |
centered |
float2, uv with 0 at the centre and x scaled by aspect, so a circle drawn in it stays round |
frame |
int, the frames drawn since the element last cleared, 0 on the first |
deltaTime |
float, seconds since the frame before, 0 on the first |
uv already has its origin corrected, so uv.y of 0 is the bottom everywhere. This is the one place a hand written shader most often goes wrong.
The frame before
tex2D(previous, uv) reads what the program drew on the frame before: a trail, something that builds up, a simulation that moves one step a frame.
// trail.sl
float4 main() {
float4 last = tex2D(previous, uv);
float2 at = 0.5 + 0.3 * float2(cos(time * 6), sin(time * 6));
float spark = smoothstep(0.08, 0.02, length(uv - at));
return max(last * pow(0.5, deltaTime * 3), float4(1, 0.6, 0.2, 1) * spark);
}Scale whatever fades or moves by deltaTime and it looks the same at any frame rate. The previous frame starts transparent black, and goes back to it, with frame back at 0, when the program changes, the element changes size, or its clock is set.
The first frame
A browser compiles a program while the page is already running, which can take a moment on a phone. So the cart's clock waits for the programs on its first screen: until they have all compiled, or for 2 seconds at most, useFrame does not run, and a preload's bar stays up. The first frame the player sees is the first frame the cart counts, so a count kept in useFrame is 0 there, and the first dt is a sixtieth of a second rather than the time spent waiting. A program mounted later, on a menu or a second level, holds nothing. In Unity a program compiles before it first draws, so nothing waits there.
Uniforms
A value that changes without changing the program:
// glow.sl
uniform float intensity = 1;
uniform float4 tint = #ff6619;
float4 main() {
float d = length(uv - 0.5);
return tint * smoothstep(0.5, 0, d) * intensity;
}<ShaderProgram program={glow} uniforms={{ intensity: hovered ? 2 : 1 }} />The default in the file is what the program starts at, so it looks right before anything sets it. A name in uniforms has to be one the file declares, and the editor underlines a misspelling where you wrote it.
Uniforms exist so a program compiles once and only the value crosses when it changes. Without them, moving a slider would rebuild the whole program sixty times a second.
An attribute before a uniform says what control it wants, in Unity's own words:
[Header("Shape")]
[Range(0, 2)] uniform float warp = 1;
[Range(1, 16, 1)] uniform float petals = 5; // a third number is the step
[Toggle] uniform float invert = 0; // 0 or 1
[Enum(Soft, Hard, Glow)] uniform float edge = 0; // the value is the index
[Label("Glow colour")] uniform float4 tint = #ff8040;
[Hide] uniform float seed = 0; // set from code onlyPlay does not draw these controls yet: a cart still sets its values through uniforms, and builds its own sliders. The attributes describe each uniform for a tool that draws them, and they never change what the program draws. A default that does not fit its control, such as [Range(0, 2)] on a default of 5, is an error on the attribute. The one attribute that does change the program is [Color]: it makes a default written as numbers a colour, read the same way as a hex default.
Textures
texture2D smoke;
float4 main() {
return tex2D(smoke, uv * 2 + time * 0.1);
}<ShaderProgram program={fire} textures={{ smoke: "noise" }} />A string names one of the built in procedural textures (noise, noise:2, flame-mask, radial-mask), which is how an effect ships with no art at all. Anything else is a texture you loaded, or scene.texture, the 3D scene drawn for a program to grade or blur. Four slots.
tex2Dlod(smoke, uv, lod) reads one mip level of a texture that has them: 0 is full size and each level up halves it; a fraction blends the two levels either side, whatever the texture's filter mode.
Loops and branches
if is a real branch: the side not taken does not run. return works anywhere, so a pixel with nothing to draw can leave before the expensive part:
if (length(centered) > 0.5) return #00000000;A for loop unrolls when its turns are known when the cart is built, there are 64 or fewer, and nothing in it leaves early. The body is written out once per turn:
float s = 0;
for (int i = 0; i < 3; i++) {
s = s + tex2D(smoke, uv * (1 + i * 1.9) - time).r * (0.6 / (1 + i));
}Any other loop is a real one: a bound that is a uniform, a while, a loop that stops with break or skips a turn with continue. Stopping as soon as a pixel is done is usually faster than running every turn:
[Range(16, 256, 1)] uniform int iterations = 128;
float4 main() {
float2 c = centered * 2.5 - float2(0.5, 0);
float2 z = 0;
int n = 0;
for (int i = 0; i < iterations; i++) {
if (dot(z, z) > 4) break;
z = float2(z.x * z.x - z.y * z.y, 2 * z.x * z.y) + c;
n++;
}
if (n == iterations) return #000000;
return float4(hsv2rgb(float3(frac(float(n) / iterations * 3), 0.8, 1)), 1);
}A real loop always stops. It runs at most the count its bound gives, or its uniform bound's [Range] maximum (256 above), or 1024 turns when the bound says neither, so a condition that never fails ends there rather than hanging the page.
switch picks by an int. A case never falls through into the next: each ends in break or return, and labels written one after another share a body.
switch (int(uv.x * 3)) {
case 0: return #ff4040;
case 1: case 2: { float g = uv.y; return float4(g, g, g, 1); }
default: return #000000;
}?: picks between two values. A texture read inside a branch or a loop where neighbouring pixels go different ways samples the texture at full size, since those pixels cannot agree on a mip level.
Functions, and the ones you already have
A function in the file inlines, so calling it costs what writing the body out would. Recursion is refused.
A small library comes with every file and needs no import: rotate(p, angle), polar(p), circle(p, r), box(p, size), tile(p, n), palette(t, a, b, c, d) and lookRay(eye, target, lens). Alongside them are the things a shader usually pastes from a forum: noise, simplex, fbm, turbulence, ridged, voronoi, ramp, and sdf.circle, sdf.box and forty more shapes.
Rays into a 3D world
lookRay(eye, target, lens) is the direction this pixel looks in, for a camera standing at eye and looking at target: the start of a raymarcher or a path tracer. It turns the way Unity's camera does, so a program drawn over a 3D scene with the same eye, target and field of view lines up with it. lens is how long the lens is, in screen heights: 0.5 / tan(fov / 2) for a field of view fov from top to bottom, so 1.07 is 50 degrees, and a bigger number zooms in.
// march.sl
uniform float3 eye = float3(0, 1, -4);
uniform float3 target = float3(0, 0, 0);
uniform float lens = 1.07;
float world(float3 p) {
return min(length(p) - 1, p.y + 1); // a ball on a floor
}
float4 main() {
float3 rd = lookRay(eye, target, lens);
float t = 0;
for (int i = 0; i < 96; i++) {
float d = world(eye + rd * t);
if (d < 0.001 || t > 40) break;
t += d;
}
if (t > 40) return #1a2333;
float3 p = eye + rd * t;
float2 e = float2(0.001, 0);
float3 n = normalize(float3(world(p + e.xyy) - world(p - e.xyy), world(p + e.yxy) - world(p - e.yxy), world(p + e.yyx) - world(p - e.yyx)));
float3 orange = #e09a5a;
float light = saturate(dot(n, normalize(float3(0.4, 1, -0.3))));
return float4(orange * (0.15 + 0.85 * light), 1);
}import { mount, useOrbit, useStage, ShaderProgram, View } from "oj"
import march from "./march.sl"
const lens = 0.5 / Math.tan((50 / 2) * (Math.PI / 180)) // 50 degrees
function Ball() {
const stage = useStage()
const orbit = useOrbit({ distance: 5, pitch: 15, idleSpin: 10 })
return (
<View {...orbit.bind} style={{ flexGrow: 1 }}>
<ShaderProgram program={march} pixelRatio={stage.pixelRatio}
uniforms={{ eye: orbit.eye, target: orbit.target, lens }}
style={{ position: "absolute", left: 0, top: 0, right: 0, bottom: 0 }} />
</View>
)
}
mount(<Ball />)useOrbit turns the eye round the target as the player drags, and a float3 uniform takes an array of three numbers.
Sharp on a phone
A program draws one pixel for every point of its element's size, and a phone's screen has about three pixels to a point each way, so on a phone a program is drawn at a ninth of the pixels and stretched. pixelRatio={stage.pixelRatio} draws it at the screen's own pixels instead, from useStage(), which is 3 on most phones, 1 or 2 on a computer, and 1 in Unity, which already draws in the screen's pixels.
That costs the ratio squared: nine times the work at 3. A soft gradient or a glow looks the same either way, so leave those at 1, and pass the ratio to a program with fine edges or text in it. A set resolution wins over pixelRatio, and changing it clears the frame before, as a resize does.
Limits
| Uniforms | 16 |
| Textures | 4 |
The build tells you when you cross one rather than rendering something wrong. Length has no limit: a long program costs what the same shader written by hand would.
Writing a program from code
sl.program records the same graph from TypeScript, and it is what a .sl file is parsed into:
import { sl, compile } from "oj"
const plasma = compile(sl.program(({ uv, time }) => {
const p = uv.mul(8).add(time.mul(0.4))
return sl.ramp(sl.sin(p.x).add(sl.sin(p.y)).mul(0.25).add(0.5),
["#000018", "#0080ff", "#ffffff"])
}))Reach for it when a program is built by code: generated from data, or parameterised in a way a file cannot be. For a shader you sit down and write, a file is the better home. It reads as a shader, it has its own history in git, and the editor understands it.