### Test CI-Built Host with Example

Source: https://aurajs.gg/docs

Launch a real example game against a downloaded CI-built host artifact.

```bash
npm run example:testci -- auramon

```

--------------------------------

### Initialize and Run an AuraJS Project

Source: https://aurajs.gg/docs/working-with-an-aurajs-project

Standard workflow for installing the CLI, creating a new project, and starting the development server.

```bash
npm install -g auramaxx
auramaxx create my-game
cd my-game
npm run dev
auramaxx make scene Scene1
```

--------------------------------

### Run the multiplayer party example

Source: https://aurajs.gg/docs/multiplayer-quickstart

Execute the built-in multiplayer party example to test local-first connectivity and diagnostics.

```bash
cd packages/aurascript/examples/multiplayer-party
auramaxx run .

# second terminal
auramaxx run . PARTY4
```

--------------------------------

### Preview iOS Simulator Example

Source: https://aurajs.gg/docs

Launch the repository-local iOS simulator preview for an example from the 'packages/aurascript' directory without requiring signing or export.

```bash
npm run example:ios -- auramon

```

--------------------------------

### Initialize a New AuraJS Project

Source: https://aurajs.gg/docs/creating-a-new-game

The standard sequence of commands to install the CLI, scaffold a new project, and start the development server.

```bash
npm install -g auramaxx
auramaxx create my-game
cd my-game
npm run dev
```

--------------------------------

### Play AuraJS Example Game

Source: https://aurajs.gg/docs

Install the AuraJS CLI and play a specific example game like 'auramon-three'. Alternatively, run a web example from a local repository checkout.

```bash
npm install -g auramaxx
auramaxx play auramon-three

# or from this repo checkout
npm run example:web -- auramon-three

```

--------------------------------

### Install and Create AuraJS Game

Source: https://aurajs.gg/docs

Install the AuraJS CLI globally and create a new game project. Then, navigate into the project directory and run the development server.

```bash
npm install -g auramaxx
auramaxx create my-game
cd my-game
npm run dev

```

--------------------------------

### Lifecycle and Performance Monitoring

Source: https://aurajs.gg/docs/api-contract

Examples for lifecycle updates, resizing, and frame rate monitoring.

```javascript
aura.update(dt)
```

```javascript
aura.onResize(w, h)
```

```javascript
getFPS()
```

--------------------------------

### Manage Window Dimensions

Source: https://aurajs.gg/docs/api-contract

Examples of resizing the window and retrieving dimensions.

```javascript
setSize(800, 600)
```

```javascript
setSize(-1, 100)
```

```javascript
setSize(0, 0)
```

```javascript
setSize("800", 600)
```

```javascript
getSize()
```

--------------------------------

### Concrete JSON Examples

Source: https://aurajs.gg/docs/game-state-cli-contract-v1

Examples of concrete JSON payloads for game state snapshots, mutations, and error responses.

```APIDOC
### 5.1 Pass fixture: minimal snapshot

```json
{
  "schemaVersion": "aurajs.game-state.v1",
  "export": {
    "mode": "headless",
    "seed": 12345,
    "frameIndex": 0,
    "fingerprint": "0000000000000000000000000000000000000000000000000000000000000000"
  },
  "state": {
    "globals": {
      "level": "intro",
      "score": 0
    }
  }
}
```

### 5.2 Pass fixture: extended snapshot

```json
{
  "schemaVersion": "aurajs.game-state.v1",
  "export": {
    "mode": "native",
    "seed": 777,
    "frameIndex": 1440,
    "elapsedSeconds": 24,
    "fingerprint": "1111111111111111111111111111111111111111111111111111111111111111",
    "capturedAt": null
  },
  "state": {
    "globals": {
      "level": "forest-03",
      "score": 1200,
      "flags": {
        "bossUnlocked": true
      }
    },
    "camera": {
      "x": 10,
      "y": -4,
      "zoom": 1.25,
      "rotation": 0,
      "following": true,
      "activeEffects": 0
    },
    "scene3d": {
      "nodes": [
        {
          "id": 1,
          "parentId": null,
          "position": { "x": 0, "y": 0, "z": 0 },
          "rotation": { "x": 0, "y": 0, "z": 0 },
          "scale": { "x": 1, "y": 1, "z": 1 },
          "visible": true,
          "layer": 0
        }
      ],
      "clips": [
        {
          "clipId": 5,
          "nodeId": 1,
          "time": 0.5,
          "playing": true,
          "weight": 1
        }
      ]
    },
    "physics": {
      "frameIndex": 1440,
      "snapshot": null,
      "bodies": [
        {
          "id": 1,
          "kind": "dynamic",
          "position": { "x": 3, "y": 2 },
          "velocity": { "x": 0, "y": -1 },
          "angle": 0,
          "angularVelocity": 0,
          "sleeping": false
        }
      ],
      "lastReasonCode": null
    },
    "ecs": {
      "entities": [
        {
          "id": 100,
          "components": {
            "transform": { "x": 3, "y": 2 },
            "health": 95
          },
          "tags": ["player", "armed"]
        }
      ],
      "systems": [
        {
          "name": "movement",
          "enabled": true,
          "order": 0
        }
      ]
    },
    "tilemap": {
      "maps": [
        {
          "id": "overworld",
          "layers": [
            {
              "id": 0,
              "name": "ground",
              "visible": true,
              "opacity": 1,
              "order": 0,
              "collisionEnabled": false
            }
          ]
        }
      ]
    }
  }
}
```

### 5.3 Pass fixture: mutation result

```json
{
  "ok": true,
  "reasonCode": "state_apply_ok",
  "appliedMutations": 3,
  "failedMutationIndex": null,
  "fingerprint": "2222222222222222222222222222222222222222222222222222222222222222",
  "warnings": []
}
```

### 5.4 Fail fixture: schema version mismatch

```json
{
  "schemaVersion": "aurajs.game-state.v0",
  "export": {
    "mode": "headless",
    "seed": 1,
    "frameIndex": 0,
    "fingerprint": "0000000000000000000000000000000000000000000000000000000000000000"
  },
  "state": {
    "globals": {}
  }
}
```

Expected reason code: `schema_version_mismatch`
```

--------------------------------

### Display and Cursor Settings

Source: https://aurajs.gg/docs/api-contract

Examples for managing fullscreen, cursor visibility, and cursor locking.

```javascript
getPixelRatio()
```

```javascript
setFullscreen(true)
```

```javascript
setFullscreen(1)
```

```javascript
setCursorVisible(false)
```

```javascript
setCursorVisible(1)
```

```javascript
setCursorLocked(true)
```

```javascript
setCursorLocked(false)
```

--------------------------------

### Local Multiplayer Setup

Source: https://aurajs.gg/docs/creating-a-new-game

Commands to initialize a multiplayer project and join a session using a room code.

```bash
auramaxx create my-room-game --template multiplayer
cd my-room-game
npm run dev

# second terminal
npm run join -- AURA2P
```

--------------------------------

### Shareable Join URL

Source: https://aurajs.gg/docs/game-dev-api/11-networking-and-multiplayer

Example of a shareable URL for joining a room when launcherBaseUrl is configured.

```text
https://auralauncher.gg/join/AURA2P
```

--------------------------------

### Create AuraJS Game without Global Install

Source: https://aurajs.gg/docs

Use npx to run the AuraJS CLI for a one-off project bootstrap without a global installation.

```bash
npx auramaxx

```

--------------------------------

### Set Window Title

Source: https://aurajs.gg/docs/api-contract

Examples of setting the window title with various input types.

```javascript
setTitle("My Game")
```

```javascript
setTitle("")
```

```javascript
setTitle(42)
```

```javascript
setTitle(null)
```

--------------------------------

### Scaffold Projects with Specific Templates

Source: https://aurajs.gg/docs/creating-a-new-game

Examples of creating projects using different predefined templates from the AuraJS catalog.

```bash
auramaxx create starfall --template 2d-adventure
auramaxx create summit-run --template 3d-adventure
auramaxx create scratch-pad --template blank
auramaxx create room-brawl --template multiplayer
```

--------------------------------

### Start a headless session

Source: https://aurajs.gg/docs/game-dev-api/13-cli-create-build-dev-test-and-project-files

Initiates a session without a visible native window, useful for CI environments.

```bash
auramaxx session start --headless --name ci-loop --compact
```

--------------------------------

### AuraJS CLI Command Examples

Source: https://aurajs.gg/docs/game-dev-api/13-cli-create-build-dev-test-and-project-files

Commonly used commands for managing game sessions, state, and project forks via the wrapper CLI.

```bash
npx mygame play
npx mygame fork ./mygame-local
npx mygame api --port 3001
npx mygame session start
npx mygame state export --compact
npx mygame action schema --compact
```

--------------------------------

### Begin Aura UI View

Source: https://aurajs.gg/docs/api-contract

Starts a new view container with specified layout options. Use with `endView` to close the container.

```typescript
aura.ui.beginView(options: {
  id: string,
  x?: number,
  y?: number,
  width?: UIViewSize,
  height?: UIViewSize,
  direction?: UIViewDirection,
  gap?: number,
  padding?: number,
  borderWidth?: number,
  background?: UIViewColor | null,
  borderColor?: UIViewColor | null,
  clip?: boolean
}): { ok: boolean, reasonCode: string }
```

--------------------------------

### Launch games with auramaxx play

Source: https://aurajs.gg/docs/game-dev-api/13-cli-create-build-dev-test-and-project-files

Commands for launching games, managing forks, starting sessions, and exporting state or schemas.

```bash
auramaxx play mygame
auramaxx play mygame fork ./mygame-local
auramaxx play mygame session start
auramaxx play mygame state export --compact
auramaxx play mygame action schema --compact
```

--------------------------------

### Define aura.setup() Callback

Source: https://aurajs.gg/docs/api-contract

Implement the setup callback to run initialization code once after the JS entrypoint executes but before the first frame. Async operations like asset loading can be handled using await.

```javascript
aura.setup = function(): void
```

--------------------------------

### Install AuraMaxx Skill

Source: https://aurajs.gg/docs/game-dev-api/14-examples-guides-and-canonical-sources

Use this command to install the AuraMaxx skill from Aura-Industry into your codebase. This is a prerequisite for using coding agents with AuraJS.

```bash
cd <your-codebase>
npx -y skills add Aura-Industry/auramaxx

```

--------------------------------

### Manage live cube-camera captures

Source: https://aurajs.gg/docs/game-dev-api/08-draw3d-camera-lighting-shadows-and-postfx

Demonstrates creating a cube camera, setting it as the environment map, applying per-material overrides, and updating the camera position.

```javascript
const cubeCam = aura.draw3d.createCubeCamera({
  position: { x: 0, y: 2.5, z: 0 },
  resolution: 256,
  facesPerFrame: 2,
});

aura.draw3d.setEnvironmentMap(cubeCam);

// Optional per-material override over the same live cube-camera source.
aura.material.setCubeMapTexture(chromeMaterial, cubeCam);

// Refresh the shared live IBL source after moving the probe.
aura.draw3d.updateCubeCamera(cubeCam);

// Revert one material back to the shared scene IBL source.
aura.material.setCubeMapTexture(chromeMaterial, null);
```

--------------------------------

### Bootstrap and Developer Loops

Source: https://aurajs.gg/docs/game-dev-api/13-cli-create-build-dev-test-and-project-files

Commands for initializing a new project and executing standard development tasks.

```bash
npm install -g auramaxx
auramaxx create my-game
auramaxx web create my-web-game
cd my-game
npm run dev

# or run the interactive bootstrap once
npx auramaxx
```

```bash
cd my-game
npm run dev
auramaxx make scene Scene1
auramaxx vendor helpers
auramaxx explain
auramaxx check
auramaxx sync-content --check
npm run api
npm run state -- export --compact
npm run action -- schema --compact
```

--------------------------------

### Get AuraJS API Contract Version

Source: https://aurajs.gg/docs/api-contract

Query the aura.API_VERSION property to get the integer representing the API contract version. This is incremented on major version bumps that alter the API surface and is read-only.

```javascript
aura.API_VERSION: number  // 1 for this contract

```

--------------------------------

### Minimal Terrain Runtime Example

Source: https://aurajs.gg/docs/api-contract-3d

Demonstrates the creation of terrain, setting splat maps and textures, defining heightmaps, adding vegetation, and retrieving submission state.

```javascript
const terrainId = aura.terrain.create({
  width: 16,
  depth: 16,
  segmentsX: 6,
  segmentsZ: 6,
  maxHeight: 5
});

aura.terrain.setSplatMap(terrainId, "assets/terrain-splat.png");
aura.terrain.setLayerTexture(terrainId, 0, "assets/terrain-grass.png", 4);
aura.terrain.setHeightmap(terrainId, heightmapValues);

const vegetationId = aura.terrain.addVegetation(terrainId, {
  texture: "assets/terrain-grass-blade.png",
  density: 0.45,
  minHeight: 0.7,
  maxHeight: 1.35,
  splatChannel: 0
});

const terrainState = aura.terrain.getSubmissionState();

```

--------------------------------

### Get Camera Y Position

Source: https://aurajs.gg/docs/reference/contract-method-index

Retrieves the current Y coordinate of the camera.

```typescript
aura.camera.y: number
```

--------------------------------

### Get Camera Rotation

Source: https://aurajs.gg/docs/reference/contract-method-index

Retrieves the current rotation of the camera.

```typescript
aura.camera.rotation: number
```

--------------------------------

### Initialize Media Presentation Controller

Source: https://aurajs.gg/docs/native-media-presentation-contract-v1

Configures a media presentation with separate audio and video assets, including cue handling and playback options.

```javascript
import { createMediaPresentationController } from '@auraindustry/aurajs/cutscene';

const presentation = createMediaPresentationController(aura, 'cutscenes/intro.mp4', {
  audioPath: 'audio/intro.ogg',
  audioSeekMode: 'restart',
  loadOptions: {
    type: 'mp4',
    looping: true,
  },
  audio: {
    volume: 0.12,
    loop: true,
    refDistance: 2.4,
    maxDistance: 16,
  },
  cues: [
    { time: 0.2, type: 'subtitle', text: 'Native media presentation is active' },
  ],
  onSubtitle(cue) {
    hud.subtitle = cue.text;
  },
});

presentation.play();
presentation.seek(0.05);
```

--------------------------------

### Theme Management

Source: https://aurajs.gg/docs/api-contract

Functions for setting and getting the global UI theme.

```APIDOC
## Theme Management

### `aura.ui.setTheme`

Sets the global UI theme with customizable properties.

### Method

`setTheme(theme?: { gap?: number, padding?: number, fontSize?: number, lineHeight?: number, buttonHeight?: number, borderWidth?: number, textColor?: UIViewColor, mutedTextColor?: UIViewColor, panelColor?: UIViewColor, panelBorderColor?: UIViewColor, buttonColor?: UIViewColor, buttonHoverColor?: UIViewColor, buttonFocusColor?: UIViewColor, buttonActiveColor?: UIViewColor, buttonTextColor?: UIViewColor }): { ok: boolean, reasonCode: string }`

### Parameters

#### Request Body (Optional `theme` object)

- **gap** (number) - Optional - The gap between elements.
- **padding** (number) - Optional - The padding around elements.
- **fontSize** (number) - Optional - The base font size.
- **lineHeight** (number) - Optional - The line height for text.
- **buttonHeight** (number) - Optional - The height of buttons.
- **borderWidth** (number) - Optional - The width of borders.
- **textColor** (UIViewColor) - Optional - The default text color.
- **mutedTextColor** (UIViewColor) - Optional - The color for muted text.
- **panelColor** (UIViewColor) - Optional - The background color for panels.
- **panelBorderColor** (UIViewColor) - Optional - The border color for panels.
- **buttonColor** (UIViewColor) - Optional - The background color for buttons.
- **buttonHoverColor** (UIViewColor) - Optional - The background color for buttons on hover.
- **buttonFocusColor** (UIViewColor) - Optional - The background color for buttons when focused.
- **buttonActiveColor** (UIViewColor) - Optional - The background color for buttons when active.
- **buttonTextColor** (UIViewColor) - Optional - The text color for buttons.

### Response

#### Success Response (200)

- **ok** (boolean) - Indicates if the theme was set successfully.
- **reasonCode** (string) - A code indicating the result of the operation.

### Response Example

```json
{
  "ok": true,
  "reasonCode": "SUCCESS"
}
```

### `aura.ui.getTheme`

Retrieves the current global UI theme settings.

### Method

`getTheme(): { gap: number, padding: number, fontSize: number, lineHeight: number, buttonHeight: number, borderWidth: number, textColor: Color, mutedTextColor: Color, panelColor: Color, panelBorderColor: Color, buttonColor: Color, buttonHoverColor: Color, buttonFocusColor: Color, buttonActiveColor: Color, buttonTextColor: Color, transparentColor: Color }`

### Response

#### Success Response (200)

- **gap** (number) - The current gap setting.
- **padding** (number) - The current padding setting.
- **fontSize** (number) - The current font size setting.
- **lineHeight** (number) - The current line height setting.
- **buttonHeight** (number) - The current button height setting.
- **borderWidth** (number) - The current border width setting.
- **textColor** (Color) - The current text color.
- **mutedTextColor** (Color) - The current muted text color.
- **panelColor** (Color) - The current panel background color.
- **panelBorderColor** (Color) - The current panel border color.
- **buttonColor** (Color) - The current button background color.
- **buttonHoverColor** (Color) - The current button hover background color.
- **buttonFocusColor** (Color) - The current button focus background color.
- **buttonActiveColor** (Color) - The current button active background color.
- **buttonTextColor** (Color) - The current button text color.
- **transparentColor** (Color) - The current transparent color.

### Response Example

```json
{
  "gap": 8,
  "padding": 12,
  "fontSize": 16,
  "lineHeight": 24,
  "buttonHeight": 40,
  "borderWidth": 1,
  "textColor": "#FFFFFF",
  "mutedTextColor": "#AAAAAA",
  "panelColor": "#333333",
  "panelBorderColor": "#555555",
  "buttonColor": "#007BFF",
  "buttonHoverColor": "#0056b3",
  "buttonFocusColor": "#0056b3",
  "buttonActiveColor": "#003f80",
  "buttonTextColor": "#FFFFFF",
  "transparentColor": "rgba(0,0,0,0)"
}
```
```

--------------------------------

### Launch with Environment Variables

Source: https://aurajs.gg/docs/game-dev-api/11-networking-and-multiplayer

Alternative method to launch the project with relay settings using environment variables.

```bash
AURA_MULTIPLAYER_RELAY_HOST=relay.aurajs.gg npm run dev
AURA_MULTIPLAYER_RELAY_HOST=relay.aurajs.gg npm run join -- AURA2P
```

--------------------------------

### Run Development Server and Join Game

Source: https://aurajs.gg/docs/game-dev-api/11-networking-and-multiplayer

Standard commands for local development. `npm run dev` starts the server, and `npm run join -- CODE` connects a client to a specified room.

```bash
npm run dev
npm run join -- ABCD
```

--------------------------------

### Get Camera Matrices

Source: https://aurajs.gg/docs/api-contract-3d

Retrieves the current view or projection matrices.

```typescript
aura.camera3d.getViewMatrix(): Mat4
```

```typescript
aura.camera3d.getProjectionMatrix(): Mat4
```

--------------------------------

### aura.audio.play3d

Source: https://aurajs.gg/docs/api-contract

Starts playback and registers a deterministic 3D emitter spatialization.

```APIDOC
## aura.audio.play3d

### Description
Start playback + register deterministic 3D emitter spatialization.

### Parameters
#### Request Body
- **path** (string) - Required - Path to audio file.
- **options** (object) - Optional - Spatialization options including position, nodeId, minDistance, maxDistance, rolloff, and panStrength.

### Response
#### Success Response (200)
- **ok** (boolean) - Success status.
- **handle** (number) - Track handle.
- **fallbackMode** (string) - Fallback mode if spatialization is unavailable.
```

--------------------------------

### Global Execution

Source: https://aurajs.gg/docs/game-dev-api/13-cli-create-build-dev-test-and-project-files

Command to run AuraJS CLI without global installation.

```APIDOC
## `npx auramaxx`

### Description
Executes the AuraJS CLI using npx, which runs the command without requiring a global installation.

### Method
CLI Command

### Endpoint
N/A

### Parameters
N/A (Passes arguments to the `auramaxx` command)

### Request Example
```bash
npx auramaxx create my-new-project
```

### Response
N/A
```

--------------------------------

### Configure 3D Environment and Lighting

Source: https://aurajs.gg/docs/game-dev-api/08-draw3d-camera-lighting-shadows-and-postfx

Initializes the environment map, enables conservative occlusion culling, and sets up a spot light. Use this to establish basic scene lighting and performance optimizations.

```javascript
aura.draw3d.setEnvironmentMap('env/cyberpunk.hdr');
aura.draw3d.setOcclusionCulling({ enabled: true, conservative: true });
aura.light.spot(
  { x: 8, y: 6, z: 8 },
  { x: -0.45, y: -1.0, z: -0.25 },
  { r: 0.45, g: 0.78, b: 1.0 },
  1.35,
  28,
  0.72,
);
```

--------------------------------

### Transformations

Source: https://aurajs.gg/docs/api-contract

Functions for setting and getting local and world transforms of scene nodes.

```APIDOC
## Transformations

### `aura.scene3d.setLocalTransform(nodeId: number, transform: object): boolean`

Sets the local transformation (position, rotation, scale) of a node.

### `aura.scene3d.getLocalTransform(nodeId: number): object | null`

Gets the local transformation of a node.

### `aura.scene3d.getWorldTransform(nodeId: number): object | null`

Gets the world transformation of a node, calculated from its local transform and its ancestors' transforms.
```

--------------------------------

### Get Camera Zoom Level

Source: https://aurajs.gg/docs/reference/contract-method-index

Retrieves the current zoom level of the camera.

```typescript
aura.camera.zoom: number
```

--------------------------------

### Create AuraJS Projects

Source: https://aurajs.gg/docs/working-with-an-aurajs-project

Commands to initialize a new project with specific templates.

```bash
auramaxx create my-game
auramaxx create my-game --template 2d-adventure
auramaxx create my-game --template 3d-adventure
auramaxx create my-game --template blank
```

--------------------------------

### Explain Project with AuraMaxx

Source: https://aurajs.gg/docs/working-with-ai-agents

Run this command to get a JSON explanation of your current project. This is useful for AI agents to understand the project structure and components.

```bash
auramaxx explain --json

```

--------------------------------

### Get Camera X Position

Source: https://aurajs.gg/docs/reference/contract-method-index

Retrieves the current X coordinate of the camera.

```typescript
aura.camera.x: number
```

--------------------------------

### Create a Reflection Probe

Source: https://aurajs.gg/docs/game-dev-api/09-meshes-materials-scene3d-gltf-and-skinned-mesh

Use `createReflectionProbe` to initialize a new reflection probe. Options can configure its position, capture settings, and material bindings.

```javascript
aura.draw3d.createReflectionProbe(options?)
```

--------------------------------

### Create a new AuraJS game

Source: https://aurajs.gg/docs/supported-starter-catalog

Use the auramaxx CLI to initialize a new project using either the default canonical starter or a specific template.

```bash
auramaxx create my-game
auramaxx create my-game --template 3d-adventure
```

--------------------------------

### AuraJS App State Initialization Example

Source: https://aurajs.gg/docs/working-with-an-aurajs-project

Demonstrates how to initialize and manage session state for run flags using `context.ensureSessionState` in `src/runtime/app-state.js`. Ensures a flag `DID_START` is set to true on the first run.

```javascript
const runFlags = context.ensureSessionState('runFlags', { DID_START: false });
if (!runFlags.DID_START) {
  runFlags.DID_START = true;
}

```

--------------------------------

### Get Component

Source: https://aurajs.gg/docs/api-contract

Retrieves the value of a component attached to an entity, returning undefined if not found.

```typescript
aura.ecs.getComponent(entityId: number, componentName: string): unknown | undefined
```

--------------------------------

### Get Listener State

Source: https://aurajs.gg/docs/api-contract

Retrieves a snapshot of the current listener configuration for debugging purposes.

```typescript
aura.audio.getListenerState(): {
  ok: boolean,
  reasonCode: string | null,
  supported?: boolean,
  mode?: "manual" | "scene3d",
  attachedNodeId?: number | null,
  position?: object,
  forward?: object,
  up?: object,
  spatial?: object,
  hrtfEnabled?: boolean,
  reverbZone?: object | null
}
```

--------------------------------

### Manage Local Development

Source: https://aurajs.gg/docs/working-with-an-aurajs-project

Commands for running the development loop and inspecting project status.

```bash
cd my-game
npm run dev
auramaxx explain
auramaxx check
```

--------------------------------

### Get aura.three State

Source: https://aurajs.gg/docs/api-contract-3d

Retrieve the current configuration and availability status of the aura.three module.

```typescript
aura.three.getState(): {
  namespace: "aura.three";
  available: boolean;
  backend: string | null;
  requestedBackend: string | null;
  reasonCode: string | null;
  ownership: "aura-runtime-owned";
  scope: "custom-root-only";
  webOnly: true;
  nativeSupported: false;
  nativeReasonCode: "aura_web_three_native_unsupported";
  customShaderMaterialLaneAvailable: boolean;
  customShaderMaterialOwnership: "user-owned-web-only-material";
  rawShaderMaterialLaneAvailable: boolean;
  rawShaderMaterialOwnership: "user-owned-web-only-raw-material";
  customPassLaneAvailable: boolean;
  customPassOwnership: "aura-runtime-owned-composer-user-authored-pass";
  registeredCustomPassCount: number;
  frameHookLaneAvailable: boolean;
  frameHookOwnership: "aura-runtime-owned-borrowed-frame-context";
  registeredFrameHookCount: number;
}
```

--------------------------------

### Create a Custom Shader

Source: https://aurajs.gg/docs/game-dev-api/09-meshes-materials-scene3d-gltf-and-skinned-mesh

Use `createCustom` for advanced shader creation when standard PBR controls are insufficient. Uniforms are for scalar/vector/matrix data, while textures are handled separately.

```javascript
createCustom(options)
```

--------------------------------

### Create a Compute Pipeline

Source: https://aurajs.gg/docs/api-contract-3d

Creates a compute pipeline from WGSL shader code. The entry point defaults to 'main' if not specified.

```typescript
aura.compute.createPipeline(
  wgslCode: string,
  entryPoint?: string
): ComputePipelineHandle
```

--------------------------------

### Tilemap Get Tile

Source: https://aurajs.gg/docs/reference/contract-method-index

Retrieves tile information from a specified layer within a tilemap.

```typescript
aura.tilemap.getTile(mapId, layer, {x, y})
```

--------------------------------

### Room Information API

Source: https://aurajs.gg/docs/game-dev-api/11-networking-and-multiplayer

Provides methods to get information about the current room or session.

```APIDOC
## GET /api/room/info

### Description
Returns truthful room/session metadata.

### Method
GET

### Endpoint
/api/room/info

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **role** (string) - The role of the current peer in the room ('host' or 'client').
- **code** (string) - The room code.
- **scope** (string) - The scope of the room ('local', 'direct', or 'internet').
- **transportPath** (string) - The current transport path.
- **transportStatus** (string | null) - The status of the transport.
- **lastReasonCode** (string | null) - The reason code for the last status change.
- **peerCandidate** (object | null) - Information about the peer candidate.
- **requestedMode** (string) - The requested connection mode.
- **joinPath** (string | null) - The path taken to join the room.
- **migrating** (boolean) - Indicates if host migration is in progress.
- **migrationCompleted** (boolean) - Indicates if host migration has completed.
- **previousHostId** (number | null) - The ID of the previous host.
- **newHostId** (number | null) - The ID of the new host.
- **connectivity** (object) - Connectivity details.
  - **mode** (string) - The connectivity mode.
  - **coordinatorUrl** (string | null) - The coordinator URL.
  - **relayUrl** (string | null) - The relay URL.

#### Response Example
```json
{
  "role": "host",
  "code": "ABCD",
  "scope": "local",
  "transportPath": "local_room",
  "transportStatus": null,
  "lastReasonCode": null,
  "peerCandidate": null,
  "requestedMode": "local",
  "joinPath": "local",
  "migrating": false,
  "migrationCompleted": false,
  "previousHostId": null,
  "newHostId": null,
  "connectivity": {
    "mode": "local",
    "coordinatorUrl": null,
    "relayUrl": null
  }
}
```
```

--------------------------------

### 2D Authoring Layer Helpers

Source: https://aurajs.gg/docs/game-dev-api/05-animation-tween-particles-and-tilemaps

Overview of the scaffolded 2D authoring layer utilities available in `src/starter-utils/` and their direct package import path.

```APIDOC
## 2D Authoring Layer

Non-blank generated projects also ship a higher-level 2D authoring layer in `src/starter-utils/`:

* `animation-2d.js`: For named sprite states and current-frame resolution.
* `animation-packaging-2d.js`: For atlas/clip/state packaging over the sprite animation lane.
* `atlas-assets-2d.js`: For explicit image-path plus animation-manifest ownership over the packaging lane.
* `tween-2d.js`: For sequence/parallel/delay/yoyo/repeat style motion composition.
* `combat-feedback-2d.js`: For floating text, hit sparks, hit flashes, and hover/lift feedback.
* `tilemap-world-2d.js`: For one-map load/query/move ownership over `aura.tilemap`.
* `tilemap-nav-2d.js`: For mutable grid navigation with topology and occupancy invalidation.
* `streamed-world-2d.js`: For explicit region ownership, focus-driven load/unload, and routed point/AABB/ray queries over multiple tilemap-world regions.

When you need the shared package-backed helper lane directly, use `@auraindustry/aurajs/helpers/2d`.

For authored sprite atlases, the packaging helper keeps the boundary explicit:

* Clips own frame ranges / loop / timing defaults.
* States map gameplay-facing names onto those clips.
* The helper still compiles onto the existing `animation-2d.js` runtime lane instead of inventing a second playback system.
* `atlas-assets-2d.js` is the truthful paved road when the image path and the clip/state manifest should stay separate but packaged together in authored JS.
* The accepted packaged/native atlas path is a project-relative asset path such as `assets/pilot-ui-sheet.png`.
* `generated://...` remains a proof-only or runtime-authored image source, not the packaged asset guarantee for a shipped project.
```

--------------------------------

### Get Node Parent

Source: https://aurajs.gg/docs/game-dev-api/09-meshes-materials-scene3d-gltf-and-skinned-mesh

Retrieve the parent ID of a given node using `getParent`.

```javascript
getParent(nodeId)
```

--------------------------------

### GET aura.draw3d.getPostFXState()

Source: https://aurajs.gg/docs/api-contract-3d

Retrieves the deterministic retained composer telemetry for tools, inspectors, and runtime assertions.

```APIDOC
## GET aura.draw3d.getPostFXState()

### Description
Returns the current state of the post-processing pipeline, including pass configurations, resolved execution steps, and custom shader contracts.

### Response
#### Success Response (200)
- **passes** (Array) - List of active post-processing passes.
- **resolvedSteps** (Array) - The deterministic runtime execution order.
- **targetChain** (Object) - Configuration of intermediate targets and composition modes.
- **customShaderBindings** (Array) - Public custom-postfx input surface bindings.
- **customShaderContract** (Object) - Contract details for custom shader inputs.
- **totalPasses** (number) - Total count of passes.
- **enabledPasses** (number) - Count of enabled passes.
- **lastOperation** (string) - The last performed operation.
```

--------------------------------

### Get 3D Camera View Matrix

Source: https://aurajs.gg/docs/reference/contract-method-index

Retrieves the current view matrix for the 3D camera.

```typescript
aura.camera3d.getViewMatrix(): Mat4
```

--------------------------------

### Get 3D Camera Projection Matrix

Source: https://aurajs.gg/docs/reference/contract-method-index

Retrieves the current projection matrix for the 3D camera.

```typescript
aura.camera3d.getProjectionMatrix(): Mat4
```

--------------------------------

### Get World Transform

Source: https://aurajs.gg/docs/game-dev-api/09-meshes-materials-scene3d-gltf-and-skinned-mesh

Calculate and retrieve the world transformation matrix of a scene node with `getWorldTransform`.

```javascript
getWorldTransform(nodeId)
```

--------------------------------

### Build and Run Commands

Source: https://aurajs.gg/docs/game-dev-api/13-cli-create-build-dev-test-and-project-files

Commands for building the project for various targets and running the application.

```APIDOC
## `auramaxx build`

### Description
Builds the AuraJS project for specified targets.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--target** (string) - Optional - Specifies the build target (e.g., 'windows', 'mac', 'linux', 'all', 'web', 'android', 'ios', 'mobile').

### Request Example
```bash
auramaxx build --target android
```

### Response
N/A
```

```APIDOC
## `auramaxx run`

### Description
Launches the AuraJS application. Used for web preview or native session registration.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Query Parameters
- **--session** (boolean) - Optional - Enables explicit live session registration for native projects.

### Request Example
```bash
auramaxx run --session
```

### Response
N/A
```

```APIDOC
## `auramaxx play`

### Description
Provides a fast local path for running a visible native game with a live developer session.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
- **game** (string) - Optional - Specifies the game to play.

### Request Example
```bash
auramaxx play my-game
```

### Response
N/A
```