v3 renaming (bikeshedding encouraged!)

[SanderMertens]

The v3 release is getting closer, and I want to take the opportunity to clean up some of the names in the API. Areas that I think can be improved are:

• Relationship terminology (subject, object)
• Query terminology (term, predicate, subject, object, superset, subset, ...)
• more?

I'll post progress on v3 naming here, feel free to leave suggestions!

[randy408]

FLECS_FLOAT -> FLECS_TIME because it's only used for time measurement and doesn't necessarily have to be a float.

[SanderMertens]

Yup, agreed

[SanderMertens]

Done!

[nicokruger]

One of the things that has confused me a couple of times are triggers vs observers - I understand why the difference is made conceptually (triggers can be more performant because only one component), but the fact that the API allows me (in C++) to write:

ecs.trigger<ComponentA, ComponentB>()

has caused me some head scratching in the past :-)

[ebkgne]

yes I remember going through this this too :) great news about v3 BTW

[SanderMertens]

Done! I just merged a PR that merges the trigger API with the observer API: #466 (comment)

[randy408]

Using a global for ecs_os_enable_high_timer_resolution() on Windows is not enough for it to work property and its state should be tied to the world instead. Move the global to ecs_world_t and take ecs_world_t* (or its state variable) as first argument, I'll describe the issue in details:

1. World 1 created with >= 60 fps, high resolution timer is requested
2. World 2 created with no fps
3. World 2 is destroyed -> ecs_os_enable_high_timer_resolution(false) is called
4. World 1 runs without high resolution timer

Alternative scenario:

1. World 1 and World 2 created with >= 60 fps, high resolution timer is requested
2. World 2 is destroyed -> ecs_os_enable_high_timer_resolution(false) is called
3. World 1 runs without high resolution timer

I could revise the Windows implementation so it only requires a bool enabled instead of ULONG resolution, it'll lose the option of falling back to 2 ms resolution if 1 ms is not possible, but I don't think that's an issue on most platforms.

[SanderMertens]

I will change this to set the high timer resolution to a default value on first initialization of the OS API.

[SanderMertens]

Done!

[SanderMertens]

I'm going to make the following changes to query/relationship terminology:

• object => target
• subject => source
• predicate => relationship

I'll try to reduce using these terms in the API where possible, and use "first" and "second" instead when referring to the elements of a pair. For example:

ecs_filter_init(world, &f, &(ecs_filter_desc_t) {
  .terms = {{
    .first.id = Likes, .second.id = Apples
  }}
});

In parts of the API that do not exist within a context that explicitly works with pairs, using first or second could lead to confusing names. In places like these I will use the above naming, for example:

entity.get_target(flecs::ChildOf);

[SanderMertens]

I'm going to remove the usage of term in the iterator API and replace it with field. This will do two things:

• a term will unambiguously refer to an element of a query
• a field is just a value or array of values that is provided by an iterator

This will prevent confusion for the upcoming node API, where data provided by an iterator can come not just from queries, but could for example be the output of another system.

An example of what this will look like in the new API:

auto q = world.query_builder()
  .term<Position>() // queries still have terms
  .build();

q.iter([](flecs::iter& it) {
  auto pos = it.field<Position>(1);
  // iterate as usual
});

[SanderMertens]

The added argument of the get_mut function will be removed. This used to be necessary before component constructors were properly supported. An application can still use has to check if an entity has a component before calling get_mut.

[Tisten]

In our usage of flecs, we've noticed that we either have the has check before every call to get_mut, or we have a bug because we incorrectly assumed that get_mut will return null if the id didn't exist. The call to has will search for the id, and then the get_mut will do the same search once more, while as the added arg gave that info "for free", PLUS that it highlighted the fact that the function creates an id which doesn't exist without reading the documentation.

Additionally, the documentation still says that the component will be added by this operation. In this case the is_added out parameter will be set to true..

flecs/include/flecs.h

Line 2369 in b55a883

* this operation. In this case the is_added out parameter will be set to true.

I will create an issue about this documentation error. But please write a motivation for why the IMHO unclear interface and worse performance is preferred over the old API.

Sending ping to @ElementalAndy about this as well.

[SanderMertens]

There were a couple of reasons this argument was removed:

• Having to return the argument increased the complexity of the implementation. The additional branching (checking old vs. new table, checking whether the arg is not null) measurably decreased the performance of the get_mut
• The semantics of is_added were less well defined from a deferred context. You could do multiple get_mut's for the same entity/component where is_added would return true
• Older versions of Flecs didn't have component hooks (https://github.com/SanderMertens/flecs/tree/master/examples/c/entities/hooks) which meant that is_added was the only way to know when to initialize a component.
• It complicates the API. In the vast majority of scenarios (because of ctor hooks) the is_added argument was no longer necessary but it still required the extra argument.

For reference, compare the implementation of get_mut in 2.4.8:
https://github.com/SanderMertens/flecs/blob/v2.4.8/src/entity.c#L3025 and
https://github.com/SanderMertens/flecs/blob/v2.4.8/src/entity.c#L1214

And in 3.1.4:
https://github.com/SanderMertens/flecs/blob/master/src/entity.c#L943 and
https://github.com/SanderMertens/flecs/blob/master/src/entity.c#L2599

The new implementation is much simpler (and faster), and this is in part a result of the removal of is_added.

---

The call to has will search for the id, and then the get_mut will do the same search once more, while as the added arg gave that info "for free"

You will have a double search, but with the introduction of (ctor) hooks I would have expected this scenario to be much less common. You would need the has check only when you want to modify a component if it existed. I haven't encountered this in my own code, and this issue hasn't been raised by others. That's not to say I think there can't be valid scenarios that require it, but my assumption so far has been that these are uncommon, and the overhead of an occasional has is a good tradeoff with the performance gains in other, more common scenarios.

Also note that the performance overhead of get_mut used to be 19ns. In 3.1.4 has + get_mut = 3.75 + 7.5 = 11.25ns. So even if you were to compare the old API with the is_added argument, it would be slower than doing has + get_mut in the new API.

There is also a way to avoid the has check, by using an ecs_ref_t. ecs_ref_get_id costs ~2ns. It returns NULL if the component doesn't exist, and a non-const pointer if the component does exist.

Long answer 😅 but it's good that the rationale is captured somewhere. Hope that makes sense!

[randy408]

ecs_uptr_t ->ecs_uintptr_t so uintptr_t and the signed equivalent is recognized automatically when using ECS_STRUCT()? Right now I have to register the type manually.