619 lines
22 KiB
C#
619 lines
22 KiB
C#
using System.Diagnostics;
|
|
using R3;
|
|
|
|
namespace OECS;
|
|
|
|
/// <summary>
|
|
/// The central container for all ECS state.
|
|
///
|
|
/// Manages entity lifecycle, component storage, and provides the primary
|
|
/// API for adding, removing, and querying components.
|
|
/// </summary>
|
|
public class World : IDisposable
|
|
{
|
|
private readonly EntityAllocator _allocator;
|
|
private readonly ComponentStore _components;
|
|
private readonly CommandQueue _commands;
|
|
private readonly RelationshipIndex _relationships;
|
|
private readonly ChangeBuffer _changes;
|
|
private readonly Dictionary<Type, Entity> _singletonEntities = new();
|
|
private bool _disposed;
|
|
|
|
// Deferred structural mutation support: when inside a batching scope
|
|
// (e.g., a foreach iteration or a system run), AddComponent,
|
|
// RemoveComponent, and DestroyEntity are buffered and applied when
|
|
// the outermost scope ends.
|
|
private int _batchingDepth;
|
|
private readonly List<PendingMutation> _pendingMutations = new();
|
|
|
|
private enum PendingMutationKind { AddComponent, RemoveComponent, DestroyEntity }
|
|
|
|
private struct PendingMutation
|
|
{
|
|
public PendingMutationKind Kind;
|
|
public Entity Entity;
|
|
public object? Component; // boxed struct for AddComponent
|
|
public Type ComponentType;
|
|
}
|
|
|
|
// Auto-dirty-marking: during a batching scope, component accesses via
|
|
// GetComponent<T> are tracked. When the scope ends, all accessed
|
|
// components are automatically marked as modified.
|
|
// Outside of a batching scope, MarkModified<T> must be called explicitly.
|
|
private readonly HashSet<(Entity Entity, Type ComponentType)> _accessedComponents = new();
|
|
private readonly HashSet<(Entity Entity, Type ComponentType)> _markedModified = new();
|
|
|
|
public World()
|
|
{
|
|
_allocator = new EntityAllocator();
|
|
_components = new ComponentStore();
|
|
_commands = new CommandQueue();
|
|
_relationships = new RelationshipIndex();
|
|
_changes = new ChangeBuffer();
|
|
}
|
|
|
|
// ── Entity Management ────────────────────────────────────────────
|
|
|
|
/// <summary>
|
|
/// Creates a new entity and returns its handle.
|
|
/// Automatically marks an <see cref="ChangeKind.EntityAdded"/> change.
|
|
/// </summary>
|
|
public Entity CreateEntity()
|
|
{
|
|
var entity = _allocator.Allocate();
|
|
_changes.Pending.MarkEntityAdded(entity);
|
|
return entity;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Creates an entity with a specific handle. Used during deserialization
|
|
/// to restore entities with their original IDs and versions.
|
|
/// Does NOT mark an EntityAdded change (caller is responsible for
|
|
/// posting changes after the full load).
|
|
/// </summary>
|
|
internal Entity CreateEntity(Entity handle)
|
|
{
|
|
_allocator.Reserve(handle);
|
|
return handle;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Destroys an entity, removing all its components and recycling its ID.
|
|
///
|
|
/// Cascade behavior:
|
|
/// - All relationships where this entity is the <b>source</b> are removed.
|
|
/// - All relationships where this entity is the <b>target</b> are removed
|
|
/// from the source entities.
|
|
/// </summary>
|
|
public void DestroyEntity(Entity entity)
|
|
{
|
|
if (_batchingDepth > 0)
|
|
{
|
|
_pendingMutations.Add(new PendingMutation
|
|
{
|
|
Kind = PendingMutationKind.DestroyEntity,
|
|
Entity = entity
|
|
});
|
|
return;
|
|
}
|
|
|
|
DestroyEntityImpl(entity);
|
|
}
|
|
|
|
private void DestroyEntityImpl(Entity entity)
|
|
{
|
|
if (!_allocator.IsAlive(entity))
|
|
return;
|
|
|
|
// Remove all relationships where this entity is the target.
|
|
// Materialize to avoid collection-modified-during-enumeration when
|
|
// OnRemoved mutates the same HashSet we're iterating.
|
|
var incoming = _relationships.GetIncomingRelationships(entity)
|
|
.Select(r => (r.RelationshipType, r.Sources.ToList()))
|
|
.ToList();
|
|
foreach (var (relType, sources) in incoming)
|
|
{
|
|
foreach (var source in sources)
|
|
{
|
|
_relationships.OnRemoved(relType, source, entity);
|
|
_components.Remove(source, relType);
|
|
_changes.Pending.MarkComponentRemoved(source, relType);
|
|
}
|
|
}
|
|
|
|
// Remove all relationships where this entity is the source.
|
|
_relationships.RemoveAllSourcesForEntity(entity);
|
|
|
|
// Mark component removals for each component type before removing them.
|
|
foreach (var componentType in _components.ComponentTypes.ToList())
|
|
{
|
|
if (_components.GetSet(componentType)?.Contains(entity) == true)
|
|
{
|
|
_changes.Pending.MarkComponentRemoved(entity, componentType);
|
|
}
|
|
}
|
|
|
|
_components.RemoveAll(entity);
|
|
_allocator.Free(entity);
|
|
|
|
_changes.Pending.MarkEntityRemoved(entity);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns true if the entity is currently alive (not destroyed).
|
|
/// </summary>
|
|
public bool IsAlive(Entity entity)
|
|
{
|
|
return _allocator.IsAlive(entity);
|
|
}
|
|
|
|
// ── Component Management ─────────────────────────────────────────
|
|
|
|
/// <summary>
|
|
/// Adds a component to the entity. Replaces the existing component if
|
|
/// the entity already has one of type <typeparamref name="T"/>.
|
|
///
|
|
/// If <typeparamref name="T"/> implements <see cref="IRelationship"/>,
|
|
/// the reverse index is updated automatically.
|
|
/// </summary>
|
|
public void AddComponent<T>(Entity entity, T component) where T : struct
|
|
{
|
|
if (_batchingDepth > 0)
|
|
{
|
|
_pendingMutations.Add(new PendingMutation
|
|
{
|
|
Kind = PendingMutationKind.AddComponent,
|
|
Entity = entity,
|
|
Component = component,
|
|
ComponentType = typeof(T)
|
|
});
|
|
return;
|
|
}
|
|
|
|
AddComponentImpl(entity, component);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Adds a boxed component to the entity. Used by <see cref="WorldSerializer"/>
|
|
/// during deserialization after relationship Source fixup.
|
|
/// Calls <see cref="AddComponentImpl{T}"/> via reflection to avoid
|
|
/// duplicating the relationship index logic.
|
|
/// </summary>
|
|
internal void AddComponentBoxed(Entity entity, object component, Type componentType)
|
|
{
|
|
var method = s_addComponentImpl.MakeGenericMethod(componentType);
|
|
method.Invoke(this, [entity, component]);
|
|
}
|
|
|
|
private static readonly System.Reflection.MethodInfo s_addComponentImpl =
|
|
typeof(World).GetMethod(
|
|
nameof(AddComponentImpl),
|
|
System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)!;
|
|
|
|
private void AddComponentImpl<T>(Entity entity, T component) where T : struct
|
|
{
|
|
ThrowIfNotAlive(entity);
|
|
|
|
// If replacing an existing relationship, remove the old index entry first.
|
|
if (component is IRelationship)
|
|
{
|
|
if (_components.TryGet<T>(entity, out var old))
|
|
{
|
|
var oldRel = (IRelationship)(object)old;
|
|
_relationships.OnRemoved(typeof(T), entity, oldRel.Target);
|
|
}
|
|
}
|
|
|
|
bool isNew = !_components.Has<T>(entity);
|
|
_components.Add(entity, component);
|
|
|
|
// Update relationship index.
|
|
if (component is IRelationship rel)
|
|
{
|
|
_relationships.OnAdded(typeof(T), entity, rel.Target);
|
|
}
|
|
|
|
// Mark change.
|
|
if (isNew)
|
|
_changes.Pending.MarkComponentAdded(entity, typeof(T));
|
|
}
|
|
|
|
/// <summary>
|
|
/// Removes the component of type <typeparamref name="T"/> from the entity.
|
|
/// No-op if the entity does not have the component.
|
|
///
|
|
/// If <typeparamref name="T"/> implements <see cref="IRelationship"/>,
|
|
/// the reverse index is updated automatically.
|
|
/// </summary>
|
|
public void RemoveComponent<T>(Entity entity) where T : struct
|
|
{
|
|
if (_batchingDepth > 0)
|
|
{
|
|
_pendingMutations.Add(new PendingMutation
|
|
{
|
|
Kind = PendingMutationKind.RemoveComponent,
|
|
Entity = entity,
|
|
ComponentType = typeof(T)
|
|
});
|
|
return;
|
|
}
|
|
|
|
RemoveComponentImpl<T>(entity);
|
|
}
|
|
|
|
private void RemoveComponentImpl<T>(Entity entity) where T : struct
|
|
{
|
|
// Update relationship index before removal.
|
|
if (typeof(IRelationship).IsAssignableFrom(typeof(T)))
|
|
{
|
|
if (_components.TryGet<T>(entity, out var existing))
|
|
{
|
|
var rel = (IRelationship)(object)existing;
|
|
_relationships.OnRemoved(typeof(T), entity, rel.Target);
|
|
}
|
|
}
|
|
|
|
bool existed = _components.Has<T>(entity);
|
|
_components.Remove<T>(entity);
|
|
|
|
if (existed)
|
|
_changes.Pending.MarkComponentRemoved(entity, typeof(T));
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns a reference to the component of type <typeparamref name="T"/>
|
|
/// for the given entity. Throws if the entity does not have the component.
|
|
///
|
|
/// During iteration, this access is auto-marked as modified since it
|
|
/// returns a mutable ref. Use <see cref="ReadComponent{T}"/> if you
|
|
/// only need to read the value.
|
|
/// </summary>
|
|
public ref T GetComponent<T>(Entity entity) where T : struct
|
|
{
|
|
if (_batchingDepth > 0)
|
|
_accessedComponents.Add((entity, typeof(T)));
|
|
return ref _components.Get<T>(entity);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Tracks a component access for auto-dirty-marking without returning
|
|
/// a ref. Used by <see cref="SelectN"/> iterators when they expose
|
|
/// component refs directly from the sparse set.
|
|
/// </summary>
|
|
internal void TrackAccess(Entity entity, Type componentType)
|
|
{
|
|
if (_batchingDepth > 0)
|
|
_accessedComponents.Add((entity, componentType));
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns a copy of the component of type <typeparamref name="T"/>
|
|
/// for the given entity. Never auto-marks as modified — use this when
|
|
/// you only need to read the value.
|
|
/// </summary>
|
|
public T ReadComponent<T>(Entity entity) where T : struct
|
|
{
|
|
return _components.Get<T>(entity);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Tries to get the component of type <typeparamref name="T"/> for the
|
|
/// given entity. Returns true and copies the value to
|
|
/// <paramref name="value"/> if the component exists; otherwise returns false.
|
|
/// Never auto-marks as modified.
|
|
/// </summary>
|
|
public bool TryGetComponent<T>(Entity entity, out T value) where T : struct
|
|
{
|
|
return _components.TryGet<T>(entity, out value);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns true if the entity has a component of type <typeparamref name="T"/>.
|
|
/// </summary>
|
|
public bool HasComponent<T>(Entity entity) where T : struct
|
|
{
|
|
return _components.Has<T>(entity);
|
|
}
|
|
|
|
// ── Change Tracking ──────────────────────────────────────────────
|
|
|
|
/// <summary>
|
|
/// Marks a component of type <typeparamref name="T"/> on the given entity
|
|
/// as modified. Only needed outside of iteration scopes — during a
|
|
/// <c>Select</c> loop, components accessed via <see cref="GetComponent{T}"/>
|
|
/// are auto-marked.
|
|
/// </summary>
|
|
public void MarkModified<T>(Entity entity) where T : struct
|
|
{
|
|
_changes.Pending.MarkComponentModified(entity, typeof(T));
|
|
_markedModified.Add((entity, typeof(T)));
|
|
}
|
|
|
|
/// <summary>
|
|
/// Posts all pending changes to R3 subscribers, then clears the pending set.
|
|
/// Called automatically by <see cref="SystemGroup"/> after each system
|
|
/// and after the full tick.
|
|
/// </summary>
|
|
public void PostChanges()
|
|
{
|
|
_changes.Post();
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns an observable that emits all entity changes (adds, removes,
|
|
/// component adds, component removes, component modifications).
|
|
/// </summary>
|
|
public Observable<EntityChange> ObserveEntityChanges()
|
|
{
|
|
return _changes.ObserveEntityChanges();
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns an observable that emits changes for a specific component type
|
|
/// <typeparamref name="T"/> (added, removed, or modified).
|
|
/// </summary>
|
|
public Observable<EntityChange> ObserveComponentChanges<T>() where T : struct
|
|
{
|
|
return _changes.ObserveComponentChanges(typeof(T));
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns an observable that emits component-level changes matching
|
|
/// the given query's With types and excluding its Without types.
|
|
/// </summary>
|
|
public Observable<EntityChange> ObserveQuery<T1>(Query<T1> query = default)
|
|
where T1 : struct
|
|
{
|
|
return _changes.ObserveQuery(query);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns an observable that emits component-level changes matching
|
|
/// the given query.
|
|
/// </summary>
|
|
public Observable<EntityChange> ObserveQuery<T1, T2>(Query<T1, T2> query = default)
|
|
where T1 : struct where T2 : struct
|
|
{
|
|
return _changes.ObserveQuery(query);
|
|
}
|
|
|
|
// ── Singletons ───────────────────────────────────────────────────
|
|
|
|
/// <summary>
|
|
/// Sets (adds or replaces) a singleton component of type <typeparamref name="T"/>.
|
|
/// Each singleton component type gets its own dedicated entity.
|
|
/// </summary>
|
|
public void SetSingleton<T>(T component) where T : struct
|
|
{
|
|
if (!_singletonEntities.TryGetValue(typeof(T), out var entity))
|
|
{
|
|
entity = _allocator.Allocate();
|
|
_singletonEntities[typeof(T)] = entity;
|
|
}
|
|
AddComponent(entity, component);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns a reference to the singleton component of type <typeparamref name="T"/>.
|
|
/// Throws if the singleton has not been set. Auto-marks as modified during iteration.
|
|
/// </summary>
|
|
public ref T GetSingleton<T>() where T : struct
|
|
{
|
|
return ref GetComponent<T>(GetSingletonEntity<T>());
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns a copy of the singleton component of type <typeparamref name="T"/>.
|
|
/// Never auto-marks as modified — use this when you only need to read the singleton.
|
|
/// </summary>
|
|
public T ReadSingleton<T>() where T : struct
|
|
{
|
|
return ReadComponent<T>(GetSingletonEntity<T>());
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns true if a singleton component of type <typeparamref name="T"/> exists.
|
|
/// </summary>
|
|
public bool HasSingleton<T>() where T : struct
|
|
{
|
|
return _singletonEntities.TryGetValue(typeof(T), out var entity)
|
|
&& HasComponent<T>(entity);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Removes the singleton component of type <typeparamref name="T"/>.
|
|
/// No-op if the singleton does not have the component.
|
|
/// </summary>
|
|
public void RemoveSingleton<T>() where T : struct
|
|
{
|
|
if (_singletonEntities.TryGetValue(typeof(T), out var entity))
|
|
RemoveComponent<T>(entity);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Gets the entity backing the singleton of type <typeparamref name="T"/>,
|
|
/// creating it if it doesn't exist yet.
|
|
/// </summary>
|
|
private Entity GetSingletonEntity<T>() where T : struct
|
|
{
|
|
if (!_singletonEntities.TryGetValue(typeof(T), out var entity))
|
|
{
|
|
entity = _allocator.Allocate();
|
|
_singletonEntities[typeof(T)] = entity;
|
|
}
|
|
return entity;
|
|
}
|
|
|
|
// ── Relationships ────────────────────────────────────────────────
|
|
|
|
/// <summary>
|
|
/// Returns all source entities that have a relationship of type
|
|
/// <typeparamref name="T"/> pointing to the given target entity.
|
|
/// Sources are iterated in insertion order.
|
|
/// </summary>
|
|
public IReadOnlyCollection<Entity> GetSources<T>(Entity target)
|
|
where T : struct, IRelationship
|
|
{
|
|
return _relationships.GetSources<T>(target);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Reorders the source set for the given relationship type and target
|
|
/// to match the order of entities in <paramref name="ordered"/>.
|
|
/// All entities currently in the set must appear exactly once in the
|
|
/// provided collection; no entities are added or removed.
|
|
/// Fires a <see cref="ChangeKind.RelationshipReordered"/> change event
|
|
/// on the target entity.
|
|
/// </summary>
|
|
public void ReorderSources<T>(Entity target, IReadOnlyList<Entity> ordered)
|
|
where T : struct, IRelationship
|
|
{
|
|
_relationships.ReorderSources<T>(target, ordered);
|
|
_changes.Pending.MarkRelationshipReordered(target, typeof(T));
|
|
}
|
|
|
|
// ── Commands ──────────────────────────────────────────────────────
|
|
|
|
/// <summary>
|
|
/// The command queue for deferred, serializable commands.
|
|
/// Systems enqueue commands via <c>world.Commands.Enqueue(...)</c>.
|
|
/// </summary>
|
|
public CommandQueue Commands => _commands;
|
|
|
|
/// <summary>
|
|
/// Manually drains the command queue, executing all pending commands.
|
|
/// Called automatically by <see cref="SystemGroup"/> after each system
|
|
/// and after the full tick.
|
|
/// </summary>
|
|
public void ExecuteCommands()
|
|
{
|
|
_commands.ExecuteAll(this);
|
|
}
|
|
|
|
// ── Iteration Lifecycle ──────────────────────────────────────────
|
|
|
|
/// <summary>
|
|
/// Begins a batching scope. Structural mutations (AddComponent,
|
|
/// RemoveComponent, DestroyEntity) are buffered until the outermost
|
|
/// <see cref="EndBatching"/> call. Component accesses via
|
|
/// <see cref="GetComponent{T}"/> are auto-tracked for modification.
|
|
/// </summary>
|
|
internal void BeginBatching()
|
|
{
|
|
_batchingDepth++;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Ends a batching scope. When the outermost scope ends, all
|
|
/// buffered structural mutations are applied and auto-tracked
|
|
/// component modifications are posted.
|
|
/// </summary>
|
|
internal void EndBatching()
|
|
{
|
|
_batchingDepth--;
|
|
if (_batchingDepth == 0)
|
|
{
|
|
// Auto-mark all components accessed via GetComponent<T>
|
|
// during the iteration as modified.
|
|
foreach (var (entity, componentType) in _accessedComponents)
|
|
{
|
|
if (!_markedModified.Contains((entity, componentType)))
|
|
{
|
|
_changes.Pending.MarkComponentModified(entity, componentType);
|
|
}
|
|
}
|
|
_accessedComponents.Clear();
|
|
_markedModified.Clear();
|
|
|
|
FlushPendingMutations();
|
|
}
|
|
}
|
|
|
|
public void FlushPendingMutations()
|
|
{
|
|
if (_pendingMutations.Count == 0)
|
|
return;
|
|
|
|
foreach (var m in _pendingMutations)
|
|
{
|
|
switch (m.Kind)
|
|
{
|
|
case PendingMutationKind.AddComponent:
|
|
// Use reflection to call AddComponentImpl<T>.
|
|
var addMethod = typeof(World).GetMethod(
|
|
nameof(AddComponentImpl),
|
|
System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)!;
|
|
var genericAdd = addMethod.MakeGenericMethod(m.ComponentType);
|
|
genericAdd.Invoke(this, [m.Entity, m.Component]);
|
|
break;
|
|
|
|
case PendingMutationKind.RemoveComponent:
|
|
var removeMethod = typeof(World).GetMethod(
|
|
nameof(RemoveComponentImpl),
|
|
System.Reflection.BindingFlags.NonPublic | System.Reflection.BindingFlags.Instance)!;
|
|
var genericRemove = removeMethod.MakeGenericMethod(m.ComponentType);
|
|
genericRemove.Invoke(this, [m.Entity]);
|
|
break;
|
|
|
|
case PendingMutationKind.DestroyEntity:
|
|
DestroyEntityImpl(m.Entity);
|
|
break;
|
|
}
|
|
}
|
|
|
|
_pendingMutations.Clear();
|
|
}
|
|
|
|
// ── Internal Access ───────────────────────────────────────────────
|
|
|
|
/// <summary>
|
|
/// The component store. Exposed internally for query execution and
|
|
/// system infrastructure.
|
|
/// </summary>
|
|
internal ComponentStore Components => _components;
|
|
|
|
/// <summary>
|
|
/// Gets the entity that backs the singleton of type <typeparamref name="T"/>,
|
|
/// or <see cref="Entity.Null"/> if the singleton has not been set.
|
|
/// </summary>
|
|
internal Entity GetSingletonEntityOrNull<T>() where T : struct
|
|
{
|
|
_singletonEntities.TryGetValue(typeof(T), out var entity);
|
|
return entity;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Registers an existing entity as the backing entity for a singleton component.
|
|
/// Used during deserialization to restore singleton state.
|
|
/// </summary>
|
|
internal void RegisterSingletonEntity(Type componentType, Entity entity)
|
|
{
|
|
_singletonEntities[componentType] = entity;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Returns true if the given entity is a singleton entity (backs any singleton component).
|
|
/// </summary>
|
|
internal bool IsSingletonEntity(Entity entity)
|
|
{
|
|
return _singletonEntities.ContainsValue(entity);
|
|
}
|
|
|
|
// ── Helpers ───────────────────────────────────────────────────────
|
|
|
|
private void ThrowIfNotAlive(Entity entity)
|
|
{
|
|
if (!_allocator.IsAlive(entity))
|
|
throw new InvalidOperationException($"Entity {entity} is not alive.");
|
|
}
|
|
|
|
// ── Cleanup ───────────────────────────────────────────────────────
|
|
|
|
public void Dispose()
|
|
{
|
|
if (_disposed)
|
|
return;
|
|
_disposed = true;
|
|
_changes.Dispose();
|
|
}
|
|
} |