Sierpe

Sierpe simulates a controllable, snake-like robot on top of a real-time physics engine (Rapier). The robot is a simple chain of rigid bodies connected by revolute joints. If one drives the joints into a travelling wave and models anisotropic ground friction, the chain crawls forward along a curved path, similar to a real snake.

🐍 Try the live lab → you can move the snake around to get an idea of how the simulator works.

Installation

Sierpe ships as ES modules and targets modern bundlers. Rapier is pulled in for you and initialises asynchronously.

pnpm add sierpe-sim   # within the workspace, or from your registry of choice

Quick Start

Build a simulator using the undulating motion model to get the snake to climb a small hill. You can also command the snake, as if it were following a kinematic unicycle model.

import { simulator, control, terrain } from "sierpe-sim";

// Build a physical, undulating snake on a small hill.
const sim = await simulator.undulation({
  snake: {
    segmentCount: 10,
    segmentLength: 0.25,
    startPosition: [0, 0],
    startHeading: 0,
  },
  timeStepSize: 1 / 60,
  terrain: terrain.gaussianBump({ peak: 0.4, sigma: 1, center: [4, 0] }),
});

// Use a PI controller to command the system like you would a unicycle.
const pilot = control.unicycle(sim, { timeStepSize: 1 / 60 });
for (let step = 0; step < 600; step++) {
  pilot.step({ linear: 0.6, angular: 0.2 }); // 0.6 u/s forward, 0.2 rad/s turn
}

const { position, heading } = sim.state.snake.head;
console.log(position, heading); // This is the final state of the simulation.

If you prefer to control the snake more directly, you can use throttle and steering. These are normalized control inputs, so the actual speed emerges from the physics:

for (let step = 0; step < 300; step++) {
  sim.step({ throttle: 1.0, steering: 0.3 }); // crawl forward, curve gently left
}

Simulation components

| | | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Motion models | simulator.undulation drives the joints into a travelling wave and lets anisotropic friction convert it into motion, simulator.trail is a kinematic model where each segment follows the head's past path. | | Closed-loop control | control.unicycle wraps the simulator so you can command a forward speed (linear) and turn rate (angular) instead of using lower-level inputs. | | Terrain | The ground is an analytic height function y = f(x, z), sampled under each segment. Some presets like flat terrain, a Gaussian bump, a field of random bumps, or rolling waves are readily available. The undulation model reacts to the terrain, while the trail one does not. |

Rendering (add-on)

If you like the rendering used in the live lab, you can use it too! You can use the rendering package (based on three.js), available under the sierpe-sim/render subpath. It is opt-in, so the core sierpe-sim does not automatically include related dependencies. You need to install the optional peer dependency three as follows:

pnpm add sierpe-sim three

In order to visualize the simulation, create a Viewer and call its frame method every time you step the simulator:

import { simulator, terrain } from "sierpe-sim";
import { Viewer } from "sierpe-sim/render";

const sim = await simulator.undulation({
  snake: {
    segmentCount: 10,
    segmentLength: 0.25,
    startPosition: [0, 0],
    startHeading: 0,
  },
  timeStepSize: 1 / 60,
  terrain: terrain.gaussianBump({ peak: 0.4, sigma: 1, center: [4, 0] }),
});

const viewer = new Viewer(document.body, sim.terrain, { segmentCount: 10 });

function frame(): void {
  sim.step({ throttle: 1, steering: 0.2 });
  viewer.frame(sim.state.snake); // update meshes + camera, then render
  requestAnimationFrame(frame);
}
frame();

If you prefer to modify the rendering to suit your needs, you can use the underlying building blocks Renderer, GridView, TerrainView, SnakeView, etc.

Documentation

| | | | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | Getting started | Build a snake, drive it, read its state | | Concepts | More on the building blocks of the simulator and how they work together | | API reference | Every type and function in one place | | Live lab | Drive the simulation in your browser |

Development

Prerequisites:

• Node.js with pnpm
• uv (for building the docs site via uvx zensical)

Get set up:

git clone https://gitlab.com/risk-metrics/sierpe.git
cd sierpe
pnpm install

Common tasks:

pnpm dev            # run the live lab locally
pnpm test           # run the test suite (vitest)
pnpm test:coverage  # tests with coverage
pnpm lint           # biome check
pnpm typecheck      # tsc --noEmit
pnpm docs:serve     # build the lab embed + serve the docs site

License

MIT, see LICENSE.