Skip to content

Game.Creatures.AnimalNavigation

Assembly: Assembly-CSharp
Namespace: Game.Creatures

Type: struct

Base: IComponentData, IQueryTypeParameter, ISerializable

Summary: AnimalNavigation is an ECS component that stores navigation and movement-related state for a creature/animal. It holds the current target position and direction, maximum movement speed, transform-related state, and activity indices used by creature animation/behavior systems. The component implements Colossal's serialization interfaces so it can be written to and read from saved data, with backward compatibility guarded by version checks.

Fields

  • public float3 m_TargetPosition Represents the world-space position the animal is trying to reach. Used by movement/pathing systems to steer the creature.

  • public float3 m_TargetDirection A normalized (or raw) direction vector indicating the desired direction of travel toward the target. Presence of this field is gated by save versions (see Deserialize).

  • public float m_MaxSpeed Maximum speed the animal should move at. Systems that update velocity or animation can use this to cap movement.

  • public TransformState m_TransformState Stores transform/animation state for the creature. The value is serialized as a byte and mapped back to the TransformState enum on deserialization.

  • public byte m_LastActivity Index/code of the last activity/animation the creature performed. Serialized for restoring animation/activity state.

  • public byte m_TargetActivity Index/code of the currently intended/target activity. Presence of this field in saved data is gated by save versions (see Deserialize).

Properties

  • None.
    AnimalNavigation exposes only public fields and no C# properties.

Constructors

  • public AnimalNavigation(float3 position)
    Initializes a new AnimalNavigation with a target position. Sets:
  • m_TargetPosition = position
  • m_TargetDirection = default(float3) (zero)
  • m_MaxSpeed = 0f
  • m_TransformState = TransformState.Default
  • m_LastActivity = 0
  • m_TargetActivity = 0

This constructor is typically used to spawn or reset navigation state for a creature.

Methods

  • public void Serialize<TWriter>(TWriter writer) where TWriter : IWriter
    Writes the fields to the provided writer in this order:
  • m_TargetPosition (float3)
  • m_TargetDirection (float3)
  • m_TargetActivity (byte)
  • m_TransformState (as byte)
  • m_LastActivity (byte)
  • m_MaxSpeed (float)

The method relies on the writer to persist primitive and struct types (float3, byte, float). It writes transform state as a single byte cast from the enum.

  • public void Deserialize<TReader>(TReader reader) where TReader : IReader
    Reads fields from the provided reader. The method uses reader.context.version checks to remain backward-compatible with older save formats:
  • Always reads m_TargetPosition.
  • If reader.context.version >= Version.creatureTargetDirection, reads m_TargetDirection.
  • If reader.context.version >= Version.creatureTargetDirection2, reads m_TargetActivity.
  • If reader.context.version >= Version.animationStateFix:
    • Reads a byte into a temporary value (transform state value saved in newer versions).
    • Reads m_LastActivity.
    • Sets m_TransformState = (TransformState)value. For older versions the transform state and last activity are handled in a compatible manner.
  • Always reads m_MaxSpeed as the last step.

Generic constraints require TReader to implement IReader; the method reads into the component's fields by reference.

Notes: - The version checks reference symbols such as Version.creatureTargetDirection, Version.creatureTargetDirection2, and Version.animationStateFix; these determine presence/ordering of fields in different save versions and ensure safe loading of older saves. - The Deserialize method uses ref locals to read directly into fields.

Usage Example

// Create a new AnimalNavigation with a target position
var nav = new AnimalNavigation(new float3(100f, 0f, 200f));
nav.m_MaxSpeed = 2.5f;
nav.m_TargetActivity = 1; // set desired activity index

// Example: serializing (writer type provided by engine/mod API)
myWriter.Write(nav.m_TargetPosition);
myWriter.Write(nav.m_TargetDirection);
myWriter.Write(nav.m_TargetActivity);
myWriter.Write((byte)nav.m_TransformState);
myWriter.Write(nav.m_LastActivity);
myWriter.Write(nav.m_MaxSpeed);

// Example: deserializing (reader/context provided by engine/mod API)
AnimalNavigation loadedNav = default;
reader.Read(out loadedNav.m_TargetPosition);
if (reader.context.version >= Version.creatureTargetDirection)
    reader.Read(out loadedNav.m_TargetDirection);
if (reader.context.version >= Version.creatureTargetDirection2)
    reader.Read(out loadedNav.m_TargetActivity);
if (reader.context.version >= Version.animationStateFix)
{
    reader.Read(out byte transformValue);
    reader.Read(out loadedNav.m_LastActivity);
    loadedNav.m_TransformState = (TransformState)transformValue;
}
reader.Read(out loadedNav.m_MaxSpeed);

// The component can then be added to an entity in an ECS system:
entityManager.AddComponentData(entity, loadedNav);

{{ Additional notes: - Intended use: attach to creature entities in ECS and read/update from Creature/Movement systems. - Interactions: TransformState and activity bytes are used by animation/behavior systems; changing them may affect how the creature animates or which behaviors it performs. - Serialization order matters for compatibility; do not reorder writes without updating versioning accordingly. }}