### Hyperfy Quick Start Installation

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/README.md

Commands to clone the Hyperfy repository, navigate into the project directory, copy example environment settings, install Node.js dependencies, and start the development server for local development.

```bash
git clone https://github.com/hyperfy-xyz/hyperfy.git my-world
cd my-world

cp .env.example .env

npm install

npm run dev
```

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

### Clone Hyperfy Repository

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/CONTRIBUTING.md

Clones the Hyperfy project repository from GitHub to your local machine, allowing you to start development.

```bash
git clone https://github.com/hyperfy-xyz/hyperfy.git
```

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

### Hyperfy Interactive Component Example

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/CONTRIBUTING.md

An example JavaScript/React component demonstrating an interactive element for Hyperfy worlds. It includes basic lifecycle management using `useEffect` for setup and cleanup.

```javascript
/**
 * Interactive component for Hyperfy worlds
 * @param {Object} props - Component properties
 * @param {Vector3} props.position - Initial position
 * @param {Function} props.onInteract - Interaction callback
 */
export default function InteractiveComponent(props) {
  const { position, onInteract } = props
  
  useEffect(() => {
    // Setup component
    return () => {
      // Cleanup
    }
  }, [])

  return (
    <component
      position={position}
      onClick={onInteract}
    >
      {/* Component content */}
    </component>
  )
}
```

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

### Run Project Tests

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/CONTRIBUTING.md

Executes the project's test suite. Running tests is an essential step before submitting changes to ensure everything works correctly and no regressions are introduced.

```bash
npm run test
```

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

### Initialize Hyperfy Particle Emitter

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Particles.md

Demonstrates how to create a new particle emitter instance using `app.create` and add it to the application. The example initializes the emitter with a 'cone' shape, specifying its radius, thickness, and angle.

```jsx
const particles = app.create('particles', {
  shape: ['cone', 1, 25, 1],
})
app.add(particles)
```

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

### Create and Style a Basic UIView in JSX

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UIView.md

This snippet demonstrates how to create a new UIView instance using the `app.create('uiview')` method and subsequently set its background color. It serves as a fundamental example for initializing and applying a simple style to a view.

```jsx
const view = app.create('uiview')
view.backgroundColor = 'rgba(0, 0, 0, 0.5)'
```

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

### Stage and Commit Git Changes

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/CONTRIBUTING.md

Stages all modified files for the next commit and then commits them to your local repository. A clear and concise commit message is required to describe the changes.

```bash
git add .
git commit -m "Clear and concise description of the changes"
```

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

### InteractiveComponent API Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/CONTRIBUTING.md

API documentation for the `InteractiveComponent` in Hyperfy, detailing its expected properties (props) and their types. This defines the interface for interacting with the component.

```APIDOC
InteractiveComponent (Component):
  Description: Interactive component for Hyperfy worlds.
  Props:
    props (Object): Component properties.
      position (Vector3): Initial position of the component.
      onInteract (Function): Callback function triggered on interaction.
```

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

### Build and Run Hyperfy Docker Container

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/DOCKER.md

This command builds a Docker image tagged 'hyperfydemo' from the current directory and then runs it in detached mode. It mounts local 'src', 'world' directories, and the '.env' file into the container, exposes port 3000, and sets critical environment variables for domain, ports, and asset URLs. Users should adjust the URLs and domain to match their specific deployment setup.

```bash
docker build -t hyperfydemo . && docker run -d -p 3000:3000 \
  -v "$(pwd)/src:/app/src" \
  -v "$(pwd)/world:/app/world" \
  -v "$(pwd)/.env:/app/.env" \
  -e DOMAIN=demo.hyperfy.host \
  -e PORT=3000 \
  -e ASSETS_DIR=/world/assets \
  -e PUBLIC_WS_URL=https://demo.hyperfy.host/ws \
  -e PUBLIC_API_URL=https://demo.hyperfy.host/api \
  -e PUBLIC_ASSETS_URL=https://demo.hyperfy.host/assets \
  hyperfydemo
```

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

### Create New Git Branch

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/CONTRIBUTING.md

Creates and switches to a new Git branch for your development work. It's crucial to choose a descriptive branch name that reflects the changes you intend to make.

```bash
git checkout -b branch-name
```

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

### UIImage Methods and Dynamic Source Update

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UIImage.md

Documentation for methods available on the UIImage component, including their parameters and return types. Also includes a practical example of dynamically changing the image source using property assignment.

```APIDOC
UIImage Methods:
  .loadImage(src: String): Promise
    Description: Loads an image from the specified URL. Returns a promise that resolves when the image is loaded or rejects if loading fails.
```

```jsx
image.src = 'https://example.com/new-image.png';
```

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

### Hyperfy Action Object API Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Action.md

Detailed API documentation for the `Action` object in Hyperfy, outlining its configurable properties and associated callback functions for interactive elements in the virtual world. It defines how users interact with objects, including visual labels, proximity triggers, interaction durations, and event handling for start, trigger, and cancel actions.

```APIDOC
Action:
  description: An action is something people can interact with in the world.
  properties:
    .label:
      type: String
      description: The label shown to the user when they are nearby. Defaults to `Interact`.
    .distance:
      type: Number
      description: The distance in meters that the action should be displayed. The engine will only ever show this if they are nearby AND there is no other action that is closer. Defaults to `3`.
    .duration:
      type: Number
      description: How long the player must hold down the interact button to trigger it, in seconds. Defaults to `0.5`.
    .onStart:
      type: Function
      description: The function to call when the interact button is first pressed.
    .onTrigger:
      type: Function
      description: The function to call when the interact button has been held down for the full `duration`.
    .onCancel:
      type: Function
      description: The function call if the interact button is released before the full `duration`.
    .{...Node}:
      description: Inherits all [Node](/docs/ref/Node.md) properties
```

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

### Push Git Changes to Remote

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/CONTRIBUTING.md

Pushes the committed changes from your local branch to your forked repository on GitHub. This makes your changes available online for a pull request.

```bash
git push origin branch-name
```

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

### Configure App UI Fields

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Props.md

Demonstrates how to configure custom UI fields for an app using `app.configure` to allow non-technical users to customize app behavior. This example creates a simple text input field with a key, type, and label.

```jsx
app.configure([
  {
    key: 'name',
    type: 'text',
    label: 'Name'
  }
])
```

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

### Accessing Configured Prop Values

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Props.md

Illustrates how to access values configured via custom UI fields using the global `props` variable. This example shows accessing a 'name' property that would have been set through a configured text input.

```jsx
props.name
```

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

### Generate Random Numbers with `num` Method

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/num.md

Illustrates the usage of the global `num` method to generate random numbers. Examples include generating a random integer between 0 and 10, and a random float between 100 and 1000 with 2 decimal places. This method is crucial in environments where standard `Math.random()` is disallowed.

```jsx
/**
 * function num(min, max, dp=0) 
 */ 

// random integer between 0 and 10
num(0, 10) 

// random float between 100 and 1000 with 2 decimal places
num(100, 1000, 2) 
```

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

### Create a Basic UI Component

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UI.md

Demonstrates how to instantiate a new UI component using `app.create('ui')` and set its background color. This creates a UI plane that can be positioned and styled in the 3D world.

```jsx
const ui = app.create('ui')
ui.backgroundColor = 'rgba(0, 0, 0, 0.5)'
```

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

### Define Particle Size Change Over Lifetime in JSX

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Particles.md

Illustrates how to define a particle's size evolution over its lifetime using a string syntax for the `sizeOverLife` property. The example shows a particle starting at 1x size, growing to 2x at half-life, and returning to 1x at the end.

```jsx
// 1) particle starts life (0) at size 1x size
// 2) at half age (0.5) the particle should be 2x size
// 3) at the end of its life (1) it should be back to 1x size
particles.sizeOverLife = '0,1|0.5,2|1,1'
```

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

### Create a UIImage Instance

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UIImage.md

Demonstrates how to create a new UIImage instance using `app.create` with various initial properties like source URL, dimensions, object fit, background color, and border radius.

```jsx
const image = app.create('uiimage', {
  src: 'https://example.com/image.png',
  width: 200,
  height: 150,
  objectFit: 'cover',
  backgroundColor: 'rgba(0, 0, 0, 0.5)',
  borderRadius: 10
});
```

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

### Hyperfy Development and Build Commands

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/README.md

Common npm commands used for developing, building, and maintaining Hyperfy projects, including modes for development, production, asset cleaning, and linting.

```bash
npm run dev

npm run build
npm start

npm run world:clean

npm run viewer:dev

npm run client:dev

npm run lint
npm run lint:fix
```

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

### Apply Constant Force to Particles (Gravity) in JSX

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Particles.md

Demonstrates how to apply a constant force, such as gravity, to particles using the `force` property. This example sets a downward force simulating gravity.

```jsx
particles.force = new Vector3(0, -9.81, 0) // gravity
```

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

### Create a Responsive UI with UIImage

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UIImage.md

Illustrates how to integrate a UIImage into a responsive UI structure, demonstrating the creation of a parent UI node and adding an image to it with specific styling for layout and appearance.

```jsx
// Create a UI node
const ui = app.create('ui', {
  space: 'screen',
  position: [0, 1, 0],
  width: 300,
  height: 200,
  backgroundColor: 'rgba(0, 0, 0, 0.7)',
  pivot: 'top-left'
});

// Create an image element
const image = app.create('uiimage', {
  src: 'https://example.com/image.png',
  width: 300,
  height: 200,
  objectFit: 'cover',
  backgroundColor: 'rgba(255, 255, 255, 0.2)',
  borderRadius: 10
});

// Add the image to the UI node
ui.add(image);
```

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

### Create and Initialize UIText Component in JSX

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UIText.md

This JSX code snippet demonstrates how to instantiate a new UIText component using the `app.create()` method and immediately assign a string value to its `value` property, making it display 'Hello world'.

```jsx
const text = app.create('uitext')
text.value = 'Hello world'
```

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

### Create Audio Node from File Prop

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Props.md

Demonstrates how to use the URL from a configured file prop (specifically an audio file) to create and play an audio node within the app. This shows practical usage of file props for dynamic asset loading.

```jsx
const audio = app.create('audio', {
  src: props.audio?.url
})
audio.play()
```

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

### Audio Object API Documentation

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Audio.md

Detailed API documentation for the Audio object, including its properties for configuring audio source, volume, looping, spatialization, and its methods for controlling playback.

```APIDOC
Audio Object:
  Description: Represents a single audio clip that can be played in the world.

  Properties:
    .src: String
      Description: An absolute url to an audio file, or an asset url from an audio file embedded in the app.
      Notes: Currently only `mp3` files are supported.
    .volume: Number
      Description: The audio volume.
      Default: 1
    .loop: Boolean
      Description: Whether the audio should loop.
      Default: false
    .group: Enum('music', 'sfx')
      Description: The type of audio being played. 'music' for ambient sounds/live events, 'sfx' for short sound effects. Users can adjust global volume for these groups independently.
      Default: 'music'
    .spatial: Boolean
      Description: Whether music should be played spatially and heard by people nearby.
      Default: true
    .distanceModel: Enum('linear', 'inverse', 'expontential')
      Description: When spatial is enabled, the distance model to use.
      Default: 'inverse'
    .refDistance: Number
      Description: When spatial is enabled, the reference distance to use.
      Default: 1
    .maxDistance: Number
      Description: When spatial is enabled, the max distance to use.
      Default: 40
    .rolloffFactor: Number
      Description: When spatial is enabled, the rolloff factor to use.
      Default: 3
    .coneInnerAngle: Number
      Description: When spatial is enabled, the cone inner angle to use.
      Default: 360
    .coneOuterAngle: Number
      Description: When spatial is enabled, the cone outer angle to use.
      Default: 360
    .coneOuterGain: Number
      Description: When spatial is enabled, the cone outer gain to use.
      Default: 0
    .currentTime: Number
      Description: Gets and sets the current playback time, in seconds.
    .{...Node}
      Description: Inherits all Node properties.

  Methods:
    .play()
      Description: Plays the audio.
      Notes: If no click gesture has ever happened within the world, playback won't begin until it has.
    .pause()
      Description: Pauses the audio, retaining the current time.
    .stop()
      Description: Stops the audio and resets the time back to zero.
```

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

### Hyperfy In-Game Chat Commands Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/commands.md

A detailed reference for all user-executable chat commands within Hyperfy, outlining their functionality, parameters, and necessary administrative roles or conditions for use.

```APIDOC
Command: /admin <code>
  Description: Grants admin privileges to the user. If an ADMIN_CODE is set in the .env file, it must be provided. If no ADMIN_CODE is set, all players temporarily gain admin role.
  Parameters:
    <code>: (Optional) The specific admin code configured in the world's .env file.
  Permissions: Requires matching ADMIN_CODE if set; otherwise, temporary for all players if not set.

Command: /spawn set
  Description: Sets the world's default spawn point for new players to the current position and facing direction of the executing player.
  Permissions: Requires admin role.

Command: /spawn clear
  Description: Resets the world's spawn point back to its default origin (0,0,0).
  Permissions: Requires admin role.

Command: /name <name>
  Description: Changes the executing player's display name within the world.
  Parameters:
    <name>: The desired new name for the player.
  Notes: This is currently the only method to change a player's name; a UI option is planned for future development.

Command: /chat clear
  Description: Clears all chat messages from the current player's chat history display.
  Permissions: Requires admin privileges.
```

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

### UI Component Properties Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UI.md

Comprehensive documentation of all configurable properties for the Hyperfy UI component, including their types, descriptions, default values, and usage notes for advanced customization.

```APIDOC
UI Component Properties:
  .space: String
    Description: Whether this UI should be rendered in `world` space or `screen` space. When `world`, a plane geometry is physically placed in the world. When `screen`, the canvas is drawn directly on the screen. Defaults to `world`.
    Note: when using `screen`, the `.position` value now represents a ratio from 0 to 1 on each axis. For example `position.x = 1` is the far right of the screen and `position.x = 0` is the far left. Use this in combination with the `pivot` and `offset` values.

  .width: Number
    Description: The width of the UI canvas in pixels. Defaults to `100`.

  .height: Number
    Description: The height of the UI canvas in pixels. Defaults to `100`.

  .size: Number
    Description: This value converts pixels to meters. For example if you set `width = 100` and `size = 0.01` your UI will have a width of one meter. This allows you to build UI while thinking in pixels instead of meters, and makes it easier to resize things later. Defaults to `0.01`.

  .lit: Boolean
    Description: Whether the canvas is affected by lighting. Defaults to `false`.

  .doubleside: Boolean
    Description: Whether the canvas is doublesided. Defaults to `false`.

  .billboard: String
    Description: Makes the UI face the camera. Can be `none`, `full` or `y`. Default to `none`.

  .pivot: String
    Description: Determines where the "center" of the UI is. Options are: `top-left`, `top-center`, `top-right`, `center-left`, `center`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right`. Defaults to `center`.

  .offset: Vector3
    Description: Only applicable when using screen-space. The offset in pixels applied after the `position` value.

  .scaler: Array|null
    Description: When creating UI in world-space you sometimes want it to scale as if it was in screen-space, so that when you are far away it scales up to match the size it would be if it were on screen and vice versa. This is useful for things like buttons and chat bubbles. Defaults to `null`.

  .pointerEvents: Boolean
    Description: Whether the UI should receive or ignore pointer events. Defaults to `true`. If you are building informational screen-space UI that does not need to respond to pointer events, this should be set to `false` for an improved user experience.

  .backgroundColor: String
    Description: The background color of the UI. Can be hex (eg `#000000`) or rgba (eg `rgba(0, 0, 0, 0.5)`). Defaults to `null`.

  .borderWidth: Number
    Description: The width of the border in pixels.

  .borderColor: String
    Description: The color of the border.

  .borderRadius: Number
    Description: The radius of the border in pixels.

  .padding: Number
    Description: The inner padding of the UI in pixels. Defaults to `0`.

  .flexDirection: String
    Description: The flex direction. `column`, `column-reverse`, `row` or `row-reverse`. Defaults to `column`.

  .justifyContent: String
    Description: Options: `flex-start`, `flex-end`, `center`. Defaults to `flex-start`.

  .alignItems: String
    Description: Options: `stretch`, `flex-start`, `flex-end`, `center`, `baseline`. Defaults to `stretch`.

  .alignContent: String
    Description: Options: `flex-start`, `flex-end`, `stretch`, `center`, `space-between`, `space-around`, `space-evenly`. Defaults to `flex-start`.

  .flexWrap: String
    Description: Options: `no-wrap`, `wrap`. Defaults to `no-wrap`.

  .gap: Number
    Description: Defaults to `0`.

  .{...Node}: Inherits all [Node](/docs/ref/Node.md) properties.
```

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

### Hyperfy Project Directory Structure

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/README.md

An overview of the main directories and files within the Hyperfy project repository, indicating the purpose of each top-level component.

```text
docs/              - Documentation and references
src/
  client/          - Client-side code and components
  core/            - Core systems (physics, networking, entities)
  server/          - Server implementation
CHANGELOG.md       - Version history and changes
```

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

### Configure Screen-Space UI with Offset

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UI.md

Illustrates how to create a UI element in screen space, positioning it relative to the screen edges using `space`, `pivot`, `position`, and `offset` properties. This allows for precise pixel-based placement on the user's display.

```jsx
/**
 * Example:
 * The following screen-space UI is rendered in the top left of the 
 * screen, 20px away from both edges.
*/
const ui = app.create('ui', {
  space: 'screen',
  pivot: 'top-right',
  position: [1, 0, 0], // far right
  offset: [-20, 20, 0] // 20px left, 20px down
})
```

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

### Hyperfy App Global Variable API Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/App.md

Detailed API documentation for the `app` global object, outlining its available properties for accessing application metadata and state, and its methods for interacting with the network, managing events, and manipulating scene nodes.

```APIDOC
app:
  Properties:
    .instanceId: String
      description: The instance ID of the current app. Every app has its own unique ID that is shared across all clients and the server.
    .version: String
      description: The version of the app instance. This number is incremented whenever the app is modified which includes but is not limited to updating scripts and models.
    .state: Object
      description: A plain old javascript object that you can use to store state in. The servers state object is sent to all new clients that connect in their initial snapshot, allowing clients to initialize correctly, eg in the right position/mode.
    .{...Node}:
      description: Inherits all Node properties.
  Methods:
    .on(name, callback):
      description: Subscribes to custom networked app events and engine update events like 'update', 'fixedUpdate' and 'lateUpdate'. Custom networked events are received when a different client/server sends an event with app.send(event, data). IMPORTANT: Only subscribe to update events when they are needed.
      parameters:
        name: string - The name of the event to subscribe to (e.g., 'update', 'fixedUpdate', 'lateUpdate', or a custom event name).
        callback: function - The function to be called when the event occurs.
    .off(name, callback):
      description: Unsubscribes from custom events and update events. IMPORTANT: Be sure to unsubscribe from update events when they are not needed.
      parameters:
        name: string - The name of the event to unsubscribe from.
        callback: function - The callback function to remove.
    .send(name, data, skipNetworkId):
      description: Sends an event across the network. If the caller is on the client, the event is sent to the server. If the caller is on the server, the event is sent to all clients.
      parameters:
        name: string - The name of the event to send.
        data: any - The data to send with the event.
        skipNetworkId: string (optional) - (Server-side only) The network ID of a client to skip sending the event to.
    .get(nodeId): Node
      description: Finds and returns any node with the matching ID from the model the app is using. (e.g., Blender object "name").
      parameters:
        nodeId: string - The ID of the node to find.
      returns: Node - The found Node object.
    .create(nodeName): Node
      description: Creates and returns a node of the specified name.
      parameters:
        nodeName: string - The name of the node to create.
      returns: Node - The created Node object.
    .control(options): Control
      description: Provides control to a client to respond to inputs and move the camera etc. (TODO)
      parameters:
        options: object - Configuration options for the control.
      returns: Control - The Control object.
    .configure(fields):
      description: Configures custom UI for your app. See Props for more info.
      parameters:
        fields: object - An object defining the custom UI fields.
```

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

### Hyperfy Audio/Video Node API Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Video.md

Detailed API documentation for the Hyperfy audio/video node, outlining its properties and methods for controlling media playback and state.

```APIDOC
Audio/Video Node Properties:
  .currentTime: Number
    Description: The current time of the video. Can be used to read and update the current time of the video.
  .{...Node}
    Description: Inherits all Node properties.

Audio/Video Node Methods:
  .play()
    Description: Plays the audio.
  .pause()
    Description: Pauses the audio, retaining the current time.
  .stop()
    Description: Stops the audio and resets the time back to zero.
```

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

### Configure UIImage with User Input

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UIImage.md

Shows how to make a UIImage configurable by the user through `app.configure`, allowing dynamic image source selection via a file input and utilizing `props` to access the selected image URL.

```jsx
// Configure the app with a file input for images
app.configure([
  {
    type: 'file',
    key: 'selectedImage',
    label: 'Upload Image',
    kind: 'texture' // Specify the kind as 'image' to restrict file types
  }
]);

// Create the image element using the selected file
const image = app.create('uiimage', {
  src: props.selectedImage?.url, // Use the URL of the selected image
  width: 300,
  height: 200,
  objectFit: 'cover',
  backgroundColor: 'rgba(255, 255, 255, 0.2)',
  borderRadius: 10
});
```

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

### Hyperfy Controller Object API

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Controller.md

Detailed API documentation for the Controller object, outlining its configurable properties and callable methods for character movement and physics interactions.

```APIDOC
Controller:
  Properties:
    .radius: Number
      The radius of the capsule. Defaults to 0.3 which is the same as the player capsule.
    .height: Number
      The height of the mid section of the capsule. Defaults to 1 which is also the same as the player capsule.
    .layer: String
      The physics layer for this controller. This determines what the controller collides with. Can be "environment" or "prop" or "tool". Defaults to "environment".
    .tag: String
      A tag that can be seen by raycast, trigger and contact events.
    .onContactStart: Function
      A function that is called whenever another physics object comes in contact with this controller.
    .onContactEnd: Function
      A function that is called whenever another physics object ends contact with this controller.
    .isGrounded: Boolean
      A read-only property describing whether the controller is standing on something.
    .{...Node}:
      Inherits all Node properties
  Methods:
    .move(vec3):
      The primary utility of a controller. Will move the controller in the direction and magnitude specified, but will also slide against walls etc.
      Note that controllers do not have gravity by default, but you can simulate this by setting vec3.y = -9.81 for example.
      Parameters:
        vec3: Vector3
    .teleport(vec3):
      Teleports the controller to a new position.
      Parameters:
        vec3: Vector3
```

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

### Hyperfy Video Component Properties Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Video.md

Detailed documentation for configuring the Hyperfy Video component, including visual display, audio settings, spatialization, and sizing options. This component allows embedding video content into the virtual environment with various customization capabilities.

```APIDOC
Video Component Properties:
  .src: String
    Description: A URL to a video file, or an asset URL from a video prop. Currently only mp4 and m3u8 (HLS streams) are supported.
  .linked: Number|String
    Description: By default, videos are not linked. Set to true or a string ID to synchronize state and control across multiple video nodes, allowing hundreds of instances of a single video to play with individual audio emitters and low overhead.
  .loop: Boolean
    Description: Whether the video should loop. Defaults to false.
  .visible: Boolean
    Description: Whether the video should be displayed. Defaults to true. Can be used to play audio headlessly with more control over audio position.
  .color: String
    Description: The color of the mesh before the video is playing. Defaults to black.
  .lit: Boolean
    Description: Whether the mesh material is lit (reacts to lighting) or not. Defaults to false.
  .doubleside: Boolean
    Description: Whether the video should play on both sides of the plane. Does not apply to custom geometry. Defaults to true.
  .castShadow: Boolean
    Description: Whether the mesh should cast a shadow. Defaults to false.
  .receiveShadow: Boolean
    Description: Whether the video should receive shadows. Defaults to false.
  .aspect: Number
    Description: The aspect ratio. Used to calculate width/height for planes before video loads, and for scaling video onto custom geometry. Ensures correct display without stretching or distortion. For custom geometry, set to the physical/visual aspect ratio of the projection surface (e.g., 16/9 for a 16:9 screen, 2/1 for a 360 sphere).
  .fit: Enum("none", "contain", "cover")
    Description: The resize strategy for fitting the video onto its surface. 'contain' shrinks the video to be entirely visible; 'cover' expands it to cover the entire surface; 'none' applies no logic. Defaults to 'contain'.
  .width: Number|null
    Description: The fixed width of the plane when not using custom geometry. Can be null for automatic sizing, matching the .ratio until video playback, then resizing to video dimensions. Defaults to null.
  .height: Number|null
    Description: The fixed height of the plane when not using custom geometry. Can be null for automatic sizing, matching the .ratio until video playback, then resizing to video dimensions. Defaults to null.
  .geometry: Geometry
    Description: The custom geometry to use instead of a plane. Geometry can be extracted from a Mesh node's .geometry property.
  .volume: Number
    Description: The volume of the video's audio. Defaults to 1.
  .group: String
    Description: The audio group this music belongs to. Players can adjust the volume of these groups individually. Must be 'music' or 'sfx' ('voice' not allowed). Defaults to 'music'.
  .spatial: Boolean
    Description: Whether music should be played spatially and heard by players nearby. Defaults to true.
  .distanceModel: Enum('linear', 'inverse', 'expontential')
    Description: When spatial is enabled, the distance model to use. Defaults to 'inverse'.
  .refDistance: Number
    Description: When spatial is enabled, the reference distance to use. Defaults to 1.
  .maxDistance: Number
    Description: When spatial is enabled, the max distance to use. Defaults to 40.
  .rolloffFactor: Number
    Description: When spatial is enabled, the rolloff factor to use. Defaults to 3.
  .coneInnerAngle: Number
    Description: When spatial is enabled, the cone inner angle to use. Defaults to 360.
  .coneOuterAngle: Number
    Description: When spatial is enabled, the cone outer angle to use. Defaults to 360.
  .coneOuterGain: Number
    Description: When spatial is enabled, the cone outer gain to use. Defaults to 0.
  .isPlaying: Boolean
    Description: Whether the video is currently playing. Read-only.
```

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

### Hyperfy Scripting Globals

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/scripts.md

This section lists the global objects available within the Hyperfy app runtime environment. These globals provide core APIs for interacting with the Hyperfy world, similar to how browser APIs are provided via the DOM.

```APIDOC
app
world
props
fetch
num
Vector3
Quaternion
Euler
Matrix4
```

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

### Create and Add a VRM Avatar Instance

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Avatar.md

Initializes a new avatar instance with a source URL and an optional emote URL, then adds it to the application. This snippet demonstrates how to instantiate an avatar object using the `app.create` method and integrate it into the scene.

```jsx
const src = props.avatar?.url
const emote = props.emote?.url
const avatar = app.create('avatar', { src, emote })
app.add(avatar)
```

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

### Hyperfy Collider Component API Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/Collider.md

Detailed API documentation for the Collider component, including its configurable properties and methods for physics interaction. It also notes current limitations and inherited properties.

```APIDOC
Collider:
  description: A collider connects to its parent rigidbody to simulate under physics.
  note: Setting/modifying the geometry are not currently supported, and only be configured within a GLTF (eg via blender).

  Properties:
    .type: String
      description: The type of collider, must be `box`, `sphere` or `geometry`. Defaults to `box`.
    .radius: Number
      description: When type is `sphere`, sets the radius of the sphere. Defaults to `0.5`.
    .convex: Boolean
      description: Whether the geometry should be considered "convex". If disabled, the mesh will act as a trimesh. Defaults to `false`.
      details: Convex meshes are not only more performant, but also allow two convex dynamic rigidbodies to collide. This is the same behavior that engines like Unity use.
    .trigger: Boolean
      description: Whether the collider is a trigger. Defaults to `false`.
      details: A trigger will not collide with anything, and instead will trigger the `onTriggerEnter` and `onTriggerLeave` functions on the parent rigidbody.
      note: Triggers are forced to act like convex shapes. This is a limitation in the physics engine.
    .{...Node}:
      description: Inherits all Node properties (see /docs/ref/Node.md)

  Methods:
    .setSize(width: Number, height: Number, depth: Number)
      description: When type is `box`, sets the size of the box. Defaults to `1, 1, 1`.
```

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

### SkinnedMesh Object API Documentation

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/SkinnedMesh.md

Comprehensive API documentation for the SkinnedMesh object, outlining its properties and methods for animation control and bone access.

```APIDOC
SkinnedMesh:
  Description: Represents a skinned mesh with bones and animations.
  Note: Skinned meshes are not automatically instanced in the engine like regular meshes.

  Properties:
    .anims: Array
      Description: An array of animation names available. Read-only.
    .castShadow: Boolean
      Description: Whether this skinned mesh should cast a shadow. Defaults to true.
    .receiveShadow: Boolean
      Description: Whether this skinned mesh should receive a shadow. Defaults to true.
    .{...Node}:
      Description: Inherits all Node properties.

  Methods:
    .play(params: Object):
      Description: Plays an animation. If a previous animation was playing it will stop/fade.
      Parameters:
        name: String
          Description: The name of the animation to play.
        fade: Number
          Description: The fade time in seconds, into this animation and out of any previous animation. Defaults to 0.15.
        loop: Boolean
          Description: Whether the animation should loop. When false, will stop on the last frame. Defaults to true.
        speed: Number
          Description: The speed to play the animation at.
    .stop(params: Object):
      Description: Stops any playing animation.
      Parameters:
        fade: Number
          Description: Fade defaults to 0.15.
    .getBone(boneName: String): Bone
      Description: Returns a bone with properties position, quaternion, rotation, scale and matrixWorld.
      Parameters:
        boneName: String
```

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

### Exporting and Importing Hyperfy .hyp Files with JavaScript

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/hyp-format.md

Illustrates how to export an app blueprint into a .hyp file and import a .hyp file to retrieve its blueprint and assets using asynchronous JavaScript functions `exportApp` and `importApp`. These functions handle the underlying file format operations.

```javascript
// Export a .hyp file
const hypFile = await exportApp(blueprint, resolveFile)

// Import a .hyp file
const { blueprint, assets } = await importApp(hypFile)
```

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

### UIImage Properties Reference

Source: https://github.com/hyperfy-xyz/hyperfy/blob/main/docs/ref/UIImage.md

Detailed documentation for all configurable properties of the UIImage component, including their types, descriptions, and default values. Note: The source description for `backgroundColor` was corrected to reflect its actual purpose.

```APIDOC
UIImage Properties:
  .display: String
    Description: Determines whether the image is displayed or hidden. Options are flex or none.
    Default: flex
  .src: String
    Description: The URL of the image to display.
    Default: null
  .height: Number
    Description: The height of the image in pixels.
    Default: null (image’s natural height)
  .objectFit: String
    Description: How the image should fit within its container. Options are contain, cover, or fill.
    Default: contain
  .backgroundColor: String
    Description: The background color of the image container.
    Default: 0
  .flexDirection: String
    Description: The flex direction for the image container. Options are column, column-reverse, row, or row-reverse.
    Default: Inherits from parent UI node by default.
  .justifyContent: String
    Description: Options: flex-start, flex-end, center.
    Default: Inherits from parent UI node by default.
  .alignItems: String
    Description: Options: flex-start, flex-end, stretch, center, space-between, space-around, space-evenly.
    Default: Inherits from parent UI node by default.
  .flexWrap: String
    Description: Options: no-wrap, wrap.
    Default: Inherits from parent UI node by default.
  .gap: Number
    Description: The gap between child elements in pixels.
    Default: Inherits from parent UI node by default.
  .margin: Number
    Description: The outer margin of the image container in pixels.
    Default: 0
  .padding: Number
    Description: The inner padding of the image container in pixels.
    Default: 0
  .borderWidth: Number
    Description: The width of the border in pixels.
    Default: 0
  .borderColor: String
    Description: The color of the border. Can be hex (e.g., #000000) or rgba (e.g., rgba(0, 0, 0, 0.5)).
    Default: null
```