@simarena/viewport 0.0.1-alpha.0 → 0.0.1-alpha.1

package/src/sync.ts

@@ -1,13 +1,13 @@
-import * as THREE from 'three';
-import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import * as THREE from "three";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 
 // ── Body index ─────────────────────────────────────────────────────────────────
 // Maps entity names → frame indices (matches the order bodies appear in sim state).
 
 export function buildBodyIdx(names: string[]): Map<string, number> {
-	const m = new Map<string, number>();
-	names.forEach((n, i) => m.set(n, i));
-	return m;
+  const m = new Map<string, number>();
+  names.forEach((n, i) => m.set(n, i));
+  return m;
 }
 
 // ── Apply world-space transforms ───────────────────────────────────────────────
@@ -17,19 +17,20 @@ export function buildBodyIdx(names: string[]): Map<string, number> {
 // Bodies not in the map are skipped automatically.
 
 export function applyTransforms(
-	xpos: Float32Array,
-	xquat: Float32Array,
-	bodyIdx: Map<string, number>,
-	bodies: Map<string, THREE.Object3D>
+  xpos: Float32Array,
+  xquat: Float32Array,
+  bodyIdx: Map<string, number>,
+  bodies: Map<string, THREE.Object3D>,
 ): void {
-	for (const [name, idx] of bodyIdx) {
-		const obj = bodies.get(name);
-		if (!obj) continue;
-		const p = idx * 3, q = idx * 4;
-		obj.position.set(xpos[p]!, xpos[p + 1]!, xpos[p + 2]!);
-		// MuJoCo wxyz → Three.js xyzw
-		obj.quaternion.set(xquat[q + 1]!, xquat[q + 2]!, xquat[q + 3]!, xquat[q]!);
-	}
+  for (const [name, idx] of bodyIdx) {
+    const obj = bodies.get(name);
+    if (!obj) continue;
+    const p = idx * 3,
+      q = idx * 4;
+    obj.position.set(xpos[p]!, xpos[p + 1]!, xpos[p + 2]!);
+    // MuJoCo wxyz → Three.js xyzw
+    obj.quaternion.set(xquat[q + 1]!, xquat[q + 2]!, xquat[q + 3]!, xquat[q]!);
+  }
 }
 
 // ── Hierarchy flattening ───────────────────────────────────────────────────────
@@ -37,44 +38,44 @@ export function applyTransforms(
 // of the scene root. Flatten before sync, restore after.
 
 export interface BodySnapshot {
-	parent: THREE.Object3D;
-	pos: THREE.Vector3;
-	quat: THREE.Quaternion;
-	scale: THREE.Vector3;
+  parent: THREE.Object3D;
+  pos: THREE.Vector3;
+  quat: THREE.Quaternion;
+  scale: THREE.Vector3;
 }
 
 export function flattenBodies(
-	bodies: Map<string, THREE.Object3D>,
-	scene: THREE.Scene
+  bodies: Map<string, THREE.Object3D>,
+  scene: THREE.Scene,
 ): Map<string, BodySnapshot> {
-	const saved = new Map<string, BodySnapshot>();
-	for (const [name, obj] of bodies) {
-		saved.set(name, {
-			parent: obj.parent ?? scene,
-			pos: obj.position.clone(),
-			quat: obj.quaternion.clone(),
-			scale: obj.scale.clone(),
-		});
-		if (obj.parent !== scene) scene.attach(obj);
-	}
-	return saved;
+  const saved = new Map<string, BodySnapshot>();
+  for (const [name, obj] of bodies) {
+    saved.set(name, {
+      parent: obj.parent ?? scene,
+      pos: obj.position.clone(),
+      quat: obj.quaternion.clone(),
+      scale: obj.scale.clone(),
+    });
+    if (obj.parent !== scene) scene.attach(obj);
+  }
+  return saved;
 }
 
 export function restoreBodies(
-	flatBodies: Map<string, THREE.Object3D>,
-	saved: Map<string, BodySnapshot>
+  flatBodies: Map<string, THREE.Object3D>,
+  saved: Map<string, BodySnapshot>,
 ): void {
-	for (const [name, obj] of flatBodies) {
-		const snap = saved.get(name);
-		if (snap) {
-			snap.parent.add(obj);
-			obj.position.copy(snap.pos);
-			obj.quaternion.copy(snap.quat);
-			obj.scale.copy(snap.scale);
-		}
-		obj.matrixWorldAutoUpdate = true;
-		obj.matrixWorldNeedsUpdate = true;
-	}
+  for (const [name, obj] of flatBodies) {
+    const snap = saved.get(name);
+    if (snap) {
+      snap.parent.add(obj);
+      obj.position.copy(snap.pos);
+      obj.quaternion.copy(snap.quat);
+      obj.scale.copy(snap.scale);
+    }
+    obj.matrixWorldAutoUpdate = true;
+    obj.matrixWorldNeedsUpdate = true;
+  }
 }
 
 // ── HTTP body loading ──────────────────────────────────────────────────────────
@@ -82,52 +83,55 @@ export function restoreBodies(
 // Returns Map<name, Object3D> keyed by entity name, matching SceneDoc entity names.
 
 export interface BodyInfo {
-	id: number;
-	name: string;
-	fixed?: boolean;
-	size?: number;
+  id: number;
+  name: string;
+  fixed?: boolean;
+  size?: number;
 }
 
 export interface LoadBodiesOpts {
-	onProgress?: (loaded: number, total: number) => void;
+  onProgress?: (loaded: number, total: number) => void;
 }
 
 const loader = new GLTFLoader();
 
 export interface LoadBodiesResult {
-	bodies: Map<string, THREE.Object3D>;
-	manifest: BodyInfo[];
+  bodies: Map<string, THREE.Object3D>;
+  manifest: BodyInfo[];
 }
 
 export async function loadBodies(
-	httpBase: string,
-	parent: THREE.Object3D,
-	opts: LoadBodiesOpts = {}
+  httpBase: string,
+  parent: THREE.Object3D,
+  opts: LoadBodiesOpts = {},
 ): Promise<LoadBodiesResult> {
-	const base = httpBase.replace(/\/$/, '');
-	const res = await fetch(`${base}/bodies`);
-	const manifest: BodyInfo[] = await res.json();
-	const bodies = new Map<string, THREE.Object3D>();
-
-	await Promise.all(manifest.map(b =>
-		new Promise<void>(resolve => {
-			loader.load(`${base}/body/${b.id}.glb`, gltf => {
-				const mesh = gltf.scene;
-				mesh.traverse(c => {
-					if ((c as THREE.Mesh).isMesh) {
-						(c as THREE.Mesh).castShadow = true;
-						(c as THREE.Mesh).receiveShadow = true;
-					}
-				});
-				parent.add(mesh);
-				bodies.set(b.name, mesh);
-				opts.onProgress?.(bodies.size, manifest.length);
-				resolve();
-			});
-		})
-	));
-
-	return { bodies, manifest };
+  const base = httpBase.replace(/\/$/, "");
+  const res = await fetch(`${base}/bodies`);
+  const manifest: BodyInfo[] = await res.json();
+  const bodies = new Map<string, THREE.Object3D>();
+
+  await Promise.all(
+    manifest.map(
+      (b) =>
+        new Promise<void>((resolve) => {
+          loader.load(`${base}/body/${b.id}.glb`, (gltf) => {
+            const mesh = gltf.scene;
+            mesh.traverse((c) => {
+              if ((c as THREE.Mesh).isMesh) {
+                (c as THREE.Mesh).castShadow = true;
+                (c as THREE.Mesh).receiveShadow = true;
+              }
+            });
+            parent.add(mesh);
+            bodies.set(b.name, mesh);
+            opts.onProgress?.(bodies.size, manifest.length);
+            resolve();
+          });
+        }),
+    ),
+  );
+
+  return { bodies, manifest };
 }
 
 // ── WebSocket sim transport ────────────────────────────────────────────────────
@@ -136,54 +140,54 @@ export async function loadBodies(
 // Buffer length must be divisible by 7 (nbody*7 = pos+quat per body).
 
 export interface SimOpts {
-	onFps?: (fps: number) => void;
-	onParticles?: (positions: Float32Array) => void;
-	onConnect?: () => void;
-	onError?: (msg: string) => void;
-	onClose?: () => void;
+  onFps?: (fps: number) => void;
+  onParticles?: (positions: Float32Array) => void;
+  onConnect?: () => void;
+  onError?: (msg: string) => void;
+  onClose?: () => void;
 }
 
 export interface SimHandle {
-	close(): void;
+  close(): void;
 }
 
 export function connectSim(
-	wsUrl: string,
-	nbody: number,
-	onFrame: (xpos: Float32Array, xquat: Float32Array) => void,
-	opts: SimOpts = {}
+  wsUrl: string,
+  nbody: number,
+  onFrame: (xpos: Float32Array, xquat: Float32Array) => void,
+  opts: SimOpts = {},
 ): SimHandle {
-	const ws = new WebSocket(wsUrl);
-	ws.binaryType = 'arraybuffer';
-
-	let frames = 0;
-	let lastTick = performance.now();
-
-	ws.onopen = () => opts.onConnect?.();
-
-	ws.onmessage = e => {
-		const buf = new Float32Array(e.data as ArrayBuffer);
-		const xpos = buf.subarray(0, nbody * 3);
-		const xquat = buf.subarray(nbody * 3, nbody * 7);
-		onFrame(xpos, xquat);
-
-		// Optional particle data appended after transforms
-		if (buf.length > nbody * 7 && opts.onParticles) {
-			const rest = buf.subarray(nbody * 7);
-			if (rest.length % 3 === 0) opts.onParticles(rest);
-		}
-
-		frames++;
-		const now = performance.now();
-		if (now - lastTick >= 1000) {
-			opts.onFps?.(frames);
-			frames = 0;
-			lastTick = now;
-		}
-	};
-
-	ws.onerror = () => opts.onError?.('WebSocket error');
-	ws.onclose = () => opts.onClose?.();
-
-	return { close: () => ws.close() };
+  const ws = new WebSocket(wsUrl);
+  ws.binaryType = "arraybuffer";
+
+  let frames = 0;
+  let lastTick = performance.now();
+
+  ws.onopen = () => opts.onConnect?.();
+
+  ws.onmessage = (e) => {
+    const buf = new Float32Array(e.data as ArrayBuffer);
+    const xpos = buf.subarray(0, nbody * 3);
+    const xquat = buf.subarray(nbody * 3, nbody * 7);
+    onFrame(xpos, xquat);
+
+    // Optional particle data appended after transforms
+    if (buf.length > nbody * 7 && opts.onParticles) {
+      const rest = buf.subarray(nbody * 7);
+      if (rest.length % 3 === 0) opts.onParticles(rest);
+    }
+
+    frames++;
+    const now = performance.now();
+    if (now - lastTick >= 1000) {
+      opts.onFps?.(frames);
+      frames = 0;
+      lastTick = now;
+    }
+  };
+
+  ws.onerror = () => opts.onError?.("WebSocket error");
+  ws.onclose = () => opts.onClose?.();
+
+  return { close: () => ws.close() };
 }

package/src/types.ts

@@ -0,0 +1,83 @@
+// ── Engine-agnostic simulation state protocol ─────────────────────────────────
+// Types live in @simarena/viewport (the bridge layer), not in engine adapters.
+// Tier 1: transforms (universal)
+// Tier 2: sensors, qpos (most engines)
+// Tier 3: contacts (MuJoCo/Isaac only)
+
+export interface SimScene {
+  bodies: { name: string; id: number }[];
+  actuators: { name: string; range: [number, number] }[];
+  /** No engine-specific address offsets — adapters map internally. */
+  sensors: { name: string; dim: number }[];
+  /** Geom→body mapping for contact name resolution. */
+  geoms: { name: string; body: string }[];
+  timestep: number;
+  nbody: number;
+  nq: number;
+  nu: number;
+}
+
+export interface Contact {
+  geom1: string;
+  geom2: string;
+  pos: [number, number, number];
+  /** Scalar contact force magnitude. */
+  force: number;
+  /** Contact frame normal (unit vector, first row of contact.frame). */
+  normal?: [number, number, number];
+}
+
+export interface SimFrame {
+  time: number;
+  /** Flat world-space positions [x0,y0,z0, x1,...] per body. */
+  xpos: Float32Array;
+  /** Flat world-space quaternions wxyz [w0,x0,y0,z0, w1,...] per body. */
+  xquat: Float32Array;
+  qpos?: Float64Array;
+  ctrl?: Float64Array;
+  /** Named sensor readings: Record<sensorName, values[]>. */
+  sensors?: Record<string, number[]>;
+  /** Per-contact detail — Tier 3 only (MuJoCo/Isaac). */
+  contacts?: Contact[];
+  /** Engine-agnostic eval result — frontend narrows to EvalResult. */
+  output?: unknown;
+}
+
+// ── Commands (consumer → engine) ──────────────────────────────────────────────
+export type SimCommand =
+  | { type: "load"; scene: unknown }
+  | { type: "stop" }
+  | { type: "reset" }
+  | { type: "ctrl"; values: Float64Array }
+  | { type: "command"; values: Float32Array }
+  | { type: "setqpos"; qpos: Float64Array }
+  | { type: "pause" }
+  | { type: "resume" }
+  | {
+      type: "configure";
+      contacts?: boolean;
+      sensors?: boolean;
+      output?: boolean;
+      snapshotHz?: number;
+      speed?: number;
+    };
+
+// ── Events (engine → consumer) ────────────────────────────────────────────────
+export type SimEvent =
+  | { type: "scene"; data: SimScene }
+  | { type: "frame"; data: SimFrame }
+  | { type: "status"; text: string }
+  | { type: "error"; message: string };
+
+// ── Connection ────────────────────────────────────────────────────────────────
+// A bidirectional channel to any sim engine — local Worker or remote server.
+// Obtained from a transport-specific factory (connectWorker, connectWs, etc.).
+export interface SimConnection {
+  send(cmd: SimCommand): void;
+  on(type: "scene", cb: (data: SimScene) => void): void;
+  on(type: "frame", cb: (data: SimFrame) => void): void;
+  on(type: "status", cb: (text: string) => void): void;
+  on(type: "error", cb: (message: string) => void): void;
+  off(type: string, cb: (...args: never[]) => void): void;
+  close(): void;
+}