Struct bevy::asset::AssetPath

pub struct AssetPath<'a> { /* private fields */ }

Expand description

Represents a path to an asset in a “virtual filesystem”.

Asset paths consist of three main parts:

AssetPath::source: The name of the AssetSource to load the asset from. This is optional. If one is not set the default source will be used (which is the assets folder by default).
AssetPath::path: The “virtual filesystem path” pointing to an asset source file.
AssetPath::label: An optional “named sub asset”. When assets are loaded, they are allowed to load “sub assets” of any type, which are identified by a named “label”.

Asset paths are generally constructed (and visualized) as strings:

// This loads the `my_scene.scn` base asset from the default asset source.
let scene: Handle<Scene> = asset_server.load("my_scene.scn");

// This loads the `PlayerMesh` labeled asset from the `my_scene.scn` base asset in the default asset source.
let mesh: Handle<Mesh> = asset_server.load("my_scene.scn#PlayerMesh");

// This loads the `my_scene.scn` base asset from a custom 'remote' asset source.
let scene: Handle<Scene> = asset_server.load("remote://my_scene.scn");

AssetPath implements From for &'static str, &'static Path, and &'a String, which allows us to optimize the static cases. This means that the common case of asset_server.load("my_scene.scn") when it creates and clones internal owned AssetPaths. This also means that you should use AssetPath::parse in cases where &str is the explicit type.

Implementations§

§

impl<'a> AssetPath<'a>

pub fn parse(asset_path: &'a str) -> AssetPath<'a>

Creates a new AssetPath from a string in the asset path format:

An asset at the root: "scene.gltf"
An asset nested in some folders: "some/path/scene.gltf"
An asset with a “label”: "some/path/scene.gltf#Mesh0"
An asset with a custom “source”: "custom://some/path/scene.gltf#Mesh0"

Prefer [From<'static str>] for static strings, as this will prevent allocations and reference counting for AssetPath::into_owned.

§Panics

Panics if the asset path is in an invalid format. Use AssetPath::try_parse for a fallible variant

pub fn try_parse( asset_path: &'a str ) -> Result<AssetPath<'a>, ParseAssetPathError>

Creates a new AssetPath from a string in the asset path format:

An asset at the root: "scene.gltf"
An asset nested in some folders: "some/path/scene.gltf"
An asset with a “label”: "some/path/scene.gltf#Mesh0"
An asset with a custom “source”: "custom://some/path/scene.gltf#Mesh0"

Prefer [From<'static str>] for static strings, as this will prevent allocations and reference counting for AssetPath::into_owned.

This will return a ParseAssetPathError if asset_path is in an invalid format.

pub fn from_path(path: &'a Path) -> AssetPath<'a>

Creates a new AssetPath from a Path.

Examples found in repository ?

examples/asset/extra_source.rs (line 37)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2dBundle::default());

    // Now we can load the asset using our new asset source.
    //
    // The actual file path relative to workspace root is
    // "examples/asset/files/bevy_pixel_light.png".
    let path = Path::new("bevy_pixel_light.png");
    let source = AssetSourceId::from("example_files");
    let asset_path = AssetPath::from_path(path).with_source(source);

    // You could also parse this URL-like string representation for the asset
    // path.
    assert_eq!(asset_path, "example_files://bevy_pixel_light.png".into());

    commands.spawn(SpriteBundle {
        texture: asset_server.load(asset_path),
        ..default()
    });
}

More examples

Hide additional examples

examples/asset/embedded_asset.rs (line 40)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2dBundle::default());

    // Each example is its own crate (with name from [[example]] in Cargo.toml).
    let crate_name = "embedded_asset";

    // The actual file path relative to workspace root is
    // "examples/asset/files/bevy_pixel_light.png".
    //
    // We omit the "examples/asset" from the embedded_asset! call and replace it
    // with the crate name.
    let path = Path::new(crate_name).join("files/bevy_pixel_light.png");
    let source = AssetSourceId::from("embedded");
    let asset_path = AssetPath::from_path(&path).with_source(source);

    // You could also parse this URL-like string representation for the asset
    // path.
    assert_eq!(
        asset_path,
        "embedded://embedded_asset/files/bevy_pixel_light.png".into()
    );

    commands.spawn(SpriteBundle {
        texture: asset_server.load(asset_path),
        ..default()
    });
}

pub fn source(&self) -> &AssetSourceId<'_>

Gets the “asset source”, if one was defined. If none was defined, the default source will be used.

pub fn label(&self) -> Option<&str>

Gets the “sub-asset label”.

pub fn label_cow(&self) -> Option<CowArc<'a, str>>

Gets the “sub-asset label”.

pub fn path(&self) -> &Path

Gets the path to the asset in the “virtual filesystem”.

pub fn without_label(&self) -> AssetPath<'_>

Gets the path to the asset in the “virtual filesystem” without a label (if a label is currently set).

pub fn remove_label(&mut self)

Removes a “sub-asset label” from this AssetPath, if one was set.

pub fn take_label(&mut self) -> Option<CowArc<'a, str>>

Takes the “sub-asset label” from this AssetPath, if one was set.

pub fn with_label(self, label: impl Into<CowArc<'a, str>>) -> AssetPath<'a>

Returns this asset path with the given label. This will replace the previous label if it exists.

pub fn with_source(self, source: impl Into<AssetSourceId<'a>>) -> AssetPath<'a>

Returns this asset path with the given asset source. This will replace the previous asset source if it exists.

Examples found in repository ?

examples/asset/extra_source.rs (line 37)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2dBundle::default());

    // Now we can load the asset using our new asset source.
    //
    // The actual file path relative to workspace root is
    // "examples/asset/files/bevy_pixel_light.png".
    let path = Path::new("bevy_pixel_light.png");
    let source = AssetSourceId::from("example_files");
    let asset_path = AssetPath::from_path(path).with_source(source);

    // You could also parse this URL-like string representation for the asset
    // path.
    assert_eq!(asset_path, "example_files://bevy_pixel_light.png".into());

    commands.spawn(SpriteBundle {
        texture: asset_server.load(asset_path),
        ..default()
    });
}

More examples

Hide additional examples

examples/asset/embedded_asset.rs (line 40)

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2dBundle::default());

    // Each example is its own crate (with name from [[example]] in Cargo.toml).
    let crate_name = "embedded_asset";

    // The actual file path relative to workspace root is
    // "examples/asset/files/bevy_pixel_light.png".
    //
    // We omit the "examples/asset" from the embedded_asset! call and replace it
    // with the crate name.
    let path = Path::new(crate_name).join("files/bevy_pixel_light.png");
    let source = AssetSourceId::from("embedded");
    let asset_path = AssetPath::from_path(&path).with_source(source);

    // You could also parse this URL-like string representation for the asset
    // path.
    assert_eq!(
        asset_path,
        "embedded://embedded_asset/files/bevy_pixel_light.png".into()
    );

    commands.spawn(SpriteBundle {
        texture: asset_server.load(asset_path),
        ..default()
    });
}

pub fn parent(&self) -> Option<AssetPath<'a>>

Returns an AssetPath for the parent folder of this path, if there is a parent folder in the path.

pub fn into_owned(self) -> AssetPath<'static>

Converts this into an “owned” value. If internally a value is borrowed, it will be cloned into an “owned Arc”. If internally a value is a static reference, the static reference will be used unchanged. If internally a value is an “owned Arc”, it will remain unchanged.

pub fn clone_owned(&self) -> AssetPath<'static>

Clones this into an “owned” value. If internally a value is borrowed, it will be cloned into an “owned Arc”. If internally a value is a static reference, the static reference will be used unchanged. If internally a value is an “owned Arc”, the Arc will be cloned.

pub fn resolve( &self, path: &str ) -> Result<AssetPath<'static>, ParseAssetPathError>

Resolves a relative asset path via concatenation. The result will be an AssetPath which is resolved relative to this “base” path.

assert_eq!(AssetPath::parse("a/b").resolve("c"), Ok(AssetPath::parse("a/b/c")));
assert_eq!(AssetPath::parse("a/b").resolve("./c"), Ok(AssetPath::parse("a/b/c")));
assert_eq!(AssetPath::parse("a/b").resolve("../c"), Ok(AssetPath::parse("a/c")));
assert_eq!(AssetPath::parse("a/b").resolve("c.png"), Ok(AssetPath::parse("a/b/c.png")));
assert_eq!(AssetPath::parse("a/b").resolve("/c"), Ok(AssetPath::parse("c")));
assert_eq!(AssetPath::parse("a/b.png").resolve("#c"), Ok(AssetPath::parse("a/b.png#c")));
assert_eq!(AssetPath::parse("a/b.png#c").resolve("#d"), Ok(AssetPath::parse("a/b.png#d")));

There are several cases:

If the path argument begins with #, then it is considered an asset label, in which case the result is the base path with the label portion replaced.

If the path argument begins with ‘/’, then it is considered a ‘full’ path, in which case the result is a new AssetPath consisting of the base path asset source (if there is one) with the path and label portions of the relative path. Note that a ‘full’ asset path is still relative to the asset source root, and not necessarily an absolute filesystem path.

If the path argument begins with an asset source (ex: http://) then the entire base path is replaced - the result is the source, path and label (if any) of the path argument.

Otherwise, the path argument is considered a relative path. The result is concatenated using the following algorithm:

The base path and the path argument are concatenated.
Path elements consisting of “/.” or “<name>/..” are removed.

If there are insufficient segments in the base path to match the “..” segments, then any left-over “..” segments are left as-is.

pub fn resolve_embed( &self, path: &str ) -> Result<AssetPath<'static>, ParseAssetPathError>

Resolves an embedded asset path via concatenation. The result will be an AssetPath which is resolved relative to this path. This is similar in operation to resolve, except that the ‘file’ portion of the base path (that is, any characters after the last ‘/’) is removed before concatenation, in accordance with the behavior specified in IETF RFC 1808 “Relative URIs”.

The reason for this behavior is that embedded URIs which start with “./” or “../” are relative to the directory containing the asset, not the asset file. This is consistent with the behavior of URIs in JavaScript, CSS, HTML and other web file formats. The primary use case for this method is resolving relative paths embedded within asset files, which are relative to the asset in which they are contained.

assert_eq!(AssetPath::parse("a/b").resolve_embed("c"), Ok(AssetPath::parse("a/c")));
assert_eq!(AssetPath::parse("a/b").resolve_embed("./c"), Ok(AssetPath::parse("a/c")));
assert_eq!(AssetPath::parse("a/b").resolve_embed("../c"), Ok(AssetPath::parse("c")));
assert_eq!(AssetPath::parse("a/b").resolve_embed("c.png"), Ok(AssetPath::parse("a/c.png")));
assert_eq!(AssetPath::parse("a/b").resolve_embed("/c"), Ok(AssetPath::parse("c")));
assert_eq!(AssetPath::parse("a/b.png").resolve_embed("#c"), Ok(AssetPath::parse("a/b.png#c")));
assert_eq!(AssetPath::parse("a/b.png#c").resolve_embed("#d"), Ok(AssetPath::parse("a/b.png#d")));