Game.Prefabs.Modes.EntityQueryModePrefab

Assembly:
Namespace: Game.Prefabs.Modes

Type: abstract class

Base: ModePrefab

Summary:
EntityQueryModePrefab is an abstract base prefab used to implement "modes" that operate on sets of ECS entities selected by an EntityQuery description. Subclasses provide the query description, optionally store/restore default data for entities, and apply mode-specific data changes (usually via jobs). This class is intended for use in Cities: Skylines 2 modding where you need to affect groups of entities managed by the DOTS/ECS world.

---

Fields

• None declared in this type.
  Additional info: any backing fields and data are expected to be implemented by subclasses. This class relies on ECS/Job APIs and may interact with inherited state from ModePrefab.

Properties

• None declared in this type.
  Additional info: mode-related state is usually handled by subclasses or the underlying ModePrefab base class.

Constructors

• None declared in this type (inherits default constructor behavior).
  Additional info: Being abstract, you implement a concrete subclass; no special construction logic is required from this base class.

Methods

• public abstract EntityQueryDesc GetEntityQueryDesc()
  Description: Return an EntityQueryDesc that describes which entities this mode targets (component types in All/Any/None, etc.). This is used to create an EntityQuery against the EntityManager.

• public virtual void StoreDefaultData(EntityManager entityManager, ref NativeArray<Entity> requestedQuery, PrefabSystem prefabSystem)
  Description: Optional override. Called to store any default/original data for the requested entities before applying mode data. Default implementation is empty. Be careful managing NativeArray lifetimes — do not leak allocations; use appropriate Allocator and dispose when done.

• public abstract void RestoreDefaultData(EntityManager entityManager, ref NativeArray<Entity> entities, PrefabSystem prefabSystem)
  Description: Abstract. Implement restoring previously stored/default data onto the provided entities (for example when switching modes off or undoing changes). Implementations should perform safe, deterministic modifications (can be done synchronously or schedule jobs).

• public abstract JobHandle ApplyModeData(EntityManager entityManager, EntityQuery requestedQuery, JobHandle deps)
  Description: Abstract. Apply the mode changes to entities matched by requestedQuery. This method should schedule any required jobs and return a JobHandle representing the resulting dependency chain (or return deps if no jobs are scheduled). Important: respect and chain the incoming deps to avoid race conditions.

• [Conditional("UNITY_EDITOR")] [Conditional("DEVELOPMENT_BUILD")] public void RecordChanges(EntityManager entityManager, ref NativeArray<Entity> entities)
  Description: Editor / development-only method used to record changes for debugging, undo, or tooling. In this implementation it merely iterates the entities (no-op). The method is compiled only in UNITY_EDITOR or DEVELOPMENT_BUILD.

• [Conditional("UNITY_EDITOR")] [Conditional("DEVELOPMENT_BUILD")] protected virtual void RecordChanges(EntityManager entityManager, Entity entity)
  Description: Editor / development-only hook for recording changes on a single entity. Default implementation is empty. Override in subclasses to capture specific change information for tooling or debug purposes.

Remarks: - NativeArray lifetimes and thread-safety: when StoreDefaultData or RestoreDefaultData receive/ref NativeArray, ensure proper allocation/disposing and respect safety rules when used across jobs. Prefer scheduling jobs rather than performing large synchronous operations on the main thread when targeting many entities. - ApplyModeData should always return a correct JobHandle representing any work scheduled, chaining the incoming deps to maintain correct synchronization with the rest of the ECS job graph. - RecordChanges methods are only present in editor/dev builds; do not rely on them for runtime logic.

Usage Example

// Simple example subclass that targets entities with MyComponent
public class MyEntityQueryMode : EntityQueryModePrefab
{
    public override EntityQueryDesc GetEntityQueryDesc()
    {
        return new EntityQueryDesc
        {
            All = new ComponentType[] { typeof(MyComponent) }
        };
    }

    public override void StoreDefaultData(EntityManager entityManager, ref NativeArray<Entity> requestedQuery, PrefabSystem prefabSystem)
    {
        // Optional: store current state for later restore (not implemented here)
    }

    public override void RestoreDefaultData(EntityManager entityManager, ref NativeArray<Entity> entities, PrefabSystem prefabSystem)
    {
        // Example synchronous restore: reset MyComponent.Value to 0
        foreach (var e in entities)
        {
            if (entityManager.HasComponent<MyComponent>(e))
                entityManager.SetComponentData(e, new MyComponent { Value = 0 });
        }
    }

    public override JobHandle ApplyModeData(EntityManager entityManager, EntityQuery requestedQuery, JobHandle deps)
    {
        // Simple synchronous example: set MyComponent.Value to 1 on matched entities.
        using (var entities = requestedQuery.ToEntityArray(Allocator.Temp))
        {
            foreach (var e in entities)
            {
                if (entityManager.HasComponent<MyComponent>(e))
                    entityManager.SetComponentData(e, new MyComponent { Value = 1 });
            }
        }
        // No jobs scheduled, so return incoming deps.
        return deps;
    }

    // Optional: record changes in editor/dev builds for tooling
    protected override void RecordChanges(EntityManager entityManager, Entity entity)
    {
#if UNITY_EDITOR || DEVELOPMENT_BUILD
        // record debug info for the entity
#endif
    }
}

Notes: - Replace MyComponent with your actual component type. - For performance with large entity sets, prefer scheduling Jobs (IJobChunk, IJobEntity, etc.) inside ApplyModeData and return the JobHandle. Ensure you chain the incoming deps parameter.