### Run Ambient Example from Main Branch

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/running_examples.md

Execute an Ambient example from the main branch after cloning the repository and installing Ambient. Ensure your Ambient installation matches the example's branch.

```bash
ambient run guest/rust/examples/basics/primitives
```

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

### Run an Example with Campfire

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/contributing.md

Use the `cargo cf run` command to execute examples. The `decals` example is shown here.

```sh
cargo cf run decals
```

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

### Run Examples with Campfire

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/overview.md

Use the Campfire tool to conveniently run examples from the guest/rust/examples directory.

```sh
cargo cf run -r primitives
```

```sh
cargo cf run -r basics/primitives
```

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

### Minimal Counter App Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/ui.md

A basic counter application demonstrating state management with `use_state` and UI element creation using `FlowColumn`, `Text`, and `Button`. This is a good starting point for understanding Ambient's UI.

```rust
use ambient_api::prelude::*;
use ambient_ui::prelude::*;

#[element_component]
fn App(hooks: &mut Hooks) -> Element {
    let (count, set_count) = use_state(hooks,0);
    FlowColumn::el([
        Text::el(format!("We've counted to {count} now")),
        Button::new("Increase", move |_| set_count(count + 1)).el(),
    ])
}

#[main]
pub fn main() {
    App.el().spawn_interactive();
}
```

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

### Example Package Manifest

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/package.md

A complete example of an `ambient.toml` file, demonstrating the package metadata including ID, name, version, content type, and Ambient version. Optional fields like authors, description, and repository are also shown.

```toml
#
# The package section describes all package metadata.
#
[package]
id = "d563xtcr72ovuuhfkvsgag6z3wiy5jwr"
name = "My Cool Package"
version = "0.0.1"
content = { type = "Asset", code = true }
ambient_version = "0.3.0"

# The following are optional:
# authors = ["Cool Cat"]
# description = "A sample package that's the coolest thing ever."
# repository = "https://my-cool-forge.io/my-cool-package"
# public = true
```

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

### Spawn Query Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/ecs.md

Spawn queries are triggered when entities are created or specific components are added. This example spawns a random colored box for each new player.

```rust
spawn_query(player()).bind(move |players| {
    // For each player joining, spawn a random colored box somewhere
    for _ in players {
        Entity::new()
            .with_merge(Transformable::suggested())
            .with(cube(), ())
            .with(translation(), rand::random())
            .with(color(), rand::random::<Vec3>().extend(1.0))
            .spawn();
    }
});
```

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

### Start Ambient for Profiling

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/profiling.md

Run your Ambient application after building with the profiling feature. This command starts the Ambient runtime, which will begin collecting performance data.

```sh
ambient run guest/examples/basics/primitives
```

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

### Build Example with Release Profile

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/contributing.md

To build Ambient and its assets with the release profile, use the `--release` flag twice: once for the Campfire command and once for the asset build.

```sh
cargo cf run --release decals -- --release
```

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

### Physics Setup with Colliders and Dynamic Objects

Source: https://context7.com/ambientrun/ambient/llms.txt

Demonstrates setting up static and dynamic colliders for physics simulation. Includes listening for collision events.

```rust
use ambient_api::prelude::*;

#[main]
pub fn main() {
    // Static sphere collider (does not move)
    Entity::new()
        .with_merge(Transformable::suggested())
        .with(sphere_collider(), 0.5)  // radius = 0.5
        .with(sphere(), ())
        .spawn();

    // Dynamic box that falls under gravity
    Entity::new()
        .with_merge(Transformable::suggested())
        .with(translation(), vec3(0.0, 0.0, 10.0))
        .with(cube_collider(), Vec3::ONE)
        .with(cube(), ())
        .with(physics_controlled(), ())
        .with(dynamic(), true)
        .spawn();

    // Listen for collision events
    Collision::subscribe(move |msg| {
        println!("Collision between: {:?}", msg.ids);
    });
}
```

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

### Install Ambient from Git Revision

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/contributing.md

Install a specific version of Ambient from a Git revision using the `cargo campfire install` command with `--git-revision`.

```sh
cargo campfire install [--git-revision <revision>] [--git-tag <tag>] [--suffix <suffix>]
```

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

### Install puffin_viewer

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/profiling.md

Install the puffin_viewer tool globally to visualize profiling data. This tool is used to connect to and display metrics from a running Ambient instance.

```sh
cargo install puffin_viewer
```

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

### Serve with Custom Certificate

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/networking.md

Starts the Ambient server using custom certificate and key files for secure communication.

```sh
ambient serve --cert ./localhost.crt --key ./localhost.key
```

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

### General Query Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/ecs.md

Use general queries to find entities with a specific set of components. This example iterates over players to update camera positions.

```rust
query((player(), player_camera_ref(), translation(), rotation())).each_frame(move |players| {
    for (_, (_, camera_id, pos, rot)) in players {
        let forward = rot * Vec3::X;
        entity::set_component(camera_id, lookat_target(), pos);
        entity::set_component(camera_id, translation(), pos - forward * 4. + Vec3::Z * 2.);
    }
});
```

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

### Install Ambient from Git Tag

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/contributing.md

Install Ambient from a specific Git tag. The executable name will be suffixed with the tag by default.

```sh
cargo campfire install --git-tag v0.1.0
```

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

### Install with Optional Features

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/advanced_installing.md

Installs Ambient from Git with optional features enabled, such as 'assimp' for extended model file format support. The --locked and --force flags are recommended.

```sh
cargo install --git https://github.com/AmbientRun/Ambient.git ambient --features assimp --locked --force
```

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

### Start puffin_viewer

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/profiling.md

Launch the puffin_viewer application. This will open a graphical interface that connects to the running Ambient instance and displays real-time performance metrics.

```sh
puffin_viewer
```

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

### Install Ambient CLI

Source: https://context7.com/ambientrun/ambient/llms.txt

Installs the Ambient command-line interface using Cargo. Ensure Rust and the WASM target are installed first.

```sh
rustup target add --toolchain stable wasm32-wasi
cargo install ambient
```

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

### Despawn Query Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/ecs.md

Despawn queries track component removals or entity despawns. This example prints a message when a player leaves.

```rust
despawn_query(user_id()).requires(player()).bind(move |players| {
    for (_, user_id) in players {
        println!("Player {user_id} left");
    }
});
```

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

### Change Query Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/ecs.md

Change queries activate when tracked components are modified. This example logs a player's updated health.

```rust
change_query((user_id(), health())).track_change(health()).requires(player()).bind(move |players| {
    for (_, (user_id, health)) in players {
        println!("Player {user_id} now has {health} health");
    }
});
```

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

### Install Ambient with Custom Suffix

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/contributing.md

Install Ambient from a Git tag and specify a custom suffix for the executable name using the `--suffix` flag.

```sh
cargo campfire install --git-tag v0.1.0 --suffix back-in-time
```

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

### Install Dependencies for Headless Linux/Ubuntu

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/advanced_installing.md

Installs additional dependencies needed to run Ambient on a headless Linux machine. This includes graphics drivers and Vulkan support, which Ambient currently assumes are available.

```sh
add-apt-repository ppa:oibaf/graphics-drivers -y
apt-get update
apt install -y libxcb-xfixes0-dev mesa-vulkan-drivers
```

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

### Build Ambient with Profiling Enabled

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/profiling.md

Use this command to install Ambient with the `profile` feature flag enabled. This is required to generate profiling data.

```sh
cargo install --path app --features profile
```

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

### Create a UI with Custom Components and State in Rust

Source: https://context7.com/ambientrun/ambient/llms.txt

Shows how to build a user interface using a React-inspired component system with hooks and state management. Includes examples of custom components, stateful components, and conditional rendering.

```rust
use ambient_api::prelude::*;
use ambient_ui::prelude::*;

#[element_component]
fn Scoreboard(hooks: &mut Hooks, scores: Vec<(String, i32)>) -> Element {
    FlowColumn::el(
        scores
            .into_iter()
            .map(|(name, score)| {
                FlowRow::el([
                    Text::el(name).with(color(), vec4(1.0, 1.0, 0.0, 1.0)),
                    Text::el(format!(/*score*/ "{score}")),
                ])
            })
            .collect::<Vec<_>>(),
    )
}

#[element_component]
fn HUD(hooks: &mut Hooks) -> Element {
    let (count, set_count) = use_state(hooks, 0);
    let (show_board, set_show_board) = use_state(hooks, false);

    FlowColumn::el([
        Text::el(format!(/*Kills:*/ "Kills: {count}")),
        Button::new("Show Scoreboard", move |_| set_show_board(!show_board)).el(),
        if show_board {
            Scoreboard::el(vec![("Alice".to_string(), 10), ("Bob".to_string(), 7)])
        } else {
            Element::new()
        },
        Button::new("+1", move |_| set_count(count + 1)).el(),
    ])
}

#[main]
pub fn main() {
    HUD.el().spawn_interactive();
}
```

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

### Run Ambient Server with Custom TLS (Shell)

Source: https://context7.com/ambientrun/ambient/llms.txt

Start the Ambient server using custom TLS certificates for secure connections. Ensure the certificate and key files are accessible.

```sh
# Run server with a custom TLS certificate
ambient serve --cert ./localhost.crt --key ./localhost.key
```

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

### Install wasm-bindgen Manually

Source: https://github.com/ambientrun/ambient/blob/main/web/README.md

Fixes 'Bad CPU type in executable' errors on Mac M1/M2 by manually installing wasm-bindgen.

```sh
cargo install -f wasm-bindgen
```

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

### Deploy Game with Ambient CLI

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/tutorials/game/7_deploying.md

Run this command in your project's directory to deploy your game to Ambient servers. The first execution may require account setup and API token generation as indicated by the error message.

```bash
ambient deploy
```

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

### Install Latest Published Release from Git

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/advanced_installing.md

Use this command to install the latest tagged release of Ambient from its Git repository. This is recommended over the development version for stability.

```sh
cargo install --git https://github.com/AmbientRun/Ambient.git --tag v0.3.2-dev ambient
```

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

### Synchronous Asset Caching Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/asset_cache.md

Demonstrates how to use the AssetCache for synchronous operations. Implement `SyncAssetKey` and use the `.get()` method to retrieve cached or compute new values.

```rust
#[derive(Debug, Clone)]
struct GenerateFractal { param1: bool, param2: u32 }
impl SyncAssetKey<Arc<Image>> for GenerateFractal {
    fn load(&self, assets: AssetCache) -> Arc<Arc<Image>> {
        // ..
    }
}

let fractal = GenerateFractal { param2: true, param2: 5 }.get(&assets);
```

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

### Build WASM Components with wasm-tools

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/package.md

These commands demonstrate the process of building WASM components for client and server targets using Cargo and wasm-tools. Ensure you have wasm-tools installed and the preview1-to-preview2 WASI adapter available.

```sh
cd your_package
cargo build --target wasm32-wasi --features client
wasm-tools component new target/wasm32-wasi/debug/your_package_client.wasm -o build/client/your_package.wasm --adapt wasi_snapshot_preview1.command.wasm

cargo build --target wasm32-wasi --features server
wasm-tools component new target/wasm32-wasi/debug/your_package_server.wasm -o build/server/your_package.wasm --adapt wasi_snapshot_preview1.command.wasm
```

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

### Install libstdc++-12-dev on Debian-based systems

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/common_pitfalls.md

If compilation fails due to a missing `<ciso646>` header, install the `libstdc++-12-dev` package on Debian-based systems. This provides the necessary header for C++20 compatibility.

```sh
sudo apt install libstdc++-12-dev
```

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

### VSCode Settings for Ambient

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/setting_up_ide.md

Example configuration for VSCode's settings.json to enable the 'server' and 'client' feature flags for rust-analyzer. This is crucial for Ambient development.

```json
{
  "rust-analyzer": {
    "cargo": {
      "allFeatures": true,
      "extraArgs": [
        "--features",
        "client server"
      ]
    }
  }
}
```

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

### Install Build Dependencies on Linux/Ubuntu

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/advanced_installing.md

Installs essential build dependencies required for compiling Ambient on Linux systems, particularly Ubuntu. This includes build-essential, cmake, pkg-config, and development libraries for fontconfig, clang, alsa, and ninja.

```sh
apt-get install -y \
    build-essential cmake pkg-config \
    libfontconfig1-dev clang libasound2-dev ninja-build
```

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

### Install Latest Development Version from Git

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/advanced_installing.md

Installs the latest development version of Ambient from the main branch. Use with caution as this branch may contain breaking changes and bugs. The --locked flag ensures reproducible builds.

```sh
cargo install --git https://github.com/AmbientRun/Ambient.git --locked --force ambient
```

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

### Test Hosted Environment Logic

Source: https://github.com/ambientrun/ambient/blob/main/CHANGELOG.md

To test if your logic functions correctly in a hosted environment, run Ambient with the `AMBIENT_HOSTED` environment variable set. For example, `AMBIENT_HOSTED=1 ambient run`.

```bash
AMBIENT_HOSTED=1 ambient run
```

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

### Rust WIT Type Conversion Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/contributing.md

Demonstrates converting between native Rust types (e.g., glam::Vec3) and WIT-generated types for better API usability and extensibility. Implement IntoBindgen and FromBindgen traits for custom structs.

```wit
record ray {
    origin: vec3,
    direction: vec3,
}
```

```rust
/// Some documentation
struct Ray {
    // Per-field
    origin: Vec3,
    // Documentation
    direction: Vec3,
}
impl IntoBindgen for Ray {
    type Item = wit::types::Ray;
    fn into_bindgen(self) -> Self::Item {
        wit::types::Ray {
            origin: self.origin.into_bindgen(),
            direction: self.direction.into_bindgen(),
        }
    }
}
impl FromBindgen for wit::types::Ray {
    type Item = Ray;
    fn from_bindgen(self) -> Self::Item {
        Ray {
            origin: self.origin.from_bindgen(),
            direction: self.direction.from_bindgen(),
        }
    }
}
impl Ray {
    /* helper methods */
}
```

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

### Asynchronous Asset Caching Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/asset_cache.md

Shows how to integrate the AssetCache with asynchronous operations using `AsyncAssetKey`. The cache ensures that the `load` function is called only once per unique key.

```rust
#[derive(Debug, Clone)]
struct LoadImageFlipY { url: String }
#[async_trait]
impl AsyncAssetKey<Arc<Image>> for LoadImageFlipY {
    async fn load(&self, assets: AssetCache) -> Arc<Image> {
        let image = ImageFromUrl { url: self.url.clone() }.get(&assets).await.unwrap();
        // ..
    }
}
```

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

### Transform Calculation with Translation, Rotation, and Scale

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/hierarchies.md

Demonstrates how `local_to_world` and `local_to_parent` are automatically recalculated from `translation`, `rotation`, and `scale` components. This example shows the order of operations for these calculations.

```rust
a.local_to_world = mat4_from(a.scale, a.rotation, a.translation);
b.local_to_parent = mat4_from(b.scale, b.rotation, b.translation);
b.local_to_world = a.local_to_world * b.local_to_parent;
```

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

### Establish Entity Hierarchies and Transforms in Rust

Source: https://context7.com/ambientrun/ambient/llms.txt

Explains how to create parent-child relationships between entities using the `parent` component and how `local_to_parent` drives inherited transformations. Includes an example of spawning a parent and child with specific translations and rotations.

```rust
use ambient_api::prelude::*;

#[main]
pub fn main() {
    // Create a parent entity
    let parent_id = Entity::new()
        .with_merge(Transformable::suggested())
        .with(translation(), vec3(5.0, 0.0, 0.0))
        .with(rotation(), Quat::from_rotation_z(0.5))
        .spawn();

    // Attach a child offset from the parent
    let child_id = Entity::new()
        .with_merge(Transformable::suggested())
        .with(parent(), parent_id)
        .with(local_to_parent(), Mat4::from_translation(vec3(0.0, 2.0, 0.0)))
        .with(cube(), ())
        .spawn();

    entity::add_child(parent_id, child_id);
}
```

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

### Configure Desktop Game Launch

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/distributing.md

Create a launch.json file to specify arguments for running a desktop version of your game. The 'args' should include 'run' and the URL pointing to your game's deployment.

```json
{
  "args": ["run", "https://assets.ambient.run/1QI2Kc6xKnzantTL0bjiOQ"]
}
```

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

### Install Ambient Version Manager

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/installing.md

Install the Ambient version manager using Cargo, the Rust package manager. This command fetches and installs the latest version of the Ambient CLI.

```bash
cargo install ambient
```

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

### Generate API Documentation

Source: https://github.com/ambientrun/ambient/blob/main/guest/rust/DEVELOPMENT.md

Run this command from the repository root to generate documentation locally. The `--open` flag will open the documentation in your browser.

```sh
cargo campfire doc api [-- --open]
```

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

### Create and Run an Ambient Project

Source: https://context7.com/ambientrun/ambient/llms.txt

Scaffolds a new Ambient package, builds it, and runs it locally. Includes commands for joining local and remote sessions, and running with a debugger.

```sh
ambient new my_project
cd my_project
ambient run
ambient join
ambient join proxy-eu.ambient.run:9898
ambient run --debugger
```

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

### Spawn Camera Concept Instance (Rust)

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/ecs.md

Demonstrates how to create and initialize a 'Camera' concept instance with suggested values in Rust.

```rust
let camera = Camera {
    local_to_world: Mat4::IDENTITY,
    near: 0.1,
    projection: Mat4::IDENTITY,
    projection_view: Mat4::IDENTITY,
    active_camera: 0.0,
    inv_local_to_world: Mat4::IDENTITY,

```

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

### Create a New Ambient Project

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/tutorials/game/1_package.md

Use this command to create a new Ambient package with the default template. Initial build times may be slow.

```sh
ambient new my_project
```

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

### Deploy Package to Ambient Platform

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/distributing.md

Use this command to package and upload your creation to the Ambient platform. The output provides URLs for joining and accessing your deployed content.

```sh
$ ambient deploy
Package "my-project" deployed successfully!
   Join: ambient join 'https://api.ambient.run/servers/ensure-running?package_id=pkgid&package_version=0.0.5'
   Web URL: 'https://ambient.run/packages/pkgid/version/0.0.5'
```

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

### ECS Entity Example

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/overview.md

Represents an entity in the ECS world with 'translation' and 'color' components.

```yml
entity 1932:
  - translation: (5, 2, 0)
  - color: (1, 0, 0, 1)
```

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

### Run an Ambient Project

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/tutorials/game/1_package.md

Navigate into your project directory and use this command to run your Ambient application. A window will appear displaying the running project.

```sh
cd my_project
ambient run
```

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

### Component Renaming Examples

Source: https://github.com/ambientrun/ambient/blob/main/CHANGELOG.md

Several 'tag components' have been prefixed with `is_` to clarify their role as tags.

```rust
core::animation::animation_player -> core::animation::is_animation_player
```

```rust
core::audio::audio_player -> core::audio::is_audio_player
```

```rust
core::audio::spatial_audio_player -> core::audio::is_spatial_audio_player
```

```rust
core::layout::screen -> core::layout::is_screen
```

```rust
core::network::persistent_resources -> core::network::is_persistent_resources
```

```rust
core::network::synced_resources -> core::network::is_synced_resources
```

```rust
core::player::player -> core::player::is_player
```

```rust
core::wasm::module -> core::wasm::is_module
```

```rust
core::wasm::module_on_server -> core::wasm::is_module_on_server
```

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

### Model Pipeline with Material Overriding

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/asset_pipeline.md

Applies a custom material to imported meshes using the 'material_overriding' example configuration.

```toml
{{ #include ../../../guest/rust/examples/assets/material_overriding/assets/pipeline.toml }}

```

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

### Add wasm32-wasi Toolchain

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/installing.md

Add the wasm32-wasi toolchain to your Rust installation to enable compilation of Rust code for Ambient.

```bash
rustup target add --toolchain stable wasm32-wasi
```

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

### Generate API Documentation

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/runtime_internals/contributing.md

Generate and open the latest API documentation for Ambient using the `cargo campfire doc api --open` command.

```sh
cargo campfire doc api --open
```

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

### Deploy Package to Ambient Platform (Shell)

Source: https://context7.com/ambientrun/ambient/llms.txt

Deploy your Ambient project to the `ambient.run` platform. This command requires you to be logged in and provides join and web URLs upon successful deployment.

```sh
# Deploy to ambient.run (requires login)
ambient deploy
# Output:
# Package "my-project" deployed successfully!
#    Join: ambient join 'https://api.ambient.run/servers/ensure-running?package_id=pkgid&package_version=0.0.5'
#    Web URL: 'https://ambient.run/packages/pkgid/version/0.0.5'
```

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

### Get All Components of the Current Package

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/package.md

Access the entity representing the current package at runtime and retrieve all its associated components using `entity::get_all_components`.

```rust
use ambient_api::prelude::*;

#[main]
fn main() {
    dbg!(entity::get_all_components(packages::this::entity()));
}
```

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

### Build Package for Self-Hosting

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/distributing.md

This command builds your package into a 'build' folder, which can then be placed on any file server for self-hosting. Use 'ambient run' with the URL to access the content.

```sh
ambient build
```

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

### Build Ambient Package Locally for Self-Hosting (Shell)

Source: https://context7.com/ambientrun/ambient/llms.txt

Compile your Ambient project locally, generating a `build/` folder suitable for self-hosting on any static file server. The output includes instructions for running directly from a URL.

```sh
# Build locally for self-hosting
ambient build
# Upload the generated `build/` folder to any static host (e.g. S3)
# Run directly from a URL:
ambient run https://your-cdn.example.com/my_game/
```

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

### Inspect Server ECS State (YAML)

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/user/debugging.md

When the debugger is active, YAML files representing the server ECS state are generated. This example shows a snippet of the typical output.

```yaml
- "id=RsE148MNkdB24bFWQrfeMA loc=48:0":
    "core::app::main_scene": ()
    "core::ecs::children": "[EntityId(koK-dbeCZDrcHzsT7QELUw, 110383077981027712353063371358575952530)]"
    "core::transform::translation": "Vec3(-5.0, -0.0019752309, 2.8536541)"
    "core::transform::scale": "Vec3(1.0, 1.0, 1.0)"
    "core::transform::rotation": "Quat(0.0, 0.0, 0.0, 1.0)"
    "core::transform::local_to_world": "Mat4 { x_axis: Vec4(1.0, 0.0, 0.0, 0.0), y_axis: Vec4(0.0, 1.0, 0.0, 0.0), z_axis: Vec4(0.0, 0.0, 1.0, 0.0), w_axis: Vec4(-5.0, -0.001970334, 2.8387475, 1.0) }"
    "core::transform::spherical_billboard": ()
  children:
    - "id=koK-dbeCZDrcHzsT7QELUw loc=46:0":
        "core::app::main_scene": ()
        "core::transform::local_to_world": "Mat4 { x_axis: Vec4(0.02, 0.0, 0.0, 0.0), y_axis: Vec4(0.0, -0.02, 1.7484555e-9, 0.0), z_axis: Vec4(0.0, -1.7484555e-9, -0.02, 0.0), w_axis: Vec4(-5.0, -0.001970334, 2.8387475, 1.0) }"
        "core::transform::local_to_parent": "Mat4 { x_axis: Vec4(0.02, 0.0, 0.0, 0.0), y_axis: Vec4(0.0, -0.02, 1.7484555e-9, 0.0), z_axis: Vec4(0.0, -1.7484555e-9, -0.02, 0.0), w_axis: Vec4(0.0, 0.0, 0.0, 1.0) }"
        "core::transform::mesh_to_local": "Mat4 { x_axis: Vec4(1.0, 0.0, 0.0, 0.0), y_axis: Vec4(0.0, 1.0, 0.0, 0.0), z_axis: Vec4(0.0, 0.0, 1.0, 0.0), w_axis: Vec4(0.0, 0.0, 0.0, 1.0) }"
        "core::transform::mesh_to_world": "Mat4 { x_axis: Vec4(0.02, 0.0, 0.0, 0.0), y_axis: Vec4(0.0, -0.02, 1.7484555e-9, 0.0), z_axis: Vec4(0.0, -1.7484555e-9, -0.02, 0.0), w_axis: Vec4(-5.0, -0.001970334, 2.8387475, 1.0) }"
        "core::rendering::color": "Vec4(1.0, 0.3, 0.3, 1.0)"
        "core::ui::text": '"user_470i61dDp7FKjGFQetZ53O"'
        "core::ui::font_size": "36.0"
        "core::player::user_id": "..."
      children: []
```

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

### Configure HTTP GET Request with Headers

Source: https://github.com/ambientrun/ambient/blob/main/CHANGELOG.md

Update existing `http::get` calls to include optional headers. Pass `None` for the second argument if no headers are needed.

```rust
http::get(url, None)
```

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

### Serve Ambient Web Client

Source: https://github.com/ambientrun/ambient/blob/main/web/README.md

Builds the web client and launches a Vite development server. The client automatically rebuilds on file changes. Note: The self-signed certificate is only valid for 127.0.0.1.

```sh
cargo campfire web serve
```

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

### Play and Blend Animations in Rust

Source: https://context7.com/ambientrun/ambient/llms.txt

Demonstrates playing single animations, blending two animations with adjustable weights, and performing masked blends on specific body parts. Also shows how to attach entities to skeleton bones and pre-load animation clips asynchronously.

```rust
use ambient_api::prelude::*;
use packages::ambient_example_skinmesh::assets;

#[main]
pub fn main() {
    // Single animation
    let clip = PlayClipFromUrlNodeRef::new(
        assets::url("Capoeira.fbx/animations/mixamo.com.anim"),
    );
    let player = AnimationPlayerRef::new(&clip);

    Entity::new()
        .with_merge(Transformable::suggested())
        .with(prefab_from_url(), assets::url("Peasant Man.fbx"))
        .with(apply_animation_player(), player.0)
        .spawn();

    // Blend two animations (30% capoeira, 70% robot dance)
    let robot = PlayClipFromUrlNodeRef::new(
        assets::url("Robot Hip Hop Dance.fbx/animations/mixamo.com.anim"),
    );
    let blend = BlendNodeRef::new(&clip, &robot, 0.3);
    let blended_player = AnimationPlayerRef::new(&blend);

    // Masked blend — capoeira upper body, robot lower body
    let masked = BlendNodeRef::new(&clip, &robot, 0.0);
    masked.set_mask_humanoid_lower_body(1.0);  // lower body 100% robot
    let masked_player = AnimationPlayerRef::new(&masked);

    // Attach an entity to a skeleton bone
    let left_foot = animation::get_bone_by_bind_id(unit_id, &BindId::LeftFoot).unwrap();
    let ball = Entity::new()
        .with_merge(Transformable::suggested())
        .with_merge(Sphere::suggested())
        .with(parent(), left_foot)
        .with(local_to_parent(), Default::default())
        .with(reset_scale(), ())
        .spawn();
    entity::add_child(left_foot, ball);

    // Pre-load a clip (async)
    run_async(async move {
        let clip = PlayClipFromUrlNodeRef::new(assets::url("Idle.fbx/animations/mixamo.com.anim"));
        clip.wait_for_load().await;
    });
}
```

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

### Run Content from Self-Hosted URL

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/distributing.md

Use this command to run content that has been built and placed on a file server. Replace the URL with the address of your self-hosted content.

```sh
ambient run https://address.to/your/content
```

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

### Update Dependency Versions with Ambient CLI

Source: https://github.com/ambientrun/ambient/blob/main/CHANGELOG.md

Use the `--version` argument with the `ambient deploy` command to update the versions of packages in your dependency tree. For example, to update to version 0.3.

```bash
ambient deploy --version 0.3
```

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

### Basic Models Pipeline

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/reference/asset_pipeline.md

A minimal configuration for the Models pipeline to load .glb and .fbx files from the current directory or subdirectories.

```toml
[[pipelines]]
type = "Models"

```

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

### Configure Mod in ambient.toml

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/tutorials/game/8_modding.md

Set up the `ambient.toml` file for a new mod, specifying its type, the game it's for, and its local development dependency on the game.

```toml
# Note: Add this field, or replace it if it already exists, making sure to update the ID:
content = { type = "Mod", for_playables = ["the_id_of_your_game_from_its_ambient_toml"] }

[dependencies]
# Note: This line will make it possible to run the mod locally, as it will pull in your game as a dependency.
# Replace LATEST_DEPLOYMENT_ID with the latest deployment ID of your game, which can be found on the game's page.
# When you want to deploy the mod, comment this line out first
my_game = { deployment = "LATEST_DEPLOYMENT_ID" }
```

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

### Configure HTTP POST Request in Server API

Source: https://github.com/ambientrun/ambient/blob/main/CHANGELOG.md

Demonstrates how to make POST requests using the `http::post` function in the server API. Optional `headers` and `body` arguments can be provided.

```rust
http::post(url, headers, body)
```

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

### Attach Animation Tree to Entity

Source: https://github.com/ambientrun/ambient/blob/main/guest/rust/api/src/anim_el_example.md

Attaches the generated animation tree to a target entity. This code snippet demonstrates how to spawn the animation tree and add it as a component to an entity, using a query to process entities that require animation setup.

```rust
let anims = Arc::new(Mutex::new(HashMap::<EntityId, ElementTree>::new()));
spawn_query(<your component>).bind({
    let anims = anims.clone();
    move |v| {
        let mut anims = anims.lock().unwrap();
        for (id, target) in v {
            let target = if target.is_null() { id } else { target };
            let tree = CharacterAnimation::from_entity(id).el().spawn_tree();
            entity::add_component(
                target,
                apply_animation_player(),
                tree.root_entity().unwrap(),
            );
            anims.insert(id, tree);
        }
    }
});
```

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

### ECS: Spawn Query for New Players

Source: https://context7.com/ambientrun/ambient/llms.txt

Uses `spawn_query(is_player()).bind(...)` to add a model, controller, and animations to a player entity the first time the `is_player()` component appears. Also spawns a random colored cube for each joining player.

```rust
use ambient_api::prelude::*;

#[main]
pub fn main() {
    // When a player joins, give them a model and controller
    spawn_query(is_player()).bind(move |players| {
        for (id, _) in players {
            entity::add_components(
                id,
                Entity::new()
                    .with_merge(ThirdPersonController::suggested())
                    .with(
                        model_from_url(),
                        packages::base_assets::assets::url("Y Bot.fbx"),
                    )
                    .with(basic_character_animations(), id),
            );
        }
    });

    // Spawn a random colored cube for every joining player
    spawn_query(player()).bind(move |players| {
        for _ in players {
            Entity::new()
                .with_merge(Transformable::suggested())
                .with(cube(), ())
                .with(translation(), rand::random())
                .with(color(), rand::random::<Vec3>().extend(1.0))
                .spawn();
        }
    });
}
```

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

### Run Project in VS Code

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/tutorials/game/1_package.md

Press F5 within VS Code to run the Ambient project after setting up the recommended tools.

```sh
F5
```

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

### Run Project with Debugger

Source: https://github.com/ambientrun/ambient/blob/main/docs/src/tutorials/game/1_package.md

Execute the Ambient project with the debugger UI enabled by appending the `--debugger` flag.

```sh
ambient run --debugger
```