NeoLemmix Formats - Structure of level groups (packs, ranks, etc)

[namida]

This guide assumes you have read and are familiar with the basics of text-based files in NeoLemmix.

This post is more like a reference of everything. If you want a "start from scratch and slowly learn the basics" approach, see the next post in this topic.

In NeoLemmix, the concept of a "pack" or a "rank" mostly does not exist on a technical level (there are still a few remnants from when it did). There's just groups of levels, which can themself contain groups of levels (which in turn, can contain more groups). What we think of as a "pack" when playing, is generally a group that itself contains no levels, but contains several groups ("ranks"); these groups contain levels, but don't contain further sub-groups. (Exceptions do exist. For example, many demos of packs have the levels directly in the main group, with no sub-groups. The NeoLemmix test levels go one level deeper with nesting.) The "levels" folder itself is the lowest group. Every folder in it is a sub-group of it - so from NeoLemmix's point of view, each pack you have installed is really just a sub-group of the "levels" folder.



In the simplest form, a group's folder will just contain level files and/or subfolders (representing sub-groups). For example, we could have the following structure:

levels
>> BlahLems
>>>> Easy
>>>>> JustDigAgain.nxlv
>>>>> JustDigSomeMore.nxlv
>>>> Medium
>>>>>> DoMoreThanDig.nxlv
...etc

From a technical point of view, we now have a subgroup of levels called "BlahLems". This in turn has subgroups "Easy", "Medium", etc. The group "Easy" contains the levels "Just Dig Again" and "Just Dig Some More", and so on.

Of course - in this case, we don't have a custom logo, nothing exists to tell NeoLemmix what order to put the subgroups / levels into (NeoLemmix's behaviour in this situation is to sort them alphabetically), and so on. We can add extra files to the groups for these things, as well as some other customization options.



levels.nxmi

Every group must contain its own "levels.nxmi" file; if there isn't one, the subgroups / levels simply get sorted into alphabetical order. So - in the main folder (the one for your "pack"), you'd have one that lists the order of the ranks. In each sub-group's folder (the folders for each "rank"), you'd have one that lists the order of levels. In a situation where a group contains both levels and sub-groups (this is perfectly valid!), the levels.nxmi file in that group would have listings for both ranks and levels.

Important: Once a group has a "levels.nxmi" file, all sub-groups or levels in that group will only show up in NeoLemmix if they're listed in the levels.nxmi file - others will be hidden.

Specifying an order for levels is simple. For each level, add a line with the "LEVEL" keyword, with the value being the level's filename. For example:

LEVEL Just_Dig.nxlv
LEVEL Only_Floaters_Can_Survive_This.nxlv
LEVEL Tailor_Made_For_Blockers.nxlv
...

Specifying an order for sub-groups is a bit trickier, this is because you specify both a name and a folder for them. As such, they need to be in a group rather than single lines:

$GROUP
  NAME Fun
  FOLDER 01 Fun
$END

This would specify a rank that's in the folder "01 Fun", and named "Fun".

One last thing - one of the few ways that NeoLemmix DOES recognize packs, is that a "levels.nxmi" file may also contain a line with the keyword "BASE" (no value). This will cause NeoLemmix to simulate treating that group as a standalone pack - for example, upon completing the last level of it, you'll wrap around to the first level, instead of going on to a different pack. It will also prevent anything that uses the rule of "copy what the parent group does" from going any higher than this group. As a general rule, include the keyword "BASE" in any levels.nxmi file that corresponds to what you'd consider a "pack" (rather than a "rank").

info.nxmi

The info.nxmi contains general properties of the group. Generally, only the group representing a "pack" will have an info.nxmi file, while "ranks" will not.

info.nxmi contains the following lines and segments:

TITLE - Specifies the title of the group. Eg: TITLE Oh No! More Lemmings!
AUTHOR - Specifies the author of the group. Eg: AUTHOR DMA Design
VERSION - Specifies the version number of the group. Eg: VERSION 1.25

$SCROLLER - Specifies text for the scroller

LINE - Specifies a line. You may include multiple lines with this keyword, but should only include one overall $SCROLLER section. Eg:
$SCROLLER
  LINE Welcome to my Lemmings pack.
  LINE Please enjoy playing!
  LINE This third line is here for no reason.
$END

music.nxmi

This file specifies the music rotation that's used for any level that doesn't specify a music file. This is a simple format - each line contains the keyword "TRACK" and a music file name. Just like when specifying music files inside a level, you can include folder names, and you should not include an extension. For example:
TRACK orig_03
TRACK orig_04
TRACK ohno_01
TRACK Lemmings_Plus_V/abstract1
This would mean levels in the group - assuming they don't specify a music file - will follow the rotation orig_03, orig_04, ohno_01, Lemmings_Plus_V/abstract1, repeat. The last one refers to a track called "abstract1", inside a "Lemmings_Plus_V" subfolder of the music folder.

You can include multiple tracks on a single entry, seperated with semicolons, to indicate a priority order. If the first track is not present, the second will be played instead, and so on.
TRACK orig_01;orig_02;orig_03
This would play orig_01 if it exists, if not, orig_02 if it does; and finally, orig_03 if neither of the others exist.

You can prepend a list of tracks with an ! to change it into a random selection instead of a priority order.
TRACK !orig_01;orig_02;orig_03
This would play a random track out of orig_01, orig_02 or orig_03.

You can also include a line with the keyword RANDOM. This will simply mean that any time this music.nxmi file is referred to, tracks will be selected randomly instead of sequentially. In this case, no TRACK entries should have multiple tracks listed or the ! prefix.

The music rotation, if absent, will be inherited from the parent group.

postview.nxmi

This file customizes the messages that appear on the postview screen.

This file consists of multiple $RESULT sections, each of which contains:
CONDITION - This specifies the condition to trigger the message.
LINE - This specifies the actual line of text. There can be up to two lines per result.

The condition can either be:
- An absolute number of lemmings. To specify this, CONDITION's value should be the number. Eg. CONDITION 40 would trigger if the player saves at least 40 lemmings.
- A number of lemmings relative to the save requirement. To specify this, CONDITION's value should be the number prefixed with + or -. Eg. CONDITION -5 would trigger if the player saves at least <save requirement, minus 5> lemmings.
- An absolute percentage. To specify this, CONDITION's value should be the percentage, suffixed with a % sign. Eg. CONDITION 50% would trigger if the player saves at least 50% of the lemmings on the level.
- A relative percentage. To specify this, CONDITION's value should be the percentage, prefixed with + or - and suffixed with a % sign. Note that this is treated as a percentage of the save requirement. Eg. CONDITION -30% would trigger if the player saves at least <save requirement, minus 30% of the save requirement>.

The postview texts, if absent, will be inherited from the parent group.

In terms of how the game actually selects which one to display, it will pick the last one in the file that fits the following conditions:
1. The player has saved enough lemmings to fulfill the condition.
2. For the specific level in question, the save requirement of any earlier-in-the-file postview text that fulfills condition 1, is lower than (not equal to) the save requirement of this text.

There is a special case - if a text's condition (not just "what it calculates to in practice") is either "save the requirement exactly" or "save 100%", it does not need to pass condition #2 (it still must pass condition #1 of course).



Groups can also contain graphic files. Note that most graphic files relating to the main menu will not change when switching up and down between ranks using the Up / Down arrows; they will only change when switching between groups via the level select menu, or when leaving and re-entering the title screen (the obvious exception is rank_graphic.png). To see how these graphic files should look, find the corresponding default ones, and work from there:

background.png
group_graphic.png
logo.png
menu_font.png
scroller_segment.png
scroller_lemmings.png
sign_play.png
sign_level_select.png
sign_config.png
sign_group.png
sign_group_up.png
sign_group_down.png
sign_quit.png
talismans.png

Custom graphics for the skill panel may also be present. These use the same filenames as they do in the standard skill panel graphics. For high-resolution panel graphics, append "-hr" to the end of the usual filename (before the ".png" extension), eg "icon_nuke-hr.png" for the high-resolution nuke icon.

Generally speaking, every group will have a "group_graphic.png" except the base "pack" group; while only the base pack group will have the others.

Custom graphics will be inherited from the parent pack where applicable.



I hope this has been useful! Feel free to reply if you have any questions, and I hope this helps you with putting together your packs - no toolkit needed!

[namida]

Pack creation crash course

This will give a brief overview of how to create a pack with the typical layout - a few ranks, containing several levels each.

You will need:
- At least 3 levels, preferably a few more than that. 10 or so is good. You could quickly create some crappy placeholder levels in the editor if you don't have enough ready-to-use ones, or just temporarily borrow a few levels from the official games.
- NeoLemmix V12.10.X stable.



Step 1 - Create a new pack

Go into NeoLemmix's "levels" folder. Create a new folder here for your pack. Put all your levels in this folder.

You now have created a pack, with your levels in it. It's a very simple pack at this stage - no custom settings or graphics, no specified ordering (levels will just get sorted into alphabetical order), no ranks - but it's a pack nonetheless, and NeoLemmix will detect it and allow you to play it!



Step 2 - Divide the pack into three subgroups (ranks)

Go into your pack's folder. Create three folders - one for each subgroup. Move a few levels into each one.

You now have some ranks. Yes, again, it's that simple! However, levels still aren't sorted - within each rank, they'll be in alphabetical order - and the ranks themself will just be in alphabetical order too.



Step 3 - Define a rank order

Go into the main folder of your pack. Create a new text file here called "levels.nxmi" and open it in your preferred plaintext editor (if you don't have a preference here, Notepad will do the job - avoid rich-text tools like Wordpad or Microsoft Word).

First, put on a line by itself the word "BASE" (without quotes). This line should always exist in the "levels.nxmi" of the pack's base folder. This isn't too important when the pack is directly in the "levels" folder, but if users like to sort their packs into subfolders, this "BASE" line is what identifies the base of an actual pack.

Now, for each rank, add the following template; replacing as appropriate:

$GROUP
  NAME <rank name here>
  FOLDER <rank folder name here>
$END

Note that the name and folder name do not have to be the same. You could put numeric prefixes at the start of the folder names, eg "01 Fun" "02 Tricky" etc, but not have these in the specified names.

Also note that (and these rules apply in general to NeoLemmix text data files, not just to levels.nxmi):
- The first (or "only", where applicable) word, usually called the "key" or "keyword", on a line is never case-sensitive - although convention is to always uppercase them. Everything after this, usually called the "value", could be case sensitive (although it still usually isn't).
- You may add blank lines anywhere you like.
- You may add or remove whitespace at the start of any line.
- You should not have a different amount of whitespace between the keyword and the value - it should always be a single space.
- You should not add any trailing whitespace at the end of lines.

Example of a full pack-base levels.nxmi file (from Lemmings Plus Alpha)

BASE

$GROUP
  NAME Mutilation
  FOLDER 01 Mutilation
$END

$GROUP
  NAME Decimation
  FOLDER 02 Decimation
$END

$GROUP
  NAME Obliteration
  FOLDER 03 Obliteration
$END

Now, when you play your pack, the ranks will be in the order you specified, instead of just being sorted into alphabetical order!



Step 3 - Define a level order

Similar to the above, we probably also want to define an order for the levels within a pack. For this, we also use a "levels.nxmi" file - but this time, in the individual ranks' folders.

In this file, we do not have the "BASE" line. This is because the ranks aren't the base of a pack - they're subgroups within the pack. Instead, we just add one line for each level file. Each line should start with the word "LEVEL", followed by a single space, then the filename of the level. These lines should be in the order the levels are in.

Important - once a folder has a "levels.nxmi" file, the "get all levels / subgroups, sort into alphabetical order" functionality no longer triggers for that folder. This means you must specify every level in that folder, in the levels.nxmi file. However, this does not extend to other folders in your pack. So for example, you could have specified orders for your "Fun", "Tricky", "Taxing" and "Mayhem" ranks, while also having a "Bonus" rank with no levels.nxmi of its own - in this case, "Bonus" will fall back to the "all levels, in alphabetical order" behaviour.

You can now fire up your pack in NeoLemmix and see that your levels, too, are in the intended order!

What if I don't want to divide the pack into ranks, but still want to order the levels?

No worries! In this case, the levels should of course be in the base folder, since there's no ranks. You would then put the "LEVEL _______" lines directly in the base folder's "levels.nxmi" file, instead of that file containing the $GROUP sections. Note that the base folder's "levels.nxmi" should still contain the line "BASE" somewhere - it doesn't matter whether this comes before or after the LEVEL lines, or even in the middle of them.

Alternatively, some people prefer to create a pack that has only one rank, and implement this rank as normal. It's completely up to you which way you prefer; NeoLemmix will accept either, and both ways are officially supported.

Step 4 - Provide some basic custom graphics for the main menu

For this, specifically, we will look at:
1. A custom title logo. For this - you will want to place a file called "logo.png" in the base folder of your pack. While there's no enforced limit on size, in practice you will likely want to keep this under 864x144 so that it doesn't go off the edges of the screen and/or overlap other objects.
2. Custom graphics for the group sign. For this - you will want to place a ~75x~28 file called "group_graphic.png" into each rank's folder. The size is approximate in both dimensions, and may be slightly different from this. If it does not line up nicely, try adding / removing padding on the sides.
3. A custom background graphic. For this, place a file called "background.png" in the base folder of your pack. This can be any size (though it is pointless for it to exceed 864px wide and/or 486px tall), and will be tiled to fit if needed.

For #1 and #2, you may use an alpha channel, and it will blend properly in-game.

It is possible to use other custom graphics too, however, that's getting a bit more advanced and is beyond the scope of this crash course - see the above post for pointers. I suggest mastering these basics of pack creation, before worrying about all the possible advanced stuff you can do.



Step 5 - Provide some metainfo

You'd probably like to provide some other custom data - a proper pack name (instead of just copying the folder name), etc. You do this by creating a text file called "info.nxmi" in the pack's base folder.

This file follows this format:

TITLE <pack title>
AUTHOR <pack author>
VERSION <pack version - this could be a number or a codename>

$SCROLLER
  LINE <scroller text 1>
  LINE <scroller text 2>
  LINE <scroller text 3>
$END

Some things to note:
- Prior to V12.10.0, it was very common for pack creators to specify the pack's version number in the Author field. For example, "AUTHOR namida | V12.01". This is because NL did not yet at the time have any official way to provide a version number for a pack. This should no longer be done in new packs; use a VERSION line instead.
- You can have as many - or few - scroller texts as you want. If you don't have any at all, omit the $SCROLLER line (and the corresponding $END line) altogether.



Step 6 - Customize the music order

You might have created levels that all specify which music they use. If that's the case, there's little point to this step. However, if you've created levels that just go through the normal music rotation based on their order, you might want to customize the order. You can do this by creating a "music.nxmi" file in the pack's base folder.

The "music.nxmi" file is, again, a plain text file. This file consists of a line for each track, starting with "TRACK" followed by the name of the music file, without an extension. (You can put an extension, but NeoLemmix will ignore it, and instead just try every supported extension in a specific order until it finds one.)



Step 7 - Fill gaps in the level order with placeholders

Note that this is not a critical "you must know this" thing, but rather, it's a useful trick that I find myself using more often than not while making packs.

If you have an overall idea of the layout of your pack (how many levels per rank etc), you might want to have placeholder levels. While you could simply create a whole bunch of placeholder levels (or more likely, copies of the same placeholder level), you can instead put a single placeholder level in the pack's base folder, then use a relative path to point to it.

For example, let's suppose we want our first rank to have 10 levels, but we've only created 5 so far - specifically, levels 1 to 3, level 7, and level 10. We want to fill 4 to 6, plus 8 and 9, with a placeholder level. We can create a single "placeholder.nxlv" level in the pack's base folder, then our first rank's levels.nxmi file can look like this:

LEVEL level01.nxlv
LEVEL level02.nxlv
LEVEL level03.nxlv
LEVEL ../placeholder.nxlv
LEVEL ../placeholder.nxlv
LEVEL ../placeholder.nxlv
LEVEL level07.nxlv
LEVEL ../placeholder.nxlv
LEVEL ../placeholder.nxlv
LEVEL level10.nxlv

By doing this - we only have to have a copy of a single placeholder level; we just reference it more than one in our various levels.nxmi files. Don't forget to remove this placeholder level when you don't need it anymore (because all spaces have been filled in).

Note that in general, you should be careful when using relative paths in levels.nxmi files. There's generally only two good reasons to do it - placeholder levels as mentioned above, or when creating a "no ranks, all levels are in the base pack directly" pack but want to put your level files in a subfolder. In particular, never do this to reference levels outside of your pack's folder.



Well, that should cover all the features of pack creation that the majority of people will use - and for those who want to go beyond it, this should provide a solid-enough foundation to start understanding the first post better. Hope this helps!