Skip to content

Game.Relative

Assembly:
(assembly not specified in file; typically the game's main assembly or mod assembly)

Namespace: Game.Objects

Type: struct

Base: IComponentData, IQueryTypeParameter, ISerializable

Summary: Represents a local transform (position + rotation) stored as an ECS component, with an associated bone index for objects that may be attached to a skeleton/bone. Contains helper methods to convert to a Transform and to serialize/deserialize the component to the game's binary format. The bone index is stored in an int3, but only the x component is written/read for older versions — y and z are initialized to -1 when deserializing to maintain compatibility.

Fields

  • public float3 m_Position Holds the local position of the object in float3 (Unity.Mathematics). Used to reconstruct a Transform via ToTransform().

  • public quaternion m_Rotation Holds the local rotation (quaternion) of the object.

  • public int3 m_BoneIndex Holds bone index data as an int3. Serialization only writes the x component (the primary bone index). During deserialization, if the save version predates multi-component bone support, y and z are explicitly set to -1 to indicate "unused".

Properties

  • (none)

Constructors

  • public Relative(Transform localTransform, int3 boneIndex) Creates a Relative from a Transform (local position/rotation) and an int3 bone index. Copies localTransform.m_Position and localTransform.m_Rotation into the component.

Methods

  • public Transform ToTransform() : Transform Returns a new Transform constructed from the component's m_Position and m_Rotation. Useful for converting the component back to the engine Transform representation.

  • public void Serialize<TWriter>(TWriter writer) where TWriter : IWriter Writes the component data to the provided writer. The code writes:

  • m_Position (float3)
  • m_Rotation (quaternion)

  • m_BoneIndex.x (int) This mirrors the persisted format expected by the game.

  • public void Deserialize<TReader>(TReader reader) where TReader : IReader Reads component data from the provided reader. The deserialization logic:

  • Reads m_Position (float3)
  • Reads m_Rotation (quaternion)
  • If reader.context.version >= Version.boneRelativeObjects, reads m_BoneIndex.x (int)
  • Sets m_BoneIndex.y and m_BoneIndex.z to -1 to ensure a defined state for those components (compatibility for versions that do not store them)

Notes: - The generic Serialize/Deserialize signatures use writer/reader types constrained to IWriter/IReader respectively to integrate with Colossal.Serialization.Entities. - The version check relies on a Version enum/constant defined elsewhere (Version.boneRelativeObjects) to support backward/forward compatibility of save data.

Usage Example

// Creating a Relative from an existing Transform and a bone index
Transform local = new Transform(new float3(1f, 2f, 3f), quaternion.identity);
int3 boneIndex = new int3(5, -1, -1);
Relative rel = new Relative(local, boneIndex);

// Convert back to a Transform when needed
Transform t = rel.ToTransform();

// Serialization (pseudo usage — depends on game's writer implementation)
writer.Write(rel); // or rel.Serialize(writer) depending on helper methods

// Deserialization (pseudo usage)
Relative loaded = default;
reader.Read(out loaded); // or loaded.Deserialize(reader)

Additional implementation notes: - This struct implements IComponentData, so it can be attached to entities in Unity's ECS (DOTS) world. - It also implements IQueryTypeParameter, making it usable as a parameter/selector type in query APIs where supported. - When modifying serialization format (e.g., extending bone index storage), update the Version checks accordingly to keep backward compatibility.