From e6c46e23716614473500931dbad16de9c7b36f3c Mon Sep 17 00:00:00 2001
From: abux <abuxtmk1@gmail.com>
Date: Mon, 3 Aug 2026 15:39:11 +0100
Subject: [PATCH] Improved documentation

---
 src/entity.zig |  10 +++-
 src/world.zig  | 123 ++++++++++++++++++++++++++++++++++++++-----------
 2 files changed, 105 insertions(+), 28 deletions(-)

diff --git a/src/entity.zig b/src/entity.zig
index a5696f1..1bb021e 100644
--- a/src/entity.zig
+++ b/src/entity.zig
@@ -1,9 +1,17 @@
-const std = @import("std");
+//! ----------------------------------------------------
+//! ----------------------------------------------------
 
+const std = @import("std");
 pub const IDType = u64;
 
+//
+// FIELDS
+//
+
 id: IDType,
 
+/// ----------------------------------------------------
+/// ----------------------------------------------------
 pub fn format(
     self: @This(),
     writer: *std.Io.Writer,
diff --git a/src/world.zig b/src/world.zig
index faa3df4..b1ef2f4 100644
--- a/src/world.zig
+++ b/src/world.zig
@@ -1,4 +1,5 @@
 //! ----------------------------------------------------
+//! `🗲` **Archetype ECS** `🗲`
 //! ----------------------------------------------------
 
 //
@@ -45,10 +46,12 @@ pub fn init(alloc: std.mem.Allocator) Self {
 /// ----------------------------------------------------
 /// ----------------------------------------------------
 pub fn deinit(self: *Self) void {
-    // --- ARCHETYPES ---
+    // --- FREE ARCHETYPES ---
     for (self.archetypes.items) |*arch| {
         arch.deinit();
     }
+
+    // --- # ---
     self.entity_map.deinit();
     self.archetypes.deinit(self.alloc);
     self.signature_map.deinit();
@@ -73,6 +76,18 @@ pub fn spawn(
 }
 
 /// ----------------------------------------------------
+/// # Example
+///
+/// ```zig
+/// const player = try world.spawnEntity(.{
+///     Player{},
+/// });
+///
+/// try world.addComponents(player, .{
+///     Transform{},
+///     Velocity{},
+/// });
+/// ```
 /// ----------------------------------------------------
 pub fn addComponents(
     self: *Self,
@@ -198,6 +213,16 @@ pub fn addComponents(
 }
 
 /// ----------------------------------------------------
+/// # Example
+///
+/// ```zig
+/// const player = try world.spawnEntity(.{
+///     Player{},
+///     Inventory{},
+/// });
+///
+/// if (world.getComponent(Inventory, player)) |inv| {...}
+/// ```
 /// ----------------------------------------------------
 pub fn getComponent(
     self: *Self,
@@ -210,6 +235,25 @@ pub fn getComponent(
 }
 
 /// ----------------------------------------------------
+/// # Example
+///
+/// ```zig
+/// const player = try world.spawnEntity(.{
+///     Player{},
+///     Inventory{},
+///     Transform{},
+///     Velocity{},
+/// });
+///
+/// const cmp = try world.getComponents(struct{
+///     inv: *Inventory,
+///     velocity: *Velocity,
+///     camera_target: ?*const CameraTarget,
+/// }, player);
+///
+/// cmp.velocity.value[0] += 1;
+/// if (cmp.camera_target) |ct| {...}
+/// ```
 /// ----------------------------------------------------
 pub fn getComponents(
     self: *Self,
@@ -247,6 +291,23 @@ pub fn getComponents(
 }
 
 /// ----------------------------------------------------
+/// # Example
+///
+/// ```zig
+/// const player = try world.spawnEntity(.{
+///     Player{},
+///     Inventory{},
+/// });
+///
+/// if (world.hasComponent(Inventory), player)
+///     std.debug.print("[PLAYER] Has Inventory Component\n", .{});
+/// ```
+///
+/// # Output
+///
+/// ```text
+/// [PLAYER] Has Inventory Component
+/// ```
 /// ----------------------------------------------------
 pub fn hasComponent(
     self: *Self,
@@ -370,6 +431,35 @@ pub fn spawnEntity(
     return entity;
 }
 
+/// ----------------------------------------------------
+/// # Filters
+///
+/// ```zig
+/// .with = &.{Velocity},
+/// .without = &.{ Exclude, Vehicle, Dead },
+/// ```
+///
+/// # Example
+///
+/// ```zig
+/// var query = world.query(struct {
+///   player: ?*Player,
+///   pos: *Position,
+///   vel: *Velocity,
+/// }, .{});
+/// while (query.next()) |entity| {
+///   if (entity.player) |player| {}
+/// }
+/// ```
+/// ----------------------------------------------------
+pub fn query(
+    self: *Self,
+    comptime Result: type,
+    comptime Filters: QueryFilters,
+) Query(Result, Filters) {
+    return .init(self);
+}
+
 /// ----------------------------------------------------
 /// ----------------------------------------------------
 fn createEntity(self: *Self) Entity {
@@ -384,8 +474,9 @@ fn createArchetype(
     self: *Self,
     comptime Components: type,
 ) !usize {
-    const fields =
-        std.meta.fields(Components);
+    const fields = std.meta.fields(
+        Components,
+    );
 
     var ids = try self.alloc.alloc(
         u64,
@@ -419,28 +510,6 @@ fn createArchetype(
     return self.archetypes.items.len - 1;
 }
 
-/// ----------------------------------------------------
-/// # Example
-///
-/// ```zig
-/// var query = world.query(struct {
-///   player: ?*Player,
-///   pos: *Position,
-///   vel: *Velocity,
-/// }, .{});
-/// while (query.next()) |entity| {
-///   if (entity.player) |player| {}
-/// }
-/// ```
-/// ----------------------------------------------------
-pub fn query(
-    self: *Self,
-    comptime Result: type,
-    comptime Filters: QueryFilters,
-) Query(Result, Filters) {
-    return .init(self);
-}
-
 //
 // TESTING
 //
@@ -488,7 +557,7 @@ test "basic" {
         e.transform.pos[1] += e.velocity.value[1];
 
         // --- DEBUG PLAYER ---
-        if (e.player) |player| {
+        if (e.player) |player_info| {
             std.debug.print(
                 \\({f}) PLAYER
                 \\| Name:     {s}
@@ -497,7 +566,7 @@ test "basic" {
                 \\
             , .{
                 it.entity(),
-                player.name,
+                player_info.name,
                 e.transform.pos,
                 e.transform.scale,
             });