EntityPath

public EntityPath();

Creates a distinct managed wrapper for an empty path. IsEmpty is true, ToString() returns "", IsAbsolute() is false and both component counts are zero. An empty path does not mean the current Entity: use "." for that.

public EntityPath(string path);

Parses /-separated Entity names and :-separated property or resource subnames. For example, "Rig/Sprite2D:position:x" has two Entity names and two subnames. A leading / marks an absolute path; . and .. mean the current Entity and its parent during lookup.

This only parses text: it does not find an Entity, verify a property or load a file. An empty string and, in the current SDK, null produce an empty path. A malformed sequence with an empty subname between colons produces native diagnostics; do not use the constructor as a user-input validator. In C#, use new EntityPath("Rig") or implicit string conversion: there is no ^"Rig" literal.

public bool IsEmpty { get; }

Tests whether native path data is absent. The empty constructor, "" and current null-input handling produce true. ".", "/" and ":position:x" are not empty. This does not test target existence or the managed reference: first ensure path is not null. Use GetEntityOrNull for an optional target.

public void Dispose();

Releases the wrapper’s owned native path, unregisters the resource and suppresses finalization. Other independently created wrappers for the same path remain usable. Does not delete the Entity addressed by the path.

Dispose your object once with using. In the current SDK, repeating Dispose() on a previously registered wrapper throws ArgumentException ("Disposable not registered"). Do not call Dispose() manually inside using, dispose borrowed wrappers or use a disposed object as a dictionary key.

public void Dispose(bool disposing);

Low-level overload: either flag value releases the native path and unregisters it. This method does not suppress finalization itself. Application code should use parameterless Dispose() or using: directly calling this overload can leave finalization scheduled for an already released resource. Repeated unregistration can throw ArgumentException.

public bool Equals(EntityPath? other);

Compares the absolute flag and all names and subnames, case-sensitively. Distinct wrappers for an equal path are equal. This does not compare resolved Entities: "Rig/../Sprite2D" and "Sprite2D" can address the same object but have different components. null differs even from an empty wrapper.

public override bool Equals(object? obj);

Compares with an EntityPath by parsed value; the same reference also matches. A string passed as object is not implicitly converted and does not equal the path; other types and null return false.

public EntityPath GetAsPropertyPath();

Returns a new wrapper for a property path. Entity names are joined with / into the first subname, followed by existing subnames; the result becomes relative. "position:x" becomes ":position:x", while "A/B:x" becomes ":A/B:x": it does not traverse separate A and B properties. The source path is unchanged.

An already pure property path keeps its value; an empty path stays empty. The returned wrapper is owned by the caller and needs its own using lifetime. This method only converts the path and does not read a property. In the example, ReadPositionX reads the current Entity2D position x; GetIndexed performs the read.

using Reckfell;

public static class EntityPathExamples
{
    public static string Describe()
    {
        using var path = new EntityPath("../Rig/Sprite2D:position:x");
        return $"{path.GetName(1)}|{path.GetConcatenatedSubNames()}|{path.GetNameCount()}|{path.GetSubNameCount()}";
        // Rig|position:x|3|2
    }

    public static float ReadPositionX(Entity2D target)
    {
        using var source = new EntityPath("position:x");
        using var property = source.GetAsPropertyPath();
        using var value = target.GetIndexed(property);
        return (float)value;
    }
}

public string GetConcatenatedNames();

Returns Entity names joined with / as a managed string. Excludes an absolute path’s leading / and everything after the first colon: "/root/Rig:position:x" yields "root/Rig". Does not modify or resolve the path. Check IsEmpty before calling on an empty EntityPath: the native method reports an error and returns an empty string.

public string GetConcatenatedSubNames();

Returns a managed string of subnames joined with :, without a leading colon. "Sprite2D:position:x" yields "position:x"; a nonempty path with no subnames yields "". The exact C# method name is GetConcatenatedSubNames. Check IsEmpty before calling on an empty path: the native implementation reports an error and returns an empty string.

public override int GetHashCode();

Returns the native hash of the parsed path, including names, subnames and the absolute flag. Equal paths have equal hashes and work as Dictionary<EntityPath, T> keys; a matching hash does not prove equality. This is not an Entity identifier or a guarantee of format stability across versions. Do not leave a disposed wrapper as a dictionary key.

public string GetName(int idx);

Reads one Entity name before the first colon. . and .. count as names too. Indices start at zero; valid range: 0 <= idx < GetNameCount(). An invalid index or empty path produces native diagnostics and an empty string rather than a guaranteed CLR exception. Check the range before calling.

public int GetNameCount();

Counts Entity names before the first colon. "../Rig/Sprite2D:position:x" yields 3; an absolute path’s leading / is not a name. An empty path returns 0. This counts path components, not found objects.

public string GetSubName(int idx);

Reads one subname after :, not an Entity name. Indices start at zero; valid range: 0 <= idx < GetSubNameCount(). An invalid index or empty path produces native diagnostics and an empty string rather than a guaranteed CLR exception. Check the range before calling.

public int GetSubNameCount();

Counts colon-separated subnames, excluding Entity names. "Rig/Sprite2D:position:x" yields 2. An empty path returns 0 without an indexed access.

public bool IsAbsolute();

Tests the parsed path’s leading-/ flag. true does not prove that a target exists. Absolute lookup requires the calling Entity to be in the active tree; its usual root Viewport is named root, hence "/root/...". "/" is a nonempty absolute path with no names, not a replacement for "/root".

public override string ToString();

Returns the parsed path representation: / for the absolute flag, /-joined names and colon-prefixed subnames. This is not an exact copy of the input: repeated /, a trailing / and a trailing empty : can disappear. . and .. are not automatically simplified. An empty path yields "". Does not validate a target or dispose the wrapper.

public static bool operator ==(EntityPath? left, EntityPath? right);

Compares parsed path values rather than managed references or lookup results. Two null references are equal; null differs from an existing empty EntityPath. Case, the absolute flag and subnames participate; . and .. are not simplified for equality.

public static implicit operator string(EntityPath? from);

Calls ToString() for an existing wrapper; null converts to null. An existing empty wrapper produces "", not null. Does not transfer ownership or dispose the path.

public static implicit operator EntityPath(string from);

Creates a new managed wrapper, equivalent to new EntityPath(from). This parses a path rather than finding an Entity. Use using for a locally created path; C# has no ^"path" literal.

public static bool operator !=(EntityPath? left, EntityPath? right);

Negates ==. Compares parsed path values rather than managed references or lookup results. Two null references are equal; null differs from an existing empty EntityPath. Case, the absolute flag and subnames participate; . and .. are not simplified for equality.