Log inGet started
World

Splatgrove

Branchmain
Branchesmain
Commitff76c26a07

README.md

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.
-- 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.

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.

    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.

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

AssetRole
SplatSkeleton.componentRigging: any animated skinned character → a splat body following its skeleton.
SplatRig.component, SplatLimb.componentRigging: a custom splat creature from bone entities.
JointSwing.componentAnimates a bone entity (legs, tails, wings) by swinging it.
rigs.module, sdf_rig.computeShaderThe rigging API and painter (smooth-unioned tapered limbs).
SdfSplatShape.componentEntity → animated SDF primitive painted in splats.
shapes.moduleGathers every shape into one source; put shapes without entities.
sdf_shapes.computeShaderThe primitive painter (8 primitives, morph, wobble, gradient, glow).
sdfSplats.moduleThe API: register/unregister sources, pool settings, lighting, status.
splatPool.renderFeatureOne shared pool for all sources: per-view cull, radix sort, splat draw.
splat_view_prep.computeShaderPer-view cull uniforms from @frame.camera.
sdf_surface.shaderModuleWGSL painter core: projection, stroke frame, shadow, AO, shading.
sdf_toolkit.shaderModuleWGSL SDF primitives, smooth booleans, noise, rotations, seeding.
splat_record.shaderModuleWGSL: write the packed 24-byte splat record.
pixelPalette.shaderPixel-art palette post pass (OKLab, ordered dither, outline).
palettes.modulePalettes and apply / register / remove for the pass.
PixelPalette.componentThe palette pass as a component.
documentation/sdf-gaussian-splats.guideHow it works and how to build on it.
sdf-gaussian-splats.agentSkillThe procedure for an agent making splat content.

Depends only on @builtin (gaussianSplats cull, gpuSort, splat composite). The guide: guides { path = "sdf-gaussian-splats" }.