NeoLemmix Formats - Level file format

Started by namida, August 12, 2019, 01:23:33 AM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

namida

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

This guide is written for NeoLemmix V12.12.0.

General Level Info

The level file usually begins with (although - keep in mind the rule about order-insensitivity, so technically this can come anywhere in the file) the general stats - title, skillset, etc.

TITLE - The level's title. To properly fit on the preview screen, this should be no more than 40 characters in length.
AUTHOR - The level's author. Optional.
THEME - The style from which the level takes its theme. This will usually reflect the style the level is mostly / entirely made using.
MUSIC - Specifies the music used on the level.
In its most basic form, the MUSIC line is followed by the name of the music to play on the level. Do not include an extension (eg. ".ogg" or ".it") in this line.

It is possible - and encouraged, when using custom songs - to use subfolders of the "music" folder by including a backslash in the name. For example, "MUSIC MyPack/Track01" would use the file "Track01" from the folder "MyPack".

You can use a track from the default rotation by specifying the music as a ?, followed by the track number. For example, "MUSIC ?5" will play the 5th track from the pack's (or default) rotation. You can specify ?? to pick a random track from the default rotation.

You can specify multiple tracks, seperated by semicolons. If you do, then the first one will play if possible; if it is missing, the second one will play; and so on. When doing this, you can additionally prefix the first track with an !. If you do, instead of treating the list as a priority order, it will be treated as "pick one of these at random".

You can combine all of the above.

If no tracks are specified, or all of them are missing, a track from the default rotation will be used depending on the level order (or if not in a pack, at random).
ID - Specifies the level ID. This is a number in the range of 1 to (2^64)-1, or 0x0000000000000001 to 0xFFFFFFFFFFFFFFFF. This should theoretically be unique for every level, and should in practice be unique for every level in a pack, unless the two levels are literally identical duplicates of each other (not just "similar"!); however it is acceptable (and expected) that the ID will remain the same between older and newer updates of the same level.
VERSION - Specifies a version number for the level. Assumed to be zero if not present. The same range of valid values applies as for level ID, with the exception that zero is also valid for the version number (whereas it is invalid as a level ID).
LEMMINGS - Specifies the number of lemmings on the level. This can be left out if the level only has preplaced lemmings, or if all windows on the level have specified lemming counts.
SAVE_REQUIREMENT - Specifies how many lemmings must be saved to pass the level.
TIME_LIMIT - Specifies a time limit for the level, in seconds. The level will have infinite time if no time limit is specified, or this can be explicitly stated by writing TIME_LIMIT INFINITE.
MAX_SPAWN_INTERVAL - Specifies the highest value the spawn interval can be raised to on the level. To convert a release rate to a spawn interval, or vice versa, the formula is (103 - RR).
SPAWN_INTERVAL_LOCKED - No value needed; if this is present, the max spawn interval is instead a fixed spawn interval that cannot be changed.

WIDTH - Specifies the width of the level.
HEIGHT - Specifies the height of the level.
START_X - Specifies the X coordinate for the center of the screen at the start of gameplay. Omit this (and START_Y) to use automatic screen start position.
START_Y - Ditto, for the Y coordinate. Omit this (and START_X) to use automatic screen start position.

BACKGROUND - Specifies the background graphic to use for the level. The format is <style>:<file>, so for example, to use the background "colors" from the style "namida_abstract", you'd write BACKGROUND namida_abstract:colors.




Skillset

The skillset is specified inside a $SKILLSET section. Skill names are used as keywords, with the skill counts as values. For example, BUILDER 3 would give the player 3 builders.

You may give infinite uses of a skill by specifying INFINITE as the value (or a number over 99). The exception is that you cannot give infinite Cloners; it will instead become 99 cloners in-game.




Talismans

Talismans are defined by adding a $TALISMAN section. You may have multiple talisman sections in a single level - there's no practical limit as to how many you can have.

Each talisman must have a name, an ID number, and a color. These are specified with the following keywords:

TITLE - Specifies the talisman's name.
COLOR - Specifies the talisman's color. Valid values are BRONZE, SILVER or GOLD.
ID - Specifies the talisman's ID number. This must be different for each talisman in the same level, and must be numeric, but beyond this has no rules. I do suggest that, if you remove one talisman from a level then add an entirely new one, don't give the new one the same ID the old one had.

With these alone, though, the talisman will be awarded simply for completing the level, no added requirements. To specify additional requirements, add the following lines:

SAVE_REQUIREMENT - Specifies a save requirement.
TIME_LIMIT - Specifies a time limit. This is measured in frames. 1 second = 17 frames, so for eg. 1 minute (60 seconds, or (60 x 17 =) 1020 frames), you'd write TIME_LIMIT 1020.
SKILL_LIMIT - Specifies a limit on the total number of skills the player may use.
XXXX_LIMIT - Specifies a limit on the number of a specific skill the player may use. Replace XXXX with the skill name. Eg. BUILDER_LIMIT 4 sets a requirement of no more than 4 builders being used.
SKILL_EACH_LIMIT - Specifies a limit on the number of uses of each individual skill a player may use. Eg. SKILL_EACH_LIMIT 3 sets a requirement of no more than 3 of each skill being used. This is just a shorthand for having one XXXX_LIMIT line for each skill.
USE_ONLY_SKILL - Specifies one skill that must be the only one used. Eg. USE_ONLY_SKILL BUILDER results in a talisman that is obtained by solving the level using only builders. This is just a shorthand for having XXXX_LIMIT 0 for every skill except the specified one.




Pre-level and post-level texts

You can specify texts to show before and after the level respectively using $PRETEXT and $POSTTEXT sections.

Either one of these contains lines with the keyword "LINE", with the value being one line of text. If you wish to include a blank line, have a LINE with no value specified. Each line of text can be up to 40 characters long.

You can include the text [HOTKEY:*****] which will be replaced with the user's hotkey(s) for a certain function. The function names are the same as in the hotkey INI file. If an extra detail is needed, separate it with another colon, eg "SKIP:-1" for "skip back one frame". You can also use the special names "SKIP+" and "SKIP-" to cover skips of any duration in a specified direction (special skips excluded). This feature mostly exists for the use of the NeoLemmix Introduction Pack, and will rarely be useful in other packs - but feel free to use it if it is useful for yours.




Objects

Object instances are specified with a $GADGET section.

The following keys are common to all types of objects:

STYLE - Specifies the style the object is from.
PIECE - Specifies which object to use.
X and Y - Specify the position of the object.
ROTATE / FLIP_HORIZONTAL / FLIP_VERTICAL - No value needed, specifies to apply the corresponding transformation to the object. Remember that files are not order-sensitive; and thus, Rotate is always applied first. For some object types, FLIP_HORIZONTAL has no visual effect, but instead has an impact on physics (eg. entrances).

These keys apply to most types of objects, though moving backgrounds and one-way arrows cannot use them:

NO_OVERWRITE - The object will be drawn behind other objects.
ONLY_ON_TERRAIN - The object will only be drawn where it overlaps terrain. This is considered deprecated and may be removed in NeoLemmix V12.15.0 or later.

For objects that are resizable:

WIDTH and HEIGHT - Specify the corresponding dimension. The fallback value if these are not specified, is determined by the style (and if no default is set there either, the default size is based on the object's graphic).

Some types of objects have additional fields specific to those types:

Exits
LEMMINGS - Specifies the maximum number of lemmings that can use the exit. If not specified, the exit will accept any number of lemmings.
Entrances
LEMMINGS - Specifies the number of lemmings that can spawn from this entrance. If nothing is specified, lemmings will spawn from the entrance until the level's lemming count is reached.
CLIMBER / SLIDER / SWIMMER / FLOATER / GLIDER / DISARMER / ZOMBIE / NEUTRAL - Lemmings spawning from this entrance will have the respective skill / state.
Teleporters, Receivers
PAIRING - A teleporter will only pair with a receiver that has the same value for PAIRING. If multiple such receivers exist, it pairs with the first unpaired receiver in the object order starting from itself (and looping around if need be).
Moving backgrounds
ANGLE - Specifies the angle of movement, in degrees. 0 is straight up, 90 is to the right. This will be rounded to the nearest 22.5 degrees; however, do not enter a decimal number (for 22.5, for example, enter either 22 or 23 instead).
SPEED - Specifies the speed of movement, in terms of pixels per in-game second (1 in-game second = 17 frames).
Pickup skills
SKILL - Specifies the skill given by the pickup.
SKILLCOUNT - Specifies the quantity of the skill given by the pickup. If absent, the pickup will give 1 skill.




Terrain pieces

A terrain instance is placed in a $TERRAIN section, and has the following lines:

STYLE - Specifies the style the terrain piece is from. To reference a terrain group, specify the style as *GROUP.
PIECE - Specifies the piece.
X and Y - Specify the piece's location.
ONE_WAY - Allows one-way arrows to be applied to the piece. Does nothing for steel pieces.
ROTATE / FLIP_HORIZONTAL / FLIP_VERTICAL - No value needed, specifies to apply the corresponding transformation to the terrain piece. Remember that files are not order-sensitive; and thus, Rotate is always applied first.
NO_OVERWRITE - The piece will be drawn behind other pieces instead of on top of them.
ERASE - The piece will function as an eraser.

For pieces that are resizable:

WIDTH and HEIGHT - Specify the corresponding dimension. The fallback value if these are not specified, is determined by the style (and if no default is set there either, the default size is based on the piece's graphic).




Terrain groups

Terrain groups - basically, collections of terrain pieces that can be used as if the resulting formation was itself a terrain piece - can be defined with a $TERRAINGROUP section.

The group consists of a NAME line which gives the group a name; after this, it consists of simply one or more $TERRAIN sections, which work exactly the same way as the $TERRAIN sections for the level itself, except that the ONE_WAY flag is ignored.

However, there is a rule about the pieces used in a terrain group - inside a single group, you cannot have a mixture of steel and non-steel pieces; they must either all be steel, or none are. The group as a whole will have the same steel / non-steel nature as the pieces inside it. Eraser pieces are exempt from this rule.

One other thing to be aware of is that while you can use a group inside another group, the "inner" group must come first in the level file. So for example, if group "BLAH" contains an instance of another group, "DERP", then the group "DERP" must be defined in the file before the group "BLAH". However, this only applies to groups that use other groups; as per the rule about "lines / sections with different keywords are not order-sensitive relative to each other", it is perfectly acceptable to have your $TERRAIN segments before your $TERRAINGROUP segments.




Preplaced lemmings

Preplaced lemmings are defined with a $LEMMING section, containing the following fields:

X and Y - Specifies the starting position of the lemming. Note that this is the physics coordinate of the lemming; ie: the point where the dot appears if you mouseover the lemming in clear physics mode.
FLIP_HORIZONTAL - Specifies that the lemming starts facing left (it will face right otherwise).
SHIMMIER / CLIMBER / SLIDER / SWIMMER / FLOATER / GLIDER / DISARMER / BLOCKER / ZOMBIE / NEUTRAL - Gives the lemming the corresponding state or permanent skill.
My projects
2D Lemmings: NeoLemmix (engine) | Lemmings Plus Series (level packs) | Doomsday Lemmings (level pack)
3D Lemmings: Loap (engine) | L3DEdit (level / graphics editor) | L3DUtils (replay / etc utility) | Lemmings Plus 3D (level pack)
Non-Lemmings: Commander Keen: Galaxy Reimagined (a Commander Keen fangame)