# splat_record
WGSL for writing Zero's packed 24-byte Gaussian splat record from a compute
shader — position, log-encoded per-axis scale, orientation quaternion, colour
and opacity, the same layout a `.spz` / `.ply` capture is decoded into — so
anything a compute shader generates (SDF surfaces, particles, simulations,
point clouds) can be drawn as Gaussian splats by the sdfSplats render feature
and the builtin splat cull, radix sort and gaussian splat draw.
Provides `write_record(i, position, sigma, quat, colour, alpha)`,
`hide_record(i)`, `quat_from_basis(t, b, n)`, `scale_byte(s)`, and the
constants `RECORD_WORDS` and `SH_C0`. The including shader declares the pool
binding `records` (`element: u32`, `read_write`) and passes absolute record
indices (`params.first + i`).
# sdf_toolkit
A WGSL library of signed-distance-field and procedural helpers for compute
painters: PCG hashing, value noise and fBm, SDF primitives (sphere,
ellipsoid, capsule, tapered capsule, torus, rounded box, octahedron, rounded
cylinder), smooth min/max and part-preserving unions, rotations (axis and
quaternion), even golden-angle / Fibonacci sphere seeding, quadratic Bezier
points, ellipsoid surface area and stroke spacing, and luminance /
saturation helpers.
Pure functions, no bindings: include it from any compute shader
(`#include "sdfSplats.sdf_toolkit"`, or `#include "~.sdf_toolkit"` inside the
package). `sdf_surface` includes it for you.
# 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" }`.