cs-movement

npm i @unsurf/cs-movement

import { World, PlayerController, brushFromAABB, vec3, DEFAULT_SETTINGS } from '@unsurf/cs-movement';

// 1. Build collision geometry.
const world = new World();
world.solids.push(brushFromAABB(vec3(-512, -16, -512), vec3(512, 0, 512)));

// 2. Spawn a player.
const player = new PlayerController(world, structuredClone(DEFAULT_SETTINGS), vec3(0, 8, 0));

// 3. Wire up WASD + pointer-lock mouse.
player.bindInput(canvas);

// 4. Step at a fixed tick rate, read state back each frame.
function gameLoop(dt: number) {
  player.tick(dt);
  // player.origin, player.velocity, player.onGround, etc.
}

import { World, PlayerController, brushFromAABB, vec3, DEFAULT_SETTINGS } from '@unsurf/cs-movement';

const world = new World();
world.solids.push(brushFromAABB(vec3(-8192, -64, -8192), vec3(8192, 0, 8192)));

const player = new PlayerController(world, structuredClone(DEFAULT_SETTINGS), vec3(0, 5, 0));
player.input.forward = true;
for (let i = 0; i < 512; i++) player.tick(1 / 128);

console.log(player.horizontalSpeed); // ~250

import { World, brushFromAABB, brushFromOrientedBox } from '@unsurf/cs-movement';

const world = new World();

// Axis-aligned box — two opposite corners.
world.solids.push(brushFromAABB(vec3(-512, -16, -512), vec3(512, 0, 512)));

// Oriented box — center, half-extents, and a local orthonormal basis.
// Tilt the "up" axis away from world-up and the top face becomes
// a walkable-or-surfable slope, decided purely by its normal.
world.solids.push(brushFromOrientedBox(
  vec3(0, 100, 0),        // center
  vec3(200, 8, 200),      // half-extents
  vec3(1, 0, 0),          // local X (right)
  vec3(0, 0.7, 0.7),      // local Y — tilted = surfable
  vec3(0, -0.7, 0.7),     // local Z
));

// Ladder volume — a Brush with a horizontal "facing" vector.
world.ladders.push({
  ...brushFromAABB(vec3(60, 0, -24), vec3(100, 600, 24)),
  facing: vec3(-1, 0, 0), // climbable face points away from the wall
});

world.trace(start, end, mins, maxs)        // hull sweep → TraceResult
world.isPositionFree(origin, mins, maxs)  // does the hull fit here?
world.ladderAt(origin, mins, maxs)        // which ladder (if any)?

new PlayerController(world: World, settings: Settings, spawn: Vec3, opts?: PlayerOptions)

interface PlayerOptions {
  log?: (msg: string) => void; // anomalies: unstuck pops, velocity kills
}

player.respawn(): void            // reset to spawn
player.tickHistoryText(): string  // last 384 ticks as text (bug reports)
player.bindInput(target: HTMLElement): void  // browser: WASD + mouse

player.input.forward = true;
player.input.jump = true;
player.yaw += 2;
player.tick(1 / 128);

import { DEFAULT_SETTINGS } from '@unsurf/cs-movement';
const settings = structuredClone(DEFAULT_SETTINGS);
settings.autobhop = true;
settings.bhopSpeedClamp = false; // uncapped CS:GO-style bhop
settings.airAccelerate = 100;   // KZ server (CS:GO default is 12)

interface StaminaSettings {
  enabled: boolean;      // default false
  max: number;           // default 1
  jumpCost: number;      // default 0.08 (fraction of max per jump)
  landCost: number;      // default 0.05 (fraction of max per landing)
  recoveryRate: number;  // default 0.5  (fraction of max per second)
  maxPenalty: number;    // default 0.4  (speed cut at full pool)
}

interface Plane {
  normal: Vec3;  // outward-facing unit normal
  dist: number;  // dot(normal, pointOnPlane)
}

interface Brush {
  planes: Plane[];
  min: Vec3;  // AABB broadphase bounds
  max: Vec3;
}

interface LadderVolume extends Brush {
  facing: Vec3;  // direction the climbable face points
}

interface TraceResult {
  fraction: number;    // 0..1 of move completed
  endPos: Vec3;
  normal: Vec3 | null; // hit plane, null if fraction === 1
  startSolid: boolean;
  allSolid: boolean;
}

interface Settings {
  sensitivity: number;
  mYaw: number;
  fov: number;
  tickRate: number;
  autobhop: boolean;
  bhopSpeedClamp: boolean;
  noPrestrafe: boolean;
  airAccelerate: number;
  runSpeed: number;
  walkSpeed: number;
  crouchSpeed: number;
  showSpeed: boolean;
  showFps: boolean;
  showDebug: boolean;
  viewPunch: boolean;
  crosshair: CrosshairSettings;
  stamina: StaminaSettings;
  perf: PerfSettings;
}

interface CrosshairSettings {
  color: string;
  size: number;
  thickness: number;
  gap: number;
  outline: boolean;
  dot: boolean;
  tStyle: boolean;
}

interface StaminaSettings {
  enabled: boolean;
  max: number;
  jumpCost: number;
  landCost: number;
  recoveryRate: number;
  maxPenalty: number;
}

interface PerfSettings {
  enabled: boolean;
  maxAirSpeed: number; // default 390
}

// In your render loop:
camera.position.set(
  player.origin.x,
  player.origin.y + player.eyeHeight,
  player.origin.z,
);
camera.rotation.order = "YXZ";
camera.rotation.y = THREE.MathUtils.degToRad(-player.yaw);
camera.rotation.x = THREE.MathUtils.degToRad(player.pitch);

// For smooth interpolation between fixed ticks:
const t = accumulator / dt; // 0..1 blend factor
camera.position.lerpVectors(
  new THREE.Vector3(player.prevPos.x, player.prevPos.y + player.prevEye, player.prevPos.z),
  new THREE.Vector3(player.currPos.x, player.currPos.y + player.currEye, player.currPos.z),
  t,
);

import { World, PlayerController, brushFromAABB, vec3, DEFAULT_SETTINGS } from '@unsurf/cs-movement';

const world = new World();
world.solids.push(brushFromAABB(vec3(-8192, -64, -8192), vec3(8192, 0, 8192)));

const player = new PlayerController(world, structuredClone(DEFAULT_SETTINGS), vec3(0, 5, 0), {
  log: (msg) => console.warn("[movement]", msg),
});

// Replay recorded inputs:
for (let i = 0; i < recordedInput.length; i++) {
  Object.assign(player.input, recordedInput[i]);
  player.tick(1 / 128);
}

// Dump for audit:
console.log(player.tickHistoryText());

// Skip bindInput entirely — drive the simulation:
player.input.forward = true;
player.input.jump = (tick % 64 < 1); // jump every 64 ticks
player.yaw += 2; // constant turn
player.tick(1 / 128);

const TICK_DT = 1 / 128;
let accumulator = 0;

function gameLoop(frameDt: number) {
  accumulator += frameDt;

  while (accumulator >= TICK_DT) {
    player.tick(TICK_DT);
    accumulator -= TICK_DT;
  }

  // Blend between prevPos and currPos for smooth rendering:
  const alpha = accumulator / TICK_DT;
  const renderX = player.prevPos.x + (player.currPos.x - player.prevPos.x) * alpha;
  const renderY = player.prevPos.y + (player.currPos.y - player.prevPos.y) * alpha;
  const renderZ = player.prevPos.z + (player.currPos.z - player.prevPos.z) * alpha;
  const renderEye = player.prevEye + (player.currEye - player.prevEye) * alpha;
  // position camera at (renderX, renderY + renderEye, renderZ)
}

const world = new World();

// Floor
world.solids.push(brushFromAABB(vec3(-2048, -16, -2048), vec3(2048, 0, 2048)));

// Surf ramp — tilt local Y ~30° from vertical
const ramp = brushFromOrientedBox(
  vec3(0, 200, 0),       // center
  vec3(512, 16, 200),    // half-extents
  vec3(1, 0, 0),         // local X
  vec3(0, 0.5, 0.866),   // local Y — tilted ~30° from vertical
  vec3(0, -0.866, 0.5),  // local Z
);
world.solids.push(ramp);

// Staircase
for (let i = 0; i < 10; i++) {
  world.solids.push(brushFromAABB(
    vec3(-100, i * 16, i * 100),
    vec3(100, (i + 1) * 16, (i + 1) * 100),
  ));
}