EntityPath

public EntityPath();

Создаёт отдельную управляемую оболочку пустого пути. IsEmpty равен true, ToString() возвращает "", IsAbsolute() — false; оба счётчика частей равны нулю. Пустой путь не означает текущую сущность: для неё используйте ".".

public EntityPath(string path);

Разбирает путь на имена сущностей через / и имена свойств или ресурсов через :. Например, "Rig/Sprite2D:position:x" содержит два имени сущностей и два подимени. Ведущий / отмечает абсолютный путь; . и .. обозначают текущую сущность и родителя при поиске.

Это только разбор текста: конструктор не ищет сущность, не проверяет наличие свойства и не загружает файл. Пустая строка и, в текущем SDK, null дают пустой путь. Ошибочная последовательность с пустым подименем между двоеточиями вызывает нативную диагностику; не используйте конструктор как валидатор пользовательского ввода. В C# используйте new EntityPath("Rig") или неявное преобразование из string: литерала ^"Rig" нет.

public bool IsEmpty { get; }

Проверяет отсутствие нативных данных пути. Пустой конструктор, "" и текущая обработка null дают true. ".", "/" и ":position:x" не пусты. Это не проверка существования цели и не проверка управляемой ссылки: сначала убедитесь, что path is not null. Для необязательной цели используйте GetEntityOrNull.

public void Dispose();

Освобождает принадлежащий оболочке нативный путь, снимает регистрацию ресурса и подавляет финализатор. Другие самостоятельно созданные оболочки того же пути продолжают работать. Это не удаляет сущность, на которую указывал путь.

Освобождайте свой объект один раз через using. В текущем SDK повторный Dispose() ранее зарегистрированной оболочки выбрасывает ArgumentException («Disposable not registered»). Не вызывайте Dispose() вручную внутри using, не освобождайте заимствованные оболочки и не используйте освобождённый объект как ключ словаря.

public void Dispose(bool disposing);

Низкоуровневая перегрузка: оба значения флага освобождают нативный путь и снимают регистрацию. Сам метод не подавляет финализатор. Для прикладного кода используйте Dispose() без аргумента или using: прямой вызов этой перегрузки может оставить финализатор уже освобождённого ресурса. Повторное снятие регистрации может выбросить ArgumentException.

public bool Equals(EntityPath? other);

Сравнивает признак абсолютности и все имена и подимена с учётом регистра. Разные оболочки равного пути равны. Это не сравнение найденных сущностей: "Rig/../Sprite2D" и "Sprite2D" могут указывать на один объект, но имеют разные части пути. null не равен даже пустой оболочке.

public override bool Equals(object? obj);

Сравнивает с EntityPath по разобранному значению; та же ссылка тоже равна. Строка, переданная как object, не преобразуется автоматически и не равна пути; другие типы и null дают false.

public EntityPath GetAsPropertyPath();

Возвращает новую оболочку пути к свойству. Имена сущностей объединяются через / в первое подимя, затем сохраняются существующие подимена; результат становится относительным. "position:x" превращается в ":position:x", а "A/B:x" — в ":A/B:x": это не обход двух свойств A и B. Исходный путь не меняется.

Уже чистый путь к свойству сохраняет значение; пустой путь остаётся пустым. Возвращённая оболочка принадлежит вызывающему коду и требует своего using. Метод только преобразует путь и не читает свойство. В примере ReadPositionX читает x текущей позиции Entity2D; чтение выполняет GetIndexed.

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();

Возвращает управляемую строку имён сущностей, соединённых через /. Начальный / абсолютного пути и часть после : не включаются: для "/root/Rig:position:x" результат — "root/Rig". Метод не меняет и не разрешает путь. Для пустого EntityPath сначала проверьте IsEmpty: нативный метод сообщает об ошибке и возвращает пустую строку.

public string GetConcatenatedSubNames();

Возвращает управляемую string из подимён, соединённых через :, без начального двоеточия. Для "Sprite2D:position:x" результат — "position:x"; у непустого пути без подимён — "". Точное C#-имя метода — GetConcatenatedSubNames. Перед вызовом на пустом пути проверьте IsEmpty: нативная реализация выдаёт ошибку и возвращает пустую строку.

public override int GetHashCode();

Возвращает нативный хеш разобранного пути с учётом имён, подимён и абсолютного признака. Равные пути имеют одинаковый хеш и подходят для Dictionary<EntityPath, T>; совпадение хеша не доказывает равенство. Это не идентификатор сущности и не обещание стабильности формата между версиями. Не оставляйте освобождённую оболочку ключом словаря.

public string GetName(int idx);

Читает одно имя сущности в части до первого :. . и .. тоже считаются именами. Индексация начинается с нуля; допустимо 0 <= idx < GetNameCount(). Неверный индекс или пустой путь приводят к нативной диагностике и пустой строке, а не к гарантированному CLR-исключению. Проверяйте диапазон до вызова.

public int GetNameCount();

Считает имена сущностей до первого двоеточия. "../Rig/Sprite2D:position:x" даёт 3; начальный / абсолютного пути не считается именем. У пустого пути возвращает 0. Это число частей пути, а не число найденных объектов.

public string GetSubName(int idx);

Читает одно подимя после :, не имя сущности. Индексация начинается с нуля; допустимо 0 <= idx < GetSubNameCount(). Неверный индекс или пустой путь приводят к нативной диагностике и пустой строке, а не к гарантированному CLR-исключению. Проверяйте диапазон до вызова.

public int GetSubNameCount();

Считает подимена после двоеточий, не включая имена сущностей. "Rig/Sprite2D:position:x" даёт 2. У пустого пути возвращает 0 без обращения по индексу.

public bool IsAbsolute();

Проверяет признак начального / в разобранном пути. Сам по себе true не доказывает существование цели. Для поиска абсолютного пути вызывающая сущность должна находиться в активном дереве; обычный корень Viewport имеет имя root, поэтому используется "/root/...". "/" — непустой абсолютный путь без имён; это не замена "/root".

public override string ToString();

Возвращает строковое представление разобранного пути: / для абсолютного признака, имена через / и подимена после :. Это не точная копия входа: повторные /, завершающий / и завершающее пустое : могут исчезнуть. . и .. автоматически не сокращаются. Пустой путь даёт "". Метод не проверяет цель и не освобождает оболочку.

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

Сравнивает разобранные значения путей, а не управляемые ссылки или результаты поиска. Две ссылки null равны; null и существующий пустой EntityPath различаются. Регистр, абсолютность и подимена участвуют в сравнении; . и .. для равенства не сокращаются.

public static implicit operator string(EntityPath? from);

Для существующей оболочки вызывает ToString(); null преобразуется в null. Пустая существующая оболочка даёт "", а не null. Преобразование не передаёт владение и не освобождает путь.

public static implicit operator EntityPath(string from);

Создаёт новую управляемую оболочку так же, как new EntityPath(from). Это разбор пути, а не поиск сущности. Для локально созданного пути используйте using; C# не поддерживает литерал ^"path".

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

Отрицает ==. Сравнивает разобранные значения путей, а не управляемые ссылки или результаты поиска. Две ссылки null равны; null и существующий пустой EntityPath различаются. Регистр, абсолютность и подимена участвуют в сравнении; . и .. для равенства не сокращаются.