feat(locomotion): expose config options in WorldOptions and add enableJumping

Summary:
Forward initialPlayerPosition, comfortAssist, turningMethod, and a new
enableJumping toggle through WorldOptions.features.locomotion so users
can configure locomotion at World.create time without reaching into
system internals.

Reviewed By: zjm-meta

Differential Revision: D94388774

fbshipit-source-id: 2e22fd5843dd7f659ba4b7e7a83acff30d06fc20

Author: felixtrz

.gitignore

@@ -62,6 +62,9 @@ temp/
 # Development tools
 .aider.conf.yml
 .claude/
+.codex/
+.cursor/
+.mcp.json
 
 # Backup files created by build scripts
 **/package.json.backup
@@ -82,13 +85,13 @@ examples/**/public/glxf/
 examples/**/public/gltf/generated/
 examples/**/public/ui/
 examples/**/metaspatial/components/
-example-local-build/**/public/glxf/
-example-local-build/**/public/gltf/generated/
-example-local-build/**/public/ui/
 
 # Auto generated version files
 **/version.ts
 **/version.js
 
 # Meta Spatial Editor CLI (downloaded by build-examples.sh in CI)
 .meta-spatial-cli/
+
+# Local playground (created via `node packages/create/dist/cli.js playground`)
+/playground/

packages/core/src/init/world-initializer.ts

@@ -27,7 +27,7 @@ import { Interactable, Hovered, Pressed } from '../grab/index.js';
 import { InputSystem } from '../input/index.js';
 import { LevelTag, LevelRoot } from '../level/index.js';
 import { LevelSystem } from '../level/index.js';
-import { LocomotionSystem } from '../locomotion/index.js';
+import { LocomotionSystem, TurningMethod } from '../locomotion/index.js';
 import { MCPRuntime } from '../mcp/index.js';
 import {
   PhysicsBody,
@@ -101,7 +101,16 @@ export type WorldOptions = {
   /** Opt‑in feature systems. */
   features?: {
     /** Locomotion (teleport/slide/turn). Boolean or config. @defaultValue false */
-    locomotion?: boolean | { useWorker?: boolean };
+    locomotion?:
+      | boolean
+      | {
+          useWorker?: boolean;
+          initialPlayerPosition?: [number, number, number];
+          comfortAssistLevel?: number;
+          turningMethod?: TurningMethod;
+          /** Whether jumping is enabled. @defaultValue true */
+          enableJumping?: boolean;
+        };
     /** Grabbing (one/two‑hand, distance). @defaultValue false */
     grabbing?: boolean | { useHandPinchForGrab?: boolean };
     /** Physics simulation (Havok). @defaultValue false */
@@ -442,7 +451,13 @@ function registerFeatureSystems(
 ) {
   const locomotion = config.features.locomotion as
     | boolean
-    | { useWorker?: boolean };
+    | {
+        useWorker?: boolean;
+        initialPlayerPosition?: [number, number, number];
+        comfortAssistLevel?: number;
+        turningMethod?: TurningMethod;
+        enableJumping?: boolean;
+      };
   const locomotionEnabled = !!locomotion;
   const grabbing = config.features.grabbing as
     | boolean
@@ -467,7 +482,15 @@ function registerFeatureSystems(
   if (locomotionEnabled) {
     const locOpts =
       typeof locomotion === 'object' && locomotion
-        ? { useWorker: locomotion.useWorker }
+        ? Object.fromEntries(
+            Object.entries({
+              useWorker: locomotion.useWorker,
+              initialPlayerPosition: locomotion.initialPlayerPosition,
+              comfortAssist: locomotion.comfortAssistLevel,
+              turningMethod: locomotion.turningMethod,
+              enableJumping: locomotion.enableJumping,
+            }).filter(([, v]) => v !== undefined),
+          )
         : undefined;
     world.registerSystem(LocomotionSystem, {
       priority: -5,
@@ -478,7 +501,11 @@ function registerFeatureSystems(
   if (grabbingEnabled) {
     const grabOpts =
       typeof grabbing === 'object' && grabbing
-        ? { useHandPinchForGrab: grabbing.useHandPinchForGrab }
+        ? Object.fromEntries(
+            Object.entries({
+              useHandPinchForGrab: grabbing.useHandPinchForGrab,
+            }).filter(([, v]) => v !== undefined),
+          )
         : undefined;
     world.registerSystem(GrabSystem, { priority: -3, configData: grabOpts });
   }
@@ -496,7 +523,11 @@ function registerFeatureSystems(
   if (sceneUnderstandingEnabled) {
     const sceneOpts =
       typeof sceneUnderstanding === 'object' && sceneUnderstanding
-        ? { showWireFrame: sceneUnderstanding.showWireFrame }
+        ? Object.fromEntries(
+            Object.entries({
+              showWireFrame: sceneUnderstanding.showWireFrame,
+            }).filter(([, v]) => v !== undefined),
+          )
         : undefined;
     world
       .registerComponent(XRPlane)

packages/core/src/locomotion/locomotion.ts

@@ -90,6 +90,8 @@ export class LocomotionSystem extends createSystem(
     jumpCooldown: { type: Types.Float32, default: 0.1 },
     /** Button used to jump in SlideSystem. */
     jumpButton: { type: Types.String, default: InputComponent.A_Button },
+    /** Whether jumping is enabled. */
+    enableJumping: { type: Types.Boolean, default: true },
   },
 ) {
   private locomotor!: Locomotor;
@@ -150,6 +152,11 @@ export class LocomotionSystem extends createSystem(
             this.slideSystem.config.jumpButton.value = value;
           }
         }),
+        this.config.enableJumping.subscribe((value) => {
+          if (this.slideSystem) {
+            this.slideSystem.config.enableJumping.value = value;
+          }
+        }),
       );
     });
 
@@ -190,6 +197,7 @@ export class LocomotionSystem extends createSystem(
         maxSpeed: this.config.slidingSpeed.value,
         comfortAssist: this.config.comfortAssist.value,
         jumpButton: this.config.jumpButton.value,
+        enableJumping: this.config.enableJumping.value,
         locomotor: this.locomotor,
       },
     });
@@ -204,6 +212,9 @@ export class LocomotionSystem extends createSystem(
   }
 
   private addEnvironmentToEngine(entity: Entity): void {
+    if (!this.locomotor?.isInitialized()) {
+      return;
+    }
     if (entity.getValue(LocomotionEnvironment, '_initialized')) {
       return; // Already initialized
     }
@@ -230,6 +241,9 @@ export class LocomotionSystem extends createSystem(
   }
 
   private removeEnvironmentFromEngine(entity: Entity): void {
+    if (!this.locomotor) {
+      return;
+    }
     const envHandle = entity.getValue(LocomotionEnvironment, '_envHandle');
     if (envHandle === 0) {
       return; // Not initialized or invalid handle
@@ -239,6 +253,9 @@ export class LocomotionSystem extends createSystem(
   }
 
   update(delta: number): void {
+    if (!this.locomotor) {
+      return;
+    }
     this.locomotor.updateKinematicEnvironments();
     this.locomotor.update(delta);
     this.player.position.copy(this.locomotor.position);
@@ -285,6 +302,5 @@ export class LocomotionSystem extends createSystem(
     if (this.slideSystem) {
       this.world.unregisterSystem(SlideSystem);
     }
-    this.cleanupFuncs.forEach((fn) => fn());
   }
 }

packages/core/src/locomotion/slide.ts

@@ -87,6 +87,8 @@ export class SlideSystem extends createSystem(
     comfortAssist: { type: Types.Float32, default: 0.5 },
     /** Button used to trigger jump. */
     jumpButton: { type: Types.String, default: InputComponent.A_Button },
+    /** Whether jumping is enabled. */
+    enableJumping: { type: Types.Boolean, default: true },
   },
 ) {
   private movementVector = new Vector3();
@@ -111,6 +113,7 @@ export class SlideSystem extends createSystem(
 
     // Handle jump input
     if (
+      this.config.enableJumping.value &&
       this.input.gamepads.right?.getButtonDown(
         this.config.jumpButton.value as InputComponent,
       )