@reactvision/react-viro 2.53.1 → 2.55.0

package/components/Studio/domain/collisionBindingsRuntime.ts

@@ -0,0 +1,93 @@
+import { MutableRefObject } from "react";
+import { StudioAnimation, StudioCollisionBinding } from "../types";
+import { canonicalizeCollisionAssetIds, collisionPairKey } from "./collisionPairKey";
+import { executeFunctionWithRelations } from "./sceneNavigationHandler";
+
+const DEFAULT_COOLDOWN_MS = 750;
+
+function pairCooldownKey(pairKey: string, functionId: string): string {
+  return `${pairKey}::${functionId}`;
+}
+
+/**
+ * Dispatches scene functions for collision bindings matching the canonical pair.
+ * Cooldown prevents per-frame spam while physics contacts overlap.
+ */
+export function dispatchCollisionBindingActions(params: {
+  selfPlacementId: string;
+  otherTag: string;
+  bindingsByPairKey: Map<string, StudioCollisionBinding[]>;
+  sceneNavigator?: unknown;
+  animations: StudioAnimation[];
+  onSceneChange?: (sceneId: string, sceneName: string) => void;
+  onAnimationTrigger?: (targetAssetId: string, animationKey: string) => void;
+  cooldownMs?: number;
+  lastFiredRef: MutableRefObject<Map<string, number>>;
+}): void {
+  const {
+    selfPlacementId,
+    otherTag,
+    bindingsByPairKey,
+    sceneNavigator,
+    animations,
+    onSceneChange,
+    onAnimationTrigger,
+    cooldownMs = DEFAULT_COOLDOWN_MS,
+    lastFiredRef,
+  } = params;
+
+  if (!otherTag) return;
+
+  const { asset_x_id, asset_y_id } = canonicalizeCollisionAssetIds(
+    selfPlacementId,
+    otherTag
+  );
+  const pKey = collisionPairKey(asset_x_id, asset_y_id);
+  const rows = bindingsByPairKey.get(pKey);
+  if (!rows?.length) return;
+
+  const now = Date.now();
+  const map = lastFiredRef.current;
+
+  for (const row of rows) {
+    const fn = row.scene_function;
+    if (!fn) continue;
+
+    const ck = pairCooldownKey(pKey, row.function_id);
+    const last = map.get(ck) ?? 0;
+    if (now - last < cooldownMs) continue;
+    map.set(ck, now);
+
+    executeFunctionWithRelations(fn, sceneNavigator, animations, onAnimationTrigger, 0, onSceneChange);
+  }
+}
+
+/**
+ * Returns an onCollision handler for a given placement asset ID.
+ */
+export function createPlacementCollisionHandler(
+  placementId: string,
+  bindingsByPairKey: Map<string, StudioCollisionBinding[]>,
+  sceneNavigator: unknown,
+  animations: StudioAnimation[],
+  lastFiredRef: MutableRefObject<Map<string, number>>,
+  onAnimationTrigger?: (targetAssetId: string, animationKey: string) => void,
+  onSceneChange?: (sceneId: string, sceneName: string) => void,
+): (
+  viroTag: string,
+  collidedPoint: [number, number, number],
+  collidedNormal: [number, number, number]
+) => void {
+  return (viroTag) => {
+    dispatchCollisionBindingActions({
+      selfPlacementId: placementId,
+      otherTag: viroTag,
+      bindingsByPairKey,
+      sceneNavigator,
+      animations,
+      onSceneChange,
+      onAnimationTrigger,
+      lastFiredRef,
+    });
+  };
+}

package/components/Studio/domain/collisionPairKey.ts

@@ -0,0 +1,15 @@
+/**
+ * Canonical collision pair — matches DB constraint where asset_x_id < asset_y_id lexicographically.
+ */
+export function canonicalizeCollisionAssetIds(
+  a: string,
+  b: string
+): { asset_x_id: string; asset_y_id: string } {
+  return a < b
+    ? { asset_x_id: a, asset_y_id: b }
+    : { asset_x_id: b, asset_y_id: a };
+}
+
+export function collisionPairKey(assetX: string, assetY: string): string {
+  return `${assetX}|${assetY}`;
+}

package/components/Studio/domain/dragConfiguration.ts

@@ -0,0 +1,48 @@
+import { StudioAsset, StudioSceneMeta } from "../types";
+
+export type DragType = "FixedToWorld" | "FixedToPlane" | undefined;
+
+export type DragPlane = {
+  planePoint: [number, number, number];
+  planeNormal: [number, number, number];
+  maxDistance: number;
+};
+
+export class DragConfiguration {
+  /**
+   * Chooses FixedToPlane when the scene uses plane detection, FixedToWorld otherwise.
+   * Returns undefined if the asset is not draggable.
+   */
+  static getDragType(asset: StudioAsset, scene: StudioSceneMeta | null): DragType {
+    if (!asset.is_draggable) return undefined;
+
+    const planeDetection = ((scene?.plane_detection as string) ?? "NONE").toUpperCase();
+
+    if (planeDetection === "AUTOMATIC" || planeDetection === "MANUAL") {
+      return "FixedToPlane";
+    }
+    return "FixedToWorld";
+  }
+
+  /**
+   * Returns a drag plane that passes through the object's current position,
+   * preventing objects from jumping on drag start. maxDistance caps how far
+   * objects can travel from the camera.
+   */
+  static getDragPlane(
+    planeAlignment: string,
+    objectPosition: [number, number, number],
+  ): DragPlane {
+    switch (planeAlignment.toLowerCase()) {
+      case "horizontal":
+      case "horizontalupward":
+        return { planePoint: objectPosition, planeNormal: [0, 1, 0], maxDistance: 1.5 };
+      case "horizontaldownward":
+        return { planePoint: objectPosition, planeNormal: [0, -1, 0], maxDistance: 1.5 };
+      case "vertical":
+        return { planePoint: objectPosition, planeNormal: [0, 0, 1], maxDistance: 1.5 };
+      default:
+        return { planePoint: objectPosition, planeNormal: [0, 1, 0], maxDistance: 1.5 };
+    }
+  }
+}

package/components/Studio/domain/materialConfig.ts

@@ -0,0 +1,276 @@
+/**
+ * Studio material_config parsing and Viro material definition building.
+ * Ported from studio-go/domain/materialConfig.ts — no zod dependency.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+type ShaderModifierStage = {
+  uniforms?: string;
+  body?: string;
+  varyings?: unknown;
+  requiresSceneDepth?: boolean;
+  requiresCameraTexture?: boolean;
+  priority?: unknown;
+};
+
+export type MaterialConfig = {
+  presetName?: string;
+  lightingModel: "Constant" | "Lambert" | "Blinn" | "Phong" | "PBR";
+  diffuseColor?: string;
+  roughness?: number;
+  metalness?: number;
+  shininess?: number;
+  alpha?: number;
+  blendMode?: string;
+  bloomThreshold?: number | null;
+  wrapS?: "Clamp" | "Repeat" | "Mirror";
+  wrapT?: "Clamp" | "Repeat" | "Mirror";
+  diffuseTexture?: string | null;
+  normalTexture?: string | null;
+  roughnessTexture?: string | null;
+  metalnessTexture?: string | null;
+  ambientOcclusionTexture?: string | null;
+  specularTexture?: string | null;
+  shaderModifiers?: Record<string, ShaderModifierStage | string>;
+  materialUniforms?: Array<{ name: string; type: string; value: unknown }>;
+  transparencyMode?: string;
+  cullMode?: string;
+};
+
+export type ViroMaterialDefinition = Record<string, unknown>;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const TEXTURE_KEYS = [
+  "diffuseTexture",
+  "normalTexture",
+  "roughnessTexture",
+  "metalnessTexture",
+  "ambientOcclusionTexture",
+  "specularTexture",
+] as const;
+
+function textureToViro(uri: string | null | undefined): { uri: string } | undefined {
+  if (uri == null || uri === "") return undefined;
+  return { uri };
+}
+
+function collectShaderModifierStrings(config: MaterialConfig): string[] {
+  const mods = config.shaderModifiers;
+  if (!mods) return [];
+  const strings: string[] = [];
+  for (const stage of Object.values(mods)) {
+    if (typeof stage === "string") {
+      strings.push(stage);
+    } else if (stage && typeof stage === "object") {
+      const s = stage as ShaderModifierStage;
+      if (typeof s.uniforms === "string") strings.push(s.uniforms);
+      if (typeof s.body === "string") strings.push(s.body);
+    }
+  }
+  return strings;
+}
+
+const TIME_WORD_RE = /\btime\b/i;
+const CAMERA_TEXTURE_RE = /\bcamera_texture\b/;
+const RF_VIEWPORT_RE = /\b_rf_vpw\b|\b_rf_vph\b/;
+
+export function materialConfigNeedsTimeUniform(config: MaterialConfig): boolean {
+  if (config.materialUniforms?.some((u) => u.name === "time")) return true;
+  return collectShaderModifierStrings(config).some((s) => TIME_WORD_RE.test(s));
+}
+
+/**
+ * True if the shader uses _rf_vpw/_rf_vph viewport uniforms.
+ * These must be pushed via ViroMaterials.updateShaderUniform on mount and orientation change.
+ */
+export function materialConfigNeedsViewportUniforms(config: MaterialConfig): boolean {
+  return collectShaderModifierStrings(config).some((s) => RF_VIEWPORT_RE.test(s));
+}
+
+/**
+ * Prepends GLSL uniform declarations that the body references but the uniforms block omits.
+ * Required when shaders are authored for remote delivery without explicit sampler declarations.
+ */
+function injectMissingGlslDeclarations(uniforms: string, body: string): string {
+  let result = uniforms;
+  if (CAMERA_TEXTURE_RE.test(body) && !CAMERA_TEXTURE_RE.test(result)) {
+    result =
+      "uniform sampler2D camera_texture;\nuniform highp mat4 camera_image_transform;\n" +
+      result;
+  }
+  if (RF_VIEWPORT_RE.test(body) && !/\b_rf_vpw\b/.test(result)) {
+    result = "uniform highp float _rf_vpw;\nuniform highp float _rf_vph;\n" + result;
+  }
+  return result;
+}
+
+/**
+ * iOS only applies `ViroMaterials.updateShaderUniform` to uniforms registered
+ * via `materialUniforms`. If a shader references `time` or viewport uniforms in
+ * GLSL only, we add the runtime binding here.
+ */
+function mergeMaterialUniformsForViro(
+  config: MaterialConfig,
+): Array<{ name: string; type: string; value: unknown }> | undefined {
+  const list = config.materialUniforms
+    ? config.materialUniforms.map((u) => ({ name: u.name, type: u.type, value: u.value }))
+    : [];
+
+  if (materialConfigNeedsTimeUniform(config) && !list.some((u) => u.name === "time")) {
+    list.push({ name: "time", type: "float", value: 0 });
+  }
+
+  if (materialConfigNeedsViewportUniforms(config)) {
+    if (!list.some((u) => u.name === "_rf_vpw"))
+      list.push({ name: "_rf_vpw", type: "float", value: 0 });
+    if (!list.some((u) => u.name === "_rf_vph"))
+      list.push({ name: "_rf_vph", type: "float", value: 0 });
+  }
+
+  return list.length > 0 ? list : undefined;
+}
+
+/**
+ * Studio stores modifiers as `{ uniforms, body }`; Viro works best with a single
+ * GLSL string per stage. Stages with advanced fields are kept as structured objects.
+ * Camera texture usage is detected from GLSL and auto-flagged so the Viro native
+ * layer binds the camera feed even when the DB JSON omits `requiresCameraTexture`.
+ */
+function normalizeShaderModifiersForViro(
+  mods: NonNullable<MaterialConfig["shaderModifiers"]>,
+): Record<string, string | object> {
+  const out: Record<string, string | object> = {};
+  for (const [key, stage] of Object.entries(mods)) {
+    if (typeof stage === "string") {
+      out[key] = stage;
+      continue;
+    }
+    if (stage && typeof stage === "object") {
+      const s = stage as ShaderModifierStage;
+      const uniforms = typeof s.uniforms === "string" ? s.uniforms : "";
+      const body = typeof s.body === "string" ? s.body : "";
+
+      // Detect camera texture usage in GLSL even when the flag is absent from DB JSON.
+      const usesCameraTexture =
+        CAMERA_TEXTURE_RE.test(body) || CAMERA_TEXTURE_RE.test(uniforms);
+
+      const hasAdvanced =
+        s.varyings != null ||
+        s.requiresSceneDepth === true ||
+        s.requiresCameraTexture === true ||
+        usesCameraTexture ||
+        s.priority != null;
+
+      if (hasAdvanced) {
+        if (usesCameraTexture && s.requiresCameraTexture !== true) {
+          // Auto-fix: flag the stage and inject any missing GLSL declarations so the
+          // native Viro layer binds camera_texture and the shader compiles cleanly.
+          out[key] = {
+            ...s,
+            requiresCameraTexture: true,
+            uniforms: injectMissingGlslDeclarations(uniforms, body),
+          };
+        } else {
+          out[key] = stage as object;
+        }
+        continue;
+      }
+      const merged = [uniforms.trim(), body.trim()].filter(Boolean).join("\n");
+      out[key] = merged.length > 0 ? merged : (stage as object);
+    }
+  }
+  return out;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export function studioMaterialName(assetId: string): string {
+  return `studio_${assetId}`;
+}
+
+/**
+ * Parses `scene_assets.material_config` JSON. Returns null if missing or invalid.
+ */
+export function parseMaterialConfig(raw: unknown): MaterialConfig | null {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+
+  try {
+    const config: MaterialConfig = {
+      lightingModel:
+        (["Constant", "Lambert", "Blinn", "Phong", "PBR"].includes(r.lightingModel as string)
+          ? r.lightingModel
+          : "PBR") as MaterialConfig["lightingModel"],
+    };
+
+    if (typeof r.presetName === "string")    config.presetName    = r.presetName;
+    if (typeof r.diffuseColor === "string")  config.diffuseColor  = r.diffuseColor;
+    if (typeof r.roughness === "number")     config.roughness     = r.roughness;
+    if (typeof r.metalness === "number")     config.metalness     = r.metalness;
+    if (typeof r.shininess === "number")     config.shininess     = r.shininess;
+    if (typeof r.alpha === "number")         config.alpha         = r.alpha;
+    if (typeof r.blendMode === "string")     config.blendMode     = r.blendMode;
+    if (r.bloomThreshold != null && typeof r.bloomThreshold === "number")
+                                             config.bloomThreshold = r.bloomThreshold;
+    if (["Clamp","Repeat","Mirror"].includes(r.wrapS as string)) config.wrapS = r.wrapS as any;
+    if (["Clamp","Repeat","Mirror"].includes(r.wrapT as string)) config.wrapT = r.wrapT as any;
+    if (typeof r.transparencyMode === "string") config.transparencyMode = r.transparencyMode;
+    if (typeof r.cullMode === "string")      config.cullMode      = r.cullMode;
+
+    for (const key of TEXTURE_KEYS) {
+      const v = r[key];
+      if (typeof v === "string" || v === null) (config as any)[key] = v;
+    }
+
+    if (r.shaderModifiers && typeof r.shaderModifiers === "object" && !Array.isArray(r.shaderModifiers)) {
+      config.shaderModifiers = r.shaderModifiers as Record<string, ShaderModifierStage | string>;
+    }
+
+    if (Array.isArray(r.materialUniforms)) {
+      config.materialUniforms = r.materialUniforms.filter(
+        (u): u is { name: string; type: string; value: unknown } =>
+          u && typeof u.name === "string" && typeof u.type === "string",
+      );
+    }
+
+    return config;
+  } catch (e) {
+    console.warn("[material_config] Failed to parse material_config", e);
+    return null;
+  }
+}
+
+/**
+ * Maps a validated Studio material_config to Viro's `createMaterials` definition shape.
+ */
+export function buildViroMaterialDefinition(config: MaterialConfig): ViroMaterialDefinition {
+  const out: ViroMaterialDefinition = { lightingModel: config.lightingModel };
+
+  if (config.diffuseColor  !== undefined) out.diffuseColor  = config.diffuseColor;
+  if (config.roughness     !== undefined) out.roughness     = config.roughness;
+  if (config.metalness     !== undefined) out.metalness     = config.metalness;
+  if (config.shininess     !== undefined) out.shininess     = config.shininess;
+  if (config.alpha         !== undefined) out.alpha         = config.alpha;
+  if (config.blendMode     !== undefined) out.blendMode     = config.blendMode;
+  if (config.bloomThreshold!= undefined) out.bloomThreshold = config.bloomThreshold;
+  if (config.wrapS         !== undefined) out.wrapS         = config.wrapS;
+  if (config.wrapT         !== undefined) out.wrapT         = config.wrapT;
+  if (config.transparencyMode !== undefined) out.transparencyMode = config.transparencyMode;
+  if (config.cullMode      !== undefined) out.cullMode      = config.cullMode;
+
+  for (const key of TEXTURE_KEYS) {
+    const mapped = textureToViro((config as any)[key]);
+    if (mapped !== undefined) out[key] = mapped;
+  }
+
+  if (config.shaderModifiers !== undefined) {
+    out.shaderModifiers = normalizeShaderModifiersForViro(config.shaderModifiers);
+  }
+
+  const mergedUniforms = mergeMaterialUniformsForViro(config);
+  if (mergedUniforms !== undefined) out.materialUniforms = mergedUniforms;
+
+  return out;
+}

package/components/Studio/domain/physicsConfig.ts

@@ -0,0 +1,204 @@
+/**
+ * Studio physics_config and physics_world_config parsing and Viro prop building.
+ * Ported from studio-go/domain/physicsConfig.ts — no zod dependency.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+type Vec3 = [number, number, number];
+
+type ForceEntry = { value: Vec3; position?: Vec3 };
+
+type PhysicsShape =
+  | { type: "Box"; params: [number, number, number] }
+  | { type: "Sphere"; params: [number] }
+  | { type: "Compound"; children: Array<{ type: "Box" | "Sphere"; params: number[]; position: Vec3; rotation?: Vec3 }> };
+
+export type PhysicsBodyConfig = {
+  enabled: boolean;
+  type: "Dynamic" | "Kinematic" | "Static";
+  mass: number;
+  shape?: PhysicsShape;
+  restitution?: number;
+  friction?: number;
+  useGravity?: boolean;
+  viroTag?: string;
+  force?: ForceEntry | ForceEntry[];
+  torque?: Vec3 | Vec3[];
+  velocity?: Vec3;
+};
+
+export type PhysicsWorldConfig = {
+  enabled: boolean;
+  gravity: Vec3;
+  drawBounds: boolean;
+};
+
+export type BuildViroPhysicsBodyOptions = {
+  /** Forces Dynamic body to Kinematic with mass 0 while dragging. */
+  kinematicDragOverride?: boolean;
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function isVec3(v: unknown): v is Vec3 {
+  return Array.isArray(v) && v.length === 3 && v.every((n) => typeof n === "number");
+}
+
+function parseShape(raw: unknown): PhysicsShape | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const r = raw as Record<string, unknown>;
+
+  if (r.type === "Box" && Array.isArray(r.params) && r.params.length === 3) {
+    return { type: "Box", params: r.params as [number, number, number] };
+  }
+  if (r.type === "Sphere" && Array.isArray(r.params) && r.params.length >= 1) {
+    return { type: "Sphere", params: [r.params[0] as number] };
+  }
+  if (r.type === "Compound" && Array.isArray(r.children)) {
+    const children = (r.children as unknown[]).filter((c): c is { type: "Box" | "Sphere"; params: number[]; position: Vec3; rotation?: Vec3 } => {
+      if (!c || typeof c !== "object") return false;
+      const ch = c as Record<string, unknown>;
+      return (ch.type === "Box" || ch.type === "Sphere") && Array.isArray(ch.params) && isVec3(ch.position);
+    });
+    if (children.length > 0) return { type: "Compound", children };
+  }
+  return undefined;
+}
+
+function mapShapeToViro(shape: PhysicsShape): Record<string, unknown> {
+  if (shape.type === "Box") return { type: "Box", params: [...shape.params] };
+  if (shape.type === "Sphere") return { type: "Sphere", params: [...shape.params] };
+  return {
+    type: "Compound",
+    params: [],
+    children: shape.children.map((c) => {
+      const base: Record<string, unknown> = { type: c.type, params: [...c.params], position: [...c.position] };
+      if (c.rotation) base.rotation = [...c.rotation];
+      return base;
+    }),
+  };
+}
+
+function normalizeTorque(torque: Vec3 | Vec3[]): Vec3 {
+  if (Array.isArray(torque[0])) {
+    return (torque as Vec3[]).reduce<Vec3>(
+      (acc, t) => [acc[0] + t[0], acc[1] + t[1], acc[2] + t[2]],
+      [0, 0, 0],
+    );
+  }
+  return [...(torque as Vec3)] as Vec3;
+}
+
+function normalizeForce(force: ForceEntry | ForceEntry[]): Array<{ value: number[]; position?: number[] }> {
+  const arr = Array.isArray(force) ? force : [force];
+  return arr.map((f) => ({
+    value: [...f.value],
+    position: f.position != null ? [...f.position] : undefined,
+  }));
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Parses `scene.physics_world_config` JSON. Returns null if missing or invalid.
+ */
+export function parsePhysicsWorldConfig(raw: unknown): PhysicsWorldConfig | null {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+  try {
+    return {
+      enabled: typeof r.enabled === "boolean" ? r.enabled : false,
+      gravity: isVec3(r.gravity) ? r.gravity : [0, -9.8, 0],
+      drawBounds: typeof r.drawBounds === "boolean" ? r.drawBounds : false,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parses `asset.physics_config` JSON. Returns null if missing or invalid.
+ */
+export function parsePhysicsBodyConfig(raw: unknown): PhysicsBodyConfig | null {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+  try {
+    const type = (["Dynamic", "Kinematic", "Static"].includes(r.type as string)
+      ? r.type
+      : undefined) as PhysicsBodyConfig["type"] | undefined;
+    if (!type) return null;
+
+    const mass = typeof r.mass === "number" ? r.mass : 0;
+    const config: PhysicsBodyConfig = {
+      enabled: typeof r.enabled === "boolean" ? r.enabled : true,
+      type,
+      mass,
+    };
+
+    const shape = parseShape(r.shape);
+    if (shape) config.shape = shape;
+    if (typeof r.restitution === "number") config.restitution = r.restitution;
+    if (typeof r.friction === "number")    config.friction    = r.friction;
+    if (typeof r.useGravity === "boolean") config.useGravity  = r.useGravity;
+    if (typeof r.viroTag === "string")     config.viroTag     = r.viroTag;
+    if (isVec3(r.velocity))               config.velocity    = r.velocity;
+    if (r.torque != null)                 config.torque      = r.torque as Vec3 | Vec3[];
+    if (r.force != null)                  config.force       = r.force as ForceEntry | ForceEntry[];
+
+    return config;
+  } catch {
+    return null;
+  }
+}
+
+/** Viro `ViroARScene` physicsWorld prop. */
+export function buildViroPhysicsWorld(config: PhysicsWorldConfig): {
+  gravity: Vec3;
+  drawBounds?: boolean;
+} {
+  return {
+    gravity: [...config.gravity] as Vec3,
+    ...(config.drawBounds ? { drawBounds: true } : {}),
+  };
+}
+
+/** Maps validated Studio physics_config to Viro `physicsBody` prop. */
+export function buildViroPhysicsBody(
+  config: PhysicsBodyConfig,
+  options?: BuildViroPhysicsBodyOptions,
+): Record<string, unknown> {
+  const kinematicDrag =
+    options?.kinematicDragOverride === true && config.type === "Dynamic" && config.enabled;
+
+  const type = kinematicDrag ? "Kinematic" : config.type;
+  const mass = kinematicDrag ? 0 : config.mass;
+  const shape = mapShapeToViro(config.shape ?? { type: "Box", params: [1, 1, 1] });
+
+  const body: Record<string, unknown> = { type, mass, shape, enabled: config.enabled };
+
+  if (config.restitution !== undefined) body.restitution = config.restitution;
+  if (config.friction    !== undefined) body.friction    = config.friction;
+  if (config.useGravity  !== undefined) body.useGravity  = kinematicDrag ? false : config.useGravity;
+  if (config.velocity    !== undefined) body.velocity    = [...config.velocity];
+  if (config.torque      !== undefined) body.torque      = normalizeTorque(config.torque);
+  if (config.force       !== undefined) body.force       = normalizeForce(config.force);
+
+  return body;
+}
+
+/**
+ * Draggable Dynamic bodies need kinematic override during drag so the simulation
+ * doesn't fight the gesture.
+ */
+export function shouldUseKinematicPhysicsDrag(
+  asset: { is_draggable: boolean },
+  config: PhysicsBodyConfig | null,
+): boolean {
+  return (
+    asset.is_draggable === true &&
+    config != null &&
+    config.enabled === true &&
+    config.type === "Dynamic"
+  );
+}