Does Ark guarentee any kind of ordering with Queries?

[Tecnology73]

I'm wondering if Ark guarentees that when querying for Entities, they are returned in a consistent order (like the order they where created in).

Say I have a factory game where items move along a belt. Items at the start of the belt would have always been created first - I never reorder the items on the belt.

| 1--5--16 |

If I do something like below, will the output always be 1, 5, 16?

type BeltItem struct { ecs.RelationMarker }
type Belt struct {}

// Kinda psuedo code
belt := beltMap.NewEntity(&Belt{})

item1 := itemMap.NewEnity(&BeltItem{}, ecs.RelIdx(0, belt))
// some other entities spawn
item5 := itemMap.NewEntity(&BeltItem{}, ecs.RelIdx(0, belt))
// some other entities spawn
item16 := itemMap.NewEntity(&BeltItem{}, ecs.RelIdx(0, belt))

q := ecs.NewFilter1[BeltItem](&world).Query(ecs.RelIdx(0, belt))
for q.Next() {
	fmt.Printf("%d\n", q.Entity().ID())
}

[mlange-42]

Hi @Tecnology73,
thank you for using Ark and for reaching out!

No, like in any archetype-based ECS, there is no such guarantee.

In your example below, you should get your expected order, but you can't generalize the assumption.

Firstly, the order depends on which archetypes the entities are in. Archetypes are iterated first, and entities within archetypes are iterated in the inner loop. Secondly, the order may change if you remove entities or move them to a different archetype (i.e. if you add or remove components). This is because swap-remove is uses for efficiency. I.e. if you remove any but the last entity of an archetype, it will be replaced by the last entity of the archetype.

However, the iteration order is deterministic. This means that if you do the same operations in the same order, iteration order will be the same in any repetition.

[Tecnology73]

ahh I see. I'll have to re-think my approach then :D Thanks!

[mlange-42]

You could add a component to you belt entity, which contains a slice (or better, a ring buffer) of item entities. Then, iterate this slice/ring and access items using some MapX.

[Tecnology73]

I've currently got the BeltItem holding a reference to the next/previous BeltItem so they work like a doubly linked list. The slice/ring buffer is another way (although a bit harder given a belt can vary in length and, by extension, the number of items varies) but I was trying to see if I could come up with a way where I could just use a query for the best perf. and avoid having to jump between archtypes.

[mlange-42]

As you conveyor belts probably don't hold tens of thousands of items (just guessing), you don't need to worry about performance. Compared to other ECS implementations available for Go, Ark is really fast. See these benchmarks. Particularly regarding random access.