Краткое руководство
Если вы используете sourcegen для состояний компонентов (AutoGenerateComponentState / AutoNetworkField), то большая часть этого делается за вас.
Если вам нужно передать EntityUid по сети, вы должны вызвать GetNetEntity на стороне отправителя (обычно сервер) и TryGetEntity / EnsureEntity на стороне клиента. Если вы находитесь внутри состояния компонента, это должно быть EnsureEntity<TComp>, но если это сообщение, вы должны использовать TryGetEntity.
Существует вероятность, что клиент не сможет разрешить сущность (как и в любом решении PVS), отправленную через сообщение, поэтому, если вам нужна отказоустойчивость, используйте состояния компонентов или иным образом переработайте свой код.
Почему EntityUid и NetEntity различаются
У клиента и сервера могут быть разные сущности. Клиент создаёт свои собственные сущности для эффектов, таких как hitscan-лазеры, поднятие предметов и т.д.
Ранее мы помечали эту сущность 28-м битовым флагом, однако в целях производительности мы хотим размещать сущности в массиве, что потребовало бы значительного объёма памяти.
Таким образом, локальный EntityUid и сетевая версия будут естественным образом рассинхронизироваться, так как клиент и сервер имеют информацию о разных сущностях. Именно здесь вступает в игру NetEntity.
Миграция
Сеть
EntityUid больше не помечен как NetSerializable. При любой попытке сериализации NetSerializer теперь будет выбрасывать исключение.
Если вы хотите передать по сети EntityUid или EntityCoordinates, EntityManager содержит методы для этого:
- GetEntity
- GetNetEntity
- GetCoordinates
- GetNetCoordinates
- TryGetEntity
- TryGetNetEntity
- EnsureEntity<T> (где T — соответствующий компонент).
Также есть версии для HashSet и List. EntitySystems также имеют методы-прокси для них.
Вам следует избегать долгосрочного хранения NetEntity в компонентах и предпочитать использовать EntityUid. NetEntity также не сериализуется в yaml.
Если у вас есть существующая структура данных, которую трудно мигрировать (например, DoAfterEvents), то размещение как EntityUid DataField, так и NetEntity в событии (с пометкой EntityUid как NonSerialized) является подходящим промежуточным решением.
Команды
Команды должны быть обновлены для использования NetEntity, так как целые числа будут парситься как NetEntity, а не EntityUid.Последнее изменение 21 июня 2026 г.