ResourceUid

public static ResourceUidInstance Singleton { get; }

Заимствованный wrapper глобального сервиса движка. Повторное получение использует cached managed wrapper; не создаёт отдельный реестр. Не вызывайте Free()/Dispose() у этого engine-owned объекта. Для обычной работы используйте статические методы класса.

public static void AddId(long id, string path);

Добавляет ID→путь в реестр процесса; при включённом reverse cache добавляет и путь→ID. Не создаёт файл, не меняет его UID-заголовок и не переименовывает ассет. Повтор существующего ID отвергается с диагностикой. Передавайте собственный допустимый ID и точный путь; изменение таблицы не является подтверждённым сохранением cache на диск.

public static long CreateId();

Генерирует неотрицательный 63-битный кандидат, отсутствующий в текущем реестре. Не резервирует его, не вызывает AddId и не создаёт файл. При ошибке генератора возможен InvalidId. Получение ID не доказывает существование ассета; для собственной регистрации выполните отдельный AddId.

public static long CreateIdForPath(string path);

Создаёт кандидат по seed из имени проекта, пути в нижнем регистре и MD5 содержимого; занятые ID пропускаются. Не регистрирует значение и не создаёт файл. Повтор без регистрации дал тот же ID; после изменения содержимого/проекта/реестра это не гарантируется. Несуществующий путь тоже может дать допустимый кандидат, поэтому метод не является проверкой файла или стабильным content address.

public static string EnsurePath(string pathOrUid);

Если строка начинается с uid://, использует UidToPath(); иначе возвращает её без изменений, даже если файла нет. Не создаёт каталог, не проверяет права и не является полной валидацией входа. Неизвестный UID наследует диагностику/пустой результат UidToPath().

public static string GetIdPath(long id);

Получает зарегистрированный путь ID; файл при этом не открывается и не проверяется. Перед вызовом в runtime проверьте неотрицательный ID и HasId(). InvalidId/неизвестный ID может дать диагностику и пустую строку. Редакторные fallback/scan отличаются и здесь не выполнялись.

public static bool HasId(long id);

Проверяет наличие ключа в текущем реестре, не файла на диске и не актуальность обратной таблицы. После RemoveId() может быть false, хотя старый reverse path от предыдущего SetId остаётся; это проверено. Не является сканированием проекта или загрузкой ресурса.

public static string IdToText(long id);

Кодирует неотрицательный ID в строку uid://. Не проверяет регистрацию или наличие файла. Для любого отрицательного значения возвращает uid://<invalid>. Это кодирование ID, не создание новой регистрации или сериализация содержимого ассета.

public static string PathToUid(string path);

Запрашивает UID пути через ResourceLoader. В runtime используется reverse cache; если UID неизвестен, возвращается исходный путь, не InvalidId или обязательно пустая строка. Старый reverse path после SetId/RemoveId может дать текст UID уже без HasId(). Проверяйте тип результата и актуальную регистрацию; это не создание файла/UID.

public static void RemoveId(long id);

Удаляет ID и reverse-запись его текущего пути, не файл и не встроенный UID. Если SetId раньше оставил старый reverse path, RemoveId его не очищает; этот дефект воспроизведён. Отсутствующий ID даёт диагностику. Автоматическое сохранение/перестройка всего cache этой операцией не подтверждены.

public static void SetId(long id, string path);

Обновляет путь уже зарегистрированного ID, не перемещая файл. Ограничение 1.0.0: новый reverse path добавляется, но старый не удаляется; PathToUid(oldPath) может продолжать возвращать тот же UID. Это воспроизведено. Чтобы избежать этого при собственном runtime-обновлении, удалите старую регистрацию до добавления новой с тем же ID, вместо SetId; операции не атомарны. Отсутствующий ID даёт диагностику.

public static long TextToId(string textId);

Разбирает uid:// в неотрицательный ID либо InvalidId для отвергнутого ввода. Не является строгой проверкой канонического UID: пустой suffix uid:// даёт 0, переполнение не является отдельной диагностикой. Не проверяет реестр/файл. Для строгого входа сопоставьте канонический IdToText() и отдельно HasId().

public static string UidToPath(string uid);

Преобразует текст UID в ID и запрашивает зарегистрированный путь. Не ищет перемещённый файл автоматически. Для неизвестного/невалидного ID возможны диагностика и пустая строка; проверяйте TextToId()/HasId() перед runtime-вызовом. Полученный путь не доказывает существование файла.

public const long InvalidId = -1;

Константа -1, обозначающая отсутствие/недопустимость ID. Это не рабочий UID и не ключ для AddId/GetIdPath. Отрицательное значение IdToText() превращает в uid://<invalid>, а не в путь файла.