Struct 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_buf(path_buf: PathBuf) -> AssetPath<'a>

Creates a new AssetPath from a PathBuf.

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

Creates a new AssetPath from a Path.

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.

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: &AssetPath<'_>) -> AssetPath<'static>

Resolves an AssetPath relative to self.

Semantics:

• If path is label-only (default source, empty path, label set), replace self’s label.
• If path begins with /, treat it as rooted at the asset-source root (not the filesystem).
• If path has an explicit source (name://...), it replaces the base source.
• Relative segments are concatenated and normalized (./.. removal), preserving extra .. if the base underflows.

let base = AssetPath::parse("a/b");
assert_eq!(base.resolve(&AssetPath::parse("c")), AssetPath::parse("a/b/c"));
assert_eq!(base.resolve(&AssetPath::parse("./c")), AssetPath::parse("a/b/c"));
assert_eq!(base.resolve(&AssetPath::parse("../c")), AssetPath::parse("a/c"));
assert_eq!(base.resolve(&AssetPath::parse("c.png")), AssetPath::parse("a/b/c.png"));
assert_eq!(base.resolve(&AssetPath::parse("/c")), AssetPath::parse("c"));
assert_eq!(AssetPath::parse("a/b.png").resolve(&AssetPath::parse("#c")), AssetPath::parse("a/b.png#c"));
assert_eq!(AssetPath::parse("a/b.png#c").resolve(&AssetPath::parse("#d")), AssetPath::parse("a/b.png#d"));

See also AssetPath::resolve_str.

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

Resolves an AssetPath relative to self using embedded (RFC 1808) semantics.

Semantics:

• Remove the “file portion” of the base before concatenation (unless the base ends with /).
• Otherwise identical to AssetPath::resolve.

let base = AssetPath::parse("a/b");
assert_eq!(base.resolve_embed(&AssetPath::parse("c")), AssetPath::parse("a/c"));
assert_eq!(base.resolve_embed(&AssetPath::parse("./c")), AssetPath::parse("a/c"));
assert_eq!(base.resolve_embed(&AssetPath::parse("../c")), AssetPath::parse("c"));
assert_eq!(base.resolve_embed(&AssetPath::parse("c.png")), AssetPath::parse("a/c.png"));
assert_eq!(base.resolve_embed(&AssetPath::parse("/c")), AssetPath::parse("c"));
assert_eq!(AssetPath::parse("a/b.png").resolve_embed(&AssetPath::parse("#c")), AssetPath::parse("a/b.png#c"));
assert_eq!(AssetPath::parse("a/b.png#c").resolve_embed(&AssetPath::parse("#d")), AssetPath::parse("a/b.png#d"));

See also AssetPath::resolve_embed_str.

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

Parses path as an AssetPath, then resolves it relative to self.

Returns an error if parsing fails.

For more details, see AssetPath::resolve.

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

Parses path as an AssetPath, then resolves it relative to self using embedded (RFC 1808) semantics.

Returns an error if parsing fails.

For more details, see AssetPath::resolve_embed.

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

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

Also strips out anything following a ? to handle query parameters in URIs

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

Returns the extension, excluding multiple . values.

Ex: Returns "ron" for "my_asset.config.ron"

Also strips out anything follow a ? to handle query parameters in URIs.

pub fn is_unapproved(&self) -> bool

Returns true if this AssetPath points to a file that is outside of its AssetSource folder.

Example

// Inside the default AssetSource.
let path = AssetPath::parse("thingy.png");
assert!( ! path.is_unapproved());
let path = AssetPath::parse("gui/thingy.png");
assert!( ! path.is_unapproved());

// Inside a different AssetSource.
let path = AssetPath::parse("embedded://thingy.png");
assert!( ! path.is_unapproved());

// Exits the `AssetSource`s directory.
let path = AssetPath::parse("../thingy.png");
assert!(path.is_unapproved());
let path = AssetPath::parse("folder/../../thingy.png");
assert!(path.is_unapproved());

// This references the linux root directory.
let path = AssetPath::parse("/home/thingy.png");
assert!(path.is_unapproved());

Trait Implementations

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

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

Returns a duplicate 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

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<Self, D::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

Formats the value using the given formatter.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<PathBuf> for AssetPath<'static>

fn from(path: PathBuf) -> Self

Converts to this type from the input type.

impl From<String> for AssetPath<'static>

fn from(asset_path: String) -> Self

Converts to this type from the input type.

impl<'a> FromReflect for AssetPath<'a>

where AssetPath<'a>: 'static,

fn from_reflect(reflect: &dyn PartialReflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

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

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

impl<'a> GetTypeRegistration for AssetPath<'a>

where AssetPath<'a>: 'static,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(_registry: &mut TypeRegistry)

Registers other types needed by this type.

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

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

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a> PartialReflect for AssetPath<'a>

where AssetPath<'a>: 'static,

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

Returns the TypeInfo of the type represented by this value.

fn to_dynamic(&self) -> Box<dyn PartialReflect>

Converts this reflected value into its dynamic representation based on its kind.

fn try_apply(&mut self, value: &dyn PartialReflect) -> Result<(), ApplyError>

Tries to apply 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<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn try_into_reflect( self: Box<Self>, ) -> Result<Box<dyn Reflect>, Box<dyn PartialReflect>>

Attempts to cast this type to a boxed, fully-reflected value.

fn try_as_reflect(&self) -> Option<&dyn Reflect>

Attempts to cast this type to a fully-reflected value.

fn try_as_reflect_mut(&mut self) -> Option<&mut dyn Reflect>

Attempts to cast this type to a mutable, fully-reflected value.

fn into_partial_reflect(self: Box<Self>) -> Box<dyn PartialReflect>

Casts this type to a boxed, reflected value.

fn as_partial_reflect(&self) -> &dyn PartialReflect

Casts this type to a reflected value.

fn as_partial_reflect_mut(&mut self) -> &mut dyn PartialReflect

Casts this type to a mutable, reflected value.

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

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

fn reflect_partial_eq(&self, value: &dyn PartialReflect) -> Option<bool>

Returns a “partial equality” comparison result.

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

Debug formatter for the value.

fn reflect_clone(&self) -> Result<Box<dyn Reflect>, ReflectCloneError>

Attempts to clone Self using reflection.

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

Applies a reflected value to this value.

fn reflect_clone_and_take<T>(&self) -> Result<T, ReflectCloneError>

where T: 'static, Self: Sized + TypePath,

For a type implementing PartialReflect, combines reflect_clone and take in a useful fashion, automatically constructing an appropriate ReflectCloneError if the downcast fails.

fn reflect_partial_cmp( &self, _value: &(dyn PartialReflect + 'static), ) -> Option<Ordering>

Returns a “partial comparison” result.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<'a> Reflect for AssetPath<'a>

where AssetPath<'a>: 'static,

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed, fully-reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a fully-reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable, fully-reflected 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.

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

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> TypePath for AssetPath<'a>

where AssetPath<'a>: '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<'a> Typed for AssetPath<'a>

where AssetPath<'a>: '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>