zig/mach
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

{module,ecs}: Mach ECS becomes the Mach' module system

Browse source 
This moves the bulk of the ECS code into `src/module`. It also makes
types like `mach.ecs.EntityID` accessible at the top-level `mach.EntityID`
instead.

The motivation of this change is to make the Mach module system a
first-class property of Mach.

Signed-off-by: Stephen Gutekanst <stephen@hexops.com>
This commit is contained in:
Stephen Gutekanst 2024-04-06 14:53:06 -07:00 • committed by Stephen Gutekanst
parent 679a05faf4
commit f578e1f5e2
15 changed files with 23 additions and 52 deletions
Download patch file Download diff file Expand all files Collapse all files

301
src/module/Archetype.zig Normal file
View file

@ -0,0 +1,301 @@
//! Represents a single archetype. i.e., entities which have a specific set of components. When a
//! component is added or removed from an entity, it's archetype changes because the archetype is
//! the set of components an entity has.
//!
//! Database equivalent: a table where rows are entities and columns are components (dense storage).
const std = @import("std");
const Allocator = std.mem.Allocator;
const testing = std.testing;
const assert = std.debug.assert;
const builtin = @import("builtin");
const StringTable = @import("StringTable.zig");
const Archetype = @This();
/// Describes a single column of the archetype (table); i.e. a single type of component
pub const Column = struct {
/// The unique name of the component this column stores.
name: StringTable.Index,
/// A unique identifier for the programming-language type this column stores. In the case of Zig
/// this is a comptime type identifier. For other languages, it may be something else or simply
/// zero if unused.
///
/// This value need only uniquely identify the column type for the duration of a single build of
/// the program.
type_id: u32,
/// The size of the component this column stores.
size: u32,
/// The alignment of the component type this column stores.
alignment: u16,
/// The actual memory where the values are stored. The length/capacity is Archetype.len and
/// Archetype.capacity, as all columns in an Archetype have identical lengths/capacities.
values: []u8,
};
/// The length of the table (in-use number of rows)
len: u32,
/// The capacity of the table (total allocated number of rows)
capacity: u32,
/// Describes the columns in this table. Each column stores all rows for that column.
columns: []Column,
/// A reference to the string table that can be used to identify Column.name's
component_names: *StringTable,
/// A hash composed of all Column.name's, effectively acting as the unique name of this table.
hash: u64,
/// An index to Entities.archetypes, used in the event of a *bucket* hash collision (not a collision
/// of the .hash field) - see Entities.archetypeOrPut for details.
next: ?u32 = null,
pub fn deinit(storage: *Archetype, gpa: Allocator) void {
if (storage.capacity > 0) {
for (storage.columns) |column| gpa.free(column.values);
}
gpa.free(storage.columns);
}
/// appends a new row to this table, with all undefined values.
pub fn appendUndefined(storage: *Archetype, gpa: Allocator) !u32 {
try storage.ensureUnusedCapacity(gpa, 1);
assert(storage.len < storage.capacity);
const row_index = storage.len;
storage.len += 1;
return row_index;
}
// TODO: comptime: missing a runtime variant of this function
pub fn append(storage: *Archetype, gpa: Allocator, row: anytype) !u32 {
debugAssertRowType(storage, row);
try storage.ensureUnusedCapacity(gpa, 1);
assert(storage.len < storage.capacity);
storage.len += 1;
storage.setRow(storage.len - 1, row);
return storage.len;
}
pub fn undoAppend(storage: *Archetype) void {
storage.len -= 1;
}
/// Ensures there is enough unused capacity to store `num_rows`.
pub fn ensureUnusedCapacity(storage: *Archetype, gpa: Allocator, num_rows: usize) !void {
return storage.ensureTotalCapacity(gpa, storage.len + num_rows);
}
/// Ensures the total capacity is enough to store `new_capacity` rows total.
pub fn ensureTotalCapacity(storage: *Archetype, gpa: Allocator, new_capacity: usize) !void {
var better_capacity = storage.capacity;
if (better_capacity >= new_capacity) return;
while (true) {
better_capacity +|= better_capacity / 2 + 8;
if (better_capacity >= new_capacity) break;
}
return storage.setCapacity(gpa, better_capacity);
}
/// Sets the capacity to exactly `new_capacity` rows total
///
/// Asserts `new_capacity >= storage.len`, if you want to shrink capacity then change the len
/// yourself first.
pub fn setCapacity(storage: *Archetype, gpa: Allocator, new_capacity: usize) !void {
assert(new_capacity >= storage.len);
// TODO: ensure columns are sorted by type_id
for (storage.columns) |*column| {
const old_values = column.values;
const new_values = try gpa.alloc(u8, new_capacity * column.size);
if (storage.capacity > 0) {
@memcpy(new_values[0..old_values.len], old_values);
gpa.free(old_values);
}
column.values = new_values;
}
storage.capacity = @as(u32, @intCast(new_capacity));
}
// TODO: comptime: missing a runtime variant of this function
/// Sets the entire row's values in the table.
pub fn setRow(storage: *Archetype, row_index: u32, row: anytype) void {
debugAssertRowType(storage, row);
const fields = std.meta.fields(@TypeOf(row));
inline for (fields, 0..) |field, index| {
const ColumnType = field.type;
if (@sizeOf(ColumnType) == 0) continue;
const column = storage.columns[index];
const column_values = @as([*]ColumnType, @ptrCast(@alignCast(column.values.ptr)));
column_values[row_index] = @field(row, field.name);
}
}
/// Sets the value of the named components (columns) for the given row in the table.
pub fn set(storage: *Archetype, row_index: u32, name: StringTable.Index, component: anytype) void {
const ColumnType = @TypeOf(component);
if (@sizeOf(ColumnType) == 0) return;
if (is_debug) debugAssertColumnType(storage, storage.columnByName(name).?, @TypeOf(component));
storage.setDynamic(
row_index,
name,
std.mem.asBytes(&component),
@alignOf(@TypeOf(component)),
typeId(@TypeOf(component)),
);
}
pub fn setDynamic(storage: *Archetype, row_index: u32, name: StringTable.Index, component: []const u8, alignment: u16, type_id: u32) void {
if (is_debug) {
// TODO: improve error messages
assert(storage.len != 0 and storage.len >= row_index);
assert(storage.columnByName(name).?.type_id == type_id);
assert(storage.columnByName(name).?.size == component.len);
assert(storage.columnByName(name).?.alignment == alignment);
}
const values = storage.getColumnValuesRaw(name) orelse @panic("no such component");
const start = component.len * row_index;
@memcpy(values[start .. start + component.len], component);
}
pub fn get(storage: *Archetype, row_index: u32, name: StringTable.Index, comptime ColumnType: type) ?ColumnType {
if (@sizeOf(ColumnType) == 0) return {};
if (is_debug) debugAssertColumnType(storage, storage.columnByName(name) orelse return null, ColumnType);
const bytes = storage.getDynamic(row_index, name, @sizeOf(ColumnType), @alignOf(ColumnType), typeId(ColumnType)) orelse return null;
return @as(*ColumnType, @alignCast(@ptrCast(bytes.ptr))).*;
}
pub fn getDynamic(storage: *Archetype, row_index: u32, name: StringTable.Index, size: u32, alignment: u16, type_id: u32) ?[]u8 {
const values = storage.getColumnValuesRaw(name) orelse return null;
if (is_debug) {
// TODO: improve error messages
assert(storage.columnByName(name).?.size == size);
assert(storage.columnByName(name).?.alignment == alignment);
assert(storage.columnByName(name).?.type_id == type_id);
}
const start = size * row_index;
const end = start + size;
return values[start..end];
}
/// Swap-removes the specified row with the last row in the table.
pub fn remove(storage: *Archetype, row_index: u32) void {
if (storage.len > 1 and row_index != storage.len - 1) {
for (storage.columns) |column| {
const dstStart = column.size * row_index;
const dst = column.values[dstStart .. dstStart + column.size];
const srcStart = column.size * (storage.len - 1);
const src = column.values[srcStart .. srcStart + column.size];
@memcpy(dst, src);
}
}
storage.len -= 1;
}
/// Tells if this archetype has every one of the given components.
pub fn hasComponents(storage: *Archetype, names: []const u32) bool {
for (names) |name| {
if (!storage.hasComponent(name)) return false;
}
return true;
}
/// Tells if this archetype has a component with the specified name.
pub fn hasComponent(storage: *Archetype, name: StringTable.Index) bool {
return storage.columnByName(name) != null;
}
pub fn getColumnValues(storage: *Archetype, name: StringTable.Index, comptime ColumnType: type) ?[]ColumnType {
const values = storage.getColumnValuesRaw(name) orelse return null;
if (is_debug) debugAssertColumnType(storage, storage.columnByName(name).?, ColumnType);
var ptr = @as([*]ColumnType, @ptrCast(@alignCast(values.ptr)));
const column_values = ptr[0..storage.capacity];
return column_values;
}
pub fn getColumnValuesRaw(storage: *Archetype, name: StringTable.Index) ?[]u8 {
const column = storage.columnByName(name) orelse return null;
return column.values;
}
pub inline fn columnByName(storage: *Archetype, name: StringTable.Index) ?*Column {
for (storage.columns) |*column| {
if (column.name == name) return column;
}
return null;
}
pub const is_debug = builtin.mode == .Debug;
/// Returns a unique comptime usize integer representing the type T. Value will change across
/// different compilations.
pub fn typeId(comptime T: type) u32 {
_ = T;
return @truncate(@intFromPtr(&struct {
var x: u8 = 0;
}.x));
}
/// Asserts that T matches the type of the column.
pub inline fn debugAssertColumnType(storage: *Archetype, column: *Archetype.Column, comptime T: type) void {
if (is_debug) {
if (typeId(T) != column.type_id) std.debug.panic("unexpected type: {s} expected: {s}", .{
@typeName(T),
storage.component_names.string(column.name),
});
}
}
/// Asserts that a tuple `row` to be e.g. appended to an archetype has values that actually match
/// all of the columns of the archetype table.
pub inline fn debugAssertRowType(storage: *Archetype, row: anytype) void {
if (is_debug) {
inline for (std.meta.fields(@TypeOf(row)), 0..) |field, index| {
debugAssertColumnType(storage, &storage.columns[index], field.type);
}
}
}
// TODO: comptime refactor
pub fn Slicer(comptime all_components: anytype) type {
return struct {
archetype: *Archetype,
pub fn slice(
slicer: @This(),
// 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 Type = @field(
@field(all_components, @tagName(namespace_name)),
@tagName(component_name),
).type;
if (namespace_name == .entity and component_name == .id) {
const name_id = slicer.archetype.component_names.index("id").?;
return slicer.archetype.getColumnValues(name_id, Type).?[0..slicer.archetype.len];
}
const name = @tagName(namespace_name) ++ "." ++ @tagName(component_name);
const name_id = slicer.archetype.component_names.index(name).?;
return slicer.archetype.getColumnValues(name_id, Type).?[0..slicer.archetype.len];
}
};
}

105
src/module/StringTable.zig Normal file
View file

@ -0,0 +1,105 @@
//! Stores null-terminated strings and maps them to unique 32-bit indices.
//!
//! Lookups are omnidirectional: both (string -> index) and (index -> string) are supported
//! operations.
//!
//! The implementation is based on:
//! https://zig.news/andrewrk/how-to-use-hash-map-contexts-to-save-memory-when-doing-a-string-table-3l33
const std = @import("std");
const StringTable = @This();
string_bytes: std.ArrayListUnmanaged(u8) = .{},
/// Key is string_bytes index.
string_table: std.HashMapUnmanaged(u32, void, IndexContext, std.hash_map.default_max_load_percentage) = .{},
pub const Index = u32;
/// Returns the index of a string key, if it exists.
pub fn index(table: *StringTable, key: []const u8) ?Index {
const slice_context: SliceAdapter = .{ .string_bytes = &table.string_bytes };
const found_entry = table.string_table.getEntryAdapted(key, slice_context);
if (found_entry) |e| return e.key_ptr.*;
return null;
}
/// Returns the index of a string key, inserting if not exists.
pub fn indexOrPut(table: *StringTable, allocator: std.mem.Allocator, key: []const u8) !Index {
const slice_context: SliceAdapter = .{ .string_bytes = &table.string_bytes };
const index_context: IndexContext = .{ .string_bytes = &table.string_bytes };
const entry = try table.string_table.getOrPutContextAdapted(allocator, key, slice_context, index_context);
if (!entry.found_existing) {
entry.key_ptr.* = @intCast(table.string_bytes.items.len);
try table.string_bytes.appendSlice(allocator, key);
try table.string_bytes.append(allocator, '\x00');
}
return entry.key_ptr.*;
}
/// Returns a null-terminated string given the index
pub fn string(table: *StringTable, idx: Index) [:0]const u8 {
return std.mem.span(@as([*:0]const u8, @ptrCast(table.string_bytes.items.ptr)) + idx);
}
pub fn deinit(table: *StringTable, allocator: std.mem.Allocator) void {
table.string_bytes.deinit(allocator);
table.string_table.deinit(allocator);
}
const IndexContext = struct {
string_bytes: *std.ArrayListUnmanaged(u8),
pub fn eql(ctx: IndexContext, a: u32, b: u32) bool {
_ = ctx;
return a == b;
}
pub fn hash(ctx: IndexContext, x: u32) u64 {
const x_slice = std.mem.span(@as([*:0]const u8, @ptrCast(ctx.string_bytes.items.ptr)) + x);
return std.hash_map.hashString(x_slice);
}
};
const SliceAdapter = struct {
string_bytes: *std.ArrayListUnmanaged(u8),
pub fn eql(adapter: SliceAdapter, a_slice: []const u8, b: u32) bool {
const b_slice = std.mem.span(@as([*:0]const u8, @ptrCast(adapter.string_bytes.items.ptr)) + b);
return std.mem.eql(u8, a_slice, b_slice);
}
pub fn hash(adapter: SliceAdapter, adapted_key: []const u8) u64 {
_ = adapter;
return std.hash_map.hashString(adapted_key);
}
};
test {
const gpa = std.testing.allocator;
var table: StringTable = .{};
defer table.deinit(gpa);
const index_context: IndexContext = .{ .string_bytes = &table.string_bytes };
_ = index_context;
// "hello" -> index 0
const hello_index = try table.indexOrPut(gpa, "hello");
try std.testing.expectEqual(@as(Index, 0), hello_index);
try std.testing.expectEqual(@as(Index, 6), try table.indexOrPut(gpa, "world"));
try std.testing.expectEqual(@as(Index, 12), try table.indexOrPut(gpa, "foo"));
try std.testing.expectEqual(@as(Index, 16), try table.indexOrPut(gpa, "bar"));
try std.testing.expectEqual(@as(Index, 20), try table.indexOrPut(gpa, "baz"));
// index 0 -> "hello"
try std.testing.expectEqualStrings("hello", table.string(hello_index));
// Lookup "hello" -> index 0
try std.testing.expectEqual(hello_index, table.index("hello").?);
// Lookup "foobar" -> null
try std.testing.expectEqual(@as(?Index, null), table.index("foobar"));
}

895
src/module/entities.zig Normal file
View file

@ -0,0 +1,895 @@
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 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 = Archetype.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 = Archetype.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 = Archetype.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) ?Archetype.Slicer(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 Archetype.Slicer(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 = .{ .type = []const u8 },
.location = .{ .type = Location },
.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 = .{ .type = []const u8 },
.location = .{ .type = Location },
.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));
}

106
src/module/main.zig Normal file
View file

@ -0,0 +1,106 @@
const std = @import("std");
const mach = @import("../main.zig");
const testing = std.testing;
pub const EntityID = @import("entities.zig").EntityID;
pub const Entities = @import("entities.zig").Entities;
pub const Archetype = @import("Archetype.zig");
pub const ModSet = @import("module.zig").ModSet;
pub const Modules = @import("module.zig").Modules;
test {
std.testing.refAllDeclsRecursive(@This());
std.testing.refAllDeclsRecursive(@import("Archetype.zig"));
std.testing.refAllDeclsRecursive(@import("entities.zig"));
std.testing.refAllDeclsRecursive(@import("query.zig"));
std.testing.refAllDeclsRecursive(@import("StringTable.zig"));
}
test "entities DB" {
const allocator = testing.allocator;
const root = struct {
pub const modules = .{ Renderer, Physics };
const Physics = struct {
pointer: u8,
pub const name = .physics;
pub const components = .{
.id = .{ .type = u32 },
};
pub const global_events = .{
.tick = .{ .handler = tick },
};
fn tick(physics: *mach.ModSet(modules).Mod(Physics)) void {
_ = physics;
}
};
const Renderer = struct {
pub const name = .renderer;
pub const components = .{
.id = .{ .type = u16 },
};
pub const global_events = .{
.tick = .{ .handler = tick },
};
fn tick(
physics: *mach.ModSet(modules).Mod(Physics),
renderer: *mach.ModSet(modules).Mod(Renderer),
) void {
_ = renderer;
_ = physics;
}
};
};
//-------------------------------------------------------------------------
// Create a world.
var world: Modules(root.modules) = undefined;
try world.init(allocator);
defer world.deinit(allocator);
// Initialize module state.
var physics = &world.mod.physics;
var renderer = &world.mod.renderer;
physics.init(.{ .pointer = 123 });
_ = physics.state().pointer; // == 123
const player1 = try physics.newEntity();
const player2 = try physics.newEntity();
const player3 = try physics.newEntity();
try physics.set(player1, .id, 1001);
try renderer.set(player1, .id, 1001);
try physics.set(player2, .id, 1002);
try physics.set(player3, .id, 1003);
//-------------------------------------------------------------------------
// Querying
var iter = world.entities.query(.{ .all = &.{
.{ .physics = &.{.id} },
} });
var archetype = iter.next().?;
var ids = archetype.slice(.physics, .id);
try testing.expectEqual(@as(usize, 2), ids.len);
try testing.expectEqual(@as(usize, 1002), ids[0]);
try testing.expectEqual(@as(usize, 1003), ids[1]);
archetype = iter.next().?;
ids = archetype.slice(.physics, .id);
try testing.expectEqual(@as(usize, 1), ids.len);
try testing.expectEqual(@as(usize, 1001), ids[0]);
// TODO: can't write @as type here easily due to generic parameter, should be exposed
// ?Archetype.Slicer(all_components)
try testing.expectEqual(iter.next(), null);
//-------------------------------------------------------------------------
// Send events to modules
world.mod.renderer.sendGlobal(.tick, .{});
try world.dispatch(.{});
}

1495
src/module/module.zig Normal file
View file

File diff suppressed because it is too large Load diff

129
src/module/query.zig Normal file
View file

@ -0,0 +1,129 @@
const std = @import("std");
const testing = std.testing;
const ComponentTypesByName = @import("module.zig").ComponentTypesByName;
pub const QueryTag = enum {
any,
all,
};
/// A complex query for entities matching a given criteria
pub fn Query(comptime all_components: anytype) type {
return union(QueryTag) {
// TODO: cleanup comptime
/// Enum matching a namespace. e.g. `.game` or `.physics2d`
pub const Namespace = std.meta.FieldEnum(@TypeOf(all_components));
// TODO: cleanup comptime
/// Enum matching a component within a namespace
/// e.g. `var a: Component(.physics2d) = .location`
pub fn Component(comptime namespace: Namespace) type {
const components = @field(all_components, @tagName(namespace));
if (@typeInfo(@TypeOf(components)).Struct.fields.len == 0) return enum {};
return std.meta.FieldEnum(@TypeOf(components));
}
// TODO: cleanup comptime
/// Slice of enums matching a component within a namespace
/// e.g. `&.{.location, .rotation}`
pub fn ComponentList(comptime namespace: Namespace) type {
return []const Component(namespace);
}
// TODO: cleanup comptime
/// Tagged union of namespaces matching lists of components
/// e.g. `.physics2d = &.{ .location, .rotation }`
pub const NamespaceComponent = T: {
const namespaces = std.meta.fields(Namespace);
var fields: [namespaces.len]std.builtin.Type.UnionField = undefined;
for (namespaces, 0..) |namespace, i| {
const ns = std.meta.stringToEnum(Namespace, namespace.name).?;
fields[i] = .{
.name = namespace.name,
.type = ComponentList(ns),
.alignment = @alignOf(ComponentList(ns)),
};
}
break :T @Type(.{ .Union = .{
.layout = .Auto,
.tag_type = Namespace,
.fields = &fields,
.decls = &.{},
} });
};
/// Matches any of these components
any: []const NamespaceComponent,
/// Matches all of these components
all: []const NamespaceComponent,
};
}
test "query" {
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 = .{ .type = []const u8 },
};
},
struct {
pub const name = .physics;
pub const components = .{
.location = .{ .type = Location },
.rotation = .{ .type = Rotation },
};
},
struct {
pub const name = .renderer;
},
}){};
const Q = Query(all_components);
// Namespace type lets us select a single namespace.
try testing.expectEqual(@as(Q.Namespace, .game), .game);
try testing.expectEqual(@as(Q.Namespace, .physics), .physics);
// Component type lets us select a single component within a namespace.
try testing.expectEqual(@as(Q.Component(.physics), .location), .location);
try testing.expectEqual(@as(Q.Component(.game), .name), .name);
// ComponentList type lets us select multiple components within a namespace.
const x: Q.ComponentList(.physics) = &.{
.location,
.rotation,
};
_ = x;
// NamespaceComponent lets us select multiple components within multiple namespaces.
const y: []const Q.NamespaceComponent = &.{
.{ .physics = &.{ .location, .rotation } },
.{ .game = &.{.name} },
};
_ = y;
// Query matching entities with *any* of these components
const z: Q = .{ .any = &.{
.{ .physics = &.{ .location, .rotation } },
.{ .game = &.{.name} },
} };
_ = z;
// Query matching entities with *all* of these components.
const w: Q = .{ .all = &.{
.{ .physics = &.{ .location, .rotation } },
.{ .game = &.{.name} },
} };
_ = w;
}