Ways to query or obtain all entities of a world

[UplinkPhobia]

If I am not mistaken, there is no proper way to simply query all entities in a world, as queries require a filter to include entities.

It would be nice to be able to query all entities, whether with something like

world.Q()  # Same result as a query matching all entities

or even by allowing to iterate over the world object

for entity in world:
    pass

The lack of iterator on worlds also seems to create an infinite loop when one tries to iterate over them. Implementing an iterator or raising an error would make things clearer.

A bit further than that, this raises the question to include or not the global entity of the world. In my opinion, it seems logical that the query would not include it, while the iterator would, as the query "feels" external to the world, while the iterator is internal (someone queries about the world, but iterates on/from the world).

That's my suggestion! I hope it makes sense.

[HexDecimal]

The issue is that an entity is in a world based on being in that worlds lookup tables. A new entity, even one made with world.new_entity(), doesn't start out in any of these tables so there is nothing in the world that knows about a new entity until that entity is assigned a component, tag, or relation.

The simple workaround is to add an "IsAlive" tag to any entity you make. Then world.Q.all_of(tags=["IsAlive"]) will query all entities. Keep in mind that any all-entity queries is going to compound on Python's performance faults. Anything in the inner-loop of this kind of query will tank performance due to the nature of the query, even outside of Python, it defeats the performance benefits of ECS to iterate over all entities for any reason.

It's also difficult to justify the ability to query entities directly without any context of what they include. It'd make more sense to iterate over all the components the worlds knows of, which could include the entities which hold those components.

My real suggestion: You need reconsider what an entity is. In tcod-ecs an entity is a composition of its components, tags, and relations. You must query entities by those elements, and you can filter entities by adding more elements to them such as tags.

A bit further than that, this raises the question to include or not the global entity of the world.

world.global_ was deprecated and replaced with world[None] which doesn't have a special meaning. You can replace None with anything because this just returns the entity with the same world/uid combo. I might need to invent a new name for these such as "Entity Singleton", and maybe better examples.

If you want these special entities included then you add the extra tags needed to include them or add any tag you'd use to exclude them. They don't get special treatment since a normal unique entity is just world[object()].

The lack of iterator on worlds also seems to create an infinite loop when one tries to iterate over them. Implementing an iterator or raising an error would make things clearer.

Do you have an example of such an infinite loop? What you're suggesting doesn't have any syntax.

[UplinkPhobia]

It's also difficult to justify the ability to query entities directly without any context of what they include. It'd make more sense to iterate over all the components the worlds knows of, which could include the entities which hold those components.

My real suggestion: You need reconsider what an entity is. In tcod-ecs an entity is a composition of its components, tags, and relations. You must query entities by those elements, and you can filter entities by adding more elements to them such as tags.

You're right, after reconsidering the "meaning" of what I was trying to do, I realized that I was a bit mislead as to what I was wanting to do. I was thinking theoretically of a "what if I want entities that are "alive" and "not alive" but then I realized that whatever I select would have another component that is what I actually want to filter.

world.global_ was deprecated and replaced with world[None] which doesn't have a special meaning. You can replace None with anything because this just returns the entity with the same world/uid combo. I might need to invent a new name for these such as "Entity Singleton", and maybe better examples.

I see, thanks for the explanation. I guess this question was mostly coming out of the "need" of querying all entities, so since that first point is invalid, the question of including this "global" entity also becomes invalid.

The lack of iterator on worlds also seems to create an infinite loop when one tries to iterate over them. Implementing an iterator or raising an error would make things clearer.

Do you have an example of such an infinite loop? What you're suggesting doesn't have any syntax.

I'm simply talking about something along the line of

world = tcod.ecs.World()
for i in world:
    print(i)

>>> <Entity(uid=0)>
<Entity(uid=1)>
<Entity(uid=2)>
<Entity(uid=3)>
<Entity(uid=4)>
<Entity(uid=5)>
<Entity(uid=6)>
<Entity(uid=7)>
<Entity(uid=8)>
<Entity(uid=9)>
<Entity(uid=10)>
[...]

Instead of raising an error, it simply loops forever, going through all possible UID it seems. I'm not certain that I understand the reason, but I would guess that python infers that a World is a sequence (because of __getitem__) and tries to iterate over all available "indexes" (which are infinite since they are actually UIDs).

[HexDecimal]

for i in world:
    print(i)

Interesting! This is actually emergent behavior from implementing a __getitem__ method on World. I never intentionally added this iteration behavior. Python seems to have assumed that this is a list-like sequence when it isn't and is trying to index it that way, and of course because any object passed to __getitem__ will return a valid entity this causes an infinite loop.

I'm actually not sure what to do here yet. There is nothing in the documentation to suggest that you can or should iterate over a World object. Don't rely on this current behavior.

[HexDecimal]

Actually. NotImplementedError is for this exact thing. So I'll add that.

[HexDecimal]

I've committed a fix to main. Iterating over World now raises TypeError like when iterating over any other non-iterable object. It's a low priority to make a new release for just this fix.

Are there any other issues?

[UplinkPhobia]

I haven't noticed any other issue, this was something I observed out of randomly testing and playing around to see what I could and could not do.
I'll close the issue, thanks for the info and the fix!

[HexDecimal]

Feel free to ask about or suggest anything else.