microecs 0.4.0__tar.gz → 0.4.2__tar.gz

{microecs-0.4.0 → microecs-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: microecs
-Version: 0.4.0
+Version: 0.4.2
 Summary: MicroECS: Minimal Entity Component System (ECS) in python and numpy
 Home-page: https://gitlab.com/meehai/microecs
 License: MIT
@@ -76,7 +76,7 @@ class MotionSystem:
     def __call__(self, world: World):
         qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
-        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
+        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
@@ -114,7 +114,7 @@ for pos, color, radius in zip(qr.position, qr.color, qr.radius):     # one entit
     rl.DrawCircle(int(pos[0]), int(pos[1]), float(radius[0]), color) # per-entity by necessity (no "draw all")
 ```
 
-There are other ways to extract a single entity e.g. `qr.some_field[i]` or `e = world.get_entity(eid)`, but these are slower in the general case and should be avoided in expensive loops, like rendering, even if they are a bit more ergonomic. See benchmark below.
+For random single-entity access, `e = world.get_entity(eid)` (or `world.get_entity(qr.entity_ids[i])` to go by query position). That's slower in the general case and should be avoided in expensive loops, like rendering, even if it is a bit more ergonomic. See benchmark below. (There is no `qr.field[i]` shortcut — the entity axis is off-limits on a query result; it raises.)
 
 <details>
 <summary> Microbenchmark: ECS vs OOP on a simple physics step </summary>
@@ -124,25 +124,25 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 | pattern | ns/entity | vs OOP-scalar |
 |---|---:|---:|
 | `micro-ecs-pool-vectorized` — `for pool: pool.f[:] = pool.f + …` | 0.9 | **52× faster** |
-| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `_Field`) | 1.8 | **27× faster** |
+| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `Field`) | 1.8 | **27× faster** |
 | **`oop-scalar`** — `for o: o.x += o.vx*dt` (python floats) | 48 | 1× (baseline) |
 | `oop-numpy` — objects holding `(2,)` numpy arrays | 605 | 13× slower |
 | `micro-ecs-zip-rows` — `for p, v in zip(qr.pos, qr.vel)` | 744 | 15× slower |
 | `micro-ecs-pool-loop` — `for pool: for i: pool.f[i]` | 870 | 18× slower |
 | `micro-ecs-get-entity` — `world.get_entity(eid)` per entity | 1450 | 30× slower |
-| `micro-ecs-index` — `qr.f[i]` per entity (an `np.searchsorted` each) | 3040 | 64× slower |
 
 Three things to take from it:
 
-1. **Vectorized wins big.** Batched ops (`_Field` or per-pool) run at 1–2 ns/entity — **27–52×
+1. **Vectorized wins big.** Batched ops (`Field` or per-pool) run at 1–2 ns/entity — **27–52×
    faster** than the *fastest* OOP loop. Same for data-parallel branches: an `np.where` clamp or
    bounce is ~34× faster than a per-entity `if`.
-2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–64× slower**
+2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–30× slower**
    than idiomatic float-based OOP — because microecs is numpy-backed, so a per-entity step pays
    numpy's tiny-array overhead (`oop-numpy` shows the same ~13× tax). One unavoidable per-entity
    pass (~750 ns/entity) costs ~500× a vectorized op (~1.5 ns) and will dominate the frame.
-3. **If you must loop, loop right.** `zip`-rows (15×) < pool-loop (18×) < `get_entity` (30×) <
-   `qr.f[i]` (64× — never in a hot loop; `qr.f[i] += …` also raises, you must bind the row first).
+3. **If you must loop, loop right.** `zip`-rows (15×) < pool-loop (18×) < `get_entity` (30×).
+   For random single-entity access use `world.get_entity(qr.entity_ids[i])` — there's no `qr.f[i]`
+   shortcut (the entity axis is off-limits on a query; it raises).
 
 **Rule of thumb:** keep systems vectorized and push branches into `np.where` / `np.clip`. If a
 workload is *irreducibly* per-entity (data-dependent control flow), plain python objects beat
@@ -152,27 +152,43 @@ microecs ~15× — use them there. microecs is the right tool for **vectorizable
 
 ## How much are `Pool` and `QueryResult` numpy-like and corner cases
 
-Given `qr=world.query(A, B)`, then `qr.position` returns a `_Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
+Given `qr=world.query(A, B)`, then `qr.position` returns a `Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
 numpy array (e.g. `(N, 2)` for a `(2,)` field). It applies each op **per pool** and stitches result back.
 
 That covers elementwise math and ufuncs (e.g. `np.where`, `np.linalg.norm(..., axis=1)` etc.), broadcasting (every operand shape numpy accepts, and it raises on the ones numpy rejects). See `test/unit/test_field_numpy_parity.py` for a whole set of operations comparing both.
 
 Edge cases worth knowing:
 
-- **Not a full ndarray — these raise, never lie.** Entity-axis indexing beyond a single
-  `qr.f[i]` (`qr.f[:]`, `qr.f[2:4]`, `qr.f[mask]`, fancy), partial entity writes, and ndarray
-  methods/attrs (`.sum()`, `.mean()`, `.dtype`, `.ndim`, `.T`). Need any of these? Materialize
-  first with `qr.f.numpy()`.
+- **Not a full ndarray — these raise, never lie.** Entity-axis indexing of any kind
+  (`qr.f[i]`, `qr.f[:]`, `qr.f[2:4]`, `qr.f[mask]`, fancy), partial entity writes, and ndarray
+  methods/attrs (`.sum()`, `.mean()`, `.dtype`, `.ndim`, `.T`). Need a single entity? Use
+  `world.get_entity(qr.entity_ids[i])`. Need a real array? Materialize first with `qr.f.numpy()`.
 - **Axis-0 ops are per-pool, not global (footgun).** `np.sort` / `np.cumsum` / `np.sum` over
   `axis=0` run within each pool and reset at pool boundaries — they do **not** see all entities
   at once, so they differ from numpy. They're allowed, but if you want a global result, do
   `qr.f.numpy()` first. A reduction that collapses the entity axis is rejected when its length no
   longer matches the pool's row count.
 - **Operands must come from the same query.** Alignment is per-pool, not by flat index, so don't
-  mix a `_Field` from one `world.query(...)` into an op on another.
+  mix a `Field` from one `world.query(...)` into an op on another.
 - **Reserved field names.** A field is read back as `qr.<field>` and `entity.<field>`, so it may not
   collide with an attribute or method of `QueryResult` or `Entity` — `World(...)` rejects such a
   component at construction instead of silently shadowing it. The reserved set (source of truth:
-  `QUERY_RESULT_RESERVED_NAMES` in `query_result.py`, `ENTITY_RESERVED_NAMES` in `entity.py`):
+  `QUERY_RESULT_INTERNAL_ATTRS` in `query_result.py`, `ENTITY_INTERNAL_ATTRS` in `entity.py`):
   - from `QueryResult`: `pool_list`, `entity_ids`, `fields`, `_data`, `_len`, `_field_shapes`, `_field_dtypes`
   - from `Entity`: `entity_id`, `get_components`, `get_fields`, `to_dict`, `_eid_to_pool_ix`, `_pool_to_components`
+
+## Mutation timing: field writes are eager, structural changes are deferred
+
+One frame holds two different timings. Know which is which:
+
+- **Structural changes are lazy (command-buffered).** `add_entity`, `remove_entity`, `add_component`,
+  `remove_component` only queue a command; they take effect at the next `world.update()`. This is what
+  keeps queries stable within a tick — pools don't move under a running system.
+- **Field writes are eager.** A write through an `Entity` (`e.position = ...`, `e.position += ...`),
+  `world.set_entity_data(id, f, v)`, and the vectorized `qr.field[:] = ...` path all write straight into
+  the pool buffer and are visible immediately — no `update()` needed.
+
+So inside one tick: a freshly spawned entity is **not** visible until `update()`, but a field write on an
+already-committed entity **is** visible at once. Rule of thumb: **structure is deferred, data is live.**
+If a field write must be ordered against a spawn/despawn, do the structural change, call `update()`, then
+write.

{microecs-0.4.0 → microecs-0.4.2}/README.md

@@ -64,7 +64,7 @@ class MotionSystem:
     def __call__(self, world: World):
         qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
-        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
+        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
@@ -102,7 +102,7 @@ for pos, color, radius in zip(qr.position, qr.color, qr.radius):     # one entit
     rl.DrawCircle(int(pos[0]), int(pos[1]), float(radius[0]), color) # per-entity by necessity (no "draw all")
 ```
 
-There are other ways to extract a single entity e.g. `qr.some_field[i]` or `e = world.get_entity(eid)`, but these are slower in the general case and should be avoided in expensive loops, like rendering, even if they are a bit more ergonomic. See benchmark below.
+For random single-entity access, `e = world.get_entity(eid)` (or `world.get_entity(qr.entity_ids[i])` to go by query position). That's slower in the general case and should be avoided in expensive loops, like rendering, even if it is a bit more ergonomic. See benchmark below. (There is no `qr.field[i]` shortcut — the entity axis is off-limits on a query result; it raises.)
 
 <details>
 <summary> Microbenchmark: ECS vs OOP on a simple physics step </summary>
@@ -112,25 +112,25 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 | pattern | ns/entity | vs OOP-scalar |
 |---|---:|---:|
 | `micro-ecs-pool-vectorized` — `for pool: pool.f[:] = pool.f + …` | 0.9 | **52× faster** |
-| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `_Field`) | 1.8 | **27× faster** |
+| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `Field`) | 1.8 | **27× faster** |
 | **`oop-scalar`** — `for o: o.x += o.vx*dt` (python floats) | 48 | 1× (baseline) |
 | `oop-numpy` — objects holding `(2,)` numpy arrays | 605 | 13× slower |
 | `micro-ecs-zip-rows` — `for p, v in zip(qr.pos, qr.vel)` | 744 | 15× slower |
 | `micro-ecs-pool-loop` — `for pool: for i: pool.f[i]` | 870 | 18× slower |
 | `micro-ecs-get-entity` — `world.get_entity(eid)` per entity | 1450 | 30× slower |
-| `micro-ecs-index` — `qr.f[i]` per entity (an `np.searchsorted` each) | 3040 | 64× slower |
 
 Three things to take from it:
 
-1. **Vectorized wins big.** Batched ops (`_Field` or per-pool) run at 1–2 ns/entity — **27–52×
+1. **Vectorized wins big.** Batched ops (`Field` or per-pool) run at 1–2 ns/entity — **27–52×
    faster** than the *fastest* OOP loop. Same for data-parallel branches: an `np.where` clamp or
    bounce is ~34× faster than a per-entity `if`.
-2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–64× slower**
+2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–30× slower**
    than idiomatic float-based OOP — because microecs is numpy-backed, so a per-entity step pays
    numpy's tiny-array overhead (`oop-numpy` shows the same ~13× tax). One unavoidable per-entity
    pass (~750 ns/entity) costs ~500× a vectorized op (~1.5 ns) and will dominate the frame.
-3. **If you must loop, loop right.** `zip`-rows (15×) < pool-loop (18×) < `get_entity` (30×) <
-   `qr.f[i]` (64× — never in a hot loop; `qr.f[i] += …` also raises, you must bind the row first).
+3. **If you must loop, loop right.** `zip`-rows (15×) < pool-loop (18×) < `get_entity` (30×).
+   For random single-entity access use `world.get_entity(qr.entity_ids[i])` — there's no `qr.f[i]`
+   shortcut (the entity axis is off-limits on a query; it raises).
 
 **Rule of thumb:** keep systems vectorized and push branches into `np.where` / `np.clip`. If a
 workload is *irreducibly* per-entity (data-dependent control flow), plain python objects beat
@@ -140,27 +140,43 @@ microecs ~15× — use them there. microecs is the right tool for **vectorizable
 
 ## How much are `Pool` and `QueryResult` numpy-like and corner cases
 
-Given `qr=world.query(A, B)`, then `qr.position` returns a `_Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
+Given `qr=world.query(A, B)`, then `qr.position` returns a `Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
 numpy array (e.g. `(N, 2)` for a `(2,)` field). It applies each op **per pool** and stitches result back.
 
 That covers elementwise math and ufuncs (e.g. `np.where`, `np.linalg.norm(..., axis=1)` etc.), broadcasting (every operand shape numpy accepts, and it raises on the ones numpy rejects). See `test/unit/test_field_numpy_parity.py` for a whole set of operations comparing both.
 
 Edge cases worth knowing:
 
-- **Not a full ndarray — these raise, never lie.** Entity-axis indexing beyond a single
-  `qr.f[i]` (`qr.f[:]`, `qr.f[2:4]`, `qr.f[mask]`, fancy), partial entity writes, and ndarray
-  methods/attrs (`.sum()`, `.mean()`, `.dtype`, `.ndim`, `.T`). Need any of these? Materialize
-  first with `qr.f.numpy()`.
+- **Not a full ndarray — these raise, never lie.** Entity-axis indexing of any kind
+  (`qr.f[i]`, `qr.f[:]`, `qr.f[2:4]`, `qr.f[mask]`, fancy), partial entity writes, and ndarray
+  methods/attrs (`.sum()`, `.mean()`, `.dtype`, `.ndim`, `.T`). Need a single entity? Use
+  `world.get_entity(qr.entity_ids[i])`. Need a real array? Materialize first with `qr.f.numpy()`.
 - **Axis-0 ops are per-pool, not global (footgun).** `np.sort` / `np.cumsum` / `np.sum` over
   `axis=0` run within each pool and reset at pool boundaries — they do **not** see all entities
   at once, so they differ from numpy. They're allowed, but if you want a global result, do
   `qr.f.numpy()` first. A reduction that collapses the entity axis is rejected when its length no
   longer matches the pool's row count.
 - **Operands must come from the same query.** Alignment is per-pool, not by flat index, so don't
-  mix a `_Field` from one `world.query(...)` into an op on another.
+  mix a `Field` from one `world.query(...)` into an op on another.
 - **Reserved field names.** A field is read back as `qr.<field>` and `entity.<field>`, so it may not
   collide with an attribute or method of `QueryResult` or `Entity` — `World(...)` rejects such a
   component at construction instead of silently shadowing it. The reserved set (source of truth:
-  `QUERY_RESULT_RESERVED_NAMES` in `query_result.py`, `ENTITY_RESERVED_NAMES` in `entity.py`):
+  `QUERY_RESULT_INTERNAL_ATTRS` in `query_result.py`, `ENTITY_INTERNAL_ATTRS` in `entity.py`):
   - from `QueryResult`: `pool_list`, `entity_ids`, `fields`, `_data`, `_len`, `_field_shapes`, `_field_dtypes`
   - from `Entity`: `entity_id`, `get_components`, `get_fields`, `to_dict`, `_eid_to_pool_ix`, `_pool_to_components`
+
+## Mutation timing: field writes are eager, structural changes are deferred
+
+One frame holds two different timings. Know which is which:
+
+- **Structural changes are lazy (command-buffered).** `add_entity`, `remove_entity`, `add_component`,
+  `remove_component` only queue a command; they take effect at the next `world.update()`. This is what
+  keeps queries stable within a tick — pools don't move under a running system.
+- **Field writes are eager.** A write through an `Entity` (`e.position = ...`, `e.position += ...`),
+  `world.set_entity_data(id, f, v)`, and the vectorized `qr.field[:] = ...` path all write straight into
+  the pool buffer and are visible immediately — no `update()` needed.
+
+So inside one tick: a freshly spawned entity is **not** visible until `update()`, but a field write on an
+already-committed entity **is** visible at once. Rule of thumb: **structure is deferred, data is live.**
+If a field write must be ordered against a spawn/despawn, do the structural change, call `update()`, then
+write.

{microecs-0.4.0 → microecs-0.4.2}/microecs/__init__.py

@@ -1,10 +1,10 @@
 """init file"""
 
 from .world import World
-from .query_result import QueryResult
+from .query_result import QueryResult, Field
 from .pool import Pool
 from .entity import Entity
 from .component import Component
 from .utils import EntityId
 
-__all__ = ["World", "QueryResult", "Pool", "Component", "Entity", "EntityId"]
+__all__ = ["World", "QueryResult", "Field", "Pool", "Component", "Entity", "EntityId"]

{microecs-0.4.0 → microecs-0.4.2}/microecs/entity.py

@@ -57,7 +57,7 @@ class Entity:
         except KeyError:
             raise AttributeError(f"Entity {self.entity_id} not committed yet. Call `world.update()` (reading '{name}')")
 
-        if name not in (_fields := pool.fields):
+        if name not in (_fields := pool.fields_set):
             raise AttributeError(f"Attribute '{name}' not in entity fields: {_fields} (entity id: {self.entity_id})")
 
         return pool.data[name][pool_index]
@@ -67,6 +67,6 @@ class Entity:
             super().__setattr__(name, value)
             return
         pool, pool_index = self._eid_to_pool_ix[self.entity_id]
-        if name not in (_fields := pool.fields):
+        if name not in (_fields := pool.fields_set):
             raise AttributeError(f"Attribute '{name}' not in entity fields: {_fields} (entity id: {self.entity_id})")
         pool.data[name][pool_index] = value

{microecs-0.4.0 → microecs-0.4.2}/microecs/pool.py

@@ -8,14 +8,15 @@ class Pool:
     Pool has no concept of entity ids.
     """
     INITIAL_CAPACITY = 100
-    RESERVED_NAMES = {"size", "capacity", "fields", "shapes", "dtypes", "data"}
+    RESERVED_NAMES = {"size", "capacity", "fields", "shapes", "dtypes", "data", "fields_set"}
 
     def __init__(self, fields: list[str], shapes: list[Shape], dtypes: list[np.dtype]):
         assert len(fields) == len(shapes) == len(dtypes), (len(fields), len(shapes), len(dtypes))
-        assert not (set(fields) & Pool.RESERVED_NAMES), f"One of {fields=} in {Pool.RESERVED_NAMES}"
+        assert not ((fields_set := set(fields)) & Pool.RESERVED_NAMES), f"One of {fields=} in {Pool.RESERVED_NAMES}"
         self.fields = fields
         self.shapes = shapes
         self.dtypes = dtypes
+        self.fields_set = fields_set # useful for fast checking (e.g. in entity)
 
         self.data: dict[str, np.ndarray] = {} # the actual data is stored in dict of dynamic arrrays, one per field
         self.size = 0

{microecs-0.4.0 → microecs-0.4.2}/microecs/query_result.py

@@ -8,7 +8,8 @@ from .pool import Pool
 # Note: if QueryResult gets new fields, add them here! Otherwise the user code may overwrite them e.g. qr._len=xxx
 QUERY_RESULT_INTERNAL_ATTRS = {"pool_list", "entity_ids", "fields", "_field_shapes", "_field_dtypes", "_data", "_len"}
 
-class _Field(np.lib.mixins.NDArrayOperatorsMixin):
+class Field(np.lib.mixins.NDArrayOperatorsMixin):
+    """Field is a single field (column) from a QueryResult object obtained from world.query(...)"""
     def __init__(self, parts: list[np.ndarray]):
         self.parts = parts
         self._lens = [len(p) for p in self.parts]
@@ -22,7 +23,7 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
         return np.concatenate(self.parts) if len(self.parts) != 1 else self.parts[0]
 
     def _chunk(self, x: T, i: int) -> T:
-        if isinstance(x, _Field):
+        if isinstance(x, Field):
             return x.parts[i]
         if isinstance(x, np.ndarray) and x.ndim == len(self.shape) and x.shape[0] == self.len:
             return x[self._bounds[i]:self._bounds[i + 1]]
@@ -30,16 +31,16 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
 
     def _apply_fn_on_parts(self, fn: Callable, op_args: list, **kwargs):
         # op args can be 1 element (-qr.velocity), 2 elements (qr.position * 0.1), 3 elements (np.where(a, b, c)), etc.
-        # all of them must be chunked based on how many we have in this _Field so each subpart is called independently.
+        # all of them must be chunked based on how many we have in this Field so each subpart is called independently.
         results = []
         for i, part in enumerate(self.parts):
             pool_args = [self._chunk(x, i) for x in op_args]
-            part_result: _Field = fn(*pool_args, **kwargs)
+            part_result: Field = fn(*pool_args, **kwargs)
             # we expect f(arr(N, ...)) -> arr(N, ...) where N = number of items in the pool
             # for e.g. np.linalg.norm(velocity, axis=1) should do (N, 2) -> (N, 1) so the first axis is preserved
             assert len(part_result) == part.shape[0], f"Result: {part_result.shape} vs {part.shape}"
             results.append(part_result)
-        return _Field(results)
+        return Field(results)
 
     def __array_ufunc__(self, ufunc, method, *inputs, out=None, **kwargs):
         """wrapper for elementwise (python) primitives, e.g. qr.position[:] += 1"""
@@ -48,7 +49,7 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
         if out is None:
             return self._apply_fn_on_parts(ufunc, inputs, **kwargs)
 
-        assert len(out) == 1 and isinstance(out[0], _Field), out
+        assert len(out) == 1 and isinstance(out[0], Field), out
         for i in range(len(self.parts)):
             pool_args = [self._chunk(x, i) for x in inputs]
             ufunc(*pool_args, out=out[0].parts[i], **kwargs)
@@ -64,7 +65,7 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
             not (isinstance(key, tuple) and key and key[0] == slice(None))):
             raise TypeError("entity-axis assignment crosses pools; use [:] or [:, k] or [i][...]")
 
-        if isinstance(value, _Field):
+        if isinstance(value, Field):
             for i, part in enumerate(self.parts):
                 part[key] = value.parts[i]
             return
@@ -77,16 +78,11 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
             v[:] = chunk
 
     def __getitem__(self, key):
-        if isinstance(key, (int, np.integer)):       # qr.position[i] -> entity i's row, from its own pool
-            key = range(self.len)[key]               # numpy's exact int-index rule, for free: wraps neg, raises on OOB
-            pool_ix = int(np.searchsorted(self._bounds, key, side="right")) - 1
-            return self.parts[pool_ix][key - self._bounds[pool_ix]]
-
         if key is Ellipsis or (isinstance(key, tuple) and key and (key[0] is Ellipsis or key[0] == slice(None))):
-            return _Field([part[key] for part in self.parts])
+            return Field([part[key] for part in self.parts])
 
-        raise TypeError("Unsupported indexing. Use .numpy() for a proper array. To set items, use qr.attr[:, k]=xxx. "
-                        "For fancy indexing qr[i, 0:3, k], use qr[i][0:3, k].")
+        raise TypeError(("Only batch updates are supported, e.g. `qr.attr[:]=xxx` or `qr.attr[:, k]=xxx`. "
+                         "Use .numpy() for a proper array. For entity-level ops use `world.get_entity(eid).attr=xxx`"))
 
     def __iter__(self):
         for part in self.parts:
@@ -113,7 +109,7 @@ class QueryResult:
     def __getattr__(self, name):
         if (data := self.__dict__.get("_data")) is not None and name in data:
             # the 'or' part is in case no pools match the query and we want qr.position[:] += 1 still to work (noop)
-            return _Field(data[name] or [np.empty((0, *self._field_shapes[name]), self._field_dtypes[name])])
+            return Field(data[name] or [np.empty((0, *self._field_shapes[name]), self._field_dtypes[name])])
         raise AttributeError(f"'{name}' not part of {self.fields}")
 
     def __setattr__(self, name, value):

{microecs-0.4.0 → microecs-0.4.2}/microecs/world.py

@@ -21,8 +21,11 @@ class World:
         self.extra_metadata = extra_metadata or []
         assert isinstance(self.extra_metadata, list), type(self.extra_metadata)
         self._check_components(components)
+
+        # pools management
         self.pools: dict[PoolKey, Pool] = {}
         self.pool_to_components: dict[Pool, list[ComponentType]] = {}
+
         # components management
         self.component_names = [x.__name__ for x in components]
         self.component_types = set(components)
@@ -33,11 +36,14 @@ class World:
             c: [f.metadata["dtype"] for f in fields(c)] for c in components}
         self.component_to_field_names: dict[ComponentType, list[str]] = {
             c: [f.name for f in fields(c)] for c in components}
-        # entity id management
+        # entities management
         self._eid_to_pool_ix: dict[EntityId, tuple[Pool, int]] = {}
         self._pool_ids: dict[Pool, list[EntityId]] = {}
         self._last_id: EntityId = -1
-        self.live_entities: dict[EntityId, Entity] = {} # a cache of all live entities in 'eager' mode (before update())
+        # a dictionary of all live entities in 'eager' mode (before update()). The actual entity is created at request
+        # in get_entity, so we don't pay for the Entity object unless it's explicitly requested by the user.
+        self.live_entities: dict[EntityId, Entity | None] = {}
+
         # command buffer management. {add/remove}_{entity/component} are lazy. Taken into account after update().
         self._command_buffer: list[Callable] = []
         self._cache: dict[tuple[PoolKey, PoolKey], QueryResult] = {} # include+exclude key
@@ -58,7 +64,7 @@ class World:
         """Adds an entity to the world based on components (data->kwargs). Returns an entity id. Lazy; call update()"""
         self._check_components_against_pool(components, **kwargs)
         self._last_id += 1
-        self.live_entities[self._last_id] = Entity(self._last_id, self._eid_to_pool_ix, self.pool_to_components)
+        self.live_entities[self._last_id] = None # add the id the live_entities, but the object is created in get_entity
         self._command_buffer.append(partial(self._add_to_pool, entity_id=self._last_id,
                                             components=components, **kwargs))
         logger.debug(f"Created entity. ID: {self._last_id}. Components: {[c.__name__ for c in components]}")
@@ -73,6 +79,9 @@ class World:
     def get_entity(self, entity_id: EntityId) -> Entity:
         """Gets the entity reference given an entity id. Used for 'object-like' ops. Lazy; call world.update()"""
         assert entity_id in self.live_entities, f"Entity id: {entity_id} not in the world"
+        if self.live_entities[entity_id] is None:
+            # only instantiate on first request, so the object is not created for no reason at add_entity time.
+            self.live_entities[entity_id] = Entity(entity_id, self._eid_to_pool_ix, self.pool_to_components)
         return self.live_entities[entity_id]
 
     def set_entity_data(self, entity_id: EntityId, field_name: str, value: np.ndarray):

{microecs-0.4.0 → microecs-0.4.2}/microecs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: microecs
-Version: 0.4.0
+Version: 0.4.2
 Summary: MicroECS: Minimal Entity Component System (ECS) in python and numpy
 Home-page: https://gitlab.com/meehai/microecs
 License: MIT
@@ -76,7 +76,7 @@ class MotionSystem:
     def __call__(self, world: World):
         qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
-        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
+        # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
@@ -114,7 +114,7 @@ for pos, color, radius in zip(qr.position, qr.color, qr.radius):     # one entit
     rl.DrawCircle(int(pos[0]), int(pos[1]), float(radius[0]), color) # per-entity by necessity (no "draw all")
 ```
 
-There are other ways to extract a single entity e.g. `qr.some_field[i]` or `e = world.get_entity(eid)`, but these are slower in the general case and should be avoided in expensive loops, like rendering, even if they are a bit more ergonomic. See benchmark below.
+For random single-entity access, `e = world.get_entity(eid)` (or `world.get_entity(qr.entity_ids[i])` to go by query position). That's slower in the general case and should be avoided in expensive loops, like rendering, even if it is a bit more ergonomic. See benchmark below. (There is no `qr.field[i]` shortcut — the entity axis is off-limits on a query result; it raises.)
 
 <details>
 <summary> Microbenchmark: ECS vs OOP on a simple physics step </summary>
@@ -124,25 +124,25 @@ Benchmark: we run the same physics step `pos += vel*dt` over N=100k entities spl
 | pattern | ns/entity | vs OOP-scalar |
 |---|---:|---:|
 | `micro-ecs-pool-vectorized` — `for pool: pool.f[:] = pool.f + …` | 0.9 | **52× faster** |
-| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `_Field`) | 1.8 | **27× faster** |
+| `micro-ecs-vectorized` — `qr.f[:] = qr.f + …` (the `Field`) | 1.8 | **27× faster** |
 | **`oop-scalar`** — `for o: o.x += o.vx*dt` (python floats) | 48 | 1× (baseline) |
 | `oop-numpy` — objects holding `(2,)` numpy arrays | 605 | 13× slower |
 | `micro-ecs-zip-rows` — `for p, v in zip(qr.pos, qr.vel)` | 744 | 15× slower |
 | `micro-ecs-pool-loop` — `for pool: for i: pool.f[i]` | 870 | 18× slower |
 | `micro-ecs-get-entity` — `world.get_entity(eid)` per entity | 1450 | 30× slower |
-| `micro-ecs-index` — `qr.f[i]` per entity (an `np.searchsorted` each) | 3040 | 64× slower |
 
 Three things to take from it:
 
-1. **Vectorized wins big.** Batched ops (`_Field` or per-pool) run at 1–2 ns/entity — **27–52×
+1. **Vectorized wins big.** Batched ops (`Field` or per-pool) run at 1–2 ns/entity — **27–52×
    faster** than the *fastest* OOP loop. Same for data-parallel branches: an `np.where` clamp or
    bounce is ~34× faster than a per-entity `if`.
-2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–64× slower**
+2. **Per-entity loops are a cliff, not a tie.** Every per-entity microecs path is **15–30× slower**
    than idiomatic float-based OOP — because microecs is numpy-backed, so a per-entity step pays
    numpy's tiny-array overhead (`oop-numpy` shows the same ~13× tax). One unavoidable per-entity
    pass (~750 ns/entity) costs ~500× a vectorized op (~1.5 ns) and will dominate the frame.
-3. **If you must loop, loop right.** `zip`-rows (15×) < pool-loop (18×) < `get_entity` (30×) <
-   `qr.f[i]` (64× — never in a hot loop; `qr.f[i] += …` also raises, you must bind the row first).
+3. **If you must loop, loop right.** `zip`-rows (15×) < pool-loop (18×) < `get_entity` (30×).
+   For random single-entity access use `world.get_entity(qr.entity_ids[i])` — there's no `qr.f[i]`
+   shortcut (the entity axis is off-limits on a query; it raises).
 
 **Rule of thumb:** keep systems vectorized and push branches into `np.where` / `np.clip`. If a
 workload is *irreducibly* per-entity (data-dependent control flow), plain python objects beat
@@ -152,27 +152,43 @@ microecs ~15× — use them there. microecs is the right tool for **vectorizable
 
 ## How much are `Pool` and `QueryResult` numpy-like and corner cases
 
-Given `qr=world.query(A, B)`, then `qr.position` returns a `_Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
+Given `qr=world.query(A, B)`, then `qr.position` returns a `Field`: a view over the matching pools that behaves like one contiguous-like `(N, *e)`
 numpy array (e.g. `(N, 2)` for a `(2,)` field). It applies each op **per pool** and stitches result back.
 
 That covers elementwise math and ufuncs (e.g. `np.where`, `np.linalg.norm(..., axis=1)` etc.), broadcasting (every operand shape numpy accepts, and it raises on the ones numpy rejects). See `test/unit/test_field_numpy_parity.py` for a whole set of operations comparing both.
 
 Edge cases worth knowing:
 
-- **Not a full ndarray — these raise, never lie.** Entity-axis indexing beyond a single
-  `qr.f[i]` (`qr.f[:]`, `qr.f[2:4]`, `qr.f[mask]`, fancy), partial entity writes, and ndarray
-  methods/attrs (`.sum()`, `.mean()`, `.dtype`, `.ndim`, `.T`). Need any of these? Materialize
-  first with `qr.f.numpy()`.
+- **Not a full ndarray — these raise, never lie.** Entity-axis indexing of any kind
+  (`qr.f[i]`, `qr.f[:]`, `qr.f[2:4]`, `qr.f[mask]`, fancy), partial entity writes, and ndarray
+  methods/attrs (`.sum()`, `.mean()`, `.dtype`, `.ndim`, `.T`). Need a single entity? Use
+  `world.get_entity(qr.entity_ids[i])`. Need a real array? Materialize first with `qr.f.numpy()`.
 - **Axis-0 ops are per-pool, not global (footgun).** `np.sort` / `np.cumsum` / `np.sum` over
   `axis=0` run within each pool and reset at pool boundaries — they do **not** see all entities
   at once, so they differ from numpy. They're allowed, but if you want a global result, do
   `qr.f.numpy()` first. A reduction that collapses the entity axis is rejected when its length no
   longer matches the pool's row count.
 - **Operands must come from the same query.** Alignment is per-pool, not by flat index, so don't
-  mix a `_Field` from one `world.query(...)` into an op on another.
+  mix a `Field` from one `world.query(...)` into an op on another.
 - **Reserved field names.** A field is read back as `qr.<field>` and `entity.<field>`, so it may not
   collide with an attribute or method of `QueryResult` or `Entity` — `World(...)` rejects such a
   component at construction instead of silently shadowing it. The reserved set (source of truth:
-  `QUERY_RESULT_RESERVED_NAMES` in `query_result.py`, `ENTITY_RESERVED_NAMES` in `entity.py`):
+  `QUERY_RESULT_INTERNAL_ATTRS` in `query_result.py`, `ENTITY_INTERNAL_ATTRS` in `entity.py`):
   - from `QueryResult`: `pool_list`, `entity_ids`, `fields`, `_data`, `_len`, `_field_shapes`, `_field_dtypes`
   - from `Entity`: `entity_id`, `get_components`, `get_fields`, `to_dict`, `_eid_to_pool_ix`, `_pool_to_components`
+
+## Mutation timing: field writes are eager, structural changes are deferred
+
+One frame holds two different timings. Know which is which:
+
+- **Structural changes are lazy (command-buffered).** `add_entity`, `remove_entity`, `add_component`,
+  `remove_component` only queue a command; they take effect at the next `world.update()`. This is what
+  keeps queries stable within a tick — pools don't move under a running system.
+- **Field writes are eager.** A write through an `Entity` (`e.position = ...`, `e.position += ...`),
+  `world.set_entity_data(id, f, v)`, and the vectorized `qr.field[:] = ...` path all write straight into
+  the pool buffer and are visible immediately — no `update()` needed.
+
+So inside one tick: a freshly spawned entity is **not** visible until `update()`, but a field write on an
+already-committed entity **is** visible at once. Rule of thumb: **structure is deferred, data is live.**
+If a field write must be ordered against a spawn/despawn, do the structural change, call `update()`, then
+write.

{microecs-0.4.0 → microecs-0.4.2}/setup.py

@@ -3,7 +3,7 @@ from pathlib import Path
 from setuptools import setup, find_packages
 
 NAME = "microecs"
-VERSION = "0.4.0"
+VERSION = "0.4.2"
 DESCRIPTION = "MicroECS: Minimal Entity Component System (ECS) in python and numpy"
 URL = "https://gitlab.com/meehai/microecs"