Document compatibility guarantee precisely #223
Conversation
appgurueu
added
Content: Creators
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
| there could be collisions in the future. [^maintenance] | ||
| If you are forced to share a namespace with the engine (e.g. in entity definitions or item definitions), | ||
| the current convention is to prefix your fields with an underscore (`_`); | ||
| if multiple mods share the same namespace, using the mod name for namespacing is recommended. |
There was a problem hiding this comment.
Example might be good.
I.e. do we suggest _modname_foo or modname_foo (or modname.foo)? Some common mods use the latter (pipeworks, mesecons), but we might want to recommend the former.
| Hence you may have a working configuration, add a new mod enabling/using one of these new features, | ||
| and by this cause issues with existing old mods. | ||
|
|
||
| For example Luanti 5.9 allowed omitting punchers. |
There was a problem hiding this comment.
generally, both in obj:punch(...) and consequently also in the callbacks including e.g. on punchplayer (which is what breaks these mods), but i don't want to get into details too much
There was a problem hiding this comment.
Doesn't need more details, but context. "Omit punchers" without any context just sounds confusing.
| which is inevitable: The older mod needs to decide what to do in case of a missing puncher. | ||
|
|
||
| Backwards compatibility is not absolute. | ||
| Sometimes old mods or games will break because a bug has been fixed, |
There was a problem hiding this comment.
This should probably also be in the for-creators file.
There was a problem hiding this comment.
this is here deliberately - it explains to players that sometimes the engine will break content, and the solution may be to upgrade that content. like with the bone override bugfix.
There was a problem hiding this comment.
Yes, it should be here. But also in for-creators, because this info is part of the API backwards compatibility doc. Creators need to know that it is possible that bugs in (non-side) effects can be fixed.
| that world need no longer be compatible with older Luanti versions, | ||
| e.g. because compression has been upgraded or legacy serialization formats | ||
| have been upgraded to more modern ones. | ||
|
|
There was a problem hiding this comment.
Should probably mention the --migrate* and --recompress CLI features.
Also, while serialization formats are usually not deprecated, db backends are.
(((And btw., for advanced db backends, like postgres, that you only get if you (as an advanced user) explicitly enable it, you (as an advanced user) can be more easily expected to migrate, imo.)))
| (Some features however can be implemented purely on the server or on the client, | ||
| making them automatically compatible with older client and server versions respectively.) | ||
|
|
||
| Older clients should be able to connect to and be able to play on newer servers, |
There was a problem hiding this comment.
thought: this whole file is written in a specification style ("should" over "is/are" or "will") which isn't very reassuring to readers
There was a problem hiding this comment.
I would just shorten the entire section to this:
Within the same major Luanti version, the server and client (i.e. the instance that you
are using) agree to communicate on the lower feature set of the two. Whereas some features
can be purely client-side or server-side, others do depend on the counterpart. Hence, using
an equally new or more recent client version tends to result in a better experience.
| so long as they do not use any newer features they do not support. | ||
|
|
||
| This means that, so long as the game remains the same, | ||
| it is possible to safely upgrade client and server independently. |
There was a problem hiding this comment.
curiously this sentence is assertive while in practice it's more of a "mostly"
| For example Luanti 5.9 allowed omitting punchers. | ||
| Mods that were written against older versions may expect there to always be a puncher. | ||
| If a new mod now omits the puncher (as it may), this may cause a crash in an older mod, | ||
| which is inevitable: The older mod needs to decide what to do in case of a missing puncher. |
There was a problem hiding this comment.
examples are good but this may be too technical
There was a problem hiding this comment.
i just wonder if the point is clear without the example. if not, maybe we can find a better example?
| can and will be extended by adding new constants, functions or methods. | ||
| Generally, as a rule of thumb, "tables may have more fields in the future". | ||
|
|
||
| Maybe there is no `core.frobnicate` today, but there might be tomorrow. | ||
| This is why you should use your own namespaces and wrappers | ||
| and not try to "extend" engine namespaces or classes yourself - | ||
| there could be collisions in the future. [^maintenance] |
There was a problem hiding this comment.
Could we compress this this?
| can and will be extended by adding new constants, functions or methods. | |
| Generally, as a rule of thumb, "tables may have more fields in the future". | |
| Maybe there is no `core.frobnicate` today, but there might be tomorrow. | |
| This is why you should use your own namespaces and wrappers | |
| and not try to "extend" engine namespaces or classes yourself - | |
| there could be collisions in the future. [^maintenance] | |
| may include additional fields, return values or function arguments in the future. | |
| To avoid potentially sabotaging the engine API in the future, | |
| mods should only use and extend their own namespace where possible. |
| and not try to "extend" engine namespaces or classes yourself - | ||
| there could be collisions in the future. [^maintenance] | ||
| If you are forced to share a namespace with the engine (e.g. in entity definitions or item definitions), | ||
| the current convention is to prefix your fields with an underscore (`_`); |
There was a problem hiding this comment.
Redundant documentation. Please refer to lua_api.md -> Entity definition -> _custom_field.
Co-authored-by: sfan5 <[email protected]>
Probably needs @luanti-org/engine input to be safe.
I tried to structure this around the content creator and player perspective.
Originally I also wanted to have the server host perspective, but that turned out too sparse to be worthwhile.
Should be squashed.