Struct AssetHandle 

pub struct AssetHandle<A: Asset> { /* private fields */ }

A typed handle to an asset of type A.

AssetHandle is the primary way to reference loaded assets. It provides:

• Type Safety: AssetHandle<Texture> and AssetHandle<Audio> are distinct types
• Generation Counting: Prevents use-after-free when assets are unloaded
• FFI Compatibility: Can be passed across language boundaries

Handle States

An asset handle can be in several states:

• Invalid: The sentinel value INVALID, representing “no asset”
• Valid but Loading: Points to an asset slot where loading is in progress
• Valid and Loaded: Points to a fully loaded, usable asset
• Stale: The asset was unloaded, handle generation no longer matches

Use AssetServer::get_state() to check the current state of an asset.

FFI Layout

Offset 0:  index      (u32, 4 bytes)
Offset 4:  generation (u32, 4 bytes)
Offset 8:  _marker    (PhantomData, 0 bytes)
Total:     8 bytes, alignment 4

Example

use goud_engine::assets::{Asset, AssetHandle};

struct Shader { /* ... */ }
impl Asset for Shader {}

// Create an invalid handle (default)
let handle: AssetHandle<Shader> = AssetHandle::INVALID;
assert!(!handle.is_valid());

// Create a valid handle (normally done by AssetServer)
let handle: AssetHandle<Shader> = AssetHandle::new(42, 1);
assert!(handle.is_valid());
assert_eq!(handle.index(), 42);
assert_eq!(handle.generation(), 1);

Implementations

impl<A: Asset> AssetHandle<A>

pub const INVALID: Self

The invalid handle constant, representing “no asset”.

This is the default value for AssetHandle and is guaranteed to never match any valid asset handle.

Example

use goud_engine::assets::{Asset, AssetHandle};

struct Mesh;
impl Asset for Mesh {}

let handle: AssetHandle<Mesh> = AssetHandle::INVALID;
assert!(!handle.is_valid());
assert_eq!(handle.index(), u32::MAX);
assert_eq!(handle.generation(), 0);

pub const fn new(index: u32, generation: u32) -> Self

Creates a new asset handle with the given index and generation.

This is typically called by the asset system, not by user code.

Arguments

• index - Slot index in the asset storage
• generation - Generation counter for this slot

Example

use goud_engine::assets::{Asset, AssetHandle};

struct Audio;
impl Asset for Audio {}

let handle: AssetHandle<Audio> = AssetHandle::new(10, 3);
assert_eq!(handle.index(), 10);
assert_eq!(handle.generation(), 3);

pub const fn index(&self) -> u32

Returns the index component of this handle.

The index is the slot number in the asset storage array.

pub const fn generation(&self) -> u32

Returns the generation component of this handle.

The generation is incremented each time a slot is reused, preventing stale handles from accessing wrong assets.

pub const fn is_valid(&self) -> bool

Returns true if this handle is not the INVALID sentinel.

Note: A “valid” handle may still be stale if the asset was unloaded. Use AssetServer::is_alive() for definitive liveness checks.

Example

use goud_engine::assets::{Asset, AssetHandle};

struct Font;
impl Asset for Font {}

let valid: AssetHandle<Font> = AssetHandle::new(0, 1);
assert!(valid.is_valid());

let invalid: AssetHandle<Font> = AssetHandle::INVALID;
assert!(!invalid.is_valid());

pub fn untyped(&self) -> UntypedAssetHandle

Converts this handle to a type-erased UntypedAssetHandle.

The untyped handle preserves the asset type ID for runtime type checking.

Example

use goud_engine::assets::{Asset, AssetHandle, AssetId};

struct Texture;
impl Asset for Texture {}

let typed: AssetHandle<Texture> = AssetHandle::new(5, 2);
let untyped = typed.untyped();

assert_eq!(untyped.index(), 5);
assert_eq!(untyped.generation(), 2);
assert_eq!(untyped.asset_id(), AssetId::of::<Texture>());

pub const fn to_u64(&self) -> u64

Packs this handle into a single u64 value for FFI.

Format: upper 32 bits = generation, lower 32 bits = index.

Note: This does NOT preserve the asset type; use untyped() if you need type information across FFI boundaries.

pub const fn from_u64(packed: u64) -> Self

Creates a handle from a packed u64 value.

Format: upper 32 bits = generation, lower 32 bits = index.

pub fn asset_id() -> AssetId

Returns the asset type ID for this handle’s asset type.

This is a convenience method equivalent to AssetId::of::<A>().

pub fn asset_type() -> AssetType

Returns the asset type category for this handle’s asset type.

This is a convenience method equivalent to A::asset_type().

Trait Implementations

impl<A: Asset> Clone for AssetHandle<A>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<A: Asset> Debug for AssetHandle<A>

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

Formats the value using the given formatter.

impl<A: Asset> Default for AssetHandle<A>

fn default() -> Self

Returns AssetHandle::INVALID.

impl<A: Asset> Display for AssetHandle<A>

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

Formats the value using the given formatter.

impl<A: Asset> From<&AssetHandle<A>> for WeakAssetHandle<A>

fn from(handle: &AssetHandle<A>) -> Self

Converts to this type from the input type.

impl<A: Asset> From<AssetHandle<A>> for u64

fn from(handle: AssetHandle<A>) -> u64

Converts to this type from the input type.

impl<A: Asset> From<u64> for AssetHandle<A>

fn from(packed: u64) -> Self

Converts to this type from the input type.

impl<A: Asset> Hash for AssetHandle<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: Asset> Ord for AssetHandle<A>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<A: Asset> PartialEq for AssetHandle<A>

fn eq(&self, other: &Self) -> 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: Asset> PartialOrd for AssetHandle<A>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A: Asset> Copy for AssetHandle<A>

impl<A: Asset> Eq for AssetHandle<A>