Improve README example

README.md

@@ -11,6 +11,7 @@ This library is still very much work-in-progress and not ready for use. It's ava
 
 ```zig
 const std = @import("std");
+
 const flecs = @import("flecs-zig-ble");
 const Context = flecs.Context(void);
 const World = Context.World;
@@ -26,25 +27,35 @@ pub fn main() !void {
     const world = try World.init();
     defer world.deinit();
 
+    // Register components.
     _ = try world.component(Position);
     _ = try world.component(Velocity);
 
-    _ = try world.system("Move", move, flecs.c.EcsOnUpdate, "Position, Velocity");
+    // Register a system that moves any entity that has a `Position` by `Velocity` each update.
+    _ = try world.system("Move", move, flecs.c.EcsOnUpdate, "Position, [in] Velocity");
 
-    const e = world.entity();
+    // Create an entity with both `Position` and `Velocity` already pre-added.
+    const e = try world.entity(.{ .name = "Wroom" }, .{ Position, Velocity });
+    // However the components aren't initialized, so do that here:
     e.set(Position, .{ .x = 10, .y = 20 });
     e.set(Velocity, .{ .x = 1, .y = 2 });
 
+    // Progress the world, updating it forever.
     while (world.progress(0.0)) {  }
 }
 
 fn move(it: Iter) void {
-    const pos_field = it.field(Position, 1);
-    const vel_field = it.field(Velocity, 2);
-
-    for (pos_field, vel_field) |*p, v| {
-        p.x += v.x;
-        p.y += v.y;
+    // Entities that share components are stored in the same table.
+    // This function will be called for each table that matches the query.
+    // With `field` we can grab a column from this table as a typed slice.
+    const pos_col = it.field(Position, 1);
+    const vel_col = it.field(Velocity, 2);
+
+    // Both columns have the same size, so we can iterate them at the same time.
+    // Since we want to modify `Position` we can get a pointer to the element.
+    for (pos_col, vel_col) |*pos, vel| {
+        pos.x += vel.x * it.deltaTime();
+        pos.y += vel.y * it.deltaTime();
     }
 }
 ```

src/iter.zig

@@ -33,11 +33,11 @@ pub fn Iter(comptime ctx: anytype) type {
             return (self.raw.flags & c.EcsIterIsValid) != 0;
         }
 
-        pub fn getCount(self: Self) usize {
+        pub fn count(self: Self) usize {
             return @intCast(self.raw.count);
         }
 
-        pub fn getDeltaTime(self: Self) f32 {
+        pub fn deltaTime(self: Self) f32 {
             return self.raw.delta_time;
         }
 
@@ -45,8 +45,8 @@ pub fn Iter(comptime ctx: anytype) type {
             const raw_ptr = c.ecs_field_w_size(self.raw, @sizeOf(T), @intCast(index));
             var typed_ptr: [*]T = @alignCast(@ptrCast(raw_ptr));
             const is_self = c.ecs_field_is_self(self.raw, @intCast(index));
-            const count = if (is_self) self.getCount() else 1;
-            return typed_ptr[0..count];
+            const count_ = if (is_self) self.count() else 1;
+            return typed_ptr[0..count_];
         }
 
         pub fn fieldId(self: Self, index: usize) Id {

src/test/flecs/world.zig

@@ -24,8 +24,8 @@ fn move(it: Iter) void {
     util.Probe.probeIter(it) catch unreachable;
 
     for (pos, vel) |*p, *v| {
-        p.x += v.x * it.getDeltaTime();
-        p.y += v.y * it.getDeltaTime();
+        p.x += v.x * it.deltaTime();
+        p.y += v.y * it.deltaTime();
     }
 }
 

src/test/util.zig

@@ -50,7 +50,7 @@ pub const Probe = struct {
             try expect(e != 0);
         }
 
-        for (0..it.getCount()) |i| {
+        for (0..it.count()) |i| {
             if (i + ctx.count < 256) {
                 ctx.e[i + ctx.count] = it.raw.entities[i];
             } else {
@@ -59,7 +59,7 @@ pub const Probe = struct {
                 unreachable;
             }
         }
-        ctx.count += it.getCount();
+        ctx.count += it.count();
 
         ctx.invoked += 1;
     }