Deprecation-to-cull schedule

[namida]

You've probably noticed that some features / some details of file formats are mentioned as "deprecated". This means - the feature is still supported, but only for the sake of maintaining compatibility with older content that hasn't had a chance to update yet.

I've decided it's time to have a proper plan around how long such features will survive until they're culled altogether, and what I've come up with is - three major releases.

This means, for example, a feature that's deprecated in V12.7.0 will remain supported for three major versions (V12.7.0 itself, plus V12.8.0 and V12.9.0), then get culled in the next major release after that (ie: V12.10.0).

I don't expect deprecations in minor versions will happen very often, but if they do, the rule is three major versions - so for example, if V12.7.1 deprecated a feature, then support would remain for three major versions (V12.8.0, V12.9.0, V12.10.0) before being culled in V12.11.0.

This means that generally speaking, you'll have between 9 months and 1 year to upgrade content whenever things get deprecated.

Level pieces themself (terrain, objects, backgrounds) are exempt from this, and currently, there is no plan to cull deprecated pieces - however, you still shouldn't use them in new levels and should try to remove them from existing ones; as firstly this may change in the future, and secondly they're deprecated for a reason - usually that they're not needed anymore (eg. exit tops being deprecated due to secondary animations), or that there's a superior / fixed replacement. Note that this exception only applies to the actual pieces themself; not to the file formats behind them, or to any other aspects of styles.

As a special case, anything that was deprecated prior to V12.6.0 (but hasn't already been culled), will be treated as if it was deprecated in V12.6.0 exactly (and thus will be culled in V12.9.0, not sooner). For example, levels that use the "RELEASE_RATE" keyword (instead of the newer "SPAWN_INTERVAL" keyword) will remain working up to V12.8.X, but will need to be adjusted for V12.9.0 - I'm introducing a feature in V12.7.0 that will automate getting levels into the most up-to-date version of the format. EDIT: I've decided on a slight change here - no deprecation-related culls, where possible, will happen until V12.10.0.

Just to clarify: All level formats other than NXLV are considered deprecated already. Taking this schedule into account, V12.8.X V12.9.X will be the last version to have any support for them. If you do not get your content converted by then, you will need to dig up old versions to do so. Likewise for LRB format replays. V12.7.0 will come with a feature to assist with getting levels upgraded if any remain that haven't been yet; and I'll look into making a tool to convert LRB replays to NXRP.

To be clear - if I forget to remove a deprecated feature or overlook it in the major release that would normally cull it, any future update may do so without warning, including minor updates. However, if I specifically, intentionally say "I'll leave this one for a bit longer", then that applies.

Finally, exceptions may occur if maintaining backwards-compatibility would be extremely messy, or if there's no practical way to do so. I'll try to avoid this as much as possible, but it may happen from time to time.

[namida]

A slight change to the above: I'm doing some general tidyups of the formats, and it will be much easier to cull it all at once instead of half in V12.9.0 and the other half in V12.10.0. So, V12.10.0 will be the first version to receive the deprecation-related culls, not V12.9.0, and it will cull everything deprecated in V12.7.0 or earlier. From V12.11.0 onwards, it will be as above.

(Why am I doing these changes? As mentioned, I feel a new editor is necessary for the best support going forward - and I'd rather avoid messy backwards compatibility code in it. So I'm getting these changes - ones that really do need to be done IMO - out of the way before the new editor becomes a thing.)

[Simon]

before the new editor

I'm happy to discuss the Nepsteditor with you, how the code is designed, and what you want to add.

Are you up for it? Then, I'll skim its codebase during the first 2 weeks of September, and we can meet on IRC afterwards.

In August, you've been super productive and valuable for the community. A full editor rewrite would consume most of your time. Let's be careful.

-- Simon

[namida]

Appreciate the offer, but there are other benefits to this as well. Firstly - it's more practice with C# and MonoGame, which I see as very worthwhile to know better. Secondly - it means we've got a proper implementation, that should ideally be accurate to NL itself, in a modern language - I'll note that while the rendering routines are MonoGame-dependent, the data-loading ones are not dependent on any library except for the standard C# runtime libraries, so could easily be reused in anyone else's code. I consider it acceptable if there's minor graphical inaccuracies - of the "this pixel is ARGB 0xFF808080 in NeoLemmix but shows up ARGB 0xFF7F7F7F in the editor" type*, not the "this exit would appear open in NL but appears locked in the editor" type - but beyond that I'm going for 100% accuracy here, corner cases and all.

And thirdly - much of improving the editor would not be an easy task; as one example, a basic rule of the NL text format is "lines / sections with different keywords are not order-sensitive relative to each other" - ie: it is acceptable that which order the $TERRAIN sections are in matters, but it is not acceptable to require that $TERRAINGROUP sections come before $TERRAIN sections. This has been the case since the format was introduced. The editor's parser works line-by-line in order, and in order to handle the above example, we would have to either parse through the file twice, ignoring $TERRAIN sections on the first run and ignoring everything except that on the second (so that all $TERRAINGROUPs are loaded first), or cache the $TERRAIN groups while iterating and only load them after iterating through the file is complete. Or, the third option - rewrite the parsing code, and pretty much everything that depends on it, to correctly follow the aforementioned rule. Another example is when saving the levels - the editor often adds whitespace padding between the keyword and the value on a line; while NL does handle this correctly, it's a direct violation of the format rule that only one space should seperate these (but it is acceptable to have any amount of whitespace before the keyword).

(In NL's code, we have a class TParser; we create a TParser object, then run TParser.LoadFromFile('blahblahblah.nxmi'). The code that's loading a level, or metagadget, etc, only ever interacts with TParser, which is generally used with calls like either TParser.GetLineTrimmed['TITLE'] or TParser.GetSubSection['SKILLSET'] or TParser.DoForEachSection('TERRAIN', LoadTerrainPiece) "LoadTerrainPiece" here being a function that does exactly what the title says it does; these of course don't care which order different keywords are in. It would not be impossible to write code that operates through TParser yet is order-sensitive between different keywords, but you would have to go out of your way to do so. Likewise, the new editor code has a similar setup)

* Of course, the level's physics map could be sensitive to such variations on the alpha channel. NeoLemmix itself uses custom-written routines, rather than relying on the graphics library, when merging alpha channels for physics purposes - and the editor will do the same, using the same formulas.

[Simon]

Ah, you're already invested in the rewrite. If you want to learn C# or Monogame, sure, continue, and I'm sure it'll be a good editor, even if it takes long.

-- Simon