Make asset handles unique per asset type

[waynemwashuma]

Objective

Introduces an enhancement to the asset management system by implementing generational asset handles. The changes prevent handle reuse issues and improve the robustness of asset referencing throughout the engine.

Note

The generational handle system prevents a class of bugs where stale handles could accidentally access newly created assets that reused the same index. This is particularly important for long-running applications where assets are frequently loaded and unloaded.

Solution

• Generational Handles: Added generation tracking to asset handles to prevent stale references from accessing recycled assets
• 64-bit Asset IDs: Implemented packing/unpacking of asset indices and generations into 64-bit integers.
• System Integration: Updated animation systems and asset management to work with the new generational handle system.
• Enhanced Safety: Added validation checks to ensure handles reference valid generations before accessing assets.

Key changes include:

• Modified AssetEntry to track generation counters.
• Updated Handle class to store and validate generations.
• Integrated packInto64Int and unpackFrom64Int functions for asset ID encoding.

Showcase

The new system automatically handles generation tracking, providing safer asset references:

Basic asset usage remains unchanged:

// Creating and using assets works the same as before
const handle = assets.add(new Texture());
const texture = assets.get(handle);

// Cloning handles maintains proper reference counting
const clonedHandle = handle.clone();

Asset ID encoding now includes generation information:

// Asset IDs now encode both index and generation
const assetId = handle.id(); // 64-bit number containing index and generation

// The system can unpack this information when needed
const [index, generation] = unpackFrom64Int(assetId);

Migration Guide

This update includes breaking changes to the internal asset ID system. Most users won't need to make changes unless they directly interact with asset IDs. For advanced users working with asset IDs:

• Use unpackFrom64Int() to extract index and generation from asset IDs
• When storing asset references externally, use the full asset ID rather than just the index
• Direct index-based asset lookups should be replaced with asset id based approaches

Example migration for custom systems:

// OLD: Direct index usage (no longer works)
const asset = assets.getByAssetId(rawIndex);

// NEW: Use handles or unpack asset IDs
const [index, generation] = unpackFrom64Int(assetId);
// Or better: use the handle system directly
const handle = assets.upgrade(assetId);
const asset = assets.get(handle);

Checklist

• My change requires a change to the documentation
• I have updated the documentation accordingly
• I have added tests to cover my changes (expanded test coverage for generation handling)