Skip to content

Game.TransportVehicleSelectData

Assembly: Game
Namespace: Game.Prefabs

Type: struct

Base: System.ValueType

Summary:
TransportVehicleSelectData is a utility struct used to enumerate, select and construct vehicle prefabs (Entities) for different transport systems in the game. It scans prefab archetype chunks (via an EntityQuery), evaluates selection requirements and priorities, computes passenger/cargo capacities (including train carriage layouts and multiple-unit trains), and creates runtime vehicle entities (including multi-entity train layouts) using an EntityCommandBuffer. It integrates with the DOTS/ECS workflow (pre-update preparing chunk lists and component lookups, and post-update disposing the chunk list).

Fields

  • private NativeList<ArchetypeChunk> m_PrefabChunks
    Holds the list of prefab archetype chunks returned by the EntityQuery (filled by PreUpdate). Must be disposed in PostUpdate. Used as the source collection to scan available vehicle prefabs.

  • private VehicleSelectRequirementData m_RequirementData
    Helper structure that contains requirement checks used when deciding whether a prefab is selectable (theme, DLC, other requirements). Updated in PreUpdate.

  • private EntityTypeHandle m_EntityType
    EntityTypeHandle used to read Entity values from archetype chunks.

  • private ComponentTypeHandle<PublicTransportVehicleData> m_PublicTransportVehicleType
    ComponentTypeHandle for reading PublicTransportVehicleData from prefab chunks (read-only).

  • private ComponentTypeHandle<CargoTransportVehicleData> m_CargoTransportVehicleType
    ComponentTypeHandle for reading cargo transport metadata from prefabs (read-only).

  • private ComponentTypeHandle<TrainData> m_TrainType
    ComponentTypeHandle for reading TrainData (read-only).

  • private ComponentTypeHandle<TrainEngineData> m_TrainEngineType
    ComponentTypeHandle for reading train engine data (read-only).

  • private ComponentTypeHandle<TrainCarriageData> m_TrainCarriageType
    ComponentTypeHandle for reading train carriage data (read-only).

  • private ComponentTypeHandle<MultipleUnitTrainData> m_MultipleUnitTrainType
    ComponentTypeHandle for detecting multiple-unit trains (read-only).

  • private ComponentTypeHandle<TaxiData> m_TaxiType
    ComponentTypeHandle for Taxi-specific data (read-only).

  • private ComponentTypeHandle<CarData> m_CarType
    ComponentTypeHandle for reading CarData (read-only) — used for buses/taxis/cars.

  • private ComponentTypeHandle<AircraftData> m_AircraftType
    ComponentTypeHandle for generic aircraft data (read-only).

  • private ComponentTypeHandle<AirplaneData> m_AirplaneType
    ComponentTypeHandle for airplane-specific prefabs (read-only).

  • private ComponentTypeHandle<HelicopterData> m_HelicopterType
    ComponentTypeHandle for helicopter / rocket prefabs (read-only).

  • private ComponentTypeHandle<WatercraftData> m_WatercraftType
    ComponentTypeHandle for ships / watercraft (read-only).

  • private ComponentLookup<ObjectData> m_ObjectData
    ComponentLookup for ObjectData (read-only) — used to find the runtime archetype for non-moving objects.

  • private ComponentLookup<MovingObjectData> m_MovingObjectData
    ComponentLookup for MovingObjectData (read-only) — used to find runtime archetype for moving objects.

  • private ComponentLookup<TrainObjectData> m_TrainObjectData
    ComponentLookup for TrainObjectData (read-only) — used to find train controller archetypes.

  • private ComponentLookup<PublicTransportVehicleData> m_PublicTransportVehicleData
    ComponentLookup to read public transport vehicle data by prefab (used when calculating carriage capacities).

  • private ComponentLookup<CargoTransportVehicleData> m_CargoTransportVehicleData
    ComponentLookup to read cargo transport data by prefab (used when calculating carriage capacities).

  • private BufferLookup<VehicleCarriageElement> m_VehicleCarriages
    BufferLookup used to read VehicleCarriageElement dynamic buffers from prefab entities (carriage configurations for trains).

Properties

  • None (this struct exposes no public properties).

Constructors

  • public TransportVehicleSelectData(SystemBase system)
    Initializes all internal handles and lookups using the provided SystemBase. Prepares ComponentTypeHandle/Lookup instances (read-only) and constructs the embedded VehicleSelectRequirementData. This does not query or allocate chunk lists — call PreUpdate to prepare m_PrefabChunks.

Methods

  • public static EntityQueryDesc GetEntityQueryDesc()
    Returns the EntityQueryDesc required to find vehicle prefab entities. The returned query requires VehicleData, ObjectData and PrefabData, allows multiple transport-related types (PublicTransportVehicleData, CargoTransportVehicleData, TrainEngineData, TaxiData) and excludes Locked. Use this descriptor to create the archetype query used with PreUpdate.

  • public void PreUpdate(SystemBase system, CityConfigurationSystem cityConfigurationSystem, EntityQuery query, Allocator allocator, out JobHandle jobHandle)
    Asynchronously gathers prefab archetype chunks (query.ToArchetypeChunkListAsync) into m_PrefabChunks. Updates internal ComponentTypeHandle and ComponentLookup instances and refreshes m_RequirementData with the current system configuration. Returns a JobHandle for the async chunk read. Must be called before calling selection/creation methods which depend on m_PrefabChunks.

  • public void PostUpdate(JobHandle jobHandle)
    Disposes the m_PrefabChunks NativeList, scheduling disposal after the provided jobHandle completes. Must be called after finishing work that needed m_PrefabChunks.

  • public void ListVehicles(TransportType transportType, EnergyTypes energyTypes, SizeClass sizeClass, PublicTransportPurpose publicTransportPurpose, Resource cargoResources, NativeList<Entity> primaryPrefabs, NativeList<Entity> secondaryPrefabs)
    Collects matching vehicle prefabs for the specified filters and appends them to the provided primaryPrefabs/secondaryPrefabs lists (if created). Internally creates a Random seeded from index 0 and calls GetRandomVehicle to enumerate and evaluate prefabs. Useful to retrieve candidate prefabs without creating entities.

  • public void SelectVehicle(ref Random random, TransportType transportType, EnergyTypes energyTypes, SizeClass sizeClass, PublicTransportPurpose publicTransportPurpose, Resource cargoResources, out Entity primaryPrefab, out Entity secondaryPrefab, ref int2 passengerCapacity, ref int2 cargoCapacity)
    Chooses (via weighted random logic) a primary and possibly secondary prefab that matches the given filters. Outputs passenger and cargo capacity ranges in the passed int2 references. The caller provides an existing Random (by ref) to control randomness.

  • public Entity CreateVehicle(EntityCommandBuffer.ParallelWriter commandBuffer, int jobIndex, ref Random random, Transform transform, Entity source, Entity primaryPrefab, Entity secondaryPrefab, TransportType transportType, EnergyTypes energyTypes, SizeClass sizeClass, PublicTransportPurpose publicTransportPurpose, Resource cargoResources, ref int2 passengerCapacity, ref int2 cargoCapacity, bool parked)
    High-level overload that creates vehicle entity/entities and returns the top-level controller entity (or the primary entity). Internally calls the ref layout overload, and disposes the temporary layout list after creation. Returns Entity.Null if no prefab found.

  • public Entity CreateVehicle(EntityCommandBuffer.ParallelWriter commandBuffer, int jobIndex, ref Random random, Transform transform, Entity source, Entity primaryPrefab, Entity secondaryPrefab, TransportType transportType, EnergyTypes energyTypes, SizeClass sizeClass, PublicTransportPurpose publicTransportPurpose, Resource cargoResources, ref int2 passengerCapacity, ref int2 cargoCapacity, bool parked, ref NativeList<LayoutElement> layout)
    Main creation method. Ensures primaryPrefab is selected (calls GetRandomVehicle to resolve actual prefabs), creates controller entity when required (trains/trams/subways), creates additional unit entities for multi-unit trains and their carriages, assigns components (Transform, PrefabRef, Controller, Train, PseudoRandomSeed, PassengerTransport/EvacuatingTransport/PrisonerTransport as needed), and fills a LayoutElement buffer on the controller for train formations. Adds TripSource/Unspawned components if the vehicle isn't parked and a source is provided. Returns the created main entity or Entity.Null if selection failed.

  • private void AddTransportComponents(EntityCommandBuffer.ParallelWriter commandBuffer, int jobIndex, PublicTransportPurpose publicTransportPurpose, Entity entity)
    Adds marker components corresponding to public transport purposes: PassengerTransport, EvacuatingTransport, PrisonerTransport as appropriate. Called during creation.

  • private EntityArchetype GetArchetype(Entity prefab, bool controller, bool parked)
    Resolves and returns the appropriate EntityArchetype to use when creating a runtime entity for a given prefab depending on whether it's a train controller, parked/stopped, or a normal moving/stopped object. Uses m_TrainObjectData, m_MovingObjectData and m_ObjectData lookups.

  • private Entity GetRandomVehicle(ref Random random, TransportType transportType, EnergyTypes energyTypes, SizeClass sizeClass, PublicTransportPurpose publicTransportPurpose, Resource cargoResources, Entity primaryPrefab, Entity secondaryPrefab, NativeList<Entity> primaryPrefabs, NativeList<Entity> secondaryPrefabs, bool ignoreTheme, out bool isMultipleUnitTrain, out int unitCount, out Entity secondaryResult, ref int2 passengerCapacity, ref int2 cargoCapacity)
    Core selection algorithm. Iterates m_PrefabChunks and, depending on the transportType, reads appropriate component arrays (CarData, TrainData, WatercraftData, AircraftData, HelicopterData, etc.). Filters prefabs by energy type, size class, public transport purpose, cargo resources and configured requirements (via m_RequirementData). Uses a weighted selection mechanism (PickVehicle) to produce a chosen Entity. Handles train-specific logic including multiple-unit trains, engines vs carriages, counting carriage counts and computing passenger/cargo capacity including carriage contributions (reading m_VehicleCarriages buffer and using component lookups to get capacities of carriage prefabs). Returns selected primary entity and outputs secondaryResult, isMultipleUnitTrain and unitCount details.

  • private bool PickVehicle(ref Random random, int probability, int priority, ref int totalProbability, ref int selectedPriority)
    Weighted selection helper. Keeps track of the current selected priority and totalProbability for that priority. If the new candidate has lower priority than the current selectedPriority it's skipped. If higher, it resets totals. The candidate contributes 'probability' to the bucket and is selected based on random.NextInt(totalProbability) < probability. Returns true if this candidate becomes the selected item.

Notes and caveats: - PreUpdate must be called before calling selection/create methods to populate m_PrefabChunks and update component handles. - PostUpdate must be called to dispose m_PrefabChunks (dispose is scheduled with jobHandle). - Many internal operations access DynamicBuffer/ComponentLookup and chunk arrays — this struct is intended for use inside SystemBase update cycles and with appropriate synchronization (JobHandles returned by PreUpdate). - Train creation may create multiple Entities (controller + carriages + units) and populates a LayoutElement buffer on the controller entity representing the physical composition/order of the train.

Usage Example

// Example usage inside a SystemBase
TransportVehicleSelectData selector = new TransportVehicleSelectData(this);

// create an EntityQuery using the static descriptor
EntityQuery query = GetEntityQuery(TransportVehicleSelectData.GetEntityQueryDesc());

// prepare for selection (allocate chunk list with a temporary allocator)
JobHandle handle;
selector.PreUpdate(this, CityConfigurationSystem.Instance, query, Allocator.Temp, out handle);

// Ensure jobs complete if you plan to use selection immediately on main thread
handle.Complete();

// Select a vehicle
Random rnd = Random.CreateFromIndex(12345u);
int2 passengerCap = 0;
int2 cargoCap = 0;
Entity primary, secondary;
selector.SelectVehicle(ref rnd, TransportType.Bus, EnergyTypes.Electricity, SizeClass.Medium, PublicTransportPurpose.TransportLine, Resource.NoResource, out primary, out secondary, ref passengerCap, ref cargoCap);

// Create the vehicle entity (example)
EntityCommandBuffer.ParallelWriter ecb = /* obtain ECB */;
Transform spawnTransform = /* prepare transform */;
Entity created = selector.CreateVehicle(ecb, jobIndex: 0, ref rnd, spawnTransform, source: Entity.Null, primary, secondary,
                                       TransportType.Bus, EnergyTypes.Electricity, SizeClass.Medium,
                                       PublicTransportPurpose.TransportLine, Resource.NoResource,
                                       ref passengerCap, ref cargoCap, parked: false);

// Dispose chunk list when done
selector.PostUpdate(JobHandle.Completed);