Struct bevy::asset::AssetPath

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

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/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/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("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/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/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/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("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/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 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")));

pub fn get_full_extension(&self) -> Option<String>

Returns the full extension (including multiple ‘.’ values). Ex: Returns "config.ron" for "my_asset.config.ron"

Trait Implementations

impl<'a> Clone for AssetPath<'a>

fn clone(&self) -> AssetPath<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for AssetPath<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a> Default for AssetPath<'a>

fn default() -> AssetPath<'a>

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AssetPath<'static>

fn deserialize<D>( deserializer: D ) -> Result<AssetPath<'static>, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'a> Display for AssetPath<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a, 'b> From<&'a AssetPath<'b>> for AssetPath<'b>

fn from(value: &'a AssetPath<'b>) -> AssetPath<'b>

Converts to this type from the input type.

impl From<&'static Path> for AssetPath<'static>

fn from(path: &'static Path) -> AssetPath<'static>

Converts to this type from the input type.

impl<'a> From<&'a String> for AssetPath<'a>

fn from(asset_path: &'a String) -> AssetPath<'a>

Converts to this type from the input type.

impl From<&'static str> for AssetPath<'static>

fn from(asset_path: &'static str) -> AssetPath<'static>

Converts to this type from the input type.

impl<'a> From<AssetPath<'a>> for PathBuf

fn from(value: AssetPath<'a>) -> PathBuf

Converts to this type from the input type.

impl From<AssetPath<'static>> for ShaderRef

fn from(path: AssetPath<'static>) -> ShaderRef

Converts to this type from the input type.

impl From<PathBuf> for AssetPath<'static>

fn from(path: PathBuf) -> AssetPath<'static>

Converts to this type from the input type.

impl From<String> for AssetPath<'static>

fn from(asset_path: String) -> AssetPath<'static>

Converts to this type from the input type.

impl FromReflect for AssetPath<'static>

fn from_reflect(reflect: &(dyn Reflect + 'static)) -> Option<AssetPath<'static>>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn Reflect> ) -> Result<Self, Box<dyn Reflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl GetTypeRegistration for AssetPath<'static>

fn get_type_registration() -> TypeRegistration

impl<'a> Hash for AssetPath<'a>

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for AssetPath<'a>

fn eq(&self, other: &AssetPath<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Reflect for AssetPath<'static>

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn into_any(self: Box<AssetPath<'static>>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &(dyn Any + 'static)

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<AssetPath<'static>>) -> Box<dyn Reflect>

Casts this type to a boxed reflected value.

fn as_reflect(&self) -> &(dyn Reflect + 'static)

Casts this type to a reflected value.

fn as_reflect_mut(&mut self) -> &mut (dyn Reflect + 'static)

Casts this type to a mutable reflected value.

fn apply(&mut self, value: &(dyn Reflect + 'static))

Applies a reflected value to this value.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<AssetPath<'static>>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn clone_value(&self) -> Box<dyn Reflect>

Clones the value as a Reflect trait object.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn reflect_partial_eq(&self, value: &(dyn Reflect + 'static)) -> Option<bool>

Returns a “partial equality” comparison result.

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug formatter for the value.

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<'a> Serialize for AssetPath<'a>

fn serialize<S>( &self, serializer: S ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TypePath for AssetPath<'static>

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl Typed for AssetPath<'static>

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<'a> Eq for AssetPath<'a>

impl<'a> StructuralPartialEq for AssetPath<'a>