896 lines
40 KiB
Zig
896 lines
40 KiB
Zig
const std = @import("std");
|
|
const Allocator = std.mem.Allocator;
|
|
const testing = std.testing;
|
|
const builtin = @import("builtin");
|
|
const assert = std.debug.assert;
|
|
const query_mod = @import("query.zig");
|
|
const Archetype = @import("Archetype.zig");
|
|
const StringTable = @import("StringTable.zig");
|
|
const comp = @import("comptime.zig");
|
|
const ComponentTypesByName = @import("../module.zig").ComponentTypesByName;
|
|
|
|
/// An entity ID uniquely identifies an entity globally within an Entities set.
|
|
pub const EntityID = u64;
|
|
|
|
fn byTypeId(context: void, lhs: Archetype.Column, rhs: Archetype.Column) bool {
|
|
_ = context;
|
|
return lhs.type_id < rhs.type_id;
|
|
}
|
|
|
|
/// A database of entities. For example, all player, monster, etc. entities in a game world.
|
|
///
|
|
/// ```
|
|
/// const world = Entities.init(allocator); // all entities in our world.
|
|
/// defer world.deinit();
|
|
///
|
|
/// const player1 = world.new(); // our first "player" entity
|
|
/// const player2 = world.new(); // our second "player" entity
|
|
/// ```
|
|
///
|
|
/// Entities are divided into archetypes for optimal, CPU cache efficient storage. For example, all
|
|
/// entities with two components `Location` and `Name` are stored in the same table dedicated to
|
|
/// densely storing `(Location, Name)` rows in contiguous memory. This not only ensures CPU cache
|
|
/// efficiency (leveraging data oriented design) which improves iteration speed over entities for
|
|
/// example, but makes queries like "find all entities with a Location component" ridiculously fast
|
|
/// because one need only find the tables which have a column for storing Location components and it
|
|
/// is then guaranteed every entity in the table has that component (entities do not need to be
|
|
/// checked one by one to determine if they have a Location component.)
|
|
///
|
|
/// Components can be added and removed to entities at runtime as you please:
|
|
///
|
|
/// ```
|
|
/// try player1.set("rotation", Rotation{ .degrees = 90 });
|
|
/// try player1.remove("rotation");
|
|
/// ```
|
|
///
|
|
/// When getting a component value, you must know it's type or undefined behavior will occur:
|
|
/// TODO: improve this!
|
|
///
|
|
/// ```
|
|
/// if (player1.get("rotation", Rotation)) |rotation| {
|
|
/// // player1 had a rotation component!
|
|
/// }
|
|
/// ```
|
|
///
|
|
/// When a component is added or removed from an entity, it's archetype is said to change. For
|
|
/// example player1 may have had the archetype `(Location, Name)` before, and after adding the
|
|
/// rotation component has the archetype `(Location, Name, Rotation)`. It will be automagically
|
|
/// "moved" from the table that stores entities with `(Location, Name)` components to the table that
|
|
/// stores `(Location, Name, Rotation)` components for you.
|
|
///
|
|
/// You can have 65,535 archetypes in total, and 4,294,967,295 entities total. Entities which are
|
|
/// deleted are merely marked as "unused" and recycled
|
|
///
|
|
/// Database equivalents:
|
|
/// * Entities is a database of tables, where each table represents a single archetype.
|
|
/// * Archetype is a table, whose rows are entities and columns are components.
|
|
/// * EntityID is a mere 32-bit array index, pointing to a 16-bit archetype table index and 32-bit
|
|
/// row index, enabling entities to "move" from one archetype table to another seamlessly and
|
|
/// making lookup by entity ID a few cheap array indexing operations.
|
|
/// * ComponentStorage(T) is a column of data within a table for a single type of component `T`.
|
|
pub fn Entities(comptime all_components: anytype) type {
|
|
// TODO: validate all_components is a namespaced component set in the form we expect
|
|
return struct {
|
|
allocator: Allocator,
|
|
|
|
/// TODO!
|
|
counter: EntityID = 0,
|
|
|
|
/// A mapping of entity IDs (array indices) to where an entity's component values are actually
|
|
/// stored.
|
|
entities: std.AutoHashMapUnmanaged(EntityID, Pointer) = .{},
|
|
|
|
// All archetypes are stored in a bucket. The number of buckets is configurable, and which
|
|
// bucket an archetype will be stored in is based on the hash of all its columns / component
|
|
// names.
|
|
seed: u64 = 0xdeadbeef,
|
|
buckets: []?u32, // indices into archetypes
|
|
archetypes: std.ArrayListUnmanaged(Archetype) = .{},
|
|
|
|
/// Maps component names <-> unique IDs
|
|
component_names: *StringTable,
|
|
id_name: StringTable.Index = 0,
|
|
|
|
const Self = @This();
|
|
|
|
/// Points to where an entity is stored, specifically in which archetype table and in which row
|
|
/// of that table. That is, the entity's component values are stored at:
|
|
///
|
|
/// ```
|
|
/// Entities.archetypes.items[ptr.archetype_index].rows[ptr.row_index]
|
|
/// ```
|
|
///
|
|
pub const Pointer = struct {
|
|
archetype_index: u32,
|
|
row_index: u32,
|
|
};
|
|
|
|
/// A complex query for entities matching a given criteria
|
|
pub const Query = query_mod.Query(all_components);
|
|
pub const QueryTag = query_mod.QueryTag;
|
|
|
|
pub fn init(allocator: Allocator) !Self {
|
|
const component_names = try allocator.create(StringTable);
|
|
errdefer allocator.destroy(component_names);
|
|
component_names.* = .{};
|
|
|
|
const buckets = try allocator.alloc(?u32, 1024); // TODO: configurable size
|
|
errdefer allocator.free(buckets);
|
|
for (buckets) |*b| b.* = null;
|
|
|
|
var entities = Self{
|
|
.allocator = allocator,
|
|
.component_names = component_names,
|
|
.buckets = buckets,
|
|
};
|
|
entities.id_name = try entities.component_names.indexOrPut(allocator, "id");
|
|
|
|
const columns = try allocator.alloc(Archetype.Column, 1);
|
|
columns[0] = .{
|
|
.name = entities.id_name,
|
|
.type_id = comp.typeId(EntityID),
|
|
.size = @sizeOf(EntityID),
|
|
.alignment = @alignOf(EntityID),
|
|
.values = undefined,
|
|
};
|
|
|
|
const archetype_entry = try entities.archetypeOrPut(columns);
|
|
archetype_entry.ptr.* = .{
|
|
.len = 0,
|
|
.capacity = 0,
|
|
.columns = columns,
|
|
.component_names = entities.component_names,
|
|
.hash = archetype_entry.hash,
|
|
};
|
|
return entities;
|
|
}
|
|
|
|
pub fn deinit(entities: *Self) void {
|
|
entities.entities.deinit(entities.allocator);
|
|
entities.component_names.deinit(entities.allocator);
|
|
entities.allocator.destroy(entities.component_names);
|
|
entities.allocator.free(entities.buckets);
|
|
for (entities.archetypes.items) |*archetype| archetype.deinit(entities.allocator);
|
|
entities.archetypes.deinit(entities.allocator);
|
|
}
|
|
|
|
fn archetypeOrPut(
|
|
entities: *Self,
|
|
columns: []const Archetype.Column,
|
|
) !struct {
|
|
found_existing: bool,
|
|
hash: u64,
|
|
index: u32,
|
|
ptr: *Archetype,
|
|
} {
|
|
var hasher = std.hash.XxHash64.init(entities.seed);
|
|
for (columns) |column| {
|
|
hasher.update(std.mem.asBytes(&column.name));
|
|
}
|
|
const hash = hasher.final();
|
|
const bucket_index = hash % entities.buckets.len;
|
|
if (entities.buckets[bucket_index]) |bucket| {
|
|
// Bucket already exists
|
|
const archetype = &entities.archetypes.items[bucket];
|
|
if (archetype.next) |_| {
|
|
// Multiple archetypes in bucket (there were collisions)
|
|
while (archetype.next) |collision_index| {
|
|
const collision = &entities.archetypes.items[collision_index];
|
|
if (collision.hash == hash) {
|
|
// Probably a match
|
|
// TODO: technically a hash collision could occur here, so maybe check
|
|
// column IDs are equal here too?
|
|
return .{ .found_existing = true, .hash = hash, .index = collision_index, .ptr = collision };
|
|
}
|
|
}
|
|
|
|
// New collision
|
|
try entities.archetypes.append(entities.allocator, undefined);
|
|
const index = entities.archetypes.items.len - 1;
|
|
const ptr = &entities.archetypes.items[index];
|
|
archetype.next = @intCast(index);
|
|
return .{ .found_existing = false, .hash = hash, .index = @intCast(index), .ptr = ptr };
|
|
} else if (archetype.hash == hash) {
|
|
// Exact match
|
|
return .{ .found_existing = true, .hash = hash, .index = bucket, .ptr = archetype };
|
|
}
|
|
|
|
// New collision
|
|
try entities.archetypes.append(entities.allocator, undefined);
|
|
const index = entities.archetypes.items.len - 1;
|
|
const ptr = &entities.archetypes.items[index];
|
|
archetype.next = @intCast(index);
|
|
return .{ .found_existing = false, .hash = hash, .index = @intCast(index), .ptr = ptr };
|
|
}
|
|
|
|
// Bucket doesn't exist
|
|
try entities.archetypes.append(entities.allocator, undefined);
|
|
const index = entities.archetypes.items.len - 1;
|
|
const ptr = &entities.archetypes.items[index];
|
|
entities.buckets[bucket_index] = @intCast(index);
|
|
return .{ .found_existing = false, .hash = hash, .index = @intCast(index), .ptr = ptr };
|
|
}
|
|
|
|
/// Returns a new entity.
|
|
pub fn new(entities: *Self) !EntityID {
|
|
const new_id = entities.counter;
|
|
entities.counter += 1;
|
|
|
|
// TODO: could skip this lookup if we store pointer
|
|
const archetype_entry = try entities.archetypeOrPut(&.{
|
|
.{
|
|
.name = entities.id_name,
|
|
.type_id = comp.typeId(EntityID),
|
|
.size = @sizeOf(EntityID),
|
|
.alignment = @alignOf(EntityID),
|
|
.values = undefined,
|
|
},
|
|
});
|
|
assert(archetype_entry.found_existing);
|
|
|
|
var void_archetype = archetype_entry.ptr;
|
|
const new_row = try void_archetype.append(entities.allocator, .{ .id = new_id });
|
|
const void_pointer = Pointer{
|
|
.archetype_index = 0, // void archetype is guaranteed to be first index
|
|
.row_index = new_row,
|
|
};
|
|
errdefer void_archetype.undoAppend();
|
|
|
|
try entities.entities.put(entities.allocator, new_id, void_pointer);
|
|
return new_id;
|
|
}
|
|
|
|
/// Removes an entity.
|
|
pub fn remove(entities: *Self, entity: EntityID) !void {
|
|
var archetype = entities.archetypeByID(entity);
|
|
const ptr = entities.entities.get(entity).?;
|
|
|
|
// A swap removal will be performed, update the entity stored in the last row of the
|
|
// archetype table to point to the row the entity we are removing is currently located.
|
|
if (archetype.len > 1) {
|
|
const last_row_entity_id = archetype.get(archetype.len - 1, entities.id_name, EntityID).?;
|
|
try entities.entities.put(entities.allocator, last_row_entity_id, Pointer{
|
|
.archetype_index = ptr.archetype_index,
|
|
.row_index = ptr.row_index,
|
|
});
|
|
}
|
|
|
|
// Perform a swap removal to remove our entity from the archetype table.
|
|
archetype.remove(ptr.row_index);
|
|
|
|
_ = entities.entities.remove(entity);
|
|
}
|
|
|
|
/// Given a component name, returns its ID. A new ID is created if needed.
|
|
///
|
|
/// The set of components used is expected to be static for the lifetime of the Entities,
|
|
/// and as such this function allocates component names but there is no way to release that
|
|
/// memory until Entities.deinit() is called.
|
|
pub fn componentName(entities: *Self, name_str: []const u8) StringTable.Index {
|
|
return entities.component_names.indexOrPut(entities.allocator, name_str) catch @panic("TODO: implement stateful OOM");
|
|
}
|
|
|
|
/// Returns the archetype storage for the given entity.
|
|
pub inline fn archetypeByID(entities: *Self, entity: EntityID) *Archetype {
|
|
const ptr = entities.entities.get(entity).?;
|
|
return &entities.archetypes.items[ptr.archetype_index];
|
|
}
|
|
|
|
/// Sets the named component to the specified value for the given entity,
|
|
/// moving the entity from it's current archetype table to the new archetype
|
|
/// table if required.
|
|
pub fn setComponent(
|
|
entities: *Self,
|
|
entity: EntityID,
|
|
// TODO: cleanup comptime
|
|
comptime namespace_name: std.meta.FieldEnum(@TypeOf(all_components)),
|
|
comptime component_name: std.meta.FieldEnum(@TypeOf(@field(all_components, @tagName(namespace_name)))),
|
|
component: @field(
|
|
@field(all_components, @tagName(namespace_name)),
|
|
@tagName(component_name),
|
|
).type,
|
|
) !void {
|
|
const name_str = @tagName(namespace_name) ++ "." ++ @tagName(component_name);
|
|
const name_id = try entities.component_names.indexOrPut(entities.allocator, name_str);
|
|
|
|
const prev_archetype_idx = entities.entities.get(entity).?.archetype_index;
|
|
var prev_archetype = &entities.archetypes.items[prev_archetype_idx];
|
|
var archetype: ?*Archetype = if (prev_archetype.hasComponent(name_id)) prev_archetype else null;
|
|
var archetype_idx: u32 = if (archetype != null) prev_archetype_idx else 0;
|
|
|
|
if (archetype == null) {
|
|
// TODO: eliminate the need for allocation and sorting here, since this can occur
|
|
// if an archetype already exists (found_existing case below)
|
|
const columns = try entities.allocator.alloc(Archetype.Column, prev_archetype.columns.len + 1);
|
|
@memcpy(columns[0 .. columns.len - 1], prev_archetype.columns);
|
|
for (columns) |*column| {
|
|
column.values = undefined;
|
|
}
|
|
columns[columns.len - 1] = .{
|
|
.name = name_id,
|
|
.type_id = comp.typeId(@TypeOf(component)),
|
|
.size = @sizeOf(@TypeOf(component)),
|
|
.alignment = if (@sizeOf(@TypeOf(component)) == 0) 1 else @alignOf(@TypeOf(component)),
|
|
.values = undefined,
|
|
};
|
|
std.sort.pdq(Archetype.Column, columns, {}, byTypeId);
|
|
|
|
const archetype_entry = try entities.archetypeOrPut(columns);
|
|
if (!archetype_entry.found_existing) {
|
|
// Update prev_archetype pointer, as it would now be invalidated due to the allocation
|
|
prev_archetype = &entities.archetypes.items[prev_archetype_idx];
|
|
|
|
archetype_entry.ptr.* = .{
|
|
.len = 0,
|
|
.capacity = 0,
|
|
.columns = columns,
|
|
.component_names = entities.component_names,
|
|
.hash = archetype_entry.hash,
|
|
};
|
|
} else {
|
|
entities.allocator.free(columns);
|
|
}
|
|
archetype = archetype_entry.ptr;
|
|
archetype_idx = archetype_entry.index;
|
|
}
|
|
|
|
// Either new storage (if the entity moved between storage tables due to having a new
|
|
// component) or the prior storage (if the entity already had the component and it's value
|
|
// is merely being updated.)
|
|
var current_archetype_storage = archetype.?;
|
|
|
|
if (archetype_idx == prev_archetype_idx) {
|
|
// Update the value of the existing component of the entity.
|
|
const ptr = entities.entities.get(entity).?;
|
|
current_archetype_storage.set(ptr.row_index, name_id, component);
|
|
return;
|
|
}
|
|
|
|
// Copy to all component values for our entity from the old archetype storage (archetype)
|
|
// to the new one (current_archetype_storage).
|
|
const new_row = try current_archetype_storage.appendUndefined(entities.allocator);
|
|
const old_ptr = entities.entities.get(entity).?;
|
|
|
|
// Update the storage/columns for all of the existing components on the entity.
|
|
current_archetype_storage.set(new_row, entities.id_name, entity);
|
|
for (prev_archetype.columns) |column| {
|
|
if (column.name == entities.id_name) continue;
|
|
for (current_archetype_storage.columns) |corresponding| {
|
|
if (column.name == corresponding.name) {
|
|
const old_value_raw = prev_archetype.getDynamic(old_ptr.row_index, column.name, column.size, column.alignment, column.type_id).?;
|
|
current_archetype_storage.setDynamic(new_row, corresponding.name, old_value_raw, corresponding.alignment, corresponding.type_id);
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
// Update the storage/column for the new component.
|
|
current_archetype_storage.set(new_row, name_id, component);
|
|
|
|
prev_archetype.remove(old_ptr.row_index);
|
|
if (prev_archetype.len > 0) {
|
|
const swapped_entity_id = prev_archetype.get(old_ptr.row_index, entities.id_name, EntityID).?;
|
|
try entities.entities.put(entities.allocator, swapped_entity_id, old_ptr);
|
|
}
|
|
|
|
try entities.entities.put(entities.allocator, entity, Pointer{
|
|
.archetype_index = archetype_idx,
|
|
.row_index = new_row,
|
|
});
|
|
return;
|
|
}
|
|
|
|
/// Sets the named component to the specified value for the given entity,
|
|
/// moving the entity from it's current archetype table to the new archetype
|
|
/// table if required.
|
|
///
|
|
/// For tags, set component.len = 0 and alignment = 1
|
|
pub fn setComponentDynamic(
|
|
entities: *Self,
|
|
entity: EntityID,
|
|
name_id: StringTable.Index,
|
|
component: []const u8,
|
|
alignment: u16,
|
|
type_id: u32,
|
|
) !void {
|
|
const prev_archetype_idx = entities.entities.get(entity).?.archetype_index;
|
|
var prev_archetype = &entities.archetypes.items[prev_archetype_idx];
|
|
var archetype: ?*Archetype = if (prev_archetype.hasComponent(name_id)) prev_archetype else null;
|
|
var archetype_idx: u32 = if (archetype != null) prev_archetype_idx else 0;
|
|
|
|
if (archetype == null) {
|
|
// TODO: eliminate the need for allocation and sorting here, since this can occur
|
|
// if an archetype already exists (found_existing case below)
|
|
const columns = try entities.allocator.alloc(Archetype.Column, prev_archetype.columns.len + 1);
|
|
@memcpy(columns[0 .. columns.len - 1], prev_archetype.columns);
|
|
for (columns) |*column| {
|
|
column.values = undefined;
|
|
}
|
|
columns[columns.len - 1] = .{
|
|
.name = name_id,
|
|
.type_id = type_id,
|
|
.size = @intCast(component.len),
|
|
.alignment = alignment,
|
|
.values = undefined,
|
|
};
|
|
std.sort.pdq(Archetype.Column, columns, {}, byTypeId);
|
|
|
|
const archetype_entry = try entities.archetypeOrPut(columns);
|
|
if (!archetype_entry.found_existing) {
|
|
// Update prev_archetype pointer, as it would now be invalidated due to the allocation
|
|
prev_archetype = &entities.archetypes.items[prev_archetype_idx];
|
|
|
|
archetype_entry.ptr.* = .{
|
|
.len = 0,
|
|
.capacity = 0,
|
|
.columns = columns,
|
|
.component_names = entities.component_names,
|
|
.hash = archetype_entry.hash,
|
|
};
|
|
} else {
|
|
entities.allocator.free(columns);
|
|
}
|
|
archetype = archetype_entry.ptr;
|
|
archetype_idx = archetype_entry.index;
|
|
}
|
|
|
|
// Either new storage (if the entity moved between storage tables due to having a new
|
|
// component) or the prior storage (if the entity already had the component and it's value
|
|
// is merely being updated.)
|
|
var current_archetype_storage = archetype.?;
|
|
|
|
if (archetype_idx == prev_archetype_idx) {
|
|
// Update the value of the existing component of the entity.
|
|
const ptr = entities.entities.get(entity).?;
|
|
current_archetype_storage.setDynamic(ptr.row_index, name_id, component, alignment, type_id);
|
|
return;
|
|
}
|
|
|
|
// Copy to all component values for our entity from the old archetype storage (archetype)
|
|
// to the new one (current_archetype_storage).
|
|
const new_row = try current_archetype_storage.appendUndefined(entities.allocator);
|
|
const old_ptr = entities.entities.get(entity).?;
|
|
|
|
// Update the storage/columns for all of the existing components on the entity.
|
|
current_archetype_storage.set(new_row, entities.id_name, entity);
|
|
for (prev_archetype.columns) |column| {
|
|
if (column.name == entities.id_name) continue;
|
|
for (current_archetype_storage.columns) |corresponding| {
|
|
if (column.name == corresponding.name) {
|
|
const old_value_raw = prev_archetype.getDynamic(old_ptr.row_index, column.name, column.size, column.alignment, column.type_id).?;
|
|
current_archetype_storage.setDynamic(new_row, corresponding.name, old_value_raw, corresponding.alignment, corresponding.type_id);
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
// Update the storage/column for the new component.
|
|
current_archetype_storage.setDynamic(new_row, name_id, component, alignment, type_id);
|
|
|
|
prev_archetype.remove(old_ptr.row_index);
|
|
if (prev_archetype.len > 0) {
|
|
const swapped_entity_id = prev_archetype.get(old_ptr.row_index, entities.id_name, EntityID).?;
|
|
try entities.entities.put(entities.allocator, swapped_entity_id, old_ptr);
|
|
}
|
|
|
|
try entities.entities.put(entities.allocator, entity, Pointer{
|
|
.archetype_index = archetype_idx,
|
|
.row_index = new_row,
|
|
});
|
|
return;
|
|
}
|
|
|
|
/// Gets the named component of the given type.
|
|
/// Returns null if the component does not exist on the entity.
|
|
pub fn getComponent(
|
|
entities: *Self,
|
|
entity: EntityID,
|
|
// TODO: cleanup comptime
|
|
comptime namespace_name: std.meta.FieldEnum(@TypeOf(all_components)),
|
|
comptime component_name: std.meta.FieldEnum(@TypeOf(@field(all_components, @tagName(namespace_name)))),
|
|
) ?@field(
|
|
@field(all_components, @tagName(namespace_name)),
|
|
@tagName(component_name),
|
|
).type {
|
|
// TODO: cleanup comptime
|
|
const Component = comptime @field(
|
|
@field(all_components, @tagName(namespace_name)),
|
|
@tagName(component_name),
|
|
).type;
|
|
|
|
const name_str = @tagName(namespace_name) ++ "." ++ @tagName(component_name);
|
|
const name_id = entities.component_names.index(name_str) orelse return null;
|
|
|
|
var archetype = entities.archetypeByID(entity);
|
|
const ptr = entities.entities.get(entity).?;
|
|
|
|
return archetype.get(ptr.row_index, name_id, Component);
|
|
}
|
|
|
|
/// Gets the named component of the given type.
|
|
/// Returns null if the component does not exist on the entity.
|
|
///
|
|
/// For tags, set size = 0 and alignment = 1
|
|
pub fn getComponentDynamic(
|
|
entities: *Self,
|
|
entity: EntityID,
|
|
name_id: StringTable.Index,
|
|
size: u32,
|
|
alignment: u16,
|
|
type_id: u32,
|
|
) ?[]u8 {
|
|
var archetype = entities.archetypeByID(entity);
|
|
const ptr = entities.entities.get(entity).?;
|
|
return archetype.getDynamic(ptr.row_index, name_id, size, alignment, type_id);
|
|
}
|
|
|
|
/// Removes the named component from the entity, or noop if it doesn't have such a component.
|
|
pub fn removeComponent(
|
|
entities: *Self,
|
|
entity: EntityID,
|
|
// TODO: cleanup comptime
|
|
comptime namespace_name: std.meta.FieldEnum(@TypeOf(all_components)),
|
|
comptime component_name: std.meta.FieldEnum(@TypeOf(@field(all_components, @tagName(namespace_name)))),
|
|
) !void {
|
|
const name_str = @tagName(namespace_name) ++ "." ++ @tagName(component_name);
|
|
const name_id = try entities.component_names.indexOrPut(entities.allocator, name_str);
|
|
return entities.removeComponentDynamic(entity, name_id);
|
|
}
|
|
|
|
/// Removes the named component from the entity, or noop if it doesn't have such a component.
|
|
pub fn removeComponentDynamic(
|
|
entities: *Self,
|
|
entity: EntityID,
|
|
name_id: StringTable.Index,
|
|
) !void {
|
|
const prev_archetype_idx = entities.entities.get(entity).?.archetype_index;
|
|
var prev_archetype = &entities.archetypes.items[prev_archetype_idx];
|
|
var archetype: ?*Archetype = if (prev_archetype.hasComponent(name_id)) prev_archetype else return;
|
|
var archetype_idx: u32 = if (archetype != null) prev_archetype_idx else 0;
|
|
|
|
// Determine which archetype the entity will move to.
|
|
// TODO: eliminate this allocation in the found_existing case below
|
|
const columns = try entities.allocator.alloc(Archetype.Column, prev_archetype.columns.len - 1);
|
|
var i: usize = 0;
|
|
for (prev_archetype.columns) |old_column| {
|
|
if (old_column.name == name_id) continue;
|
|
columns[i] = old_column;
|
|
columns[i].values = undefined;
|
|
i += 1;
|
|
}
|
|
|
|
const archetype_entry = try entities.archetypeOrPut(columns);
|
|
if (!archetype_entry.found_existing) {
|
|
// Update prev_archetype pointer, as it would now be invalidated due to the allocation
|
|
prev_archetype = &entities.archetypes.items[prev_archetype_idx];
|
|
|
|
archetype_entry.ptr.* = .{
|
|
.len = 0,
|
|
.capacity = 0,
|
|
.columns = columns,
|
|
.component_names = entities.component_names,
|
|
.hash = archetype_entry.hash,
|
|
};
|
|
} else {
|
|
entities.allocator.free(columns);
|
|
}
|
|
archetype = archetype_entry.ptr;
|
|
archetype_idx = archetype_entry.index;
|
|
|
|
var current_archetype_storage = archetype.?;
|
|
|
|
// Copy all component values for our entity from the old archetype storage (archetype)
|
|
// to the new one (current_archetype_storage).
|
|
const new_row = try current_archetype_storage.appendUndefined(entities.allocator);
|
|
const old_ptr = entities.entities.get(entity).?;
|
|
|
|
// Update the storage/columns for all of the existing components on the entity that exist in
|
|
// the new archetype table (i.e. excluding the component to remove.)
|
|
current_archetype_storage.set(new_row, entities.id_name, entity);
|
|
for (current_archetype_storage.columns) |column| {
|
|
if (column.name == entities.id_name) continue;
|
|
for (prev_archetype.columns) |corresponding| {
|
|
if (column.name == corresponding.name) {
|
|
const old_value_raw = prev_archetype.getDynamic(old_ptr.row_index, column.name, column.size, column.alignment, column.type_id).?;
|
|
current_archetype_storage.setDynamic(new_row, column.name, old_value_raw, column.alignment, column.type_id);
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
prev_archetype.remove(old_ptr.row_index);
|
|
if (prev_archetype.len > 0) {
|
|
const swapped_entity_id = prev_archetype.get(old_ptr.row_index, entities.id_name, EntityID).?;
|
|
try entities.entities.put(entities.allocator, swapped_entity_id, old_ptr);
|
|
}
|
|
|
|
try entities.entities.put(entities.allocator, entity, Pointer{
|
|
.archetype_index = archetype_idx,
|
|
.row_index = new_row,
|
|
});
|
|
}
|
|
|
|
// Queries for archetypes matching the given query.
|
|
pub fn query(
|
|
entities: *Self,
|
|
q: Query,
|
|
) ArchetypeIterator(all_components) {
|
|
return ArchetypeIterator(all_components).init(entities, q);
|
|
}
|
|
|
|
// TODO: queryDynamic
|
|
|
|
// TODO: iteration over all entities
|
|
// TODO: iteration over all entities with components (U, V, ...)
|
|
// TODO: iteration over all entities with type T
|
|
// TODO: iteration over all entities with type T and components (U, V, ...)
|
|
|
|
// TODO: "indexes" - a few ideas we could express:
|
|
//
|
|
// * Graph relations index: e.g. parent-child entity relations for a DOM / UI / scene graph.
|
|
// * Spatial index: "give me all entities within 5 units distance from (x, y, z)"
|
|
// * Generic index: "give me all entities where arbitraryFunction(e) returns true"
|
|
//
|
|
|
|
// TODO: ability to remove archetype entirely, deleting all entities in it
|
|
// TODO: ability to remove archetypes with no entities (garbage collection)
|
|
};
|
|
}
|
|
|
|
// TODO: move this type somewhere else
|
|
pub fn ArchetypeIterator(comptime all_components: anytype) type {
|
|
const EntitiesT = Entities(all_components);
|
|
return struct {
|
|
entities: *EntitiesT,
|
|
query: EntitiesT.Query,
|
|
index: usize,
|
|
|
|
const Self = @This();
|
|
|
|
pub fn init(entities: *EntitiesT, query: EntitiesT.Query) Self {
|
|
return Self{
|
|
.entities = entities,
|
|
.query = query,
|
|
.index = 0,
|
|
};
|
|
}
|
|
|
|
// TODO: all_components is a superset of queried items, not type-safe.
|
|
pub fn next(iter: *Self) ?comp.ArchetypeSlicer(all_components) {
|
|
while (iter.index < iter.entities.archetypes.items.len) {
|
|
const archetype = &iter.entities.archetypes.items[iter.index];
|
|
iter.index += 1;
|
|
if (iter.match(archetype)) return comp.ArchetypeSlicer(all_components){ .archetype = archetype };
|
|
}
|
|
return null;
|
|
}
|
|
|
|
pub fn match(iter: *Self, consideration: *Archetype) bool {
|
|
if (consideration.len == 0) return false;
|
|
var buf: [2048]u8 = undefined;
|
|
switch (iter.query) {
|
|
.all => {
|
|
for (iter.query.all) |namespace| {
|
|
switch (namespace) {
|
|
inline else => |components| {
|
|
for (components) |component| {
|
|
if (@typeInfo(@TypeOf(component)).Enum.fields.len == 0) continue;
|
|
const name = switch (component) {
|
|
inline else => |c| std.fmt.bufPrint(&buf, "{s}.{s}", .{ @tagName(namespace), @tagName(c) }) catch break,
|
|
};
|
|
const name_id = iter.entities.componentName(name);
|
|
var has_column = false;
|
|
for (consideration.columns) |column| {
|
|
if (column.name == name_id) {
|
|
has_column = true;
|
|
break;
|
|
}
|
|
}
|
|
if (!has_column) return false;
|
|
}
|
|
},
|
|
}
|
|
}
|
|
return true;
|
|
},
|
|
.any => @panic("TODO"),
|
|
}
|
|
}
|
|
};
|
|
}
|
|
|
|
test {
|
|
std.testing.refAllDeclsRecursive(Entities(.{}));
|
|
}
|
|
|
|
// TODO: require "one big registration of components" even when using dynamic API? Would alleviate
|
|
// some of the confusion about using world.componentName, and would perhaps improve GUI editor
|
|
// compatibility in practice.
|
|
test "dynamic" {
|
|
const allocator = testing.allocator;
|
|
const asBytes = std.mem.asBytes;
|
|
|
|
const Location = struct {
|
|
x: f32 = 0,
|
|
y: f32 = 0,
|
|
z: f32 = 0,
|
|
};
|
|
|
|
const Rotation = struct { degrees: f32 };
|
|
|
|
// Create a world.
|
|
var world = try Entities(.{}).init(allocator);
|
|
defer world.deinit();
|
|
|
|
// Create an entity and add dynamic components.
|
|
const player1 = try world.new();
|
|
try world.setComponentDynamic(player1, world.componentName("game.name"), "jane", @alignOf([]const u8), 100);
|
|
try world.setComponentDynamic(player1, world.componentName("game.name"), "joey", @alignOf([]const u8), 100);
|
|
try world.setComponentDynamic(player1, world.componentName("game.location"), asBytes(&Location{ .x = 1, .y = 2, .z = 3 }), @alignOf(Location), 101);
|
|
|
|
// Get components
|
|
try testing.expect(world.getComponentDynamic(player1, world.componentName("game.rotation"), @sizeOf(Rotation), @alignOf(Rotation), 102) == null);
|
|
const loc = world.getComponentDynamic(player1, world.componentName("game.location"), @sizeOf(Location), @alignOf(Location), 101);
|
|
try testing.expectEqual(Location{ .x = 1, .y = 2, .z = 3 }, std.mem.bytesToValue(Location, @as(*[12]u8, @ptrCast(loc.?.ptr))));
|
|
try testing.expectEqualStrings(world.getComponentDynamic(player1, world.componentName("game.name"), 4, @alignOf([]const u8), 100).?, "joey");
|
|
}
|
|
|
|
test "entity ID size" {
|
|
try testing.expectEqual(8, @sizeOf(EntityID));
|
|
}
|
|
|
|
test "example" {
|
|
const allocator = testing.allocator;
|
|
|
|
const Location = struct {
|
|
x: f32 = 0,
|
|
y: f32 = 0,
|
|
z: f32 = 0,
|
|
};
|
|
|
|
const Rotation = struct { degrees: f32 };
|
|
|
|
const all_components = ComponentTypesByName(.{
|
|
struct {
|
|
pub const name = .game;
|
|
pub const components = .{
|
|
.{ .name = .name, .type = []const u8 },
|
|
.{ .name = .location, .type = Location },
|
|
.{ .name = .rotation, .type = Rotation },
|
|
};
|
|
},
|
|
}){};
|
|
|
|
//-------------------------------------------------------------------------
|
|
// Create a world.
|
|
var world = try Entities(all_components).init(allocator);
|
|
defer world.deinit();
|
|
|
|
//-------------------------------------------------------------------------
|
|
// Create first player entity.
|
|
const player1 = try world.new();
|
|
try world.setComponent(player1, .game, .name, "jane"); // add .name component
|
|
try world.setComponent(player1, .game, .name, "joe"); // update .name component
|
|
try world.setComponent(player1, .game, .location, .{}); // add .location component
|
|
|
|
// Create second player entity.
|
|
const player2 = try world.new();
|
|
try testing.expect(world.getComponent(player2, .game, .location) == null);
|
|
try testing.expect(world.getComponent(player2, .game, .name) == null);
|
|
|
|
//-------------------------------------------------------------------------
|
|
// We can add new components at will.
|
|
try world.setComponent(player2, .game, .rotation, .{ .degrees = 90 });
|
|
try world.setComponent(player2, .game, .rotation, .{ .degrees = 91 }); // update .rotation component
|
|
try testing.expect(world.getComponent(player1, .game, .rotation) == null); // player1 has no rotation
|
|
|
|
//-------------------------------------------------------------------------
|
|
// Remove a component from any entity at will.
|
|
// TODO: add a way to "cleanup" truly unused archetypes
|
|
try world.removeComponent(player1, .game, .name);
|
|
try world.removeComponent(player1, .game, .location);
|
|
// try world.removeComponent(player1, .game, .location); // doesn't exist? no problem.
|
|
|
|
//-------------------------------------------------------------------------
|
|
// Introspect things.
|
|
//
|
|
// Archetype IDs, these are our "table names" - they're just hashes of all the component names
|
|
// within the archetype table.
|
|
const archetypes = world.archetypes.items;
|
|
try testing.expectEqual(@as(usize, 5), archetypes.len);
|
|
// TODO: better table names, based on columns
|
|
// try testing.expectEqual(@as(u64, 0), archetypes[0].hash);
|
|
// try testing.expectEqual(@as(u32, 4), archetypes[1].name);
|
|
// try testing.expectEqual(@as(u32, 14), archetypes[2].name);
|
|
// try testing.expectEqual(@as(u32, 28), archetypes[3].name);
|
|
// try testing.expectEqual(@as(u32, 14), archetypes[4].name);
|
|
|
|
// Number of (living) entities stored in an archetype table.
|
|
try testing.expectEqual(@as(usize, 1), archetypes[0].len);
|
|
try testing.expectEqual(@as(usize, 0), archetypes[1].len);
|
|
try testing.expectEqual(@as(usize, 0), archetypes[2].len);
|
|
try testing.expectEqual(@as(usize, 1), archetypes[3].len);
|
|
|
|
// Resolve archetype by entity ID and print column names
|
|
const columns = world.archetypeByID(player2).columns;
|
|
try testing.expectEqual(@as(usize, 2), columns.len);
|
|
try testing.expectEqualStrings("id", world.component_names.string(columns[0].name));
|
|
try testing.expectEqualStrings("game.rotation", world.component_names.string(columns[1].name));
|
|
|
|
//-------------------------------------------------------------------------
|
|
// Query for archetypes that have all of the given components
|
|
var iter = world.query(.{ .all = &.{
|
|
.{ .game = &.{.rotation} },
|
|
} });
|
|
while (iter.next()) |archetype| {
|
|
const ids = archetype.slice(.entity, .id);
|
|
try testing.expectEqual(@as(usize, 1), ids.len);
|
|
try testing.expectEqual(player2, ids[0]);
|
|
}
|
|
|
|
// TODO: iterating components an entity has not currently supported.
|
|
|
|
//-------------------------------------------------------------------------
|
|
// Remove an entity whenever you wish. Just be sure not to try and use it later!
|
|
try world.remove(player1);
|
|
}
|
|
|
|
test "empty_world" {
|
|
const allocator = testing.allocator;
|
|
//-------------------------------------------------------------------------
|
|
var world = try Entities(.{}).init(allocator);
|
|
// Create a world.
|
|
defer world.deinit();
|
|
}
|
|
|
|
test "many entities" {
|
|
const allocator = testing.allocator;
|
|
|
|
const Location = struct {
|
|
x: f32 = 0,
|
|
y: f32 = 0,
|
|
z: f32 = 0,
|
|
};
|
|
|
|
const Rotation = struct { degrees: f32 };
|
|
|
|
const all_components = ComponentTypesByName(.{
|
|
struct {
|
|
pub const name = .game;
|
|
pub const components = .{
|
|
.{ .name = .name, .type = []const u8 },
|
|
.{ .name = .location, .type = Location },
|
|
.{ .name = .rotation, .type = Rotation },
|
|
};
|
|
},
|
|
}){};
|
|
|
|
// Create many entities
|
|
var world = try Entities(all_components).init(allocator);
|
|
defer world.deinit();
|
|
for (0..8192) |_| {
|
|
const player = try world.new();
|
|
try world.setComponent(player, .game, .name, "jane");
|
|
try world.setComponent(player, .game, .location, .{});
|
|
}
|
|
|
|
// Confirm the number of archetypes created
|
|
const archetypes = world.archetypes.items;
|
|
try testing.expectEqual(@as(usize, 3), archetypes.len);
|
|
|
|
// Confirm archetypes
|
|
var columns = archetypes[0].columns;
|
|
try testing.expectEqual(@as(usize, 1), columns.len);
|
|
try testing.expectEqualStrings("id", world.component_names.string(columns[0].name));
|
|
|
|
columns = archetypes[1].columns;
|
|
try testing.expectEqual(@as(usize, 2), columns.len);
|
|
try testing.expectEqualStrings("id", world.component_names.string(columns[0].name));
|
|
try testing.expectEqualStrings("game.name", world.component_names.string(columns[1].name));
|
|
|
|
columns = archetypes[2].columns;
|
|
try testing.expectEqual(@as(usize, 3), columns.len);
|
|
try testing.expectEqualStrings("id", world.component_names.string(columns[0].name));
|
|
try testing.expectEqualStrings("game.name", world.component_names.string(columns[1].name));
|
|
try testing.expectEqualStrings("game.location", world.component_names.string(columns[2].name));
|
|
}
|