THE FIELD GUIDE
From your screen
to the sand.
Explore the browser experience, learn how the landscape works, and bring Terrain Lab to a physical sandbox.
Start with a little exploration.
The browser mode opens with a sample landscape and fullscreen view. No account, camera, or installation is needed. The live sandbox mode shares the world and wildlife controls and adds Kinect, calibration, and projector setup. Choose a color world, move the water line, and watch wildlife find its habitat. Choose Shape terrain in the pointer controls to carve with a left drag or add sand with a right drag; choose Move wildlife to rescue animals.
Browser mode is also a focused study: select individual species, compare all 26 worlds and 48 creatures, change terrain fixtures, and see what each creature is doing.
The browser landscape is simulated. A live physical sandbox needs the local Kinect bridge and projector hardware described below.
A world with a little instinct.
Foxes hunt rabbits, wolves hunt deer and rabbits, and sharks hunt koi. In the expanded worlds, Void Rays pursue Starseeds and Phages pursue Microbes; Drones animate alongside them. Each themed world has signature fauna: Atlantis mantas, coral seahorses, volcanic lava finches, desert scorpions and dust hoppers, and a Talokan anglerfish are examples. Prey interrupt resting and escape at twice their normal speed. If a predator gets close enough, the prey is eaten and disappears without gore. A replacement spawns in safe habitat after 10–16 seconds.
Drag an animal into safe land or water to rescue it. Invalid drop locations are rejected, so a fish cannot be dropped onto land. The animal receives three seconds of protection after release, marked by a pale green ring.
Earth's random population has six prey animals and two predators; other worlds start with their own themed rosters. New population reshuffles positions. Presets and individual selectors let you experiment. Large animals may wait off-screen when there is not enough safe habitat. Raising water or reshaping the terrain can bring them back.
Landscapes that come alive
Each of the 26 themes has its own scenery and atmosphere: rain in the forest, drifting snow over glaciers, dust devils on Mars, steam around geothermal formations, and waves along beaches. Copper builds a lost dwarven city on high ground: bronze-domed towers, vaulted halls, broken gates, working steam foundries, and stone streets patrolled by articulated automatons. Emerald City grows palaces and yellow brick roads across raised land and water, with guardians, citizens, broom-riding witches, sparkling gems, and passing rainbows. Both recede when their ground sinks below water. Universe turns raised sand into rotating galaxies and low basins into scattered starfields. Microscopic, Neuron Network, Atomic, Cyberpunk, and Dreamscape add cells, signals, orbitals, drones, and surreal scenery. Atlantis is a full underwater world with treasure chests, tridents, ruins, coral, and moving bubbles.
To awaken a volcano, select Volcanic in the sandbox, choose Raise, and hold on one place until a tall mountain forms. Lower it to stop the eruption. Landscape elements and Weather & motion let you control scenery separately from wildlife.
Bring the landscape into the room.
- A Kinect v1 with power supply and USB connection.
- A Mac with Python 3, Homebrew, and libfreenect.
- An overhead projector and a box of sand with an unobstructed surface.
- A stable mount for the camera and projector.
Download or clone the repository, then start the local bridge:
git clone https://github.com/msriram/terrain-lab.git
cd terrain-lab
brew install libfreenect
./scripts/run.shOpen the sandbox URL printed by the launcher, or open the hosted sandbox and press Connect Kinect. The hosted controller discovers the local bridge. Your depth frames stay on your machine.
For a fixed rig, the repository includes scripts/install-kinect-service.sh. See the Mac setup guide for the existing service and hardware workflow.
Line up the physical world.
- Connect the Kinect and confirm a live depth image.
- Open Rig setup → Calibrate. Select or detect the four inner corners of the sandbox. Adjust the outline, capture a flat reference if needed, and save the rig.
- Adjust the depth band with Position, Range, and Auto fit. Use Stability to reduce noise.
- Open the projector window. Move it onto the projector display and press F for fullscreen. Use rotation and projection alignment controls to match the sand.
- Verify shoreline and animal alignment on the sand. Both layers share the same calibrated terrain coordinates and projector transform.
In browser demo mode, the projector window is also available without a sensor. Wildlife and rescue changes synchronize from the controller to its projector window. Keep the controller open.
Make something of your own.
The terrain renderer uses Canvas; wildlife is a separate Three.js layer with local animated GLBs. Species, habitat decisions, animation clips, and effects are organized independently.
cd standalone-animal-demo
npm ci
npm run devTo build the full website, sandbox integration, and public wildlife demo from the repository root:
node scripts/build-site.mjs
python3 -m http.server 5180 --directory _siteOpen http://localhost:5180/. The build includes every runtime library, model, and texture locally. Read Adding animals and the integration contract for implementation details.
Model attribution and licenses are bundled with the demo. Original animal assets are CC0; the fox includes CC-BY credits. The upstream Magic-Sand checkout is a separate GPL reference and is not part of this website bundle.
Built to explore. Still evolving.
| Available | Needs physical verification |
|---|---|
| Browser terrain, 26 living themes, animated wildlife, rescue interaction, and habitat rules | Projected animal readability on your sand and lighting |
| Local Kinect v1 capture, saved calibration, flat reference, and projector controls | Alignment, depth noise, and performance on each complete rig |
The water line is an elevation threshold, not a fluid simulation. Animal navigation uses local steering and habitat checks; it is an interactive ecosystem prototype, not a scientific predator/prey model.