"not-colliding-with-itself" misleading description

[Optera]

Any 2 entities that both have this option enabled on their prototype and have an identical collision mask layers list will not collide. Other collision mask options are not included in the identical layer list check. This does mean that 2 different prototypes with the same collision mask layers and this option enabled will not collide.

This doesn't reflect how the game behaves.
Setting collision_mask = {"not-colliding-with-itself"} on a combinator allows it to clip with entities that have collision_mask = nil like rail signals or train stops.

It should probably read:
Entities with this flag will not collide with entities of otherwise identical collision masks. Other collision mask options are not included in the identical layer list check. This does mean that 2 different prototypes with the same collision mask layers and this option enabled on either one or both will not collide.

Edit:
Using the object inspector makes it seem even the part about otherwise identical layers is wrong:
combinator collision mask { "not-colliding-with-itself" }
train stop collision mask { "item-layer", "object-layer", "player-layer", "water-tile" }
Do not collide with another.

[Klonan]

Any 2 entities that both have this option enabled on their prototype and have an identical collision mask layers list will not collide. Other collision mask options are not included in the identical layer list check. This does mean that 2 different prototypes with the same collision mask layers and this option enabled will not collide.

This doesn't reflect how the game behaves.
Setting collision_mask = {"not-colliding-with-itself"} on a combinator allows it to clip with entities that have collision_mask = nil like rail signals or train stops.

It should probably read:
Entities with this flag will not collide with entities of otherwise identical collision masks. Other collision mask options are not included in the identical layer list check. This does mean that 2 different prototypes with the same collision mask layers and this option enabled on either one or both will not collide.

I think you just might not be understanding how it works

The entity will do normal collision checks. If an entity has an empty collision mask, its not going to collide with anything anyway.

In the special case that both the collision masks are the same, if both entities have the 'not-colliding-with-itself' flag, then they will not collide.
That is the only case the flag does anything.

In you case, you set the combinator mask to {"not-colliding-with-itself"}. This is an empty collision mask, so it will not collide with any entities at all.

[Optera]

The entity will do normal collision checks. If an entity has an empty collision mask, its not going to collide with anything anyway.

In the special case that both the collision masks are the same, if both entities have the 'not-colliding-with-itself' flag, then they will not collide.
That is the only case the flag does anything.

In you case, you set the combinator mask to {"not-colliding-with-itself"}. This is an empty collision mask, so it will not collide with any entities at all.

Thanks that clarifies a lot.
The wiki should make it clear how collision masks work, nil being no collision at all.

Side note:
Can you copy the default collision_mask to append "not-colliding-with-itself" in data stage? reading prototype.collision_mask returns nil.

[Bilka]

Thanks that clarifies a lot.
The wiki should make it clear how collision masks work, nil being no collision at all.

That's not how it works. Nil collision mask means "not set", means "use the default". The defaults are listed at https://wiki.factorio.com/Prototype/Ent ... ision_mask.
Empty table always means empty masks. Does this need further explanation on the wiki?

Side note:
Can you copy the default collision_mask to append "not-colliding-with-itself" in data stage? reading prototype.collision_mask returns nil.

No. As said above, nil means that the game uses the default masks that are defined internally. You cannot read them anywhere in lua, so you will have to hardcode them based on the documentation.

[Optera]

That's not how it works. Nil collision mask means "not set", means "use the default". The defaults are listed at https://wiki.factorio.com/Prototype/Ent ... ision_mask.
Empty table always means empty masks. Does this need further explanation on the wiki?

Yes it does need to be explained for those who are not involved with the internals.

1) With prototypes it's always unclear if nil means use default or don't use this property.

2) The wiki doesn't say anywhere {} means no collision layers.

3 )"Any 2 entities that both have this option enabled on their prototype and have an identical collision mask layers list will not collide."
{} is not identical to { "item-layer", "object-layer", "player-layer", "water-tile"}

[Bilka]

1) With prototypes it's always unclear if nil means use default or don't use this property.

2) The wiki doesn't say anywhere {} means no collision layers.

3 )"Any 2 entities that both have this option enabled on their prototype and have an identical collision mask layers list will not collide."
{} is not identical to { "item-layer", "object-layer", "player-layer", "water-tile"}

1) Anything that has a default value gives the default value in the documentation. So I don't understand what is the issue here. Could you maybe give a concrete example?

2) Added.

3) Indeed, they are not identical. What is the issue there?

[Optera]

1) With prototypes it's always unclear if nil means use default or don't use this property.

2) The wiki doesn't say anywhere {} means no collision layers.

3 )"Any 2 entities that both have this option enabled on their prototype and have an identical collision mask layers list will not collide."
{} is not identical to { "item-layer", "object-layer", "player-layer", "water-tile"}

1) Anything that has a default value gives the default value in the documentation. So I don't understand what is the issue here. Could you maybe give a concrete example?

2) Added.

3) Indeed, they are not identical. What is the issue there?

1) any property that is optional or has some alternative like icon and icons
I just looked through the wiki and all properties I could recall setting to nil in my mods where labeled (optional).
For collision_mask to be an optional property defaulting to some values we cant see when nil is quite a departure from e.g. minable.

2) Thanks, both Erandel and myself where quite surprised by {} not throwing an error. Is it live already? I can't find it.

3) The description of "not-colliding-with-itself" talking about identical layers should also link to 2) where empty tables are explained. So the wiki won't misguide moders to think only {"not-colliding-with-itself"} was valid when it seems to be pointless and we should use just {} instead?

[Bilka]

1) any property that is optional or has some alternative like icon and icons
I just looked through the wiki and all properties I could recall setting to nil in my mods where labeled (optional) so it's probably fine.

2) Thanks, both Erandel and myself where quite surprised by {} not throwing an error. Is it live already? I can't find it.

3) The description of "not-colliding-with-itself" talking about identical layers should also link to 2) where empty tables are explained. So the wiki won't misguide moders to think only {"not-colliding-with-itself"} was valid when it seems to be pointless and we should use just {} instead?

2) + 3) It's on https://wiki.factorio.com/Types/CollisionMask, which is also where the "not-colliding-with-itself" description is located. I assume this solves 3)?

[Bilka]

1) any property that is optional or has some alternative like icon and icons
I just looked through the wiki and all properties I could recall setting to nil in my mods where labeled (optional).
For collision_mask to be an optional property defaulting to some values we cant see when nil is quite a departure from e.g. minable.

(Post was edited as I made my reply, so I'm double posting)

Okay, minable is one of things where the default (= nil) is the only way to specify a certain state (not minable). However, this is also specified in the documentation, just how collision_mask specifies its (entity specific) defaults. So I am still confused on what exactly the issue is.

[Optera]

Okay, minable is one of things where the default (= nil) is the only way to specify a certain state (not minable). However, this is also specified in the documentation, just how collision_mask specifies its (entity specific) defaults. So I am still confused on what exactly the issue is.

Are you telling me my initial assumption of nil disabling/removing optional properties is wrong as well?

[posila]

Are you telling me my initial assumption of nil disabling/removing optional properties is wrong as well?

Yes. In Lua, setting property to nil is indistinguishible from not setting it at all, so the game will interpret both cases as "use default". Lot of (maybe even most of) the optional properties were added as extensions or overrides to already existing behaviors and definitions, and default values for such properties are usually picked so that the behavior matches how things worked before the property was added (if possible). Which is also the case of collision_mask, which was added to entities in 0.9. Before that, entities were using hardcoded collision masks ... which became defaults for those entities.

Of course, if you deepcopy a table, then setting properties to nil on it has effect of resetting those properties to their default value. So it makes sense to do that.