const std = @import("std"); const c = @import("./c.zig"); const err = @import("./error.zig"); const util = @import("./util.zig"); const Id = @import("./id.zig").Id; const Lookup = @import("./main.zig").Lookup; const World = @import("./world.zig").World; pub const EntityError = error{ /// Id is `0`. IsNone, /// Id is not valid. IsInvalid, /// Id is not an `Entity`. IsNotEntity, /// Generation doesn't match. GenMismatch, /// Entity is not alive. IsNotAlive, }; pub const EntityConfig = struct { name: ?[:0]const u8 = null, symbol: ?[:0]const u8 = null, use_low_id: bool = false, }; /// An `Entity` is an `Id` which represents a "thing" within the world. This /// could be a traditional game object, but is also able to represent other /// concepts such as component types, relationship types, systems, modules, /// resources, and anything else you can make fit. /// /// Each `Entity` can have a number of `Id`s added to it, which could be /// components (such as `Position`), zero-size tags (such as `Disabled`) or /// relationship `Pair`s (such as `.{ ChildOf, parent }`). /// /// Entities can be created using `World.new()` and deleted with `delete()`. /// When an entity is deleted it is no longer considered "alive". A world can /// contain up to 4 billion alive entities. /// /// An `Id` can be converted to an `Entity` using `Id.asEntity()` (fails if /// the id isn't an entity), and back again with `asId()` (always succeeds). pub fn Entity(comptime ctx: anytype) type { return struct { world: *World(ctx), raw: c.ecs_entity_t, const Self = @This(); /// Returns an `Entity` for the specified world and raw entity id. /// /// No safety checks are done, so if you pass an invalid id, an /// invalid `Entity` might be returned that could cause panics if /// passed to other API functions without ensuring their validity. pub fn fromRaw(world: *World(ctx), raw: c.ecs_entity_t) Self { return .{ .world = world, .raw = raw }; } /// Creates a new `Entity` in the specified world. /// May return an existing entity if one with the given name exists. /// May return an error if the entity creation failed. /// /// The `config` argument may be used to specify the `name` and /// `symbol` used to create the entity with. If an entity with the /// given name already exists, that one is modified instead. /// Does not take ownership of any of the provided values. /// /// The `add` argument is a tuple that specifies the `Id`s the entity /// is created with initially. For example: /// `.{ Position, Velocity, .{ ChildOf, parent } }` /// /// When you add components, they are default-initialized. To set /// their values you'll need to use one of the setter functions on the /// `Entity` returned from this function. pub fn new(world: *World(ctx), config: EntityConfig, add: anytype) !Self { var desc = std.mem.zeroes(c.ecs_entity_desc_t); desc.name = if (config.name) |n| n.ptr else null; desc.symbol = if (config.symbol) |s| s.ptr else null; desc.use_low_id = config.use_low_id; const meta = @typeInfo(@TypeOf(add)); if (meta != .Struct or (meta.Struct.is_tuple == false and meta.Struct.fields.len > 0)) @compileError("Expected tuple or empty struct, got '" ++ @typeName(@TypeOf(add)) ++ "'"); if (meta.Struct.fields.len > c.FLECS_ID_DESC_MAX) @compileError("Adding more than FLECS_ID_DESC_MAX ids"); inline for (add, 0..) |a, i| desc.add[i] = util.anyToId(ctx, a); const result = c.ecs_entity_init(world.raw, &desc); if (result == 0) return err.getLastErrorOrUnknown(); return Self.fromRaw(world, result); } /// Ensures this `Entity` is valid, returning an error otherwise. /// Invalid entities may cause panics when used with API functions. /// /// An `Entity` is valid if .. /// - .. it is not `0`. /// - .. it does not have dead bits set. /// - .. it does not have any `Id` flags set. /// - .. no entity with this id is alive, but this entity's generation is `0`. /// - .. an entity with this exact id and generation is alive in the world. pub fn ensureValid(self: Self) !void { // `0` is not a valid entity id. if (self.raw == 0) return EntityError.IsNone; // Entity ids should not contain data in dead zone bits. const VALID_BITS_MASK: c.ecs_entity_t = 0xFF00FFFFFFFFFFFF; if ((self.raw & ~VALID_BITS_MASK) != 0) return EntityError.IsInvalid; // Entity ids should not contain `Id` flag bits. if ((self.raw & c.ECS_ID_FLAGS_MASK) != 0) return EntityError.IsNotEntity; // Get the currently alive entity entity with the same id. // If entity is alive, the generation has to match. // If entity is not alive, the generation has to be `0`. const entity = c.ecs_get_alive(self.world.raw, self.raw); if (c.ECS_GENERATION(entity) != c.ECS_GENERATION(self.raw)) return EntityError.GenMismatch; } /// Ensures this `Entity` is alive in this world, returning an error if not. pub fn ensureAlive(self: Self) !void { if (!c.ecs_is_alive(self.world.raw, self.raw)) return EntityError.IsNotAlive; } pub fn asId(self: Self) Id(ctx) { return @bitCast(self); } pub fn getEntityId(self: Self) u32 { return @intCast(self.raw & c.ECS_ENTITY_MASK); } pub fn getGeneration(self: Self) u16 { return @intCast(c.ECS_GENERATION(self.raw)); } /// Deletes this `Entity` and all of its components. pub fn delete(self: Self) void { c.ecs_delete(self.world.raw, self.raw); } pub fn get(self: Self, comptime T: type) ?*const T { const id = Lookup(ctx, T).id; return @alignCast(@ptrCast(c.ecs_get_id(self.world.raw, self.raw, id))); } pub fn set(self: Self, comptime T: type, value: T) void { const id = Lookup(ctx, T).id; _ = c.ecs_set_id(self.world.raw, self.raw, id, @sizeOf(T), &value); } }; }