API Overview

This document covers the core interfaces for building simulations on PHYS.RUN.

Codex Schema

A Codex is a JSON document conforming to the CodexSchema type. At the top level:

interface CodexSchema {
  version: "2.0";
  meta: {
    title: string;
    description?: string;
    author?: string;
    tags?: string[];
  };
  world: WorldConfig;
  entities: Entity[];
  timeline?: TimelineKeyframe[];
}

WorldConfig

Controls global simulation parameters:

interface WorldConfig {
  gravity: [number, number];    // m/s², default [0, -9.81]
  bounds?: {
    width: number;              // meters
    height: number;
  };
  timestep?: number;            // seconds, default 1/60
  renderer?: "svg" | "canvas" | "webgl";
}

Entity Types

PHYS.RUN supports the following entity primitives:

Type	Description	Key Properties
circle	Circular rigid body	radius, mass
rect	Rectangular rigid body	width, height, mass
polygon	Convex polygon	vertices, mass
particle	Massless point	position, velocity
spring	Constraint between entities	stiffness, damping
curve	Parametric path	equation, domain

Runtime API

The simulation runtime exposes a JavaScript API for programmatic control:

// Get the simulation instance
const sim = PhysRun.getSimulation("my-codex-id");

// Control playback
sim.play();
sim.pause();
sim.reset();
sim.step();              // Advance one frame

// Query state
sim.getEntity("ball");   // Returns entity state
sim.getTime();           // Current simulation time

// Modify at runtime
sim.setGravity([0, -20]);
sim.addEntity({ type: "circle", position: [0, 10], radius: 0.3 });

Rate Limits

The public API enforces the following limits:

Tier	Requests/min	Max Entities	Max Duration
Free	60	50	30s
Pro	600	500	300s
Enterprise	Unlimited	Unlimited	Unlimited

Further Reading

• Introduction — Platform overview and architecture.
• Quickstart — Build your first simulation.