/** 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);
}