Skip to content

Game.TransportTrainCarriageSelectData

Assembly: Assembly-CSharp
Namespace: Game.Prefabs

Type: struct

Base: System.ValueType

Summary:
Utility data-structure used by game systems to find/select a cargo train carriage prefab that matches a requested resource type and cargo amount. It gathers prefab archetype chunks (prefabs with CargoTransportVehicleData + TrainCarriageData + PrefabData but not Locked), evaluates per-prefab requirements via VehicleSelectRequirementData, and performs a probabilistic selection weighted by simple discrete picks. The struct supports asynchronous chunk enumeration (ToArchetypeChunkListAsync) and requires matching PreUpdate/PostUpdate usage to manage the NativeList lifetime and job handles.

Fields

  • private NativeList<ArchetypeChunk> m_PrefabChunks
    Holds the list of prefab archetype chunks gathered from an EntityQuery. Populated by PreUpdate via query.ToArchetypeChunkListAsync(...) and must be disposed in PostUpdate (disposed with the supplied job handle).

  • private VehicleSelectRequirementData m_RequirementData
    Helper that encapsulates per-chunk requirement checks for vehicle prefabs (used to skip prefabs that don't meet required game-specific conditions). Updated each PreUpdate call.

  • private EntityTypeHandle m_EntityType
    EntityTypeHandle used to read the Entity array from each chunk when iterating prefabs. Must be updated before use (updated in PreUpdate).

  • private ComponentTypeHandle<CargoTransportVehicleData> m_CargoTransportVehicleType
    ComponentTypeHandle used to read CargoTransportVehicleData from each chunk. Marked read-only in construction. Must be updated before use (updated in PreUpdate).

Properties

  • None (no public properties exposed).

Constructors

  • public TransportTrainCarriageSelectData(SystemBase system)
    Initializes internal handles and requirement helper. The constructor sets m_PrefabChunks to default, constructs VehicleSelectRequirementData with the provided system, and obtains the initial EntityTypeHandle and read-only ComponentTypeHandle from the provided SystemBase. Note: handles are updated again each PreUpdate to reflect the latest system state.

Methods

  • public static EntityQueryDesc GetEntityQueryDesc()
    Returns an EntityQueryDesc that matches prefab entities that should be considered as train carriage cargo prefabs:
  • All: CargoTransportVehicleData (read-only), TrainCarriageData (read-only), PrefabData (read-only)

  • None: Locked (read-only) This query is intended to be used to build an EntityQuery which is passed to PreUpdate.

  • public void PreUpdate(SystemBase system, CityConfigurationSystem cityConfigurationSystem, EntityQuery query, Allocator allocator, out JobHandle jobHandle)
    Populates m_PrefabChunks asynchronously from the provided query (query.ToArchetypeChunkListAsync) and returns the JobHandle for the async operation. Also updates m_RequirementData, m_EntityType, and m_CargoTransportVehicleType to the current system state. The allocator parameter should be an appropriate allocator (e.g., Allocator.TempJob) and the returned jobHandle must be passed to PostUpdate to ensure safe disposal.

  • public void PostUpdate(JobHandle jobHandle)
    Disposes the m_PrefabChunks NativeList, scheduling disposal with the provided jobHandle. Must be called after PreUpdate and after any code that depends on the chunk list.

  • public Entity SelectCarriagePrefab(ref Random random, Resource resource, int amount)
    Iterates over the prefab chunks and their CargoTransportVehicleData components to find a suitable carriage prefab for the given resource type and requested amount. Selection algorithm:

  • Skips prefabs where (m_Resources & resource) == Resource.NoResource or that fail requirement checks in m_RequirementData.
  • Computes difference num2 = cargoCapacity - amount and attempts to find a prefab with the best capacity match (prefers closer capacities with a selection ordering implemented in code).

  • Uses PickVehicle to perform a probabilistic selection among equally preferred candidates (a simple cumulative probability pick). Returns the selected Entity or Entity.Null if none matched.

  • private bool PickVehicle(ref Random random, int probability, ref int totalProbability)
    Helper method implementing a simple random selection with cumulative probability. Adds probability to totalProbability and returns whether the random pick falls within the current probability bucket: random.NextInt(totalProbability) < probability. Typically called with probability = 100 to give equal weight to each candidate as they are encountered.

Usage Example

// Example inside a SystemBase derived system
public partial class TrainCarriageSelectionSystem : SystemBase
{
    private TransportTrainCarriageSelectData m_SelectData;
    private EntityQuery m_PrefabQuery;
    private CityConfigurationSystem m_CityConfigSystem; // assumed available

    protected override void OnCreate()
    {
        base.OnCreate();
        m_SelectData = new TransportTrainCarriageSelectData(this);
        m_PrefabQuery = GetEntityQuery(TransportTrainCarriageSelectData.GetEntityQueryDesc());
        // obtain m_CityConfigSystem reference as needed
    }

    protected override void OnUpdate()
    {
        // Prepare async chunk list
        JobHandle jobHandle;
        m_SelectData.PreUpdate(this, m_CityConfigSystem, m_PrefabQuery, Allocator.TempJob, out jobHandle);

        // Example selection (synchronous usage after scheduling is acceptable here
        // because SelectCarriagePrefab reads the already-enumerated chunks)
        var rnd = new Random((uint)System.Diagnostics.Stopwatch.GetTimestamp());
        Resource desiredResource = Resource.Goods; // example resource enum
        int requestedAmount = 20;

        Entity chosen = m_SelectData.SelectCarriagePrefab(ref rnd, desiredResource, requestedAmount);
        if (chosen != Entity.Null)
        {
            // use chosen prefab Entity (e.g., instantiate a vehicle)
        }

        // Dispose chunk list (pass jobHandle from PreUpdate)
        m_SelectData.PostUpdate(jobHandle);
    }
}

Notes and cautions: - Always call PreUpdate before calling SelectCarriagePrefab and call PostUpdate afterwards to avoid leaks and to ensure correct job synchronization. - The Allocator passed to PreUpdate should be appropriate for the lifetime (Allocator.TempJob is common) and must be balanced by the PostUpdate disposal. - The selection algorithm uses a simple capacity-difference-based ordering plus probabilistic picks; tune or replace if deterministic or different weighting is needed.