Calling GetSingleton on a query, which has an enableable component as part of the filter, disregards the filter, e.g.
var query = SystemAPI.QueryBuilder().WithAll<Id, GhostOwnerIsLocal>().Build();
var singleId = query.GetSingleton<Id>();
will return the first Id found completely disregarding the enabledstate of the GhostOwnerIsLocal.
In fact looking at the code for GetSingleton, it expects there to be only a single chunk, so it is for the Archetype rather than the query, that the component is a singleton.
The documentation however states: A singleton component is a component of which only one instance exists that satisfies this query.
This is intended behaviour, yes. See SystemAPI.GetSingleton for detail: This component type must not implement IEnableableComponent.
Just a heads up: This is an Entities question, not a Netcode for Entities question.
True, however it doesn’t state that the query cannot have IEnableableComponents as part of the query, as in my example. Or rather it can, but their enabled state just won’t be respected.
I think it would make sense to include that information in the docs.
True, my apologies, the reason is that this was initially thought to be related to GhostOwnerIsLocal (for which I created another post) which clearly it is not.
SystemAPI.GetSingleton does not consider (by design) the enable state of the component. And that make sense, because it is the only provided API for accessing the singleton and does not allow you to specify query option.
If you want that, you need to provide you own query that consider the enable state.
But then, for the second you would had got a tons of exceptions because they will say:
'you can’t use GetSingletonEntity, TryGetSingleton or HasSingleton, on query that has enable components`
The only way to use that is to use your own wrapper around CalculateEntityCount (unfortunately)
You are correct that if the requested type T is an IEnableableComponent, you will get an error.
However if the query simply contains an IEnableableComponent as part of the query, no error is reported, it simply ignores the enabled state, as in my example.
I query for a component called Id, which is a standard component, but then the query also requires GhostOwnerIsLocal, the enabled state of which is not considered.
In entities 1.1 this would then produce an error if the query returns more than 1 match (which is the case here), but in 1.0 you just get the first match, i.e. the first entry in the (Id, GhostOwnerIsLocal) archetype chunk.
The enable state is only ignored if you use the GetSingleton. But if you use any of the TryGetSingleton or HasSingleton or TryGetSingletonEntity, where T is not an IEneableComponent, in all these cases the CalculateEntityCount is invoked.
i.e
public bool TryGetSingleton<T>(out T value)
where T : unmanaged, IComponentData
{
var hasSingleton = HasSingleton<T>();
value = hasSingleton ? GetSingleton<T>() : default;
return hasSingleton;
}
public bool HasSingleton<T>()
{
#if ENABLE_UNITY_COLLECTIONS_CHECKS || UNITY_DOTS_DEBUG
var typeIndex = TypeManager.GetTypeIndex<T>();
if (TypeManager.IsEnableable(typeIndex))
{
var typeName = typeIndex.ToFixedString();
throw new InvalidOperationException(
$"Can't call HasSingleton<{typeName}>() with enableable component type {typeName}.");
}
#endif
//THIS ONE INCLUDE THE ENABLECOMPONENT AND ANY OTHER FILTER IN THE QUERY (i.e SharedComponent)
int matchingEntityCount = CalculateEntityCount();
#if ENABLE_UNITY_COLLECTIONS_CHECKS || UNITY_DOTS_DEBUG
if (Hint.Unlikely(matchingEntityCount > 1))
{
var typeName = typeIndex.ToFixedString();
throw new InvalidOperationException(
$"HasSingleton<{typeName}>() found {matchingEntityCount} instances of {typeName}; there must only be either zero or one.");
}
#endif
return matchingEntityCount == 1;
}
So unless there is bug, the expected behaviour is that the TryGetSingleton should return false in that case. At least this is what the code should do.
But if HasSingleton does respect it and GetSingleton does not respect it, that is totally inconsistent and hence problematic.
Using the original example query:
Let’s say we have two entities A and B with the Archetype (Id, GhostOwnerIsLocal) and appearing in that order in the chunk, with GhostOwnerIsLocal enabled for B but not for A.
A call to HasSingleton would produce true in both versions 1.0 and 1.1, right? Only B’s Id is a match.
A call to GetSingleton on the other hand:
1.0: returns A’s Id
1.1: throws an exception? or maybe this has been fixed in 1.1 so it doesn’t actually throw but will instead correctly return B’s Id?
It has been designed this way for performance reason. Consider using other way to only query enableable component that is enabled like idiomatic foreach.
The feedback will be given. We were just discussing about how things work at the moment and also why.
If you think about the semantic, GetSingleton need to always returning something (apart triggering an exception if you try to get it on something it does not have the component at all (physically)).
A system that requires a singleton to exist also has probably a RequireForUpdate(query) too or the user has to check that the query has a singleton via HasSingleton anyway for consistency.
Indeed the API is a little confusing and inconsistent in some sense, but definitively makes sense that the HasSingleton return false and the TryGetSingleton return false for that query.
We have another similar example of that for SharedComponent that expect user will always check HasComponent before invoking the GetSharedComponent that will otherwise return garbage.
However, looking at your sample, you are also doing something “in the limit”: you created three entities and you are using as GetSingleton for retrieving the only enabled instance. That is really a little borderline, because the GetSingleton expect that the chunk contains only one entity in general
Looking at the code, there are some “optimised” path that does not check for any filter or enableable component.
And the other ones, does all the work almost correctly. But the GetSingletonChunk does not consider enableable component (only query filter, like shared component).
Indeed, looks like there is a bug or at least the API need clarification about how it is expected to work.
Agreed, of course it is a matter of context, which can be solved by clarifying the documentation.
As it reads now however, it suggests that the context of the singleton is the query, but in reality the context is the world.
This is also more in tune with how singletons are usually defined, but just not clear from the docs.
For a query context, GetSingle() is probably more appropriate.
It is definitely a bug :), HasSingleton should return false if GetSingleton returns an incorrect result or throws (1.1).
Should I report it via the bug tool or has it already been done?
I think it is a good idea to report the behaviour as a case. I already notified internally about that and the discussion agreed there is a need for both uniforming and changing how the GetSingleton work in general.
Please open a case for it so it is properly tracked.
