gaussian-splat-character-controller

👉 Try the live link here

A physics-based character controller navigating a Gaussian splat scene using SparkJS, Three.js, and Rapier.

Features

• Gaussian splat rendering – Spark.js renders a 3D scene from village 3.spz with depth-of-field (adjustable focal distance and aperture in the GUI).
• First-person controller – Walk, run, and jump with keyboard (WASD, Shift, Space) or gamepad (left stick move, right stick look, A to jump, L1/L2 sprint, R1/R2 shoot).
• Physics – Rapier3D provides collision; the environment uses a static mesh collider from collider-v2.glb so you can walk on and around the scene.
• Ball shooter – Click or hold fire (mouse or gamepad) to shoot teal orbs that interact with physics.
• Post-processing – Vignette, saturation, contrast, brightness, chromatic aberration, film grain, exposure, tone mapping, sharpening, and Unreal-style bloom (all configurable in the GUI).
• Debug options – Toggle physics wireframes and the collider mesh visibility from the GUI.

Tech Stack

• Vite – Build tool
• Three.js – 3D rendering
• Spark – Gaussian splat rendering
• Rapier (rapier3d-compat) – Physics and character controller
• lil-gui – On-screen controls

Prerequisites

• Node.js (v18+ recommended)

Setup

npm install

Required Assets

Place these files so they are served from the project root (e.g. in public/ for Vite):

Asset	Path	Description
Village splat	public/village 3.spz	Spark splat scene
Collider mesh	public/models/collider-v2.glb	Static physics collider (can be hidden in-game)

Without these, the splat won’t load and the collider/physics setup will fail.

Running

# Development server (with hot reload)
npm run dev

# Production build
npm run build

# Preview production build locally
npm run preview

Open the URL shown in the terminal (e.g. http://localhost:5173) and click to lock the pointer, then use WASD to move and the mouse to look.

Controls

Input	Action
Mouse	Look (when pointer locked)
Click	Lock pointer / Shoot (when locked)
WASD	Move
Shift	Sprint
Space	Jump
Gamepad	Left stick: move · Right stick: look · A: jump · L1/L2: sprint · R1/R2: shoot

GUI

The on-screen panel (top-left) includes:

• Physics Debug – Show wireframes, show collider mesh
• Post Processing – Enable/disable and tune all effects
• Spark – Focal distance and aperture for splat DoF
• Ground – Ground plane Y position
• Shoot from – Vertical offset of ball spawn
• FPS Controls – Walk/run speed, jump, step height, slopes, sensitivity
• Controls – Gamepad and invert options
• Splat Position / Rotation / Scale – Transform the village splat
• Collider Position / Rotation / Scale – Transform the physics collider (and sync to physics)