Tutorial:Programming mission objectives

This article is an unfinished work in progress or contains transferred information that needs to be rewritten or reformatted to fit our standards. Please excuse the mess and do not mark for deletion.

One of the major components of Level Modification, the process of Editing the Mission Objectives can be rather complicated, as all the script has pretty much been reverse engineered and decoded from the original compiled NPL files. Before we get into editing the NPL files, it’s important that you actually understand the script you’re working in.

Objective Script Files

Fortunately, there are uncompiled versions of each script that are fully readable called NRN files. Both the NRN and NPL files are found in the level folder for the mission (Ex: LegoRR0/Levels/GameLevels/Level01 for Driller Night). The NRN is really a simple text file, which you can open with almost any program, even Notepad, which is the traditional program for editing scripts. Now, if you already know some programming, this should be a breeze for you, as it only seems to be a bit of modified C or C++ language. If you aren’t, not to worry, that’s what this tutorial is for.

Before going gallivanting into the wonderful world of scripting, always remember to have a back-up for your NRN or NPL files somewhere. It is best to have a back-up of the entire LegoRR0 folder and its contents, so you don’t get files mixed up with the ones in the edited folder.

Example Script

Let’s start out by looking at a pretty basic mission script, like for Level21, Air Raiders, which is an example of a Material Collecting Objective:

#include <nerpnrn.h>

TRUE ? SetTutorialFlags 0
TRUE ? SetMessagePermit 1

Function(Upgrade)

{

	TRUE ? SetToolStoreLevel 1

	TRUE ? SetTeleportPadLevel 1

	TRUE ? SetPowerStationLevel 1

}

FuncEnd(Upgrade)

// Check to see if objective is failed

TRUE ? SetR1 0

GetToolstoresBuilt = 0 ? AddR1 1

GetMinifiguresOnLevel = 0 ? AddR1 1
 
GetR1 = 2 ? SetLevelFail

// Check to see if objective is completed

GetCrystalsCurrentlyStored > 39 ? SetLevelCompleted

Not too big for a script… now the first thing you’ll notice is in the first line you have the parameter “#include <nerpnrn.h>” This is referring back to the parent file, nerpnrn.h, located in LegoRR0/Levels. Every script that includes this reference contains the information contained the parent file. This is important to notice, as when you start looking through the encoded NPL files, it will contain all this script from the parent file, followed by the actual script contained within the NRN file.

The next two lines are pretty basic, and you’ll find them in almost any GameLevel NRN script, as they indicate that there are no Tutorial stops or “Flags” set up and it just has the one message at the beginning of the level, telling you the mission description (WHICH by the way can be edited in the LegoRR1/Languages/ObjectiveText.txt file).

After that you have a function which is basically a set of parameters, in this case, indicating the preset upgrade level of various buildings present at the beginning of the mission. It is not entirely understood exactly how the actual “Function { …. } FuncEnd” part of the script is encoded in the NPL, but it’s contents (the actual settings for the upgrades) are easy to see.

The last bit is the important bit that designates what is required for the mission to be complete. First off, it is programmed to recognize that if there are no Tool Stores built, and no Rock Raiders present, the mission ends in failure, since it requires rock raiders to build Power Paths for the tool store to teleport more rock raiders down with. This bit is designated by the couple functions under the helpful “// Check to see if objective is failed.” Note that anything written in a line after “//” is ignored by the game, allowing for helpful notations to keep track of what the purpose of some lines are.

After that, there’s the simple line "GetCrystalsCurrentlyStored > 39 ? SetLevelCompleted.” This indicates that once the number of Energy Crystals collected is over 39, i.e. 40 or more, then the level has been completed successfully. And that’s that!

Other Scripts

There are many scripts that follow the format shown above. The main things you have to pay attention to is the stuff around “SetLevelCompleted” and “SetLevelFail.” Some scripts, like Level07, Search ‘n’ Rescue, require you to Find a Hidden Object, in this case, a missing rock raider, lost in an undiscovered cavern. In this mission “GetHiddenObjectsFound > 0 ?” in order to win, which means, when 1 or more hidden objects are found, the level is completed.

Others like Level06, Explosive Action, require you to travel to a certain block designated as a Tutorial Block in the level’s Tuto_06.map file, in this case, you are required to bring the designated lost digger, into the rock raider base. Some early missions require that you Construct a Support Station or Other Building in order to win the mission, like Level04, A Breath Of Fresh Air. Once “GetPoweredBarracksBuilt > 0 ?” i.e. one or more Powered Support Station has been built, then the level is completed. Some missions that have a depleting air supply will mark a level failure if “GetOxygenLevel < 1 ?” i.e. Oxygen levels hit 0.

All the basic levels usually have one of these commands as their objective. There are many more parameters to work with, as you’ll see by looking at some of the tutorial level scripts, which are much more complicated, as they designate tutorial flags which stop the mission to give a message or require you to click on something or perform some other action to move on. Other scripts include certain setups for Slimy Slug Attacks and Coordinated Monster Attacks and Intermittent Messages.

Once you got a grasp of things, you can probably get a little creative changing the level goals so that instead of having to build a power station, you have to build a geology center, to complete the game. Or you could make the mission’s goal to collect a certain amount of Ore, rather than crystals.

Editing NPL files

The next step would be to figure out how to actually change the NPL file. Note that any changes you make in the NRN file do not change anything in the NPL file. At the moment, you have to go into the NPL file and manually change its contents to your liking. The major difficulty with this is that the NPL file is encoded into hex-computer language. It basically translates the C++ language into a language that the computer can easily understand and process. To open and edit the NPL file, you will need Hex-Editing Program. There are many good Hex-editing programs out there, such as XVI32, which is free.

Upon opening it, you’ll notice that it all looks like gobbledegook, nothing but numbers letters and strange symbols. Depending on what editor your using, you may see two versions of the script. One version in letters, blank spaces, and symbols, the other in nothing but numbers. For our purposes, we will be only paying attention to the numbers, which are the real “Hex-Strings.” Every number, symbol, and parameter that is contained in the NRN script has a counterpart Hex-string in the NPL file. Included with this guide are several other documents which contain a list of known parameters, numbers, symbols, and their hex-string counterparts.

Editing the NPL file is a slow and careful process. The best thing to do is to use the search command, which most hex-editing programs have. Search for the string that you want to edit, assuming you know what it is, and once you find it, change it. Note that in order for the NPL file to work it must be the same amount of characters, ALWAYS. This means that you should never ever ever finding yourself pasting things in with Ctrl+V or deleting things with the Delete or backspace key, as these will delete characters. To edit, just change the already existing characters, rather than inserting or deleting any. This way, it will keep the same amount of characters, and will stay functioning.

Guides for Programming Mission Objectives

Here are some helpful guides to help you with Programming Mission Objectives: