·computeshader · born here
❒asset # sdf_splat_gen
Splatgrove's garden painter, and the full worked example of a custom painter
for the `sdfSplats` package: the floating island, flowers, mushrooms, trees,
rocks, the morph totem and the sky jellies as animated signed-distance shapes,
painted with Gaussian splats every frame.
One thread per splat. Each splat belongs to one shape (found by binary search
over `shapes`, sorted by their first splat). The thread seeds the splat on its
shape's current parts, projects it onto the shape's zero level set
(`splat_project`), orients it as a flat brush stroke in the tangent plane,
shades it as paint (wrapped sun, sky/ground ambient, SDF occlusion and soft
shadow or the island's blob shadows, rim light, aerial fog) and writes the
packed 24-byte splat record at `params.first + i` in the shared pool. Only the
garden-specific parts live here — shape SDFs, per-kind seeding, wind and
player lean, per-part paint; the rest comes from `#include
"sdfSplats.sdf_surface"`.
Shapes animate by changing their SDF parameters (bloom, breath, sway, lean,
morph); the splats ride the moving surface because they are re-projected from
fixed seeds each frame.
## Bindings
| Slot | Access | Contents |
|------|--------|----------|
| `records` | read_write | The shared sdfSplats pool, 6 u32 words per splat. |
| `garden` | read | `GardenUniforms` — time, sun, sky, wind, eye, fog, player positions. |
| `shapes` | read | `Shape` per garden shape, eight vec4s each. |
| `params.first` | uniform | The garden's first record in the pool. |
# 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" }`.