Resources: loading and independent copies

Entity and Resource

An Entity belongs to a hierarchy and receives lifecycle callbacks. A Resource stores data: a material, mesh, texture, sound or a packed hierarchy such as PackedEntity. A resource itself is not added to the tree with AddChild().

Not every file is a Resource: read arbitrary JSON or text with a file API. asset:// addresses the project, while user:// addresses writable user data.

Loading and caching

ResourceLoader.Load(path) obtains a resource synchronously. Its default CacheMode.Reuse can return an existing cached resource. While a resource remains in use, loading it again does not guarantee an independent copy. Other cache modes change this behavior; select them deliberately.

Load<T>() casts the result: an incompatible loaded resource throws InvalidCastException. For external or user-selected paths, load without a generic argument and test with is. Check failure before accessing properties; an existing file does not prove the correct resource type.

Loading a PackedEntity does not create game objects. That requires Instantiate() and AddChild(). Several prefab instances can reference the same material.

Give one object an independent color

Use a MeshInstance3D with a mesh and StandardMaterial3D on surface 0. A BoxMesh with a material assigned is sufficient. Attach IndependentTint.cs:

using Reckfell;

public partial class IndependentTint : MeshInstance3D
{
    [Export] public Color Tint { get; set; } = new Color(0.2f, 0.5f, 1.0f);

    public override void _Ready()
    {
        if (Mesh == null || Mesh.GetSurfaceCount() == 0 ||
            GetActiveMaterial(0) is not StandardMaterial3D shared)
        {
            ReckfellApi.PushWarning("Assign a mesh with a StandardMaterial3D on surface 0.");
            return;
        }

        var unique = (StandardMaterial3D)shared.Duplicate();
        unique.AlbedoColor = Tint;
        SetSurfaceOverrideMaterial(0, unique);
    }
}

After building and running, only this instance changes color. The source material remains unchanged. This duplicates the material itself; textures and other nested resources can remain shared. Duplicate(true) and individual property flags have additional rules, so do not assume every copy is a completely independent data graph.

A resource per prefab instance

Setting ResourceLocalToScene = true in a template before instantiation allows the engine to localize that resource during PackedEntity.Instantiate(). Enabling it on an already used resource does not retroactively create separate materials for existing objects. For an explicit local change, duplicate the resource and assign it to the intended instance.

For large loads, see ResourceLoader.LoadThreadedRequest() and its status checks. Background resource reading does not make arbitrary tree mutations thread-safe: create and attach game entities on the main thread.

If every object changes color, look for a shared resource. If code changes the mesh's material rather than one object, use a MeshInstance3D material override as above. See Resource and ResourceLoader.