Skip to content

Game.Citizens.TripNeeded

Assembly: Assembly-CSharp
Namespace: Game.Citizens

Type: public struct

Base: System.ValueType, implements Unity.Entities.IBufferElementData, Colossal.Serialization.Entities.ISerializable

Summary:
Represents a single trip requirement for a citizen agent in the ECS world. TripNeeded is a buffer element (IBufferElementData) intended to be stored in an entity buffer to describe a planned trip: the target agent/entity, the purpose of the trip, an integer data field for purpose-specific metadata, and the resource type associated with the trip. The struct implements custom serialization via ISerializable to persist/restore its fields and to maintain compatibility across engine/data-version changes (notably the resource 32-bit fix).

Fields

  • public Entity m_TargetAgent
    Refers to the agent/entity that is the destination or target of the trip. Stored as a Unity.Entities.Entity handle.

  • public Purpose m_Purpose
    An enum value describing why the trip exists (the trip's purpose). The enum is serialized as a single byte.

  • public int m_Data
    Purpose-specific integer data. Its meaning depends on the trip purpose (e.g., counts, identifiers, or other metadata required by the purpose).

  • public Resource m_Resource
    Resource type associated with the trip. During serialization this is written via EconomyUtils.GetResourceIndex and serialized as a small integer type; during deserialization the code handles older and newer save formats for compatibility.

Properties

  • None (no C# properties are declared in this struct).

Constructors

  • Implicit default constructor (value-type default).
    No explicit constructors are defined in the source: the struct uses the compiler-generated parameterless constructor and fields are expected to be set directly.

Methods

  • public void Serialize<TWriter>(TWriter writer) where TWriter : IWriter
    Writes the struct to the provided writer in the following order:
  • m_TargetAgent (Entity)
  • m_Purpose cast to byte
  • m_Data (int)
  • m_Resource as an sbyte index produced by EconomyUtils.GetResourceIndex

The resource is saved as a small signed integer (sbyte) to conserve space; the implementation relies on EconomyUtils to map Resource enum to a compact index.

  • public void Deserialize<TReader>(TReader reader) where TReader : IReader
    Reads fields back from the reader in the same order they were written. For the resource field this method checks the reader.context.version to preserve backward compatibility:
  • If reader.context.version >= Version.resource32bitFix, the resource index is read as an sbyte and converted back to a Resource via EconomyUtils.GetResource.
  • Otherwise (older save versions), the resource was stored as an int and is cast directly to Resource.

This conditional logic ensures older saved data (pre resource32bitFix) can still be loaded correctly.

Usage Example

// Example: creating and populating a TripNeeded buffer element and adding it to an entity buffer.
var trip = new Game.Citizens.TripNeeded
{
    m_TargetAgent = destinationEntity,
    m_Purpose = Purpose.Commute, // example enum value
    m_Data = 0,                  // purpose-specific metadata
    m_Resource = Resource.None   // example resource enum
};

// Add to an entity buffer (pseudo-code; requires an EntityManager and a valid entity)
var buffer = entityManager.AddBuffer<Game.Citizens.TripNeeded>(agentEntity);
buffer.Add(trip);

// Serialization is handled automatically by the game's save system using the ISerializable methods.
// The Deserialize implementation handles old save formats by checking reader.context.version.

Notes: - Purpose and Resource are enums defined elsewhere (Game.Economy namespace). EconomyUtils provides mapping helpers: GetResourceIndex(Resource) for serialization and GetResource(sbyte) for deserialization. - Because TripNeeded is an IBufferElementData, it should be used with DynamicBuffer on entities for storing multiple planned trips.