Skip to content

Game.Pathfind.PathElement

Assembly: Game
Namespace: Game.Pathfind

Type: struct

Base: IBufferElementData, ISerializable

Summary:
Represents one element/node in a path buffer used by the game's pathfinding system. Stored as an ECS dynamic buffer element (InternalBufferCapacity(0)). Contains a target Entity, a compactly serialized 2D offset (m_TargetDelta), and a set of flags (PathElementFlags). Implements custom serialization/deserialization to minimize storage by encoding common delta values (0 and 1) into a single byte and only writing full floats when necessary.

Fields

  • public Entity m_Target
    The destination Entity referenced by this path element. Typically points to a path node or a relevant target entity in the pathfinding graph.

  • public float2 m_TargetDelta
    A small 2D offset (x,y) relative to the target entity. This value is compacted during serialization: the code encodes each component as one of three states — 0.0, 1.0, or "variable" (full float), and only writes the full float values if the component is variable.

  • public PathElementFlags m_Flags
    Bit flags describing properties of this path element (e.g., secondary, path start, action, return, reverse, wait position, leader, hangaround — exact meaning depends on PathElementFlags enum). Note: the constructor default value uses a bitwise complement to set a default combination (see Constructors). When deserializing older data (pre Version.taxiDispatchCenter) the flags byte is not present and m_Flags will remain the default zero/default enum value unless set elsewhere.

Properties

  • (none)

Constructors

  • public PathElement(Entity target, float2 targetDelta, PathElementFlags flags = ~(PathElementFlags.Secondary | PathElementFlags.PathStart | PathElementFlags.Action | PathElementFlags.Return | PathElementFlags.Reverse | PathElementFlags.WaitPosition | PathElementFlags.Leader | PathElementFlags.Hangaround))
    Creates a new PathElement with the provided target Entity, targetDelta offset, and flags. The default flags value is a bitwise negation of a set of specific flags — i.e., it sets all bits except the listed ones. Be careful: using a bitwise complement as a default can be surprising; ensure this matches expected semantics for your mod.

Methods

  • public void Serialize<TWriter>(TWriter writer) where TWriter : IWriter
    Serializes the PathElement into the provided writer. Format:
  • Write the target Entity.
  • Encode each component of m_TargetDelta into a 2-bit state:
    • 0 => exact 0.0 (no float written)
    • 1 => exact 1.0 (no float written)
    • 2 => variable (full float written)
  • Both component states are packed into a single byte (low nibble = x state, high nibble = y state) which is written next.
  • Write the actual float components for any component marked as variable (state == 2) in x/y order.

  • Finally write a single byte for m_Flags (no version gating on write). This compact encoding reduces serialized size when deltas are commonly 0 or 1.

  • public void Deserialize<TReader>(TReader reader) where TReader : IReader
    Deserializes a PathElement from the provided reader. Format:

  • Read the target Entity.
  • Read the single byte containing packed component states and reconstruct m_TargetDelta:
    • If state == 0, component = 0f
    • If state == 1, component = 1f
    • If state == 2, read a full float for that component
  • If reader.context.version >= Version.taxiDispatchCenter then read an extra byte and set m_Flags from it. (Older serialized data does not include flags; in that case m_Flags will remain the default/unset value.) Notes:
  • reader.context.version is consulted to maintain backward compatibility with older save/serialization formats.

Usage Example

// Create and append a PathElement to an entity's buffer
Entity target = /* obtain entity */;
float2 delta = new float2(0.5f, 1f);
PathElementFlags flags = /* set specific flags if needed */;

var buffer = entityManager.GetBuffer<PathElement>(parentEntity);
buffer.Add(new PathElement(target, delta, flags));

Additional notes: - The struct has [InternalBufferCapacity(0)], meaning no inline storage is reserved on the entity; the buffer will be dynamically allocated. - Serialize/Deserialize are intended for use with Colossal.Serialization (IWriter/IReader). When constructing or patching serialized data for compatibility, pay attention to the version gate around flags to avoid misinterpreting old formats.