Asset pipeline

Ambient features an automated asset pipeline that is capable of loading and processing a number of assets and formats.

Within the assets folder, or any subdirectory of it, create a file with a name ending in pipeline.toml; examples include pipeline.toml and hello_pipeline.toml. The prefix can be used to disambiguate between different pipelines.

This pipelines will look at, but not necessarily process, all of the files adjacent to it in the folder.

Models

The Models pipeline can be used to compile a model, or models, to meshes that can be used by Ambient. Additionally, by default, prefabs are created for each mesh. These prefabs can have components automatically added to them through the prefab_components field of the pipeline.

Supported formats

  • FBX: Native support
  • glTF: Native support
  • Unity models: Native support
  • Quixel models: Native support
  • ~30 other formats: This support is provided through the assimp library. It is not guaranteed to be fully integrated. By default, Ambient is not built with assimp support due to issues with cross-platform builds.

Examples

Basic models

The following will load .glb and .fbx files in the folder or any of the sub-folders.

[[pipelines]]
type = "Models"

Different pipelines for different files

You can use the sources attribute to restrict different configurations to different files:

[[pipelines]]
type = "Models"
sources = [ "physical/*.glb" ]

[pipelines.collider]
type = "FromModel"

[[pipelines]]
type = "Models"
sources = [ "ghosts/*.glb" ]

sources accepts a list of glob patterns, so you can target a single file or a pattern to select all files in a directory (*.glb) or sub-tree (**/test.glb).

Combining a model with textures

The following example is the asset pipeline for the material_overriding example. It applies a custom material to the imported mesh.

[[pipelines]]
type = "Models"
sources = ["*.glb"]
prefab_components = "{ \"ib2djsnjew5tb2k5igq6le7rzjdwlvhq::is_the_best\": false }"

[[pipelines.material_overrides]]

[pipelines.material_overrides.filter]
type = "All"

[pipelines.material_overrides.material]
name = "Planks"
base_color = "./Planks037B_1K-PNG/Planks037B_1K_Color.png"
normalmap = "./Planks037B_1K-PNG/Planks037B_1K_NormalGL.png"
roughness_factor = 1.0
metallic_factor = 0.0

Generating a pipeline in code

By using a build script, you can also generate a pipeline.toml using Rust code. For instance with a build.rs like this:

use ambient_pipeline_types::{
    models::{ModelTextureSize, ModelTransform},
    ModelImporter, ModelsPipeline, Pipeline, PipelineProcessor, PipelinesFile,
};

fn main() {
    PipelinesFile {
        pipelines: vec![Pipeline {
            processor: PipelineProcessor::Models(ModelsPipeline {
                importer: ModelImporter::Regular,
                cap_texture_sizes: Some(ModelTextureSize::Custom(2)),
                transforms: vec![ModelTransform::RotateZ { deg: 90. }],
                ..Default::default()
            }),
            sources: vec!["*".to_string()],
            tags: vec![],
            categories: vec![],
        }],
    }
    .save_to_file("assets/pipeline.toml")
    .unwrap();

    ambient_package_projection::generate();
}

Which will generate the following toml:

[[pipelines]]
type = "Models"
output_prefabs = false
output_animations = false
sources = ["*"]

[pipelines.cap_texture_sizes]
Custom = 2

[[pipelines.transforms]]
type = "RotateZ"
deg = 90.0

See the generate pipeline example for a full example.

Notes

  • If you are using components in your prefab and are hot-reloading it, the incoming prefab will overwrite any corresponding components on the current state of the entity. These components should only be used for static data - that is, max_hitpoints but not current_hitpoints.

Models

Regular

Consumes model file formats into a hierarchy of entities, materials, and meshes.

Supported formats:

  • glb
  • gltf
  • fbx
  • obj

Unity

Consumes Unity packages processing all meshes, textures and materials, and LoD levels into a normalized form to consume in Ambient. Usage of a processed model during runtime is identical to Regular.

Quixel

Imports Quixel packages.

Supports collections, LoD levels, etc.

Materials

Import materials from a variety of formats. Overrides can be specified in the pipeline.

Detailed documentation is pending, but please consult the Reference.

Supported formats

  • jpg
  • png
  • gif
  • webp
  • as well as other common image formats

Audio

Detailed documentation is pending, but please consult the Reference.

Supported formats

  • ogg
  • wav
  • mp3

Reference

See rustdoc for a complete reference of supported pipelines, model importers, material configurations, and the like.

cargo doc --open -p ambient_pipeline_types