# 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.
# 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`.
# 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.
# SplatAsset
One placed copy of an `sdfSplat` asset: paints the asset's parts with
Gaussian splats under this entity's transform, live-linked to the asset (edit
its `splat.yaml` and every copy changes). Dragging an `sdfSplat` asset into a
scene adds an entity with this component; you can also add it yourself and
set `source`. `detail` scales the splat budget, `animated` runs the asset's
spin / bob / morph / pulse.
# 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.
# 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`.
# 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 })
```
# crystalCluster
A clump of faintly pulsing blue, violet and teal crystals growing out of a dark rock. Cave decoration, fantasy loot marker or glowing landmark.
# ghostWisp
A pale, translucent ghost with dark eyes, bobbing and wavering above the ground. Haunted houses, graveyards, spooky ambience.
# glowOrb
A floating, breathing orb of cyan light inside a slowly turning violet ring, on a squat stone base. A magical light source or shrine centrepiece.
# graveStone
A weathered, mossy headstone leaning over a dark earth grave mound. Graveyards, horror scenes, haunted places.
# morphTotem
A stone pedestal under a floating cyan-violet form that slowly morphs between a torus and an octahedron, with an orbiting light. A puzzle object, portal marker or sci-fi shrine.
# 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.
# pixelPalette
Pixel-art palette post pass (display space). Cuts the frame into square
cells `rows` tall, snaps each cell to the nearest ink of an indexed palette
(up to 24 inks) in OKLab with a 4x4 ordered dither between the two nearest
inks, and darkens cells on strong value edges as an outline. `amount = 0`
shows the picture unfiltered. Loaded and driven by `palettes.module` /
`PixelPalette.component`.
# 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.
# sdf-gaussian-splats
Agent skill for making procedural, animated Gaussian splat content with the
sdfSplats package: when to rig a splat body (SplatSkeleton on an animated
character, SplatRig + SplatLimb bone entities), when to use the no-code
SdfSplatShape component, when to
write an SDF painter on `sdf_surface`, when any compute shader can be a
source, how to add the pixel-art palette, and how to verify the result.
# sdfSplat (asset type)
A procedural Gaussian splat object you place in scenes like a model. Part of
the `sdfSplats` package.
## Make one
```luau
asset.create("sdfSplat", "lantern") -- lantern.sdfSplat/ with a starter splat.yaml
```
Then edit `lantern.sdfSplat/splat.yaml`:
```yaml
parts:
- shape: cylinder # sphere box torus capsule cylinder cone octahedron blob
position: [0, 0.3, 0] # metres, relative to the object's origin
rotation: [0, 0, 0] # degrees (x pitch, y yaw, z roll)
size: [0.3, 0.6, 0.3] # metres, a number or [x, y, z]
splats: 5000
color: "#3a2e22" # bottom colour
tipColor: "#5a4632" # colour toward local +Y
roundness: 0.3 # box / cylinder / cone / octahedron edges
- shape: sphere
morphTo: octahedron # optional second primitive
morph: 0.3 # 0..1 blend toward it
position: [0, 0.75, 0]
size: 0.25
splats: 3000
color: "#ff9a2e"
glow: 1.2
wobble: 0.3
animate:
spin: 40 # degrees per second about the part's Y
bob: [0.05, 0.5] # metres, cycles per second
morph: 0.2 # ping-pong morph cycles per second
pulse: 0.4 # glow pulse depth 0..1
```
Other part fields: `wobbleSpeed`, `thickness` (torus / capsule tube),
`opacity`, `strokeSize`.
## Place one
Drag it from the asset browser into a scene, or:
```luau
local e = asset.resolve("lantern", "sdfSplat"):instantiate(nil, { position = { 2, 0, -3 } })
```
That spawns an entity with a `SplatAsset` component (`source` = the asset,
`detail` = splat budget multiplier, `animated`). Move, turn and scale the
entity and the splats follow. Copies stay linked: edit `splat.yaml` and every
placed copy changes.
## How it draws
Each part is a signed-distance primitive repainted with brush-stroke Gaussian
splats every frame by the package's `sdf_shapes` painter, sorted with every
other splat source per view. Add the package's `PixelPalette` component for a
pixel-art look.
# 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`).
·computeshader · born here
❒asset # sdf_rig
The painter behind splat rigging (`SplatSkeleton`, `SplatRig`). A rig is a
list of limbs — tapered capsules between two world points, one per bone —
and its skin is the smooth union of all of them, so joints flow into one
body. Every frame each splat is seeded around its own limb, projected onto
the whole rig's current surface, laid along the nearest bone as a brush
stroke, coloured from that limb (base to tip) and shaded as paint with the
rig's own soft shadow and occlusion. Move the bones and the painted body
bends with them.
| Slot | Access | Contents |
|---|---|---|
| `records` | read_write | The shared sdfSplats pool (6 u32 per splat). |
| `scene` | read | `RigScene`: time, limb count, splat count, stroke size, `SplatLight`. |
| `limbs` | read | `Shape` per limb (six vec4s): endpoints and radii, colours, splat range, rig range, blend. |
| `params.first` | uniform | Where this source starts in the pool. |
·computeshader · born here
❒asset # sdf_shapes
The painter behind `SdfSplatShape`: paints every shape — sphere, rounded box,
torus, capsule, rounded cylinder, cone, octahedron or lumpy blob, each
optionally morphing into a second primitive and wobbling with animated noise —
with brush-stroke Gaussian splats every frame. Each splat is seeded on an even
Fibonacci sphere around its shape, projected onto the current surface,
oriented as a stroke, coloured with a base-to-tip gradient and shaded as paint
with self shadow and AO (`sdf_surface`). Dispatched by `shapes.module` as one
sdfSplats source.
| Slot | Access | Contents |
|---|---|---|
| `records` | read_write | The shared sdfSplats pool (6 u32 per splat). |
| `scene` | read | `ShapeScene`: time, shape count, splat count, stroke size, `SplatLight`. |
| `shapes` | read | `Shape` per shape, eight vec4s each. |
| `params.first` | uniform | Where this source starts in the pool. |
# 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.
# 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.
# 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`.
# splatAssets
The shared half of the `sdfSplat` asset type: parses an asset's `splat.yaml`
(cached by file version), and paints a placed copy of it under an entity's
world transform through the package's `shapes` source (`paint` / `clear`).
`SplatAsset.component`, the type's `behavior.luau` and its Inspector call it;
scripts rarely need to.
·renderfeature · born here
❒asset # splatPool
The render feature that draws the sdfSplats pool. Each frame it lays out every registered source in
one shared buffer of packed splat records, runs each source's generator once,
then per render target (viewport, every offscreen capture, every
render-to-texture camera) rebuilds the cull uniforms from that target's
camera (`splat_view_prep`) and runs the builtin `splat_cull`, the shared
`gpuSort` radix passes and a `channel = "gaussian"` splat draw composited over
the lit scene. It compiles its per-view programs up front and draws only once
they are ready. Started and stopped by `sdfSplats.module` as sources come and
go; you do not create it yourself.
# 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`).
·computeshader · born here
❒asset # splat_view_prep
One-thread pass that rebuilds the builtin `splat_cull`'s `CullUniforms` for
the camera the current render target is drawn from. `@frame.camera` (the
only camera input the engine resolves per target) carries the inverse
view-projection and the eye; this pass inverts it, extracts the six frustum
planes and writes the 68-float block, so the sdfSplats cull and radix sort
order the pool for the viewport, every offscreen capture and every
render-to-texture camera alike.
| Slot | Access | Contents |
|---|---|---|
| `cam` | read | `@frame.camera` — inverse view-projection, eye. |
| `statics` | read | (count, buckets, near, far), (viewport w, h, min px, 0). |
| `view` | read_write | `CullUniforms` as 68 floats. |