add Box3D-powered Bad Movers game

packages/engine/src/physics-backend.ts

@@ -0,0 +1,32 @@
+/** Runtime information a game may expose without coupling itself to an SDK. */
+export interface PhysicsBackendMetadata {
+  readonly name: string;
+  readonly runtime: string;
+  readonly version?: string;
+}
+
+/**
+ * A pluggable deterministic physics runtime for a serializable game state.
+ *
+ * Native/WASM handles stay inside the backend. The engine only checkpoints the
+ * plain State value, so a backend must be able to initialize from that value
+ * and reconcile an existing runtime to a fresh snapshot.
+ */
+export interface PhysicsBackend<State, StepResult = void> {
+  readonly metadata: PhysicsBackendMetadata;
+  initialize(state: State): void;
+  step(state: State, deltaSeconds: number): StepResult;
+  reconcile(predicted: State, snapshot: State): void;
+  reset(state: State): void;
+  dispose?(state: State): void;
+}
+
+/**
+ * Developer-facing HOF used to define a typed physics plug-in once and retain
+ * any game-specific methods added by that plug-in.
+ */
+export function definePhysicsBackend<State, StepResult = void>() {
+  return <Backend extends PhysicsBackend<State, StepResult>>(
+    backend: Backend,
+  ): Readonly<Backend> => Object.freeze(backend);
+}