# rigs
Splat rigging API: animated, articulated bodies painted with Gaussian splats.
`put(key, { limbs = { { a, b, r1, r2, color, tipColor } }, splats, blend })`
paints a rig whose limbs are tapered capsules between world points — call it
every frame with the current pose — and `remove(key)` stops it. All rigs are
one sdfSplats source painted by `sdf_rig`; each limb's share of splats is
fixed when the rig is first put, so moving bones never reshuffles strokes.
`SplatSkeleton` and `SplatRig` are built on it; `rotate(q, v)` helps place
limbs from bone rotations.
# SplatSkeleton
Turns an animated, skinned character into a body of Gaussian splats that
follows its skeleton: put it on an avatar, a player body or any entity with a
skinned mesh under it, and every frame the joint transforms its animation
clips, locomotion, IK or ragdoll produce become tapered limbs (torso, neck,
arms, legs, a head sphere, caps at hands and feet), smooth-unioned and
painted. A walking avatar walks as a painting. Bone radii come from common
bone names (humanoid, Mixamo, VRM) and fall back to bone length; `skip`
leaves out fingers, face and twist bones; `hideMesh` hides the triangle mesh
during play so only the splats show.
```luau
body.component.add("SplatSkeleton", { splats = 36000, thickness = 1.1 })
```
# SplatLimb
One bone of a `SplatRig`: a tapered capsule starting at its entity and
ending at the `to` entity, or `length` metres along one of its local axes.
It follows its entity's world transform, so a hierarchy of SplatLimb
entities is a skeleton and rotating a bone moves everything below it. Fields:
`to`, `length`, `axis`, `radius`, `endRadius`, and `ownColor` / `color` /
`tipColor` to paint one limb differently from the rest of the rig.
# JointSwing
The simplest animator for a splat rig's bones: swings its entity back and
forth around a local axis while the world plays — legs that step, tails that
wag, wings that flap, necks that bob. Applied on top of the bone's rest pose;
offset `phase` along a chain to make the motion travel. Fields: `axis`,
`amplitude` (degrees), `speed` (swings per second), `phase`, `offset`.
Play mode only; restores the rest pose when disabled.
# SplatRig
The root of a custom splat rig. Every `SplatLimb` on this entity and its
descendants becomes one bone of a single smooth body painted with Gaussian
splats. Build a skeleton as an entity hierarchy (a bone entity per joint),
give the bones SplatLimbs, and animate the bone entities — from a script,
with `JointSwing`, or with any animation that moves entities — and the
painted creature bends at every joint. Fields: `splats`, `blend` (how softly
limbs merge), `thickness`, `color`, `tipColor`, `glow`, `wobble`, `opacity`,
`strokeSize`.
# sdf_surface
The shape-independent half of an SDF Gaussian-splat painter, in WGSL. Given
a seed point near a shape, `splat_project` lands it on the shape's current
zero level set with damped Newton steps (so a shape animates just by
changing its SDF parameters and the strokes ride the surface);
`stroke_orientation` lays a flat brush stroke in the tangent plane;
`soft_shadow`, `sdf_ao` and `splat_shade` (wrapped sun, sky/ground ambient,
rim light, glow, aerial fog, under a `SplatLight`) shade it as paint. It
includes `sdf_toolkit` and `splat_record`, so one include brings everything.
Contract: the including compute shader declares `struct Shape`, `struct Ctx`
and `fn shape_sdf(p: vec3<f32>, sh: Shape, c: Ctx) -> vec4<f32>` (x distance,
y part id, z/w part coordinates). `sdf_shapes.computeShader` in this package
and Splatgrove's `sdf_splat_gen` are complete painters built on it.
# sdfSplats
The public API of the sdfSplats package: a shared GPU pool of Gaussian splats
that any number of procedural generators write into every frame. Register a
source — a record count and a `generate(frame)` function that dispatches your
compute painter over `frame.count` threads writing at `frame.first + i` — and
it is drawn, culled and depth-sorted together with every other source, for
every camera and capture, through the builtin Gaussian splat machinery.
`SdfSplatShape` components are one source; Splatgrove's garden is another.
Also holds the pool's sort `settings` (near, far, buckets), the `lighting`
the package's painters shade with (optionally following the scene's sun),
`status` for diagnosis, and colour helpers (`hex`, `linear`, `packLight`).
# SdfSplatShape
Makes its entity a signed-distance shape painted with Gaussian splats,
re-surfaced on the GPU every frame — the no-code way to put procedural splat
objects in a scene. Choose a primitive (sphere, box, torus, capsule,
cylinder, cone, octahedron, blob), colours, glow and a splat budget; the
entity's world transform places, turns and scales it. Animate it by changing
fields: `morph` flows the surface from `shape` into `morphTo`, `wobble`
breathes it, moving the entity moves the strokes.
```luau
local e = entity.spawn("orb")
e.localPosition = { 0, 1.5, 0 }
e.component.add("SdfSplatShape", { shape = "torus", morphTo = "sphere", morph = 0.3, splats = 12000 })
```
Pair it with `PixelPalette` for a pixel-art look. Fields are each peer's own.
# PixelPalette
Puts the pixel-art palette pass on the screen of every peer running its
scene: cells `rows` tall, snapped to the chosen palette with ordered dither
and outlined edges. Set `palette` by name (Dusk Garden, Moss & Moon, Ember
Riso, or one added with `palettes.register`). One driver at a time: this
component or a script calling `palettes.apply`.
# shapes
Collects every SdfSplatShape (and any shape a script `put`s by key) into one
sdfSplats source painted by `sdf_shapes`. Shapes keep a stable order, so a
shape's splats do not jump when another shape moves; the pool is re-laid out
only when a shape is added, removed or changes its splat count. Use it
directly to paint shapes without entities: `put(key, record)` /
`remove(key)`, `count()`, `PRIMITIVES`, `strokeSize`.
# palettes
Drives the `pixelPalette` post pass and holds its palettes (Dusk Garden, Moss
& Moon, Ember Riso, plus any you `register`). `apply({ palette, enabled,
rows, dither, outline, saturation, contrast })` registers the pass on first
use and writes only what changed; `remove()` takes it off. Gives any scene —
Gaussian splats or meshes — an indexed pixel-art look.
# sdfSplats — procedural, animated and rigged Gaussian splats
Gaussian splats you generate instead of capture. Signed-distance (SDF) shapes
are painted with brush-stroke Gaussian splats on the GPU every frame, so a
shape animates just by changing its numbers (bloom, morph, sway, wobble) and
the strokes ride the moving surface. Everything is drawn through the engine's
own Gaussian splat machinery — the builtin splat cull, gpuSort radix depth
sort and `channel = "gaussian"` splat draw — for every view: the viewport,
offscreen captures and render-to-texture cameras. A pixel-art palette pass
completes the painterly look.
**Splat rigging.** Splat bodies can be rigged and animated like any
character: a rig is a set of bones, each painted as a tapered limb, all
smooth-unioned into one skin that bends at the joints.
- **SplatSkeleton** — put it on any animated, skinned character (an avatar, a
player's body) and its skeleton's live pose — animation clips, locomotion,
IK, ragdoll — drives a splat body. A walking avatar walks as a painting.
- **SplatRig + SplatLimb** — build your own creature from bone entities (a
bone per joint, parented into a skeleton); animate the bones from a script,
with **JointSwing**, or any animation that moves entities.
- **rigs.put(key, rig)** — feed limb poses from code every frame.
```luau
-- a splat avatar: the player's own animated body, painted
playerBody.component.add("SplatSkeleton", { splats = 36000 })
-- a custom creature: root + bone entities
local root = entity.spawn("critter")
root.component.add("SplatRig", { splats = 20000, blend = 0.09 })
local hip = entity.spawn("hip", { parent = root })
hip.localPosition = { 0.3, 0, 0.15 }
hip.component.add("SplatLimb", { axis = "-y", length = 0.4, radius = 0.08, endRadius = 0.06 })
hip.component.add("JointSwing", { axis = "z", amplitude = 28, speed = 1.2 })
```
**Splat objects as assets — `sdfSplat`.** A splat object is an asset like a
model: a `<name>.sdfSplat/` folder whose `splat.yaml` lists its parts (SDF
primitives with placement, colours, glow, wobble, morph and simple animation).
It has a rendered preview in the asset browser and you **drag it into a
scene**; that places an entity with a `SplatAsset` component that paints it,
live-linked to the asset (edit `splat.yaml` and every placed copy changes).
Five examples ship in `examples/`: glowOrb, crystalCluster, graveStone,
morphTotem, ghostWisp.
```luau
asset.create("sdfSplat", "lantern") -- then edit lantern.sdfSplat/splat.yaml
asset.resolve("glowOrb", "sdfSplat"):instantiate(nil, { position = { 0, 0, 4 } })
```
The `sdfSplat` type's own README has the full `splat.yaml` reference.
Three ways in for shapes, from no code to your own shader:
1. **SdfSplatShape component — no code.** Put it on any entity: sphere, box,
torus, capsule, cylinder, cone, octahedron or blob, with a colour gradient,
glow, wobble, and `morph` toward a second primitive. The entity's
transform places it.
```luau
local e = entity.spawn("orb")
e.localPosition = { 0, 1.5, 0 }
e.component.add("SdfSplatShape", { shape = "torus", morphTo = "octahedron", splats = 16000 })
e.component.get("SdfSplatShape").morph = 0.5 -- animate it from any script
```
2. **Your own SDF painter — a compute shader.** Write `shape_sdf`, how your
shapes seed their splats and how they are painted; include `sdf_surface`
for the rest (Newton projection onto the surface, stroke orientation, soft
shadow, AO, paint shading, the packed splat record); register it as a
source. Splatgrove's garden painter (`splatgrove/sdf_splat_gen` in the
Splatgrove world) is a complete example: a floating island, wind-bent
flowers that open as players approach, breathing mushrooms, swaying trees,
a morphing totem and drifting sky jellies: 544,000 splats regenerated every
frame in about 16 ms on an RTX 5090.
3. **Any GPU splat generator.** Particles, simulations, point clouds: any
compute shader that writes the 24-byte record (`splat_record`) can be a
source and is depth-sorted together with every other source.
```luau
local SdfSplats = require("sdfSplats.sdfSplats")
local PAINTER = asset.resolve("myPainter", "computeShader")
SdfSplats.register("myGame.forest", {
count = 200000,
generate = function(frame) -- once per frame
PAINTER:dispatch({
buffers = { frame.records, myUniforms, myShapes },
workgroups = { math.ceil(frame.count / 64) },
params = { first = frame.first }, -- write at first + i
})
end,
})
```
For the pixel-art look add a `PixelPalette` component (or call
`require("sdfSplats.palettes").apply({ palette = "Moss & Moon" })`).
## What is in the package
| Asset | Role |
|---|---|
| `SplatSkeleton.component` | Rigging: any animated skinned character → a splat body following its skeleton. |
| `SplatRig.component`, `SplatLimb.component` | Rigging: a custom splat creature from bone entities. |
| `JointSwing.component` | Animates a bone entity (legs, tails, wings) by swinging it. |
| `rigs.module`, `sdf_rig.computeShader` | The rigging API and painter (smooth-unioned tapered limbs). |
| `SdfSplatShape.component` | Entity → animated SDF primitive painted in splats. |
| `shapes.module` | Gathers every shape into one source; `put` shapes without entities. |
| `sdf_shapes.computeShader` | The primitive painter (8 primitives, morph, wobble, gradient, glow). |
| `sdfSplats.module` | The API: register/unregister sources, pool settings, lighting, status. |
| `splatPool.renderFeature` | One shared pool for all sources: per-view cull, radix sort, splat draw. |
| `splat_view_prep.computeShader` | Per-view cull uniforms from `@frame.camera`. |
| `sdf_surface.shaderModule` | WGSL painter core: projection, stroke frame, shadow, AO, shading. |
| `sdf_toolkit.shaderModule` | WGSL SDF primitives, smooth booleans, noise, rotations, seeding. |
| `splat_record.shaderModule` | WGSL: write the packed 24-byte splat record. |
| `pixelPalette.shader` | Pixel-art palette post pass (OKLab, ordered dither, outline). |
| `palettes.module` | Palettes and `apply` / `register` / `remove` for the pass. |
| `PixelPalette.component` | The palette pass as a component. |
| `documentation/sdf-gaussian-splats.guide` | How it works and how to build on it. |
| `sdf-gaussian-splats.agentSkill` | The procedure for an agent making splat content. |
Depends only on `@builtin` (gaussianSplats cull, gpuSort, splat composite).
The guide: `guides { path = "sdf-gaussian-splats" }`.