Script API Reference

// Type: number (read-only)
const myEntityId = api.eid;
api.log(`I am entity ${myEntityId}`);

// Type: THREE.Vector3 (pooled)
 
// Read position
const pos = api.position;
console.log(pos.x, pos.y, pos.z);
 
// Modify and write back
pos.y += 1.0;
api.position = pos;
 
// Set directly
api.position = { x: 0, y: 10, z: 0 };

// Type: THREE.Euler (pooled)
 
// Rotate 45 degrees around Y
const rot = api.rotation;
rot.y = Math.PI / 4;
api.rotation = rot;
 
// Increment rotation
rot.y += 0.01;
api.rotation = rot;

// Type: THREE.Quaternion (pooled)
 
// Set quaternion directly
api.quaternion = { x: 0, y: 0.7071, z: 0, w: 0.7071 };
 
// Automatically syncs with api.rotation
const rot = api.rotation; // Updated automatically
api.log(rot.y); // Shows equivalent Euler angle

// Look at a world position
api.lookAt({ x: 10, y: 0, z: 10 });
 
// Look at another entity's position
if (api.target.exists) {
  api.lookAt(api.target.position);
}

// Type: THREE.Vector3 (pooled)
 
// Read current velocity
const vel = api.velocity;
api.log(`Speed: ${vel.length()}`);
 
// Set velocity directly
api.velocity = { x: 0, y: 5, z: 10 };

// Jump impulse
api.applyImpulse({ x: 0, y: 10, z: 0 });
 
// Knockback
api.applyImpulse({ x: -5, y: 2, z: 0 });

// Type: Promise<RaycastResult | null>
 
interface RaycastResult {
  eid: number;        // Entity ID hit
  distance: number;   // Distance from origin
  point: [number, number, number];   // Hit point
  normal: [number, number, number];  // Surface normal
}
 
// Ground check
const hit = await api.raycast(
  api.position,
  { x: 0, y: -1, z: 0 }
);
 
if (hit && hit.distance < 1.1) {
  api.log("On ground!");
}
 
// Forward check
const forwardHit = await api.raycast(
  api.position,
  { x: 0, y: 0, z: -1 }
);

// Move based on input
const { move } = api.input;
api.controller.move({
  x: move.x * speed * dt,
  y: 0,
  z: move.y * speed * dt
});

// Type: boolean (read-only)
 
if (api.controller.isGrounded) {
  // Can jump
  if (api.input.jumpDown) {
    api.applyImpulse({ x: 0, y: jumpForce, z: 0 });
  }
}

interface Navigation {
  setDestination(target: Vector3): void;
  stop(): void;
  setSpeed(speed: number): void;
  readonly isMoving: boolean;
  readonly isPathPending: boolean;
}
 
// Set destination
api.navigation.setDestination({ x: 10, y: 0, z: 10 });
 
// Stop moving
api.navigation.stop();
 
// Change speed (affects both NavMeshAgent and Steering)
api.navigation.setSpeed(5.0);
 
// Check state
if (api.navigation.isMoving) {
  api.log("Agent is moving");
}
 
if (api.navigation.isPathPending) {
  api.log("Path calculation in progress");
}

interface InputState {
  move: Vector2;      // WASD: x = left/right, y = back/forward
  look: Vector2;      // Mouse delta
  jump: boolean;      // Jump key held
  jumpDown: boolean;  // Jump pressed this frame
  sprint: boolean;    // Sprint key held
}
 
// Movement
const { move, jumpDown, sprint } = api.input;
 
const speed = sprint ? 10.0 : 5.0;
 
if (move.x !== 0 || move.y !== 0) {
  api.controller.move({
    x: move.x * speed * dt,
    y: 0,
    z: move.y * speed * dt
  });
}
 
// Mouse look
const { look } = api.input;
const rot = api.rotation;
rot.y -= look.x * 0.002;
api.rotation = rot;
 
// Jump (edge trigger)
if (jumpDown && api.controller.isGrounded) {
  api.applyImpulse({ x: 0, y: 10, z: 0 });
}

interface AnimationController {
  play(clipIndexOrName: number | string, loop?: boolean, speed?: number): void;
  crossFade(clipIndexOrName: number | string, duration: number): void;
  stop(): void;
  playSecondary(clipIndexOrName: number | string, maskBoneNameHash: number, weight?: number): void;
  stopSecondary(): void;
}
 
// Play animation by index
api.animation.play(0, true, 1.0);
 
// Play by name
api.animation.play("Walk", true);
 
// Cross-fade to another animation
api.animation.crossFade("Run", 0.3);
 
// Stop animation
api.animation.stop();

interface AudioController {
  play(assetId?: number): void;
  stop(): void;
  setVolume(volume: number): void;
}
 
// Play the assigned audio
api.audio.play();
 
// Play a specific audio asset
api.audio.play(123);
 
// Stop playback
api.audio.stop();
 
// Adjust volume (0.0 - 1.0)
api.audio.setVolume(0.5);

interface TargetAccessor {
  readonly exists: boolean;
  readonly position: THREE.Vector3;
  readonly rotation: THREE.Euler;
}
 
// Check if target exists
if (api.target.exists) {
  // Follow target
  const targetPos = api.target.position;
  api.lookAt(targetPos);
  
  // Move toward target
  const myPos = api.position;
  const dx = targetPos.x - myPos.x;
  const dz = targetPos.z - myPos.z;
  const distance = Math.sqrt(dx*dx + dz*dz);
  
  if (distance > 2.0) {
    myPos.x += (dx / distance) * speed * dt;
    myPos.z += (dz / distance) * speed * dt;
    api.position = myPos;
  }
}

interface NetworkState {
  readonly isServer: boolean;
  readonly isLocalPlayer: boolean;
  readonly ownerId: number;
}
 
// Only process input for local player
if (!api.network.isLocalPlayer) {
  return; // Skip for remote players
}
 
// Server-only logic
if (api.network.isServer) {
  // Authoritative game logic
}
 
// Check ownership
if (api.network.ownerId === localClientId) {
  // This client owns this entity
}

// Spawn a prefab at a position
const eid = await api.spawn("Bullet", { x: 0, y: 1, z: 0 });
api.log(`Spawned entity ${eid}`);
 
// Spawn with rotation
const enemyEid = await api.spawn("Enemy", 
  { x: 10, y: 0, z: 10 },
  { x: 0, y: Math.PI, z: 0 }
);

// Load a new scene (replaces current)
await api.loadScene("/scenes/level2.json");
 
// Load additively (adds to current scene)
await api.loadScene("/scenes/enemies.json", true);

api.log("Hello from script!");
api.log(`Position: ${api.position.x}, ${api.position.y}, ${api.position.z}`);

interface ScriptAPI {
  readonly eid: number;
  
  position: THREE.Vector3;
  rotation: THREE.Euler;
  velocity: THREE.Vector3;
  
  lookAt(target: THREE.Vector3): void;
  applyImpulse(force: THREE.Vector3): void;
  raycast(origin: THREE.Vector3, direction: THREE.Vector3): Promise<RaycastResult | null>;
  
  controller: CharacterControllerAPI;
  navAgent: NavAgentAPI;
  input: InputState;
  animation: AnimationAPI;
  audio: AudioAPI;
  target: TargetAPI;
  network: NetworkState;
  
  spawn(prefabId: string, position?: THREE.Vector3, rotation?: THREE.Euler): Promise<number>;
  loadScene(url: string, additive?: boolean): Promise<void>;
  log(message: string): void;
}