on_player_placed_equipment does not equipment is inserted by script

[Stringweasel]

Some modders might use on_player_placed_equipment as the catch-all event to keep track of equipment changes. However, this might be misleading because it does not handle cases where equipment is changed through script, which is not explicitly mentioned in the docs. Modders might also be more inclined to use this event as well because it has more information (player) which makes it much easier to determine the entity it was inserted to than using on_equipment_inserted.

This request is to add a note to this event's docs. Something like:

Note: This event does not fire when equipment is inserted by script. Only on_equipment_inserted is fired in this instance.

This might lead to unexcepted behaviour and bugs, such as this one: https://mods.factorio.com/mod/spidertro ... 040d7c4b85

[Rseding91]

While I have no strong optioning on having/not having additional notes this reads weird to me. The event specifically as part of it's name says "player" so I don't understand how someone would be confused that it does not fire when a non-player does the action.

[curiosity]

Completely agree with Rseding, the name is self-evident.

edit: As for the linked bug, people aren't perfect infallible beings. Notnotmelon might have simply overlooked that event or the possibility that scripted action is something they need to be concerned about. No need to overreact.

[Stringweasel]

I understand and agree that it should be evident by the name that it doesn't support scripted events. And adding a note just for this little instance is a gray area at best if it's needed or not. If this won't be added that's completely fine. It depends on the goal of the docs, and how much clutter can be added to be more helpful.

The reason I think it might be missed is because it's very easy to underestimate the extent having to react to mods changing things. This is something that took me a while to fully realize. I of course knew about it, but the full extend of it took me a while to appreciate. And in this instance even an experienced modder missed a mod interaction.

And personally I like writing docs to be more explicit and helpful, and if I notice that things get overlooked then I like adding a note. Many times I went down routes where a note like this would have saved me a lot of time, and many times a note like this showed me something that I missed. So I like to put it in place for others when I can. You can of course make the argument that modders could just "be better", but it depends on the goal of the docs. And I would prefer if it also catered for modders slightly less experienced, and people that might miss it because of limtied time/sleep, etc.

But of course, it's not my docs. And the docs can't explain every possible pitfall you might step in. There is a balance, and this is only a suggestion

No need to overreact.

That's not a nice thing to say.

[Stringweasel]

A note that might fit the context better is:

Note: To catch all possible interactions with an equipment grid use on_equipment_inserted.

[curiosity]

The reason I think it might be missed is because it's very easy to underestimate the extent having to react to mods changing things. This is something that took me a while to fully realize. I of course knew about it, but the full extend of it took me a while to appreciate. And in this instance even an experienced modder missed a mod interaction.

And personally I like writing docs to be more explicit and helpful, and if I notice that things get overlooked then I like adding a note. Many times I went down routes where a note like this would have saved me a lot of time, and many times a note like this showed me something that I missed. So I like to put it in place for others when I can. You can of course make the argument that modders could just "be better", but it depends on the goal of the docs. And I would prefer if it also catered for modders slightly less experienced, and people that might miss it because of limtied time/sleep, etc.

See, that should be a chapter in a modmaking tutorial, not a footnote in the docs. You can't convey "the full extent of it" in a footnote.