wave7-unity-object-ref-blittable-asset

UnityObjectRef — Blittable Asset Reference

Intent

Store a reference to a UnityEngine.Object (Texture2D, AudioClip, Mesh, Sprite, etc.) in a blittable struct IComponentData so it can be stored in ECS chunks and passed through job structs without making the component a class.

Use When

• A per-entity asset reference is needed in a struct component (sprite per unit, audio clip per entity, material override)
• The asset reference must be stored in chunk memory for cache-efficient access
• Asset identity must be carried through the ECS pipeline to a point-of-use on the main thread

Avoid When

• The asset reference is only needed on the main thread — AddComponentObject with class IComponentData is simpler
• Hot-path Burst code that dereferences the asset every frame — UnityObjectRef.Value access is main-thread only

Senior Pattern

public struct SpriteReference : IComponentData
{
    public UnityObjectRef<Sprite> Sprite;  // blittable (stores instance ID as int)
}

// Baker — implicit conversion from Sprite to UnityObjectRef<Sprite>:
public class SpriteReferenceBaker : Baker<SpriteReferenceAuthoring>
{
    public override void Bake(SpriteReferenceAuthoring authoring)
    {
        var entity = GetEntity(TransformUsageFlags.None);
        AddComponent(entity, new SpriteReference
        {
            Sprite = authoring.Sprite  // implicit conversion
        });
        DependsOn(authoring.Sprite);  // register asset dependency for incremental baking
    }
}

// Read asset identity in a job (blittable — safe to copy into job struct):
[BurstCompile]
public partial struct CategorizeJob : IJobEntity
{
    [BurstCompile]
    public void Execute(in SpriteReference spriteRef, ref RenderCategory category)
    {
        // UnityObjectRef carries instance ID — compare identity without dereferencing:
        category.IsHero = spriteRef.Sprite == heroSpriteRef;
    }
}

// Dereference to actual asset on main thread (point-of-use only):
[UpdateInGroup(typeof(PresentationSystemGroup))]
public partial class ApplySpriteSystem : SystemBase
{
    protected override void OnUpdate()
    {
        foreach (var (spriteRef, renderer) in
            SystemAPI.Query<RefRO<SpriteReference>, SpriteRenderer>())
        {
            renderer.sprite = spriteRef.ValueRO.Sprite.Value;  // main thread only
        }
    }
}