Scripting

Scripting in CW4 uses a custom language, 4RPL. It is stack-based, similar to an HP calculator or the Forth programming language.

4RPL commands either read data from the stack or place data on the stack. Data (arguments) on the stack are in LIFO (Last In, First Out) order. That means the argument that was placed on the stack last will be the first to be retrieved. Imagine this as a stack of coins. If you put a coin on the top, then the first coin to be taken off will also be the one that was last placed on top.

You can place arguments on the stack by typing them, or executing an instruction that will push arguments on to the stack. For instance, you can type

2 4

and then these two numbers will be pushed onto the stack when your script executes.

An easy way to familiarize yourself with 4RPL is to use the Console in the Mission Editor. Let's use this to illustrate the next few examples.

As an illustration, imagine you want to add two of the numbers you entered above. The instruction to perform addition is add. You can also simply use a “+” rather than the add command.

2 4 +
TraceAllSP

The code above puts 2 numbers on the stack, the add (or +) command took the 4 and the 2 (last-in, first out) added them and pushed the result (6) back on the stack. TraceAllSp pops (takes/removes) all elements on the stack, puts a space in between them and prints them to the Console. A “6” is now printed on the console.

Note that 4RPL is a case-insensitive language, meaning any and all capitalization is ignored. TraceAllSP may as well be written as TRACEALLSP or traceallsp, there is no difference.

Part of 4RPL is the commands that manipulate map objects, such as creeper, terrain and units. Here is a simple script to put some creeper on a specific cell on a map.

12 23 100 AddCreeper  

Run this once in the console and then unpause the game and let the game simulation run a few frames. You will see a stack of 100 deep creeper at map coordinate x=12 and z=23 ¹⁾.

Comments in 4RPL can be either a whole line or a partial line. The comment terminates when a line ends. Comments are indicated by the “hash” character #,

# This is how we add two of the three numbers
# that are on the stack
# Below is code         # Below is a comment
2 4 5  add              # adds 4 and 5 to get 9

Warp notation is an optional notation that allows the use of parentheses to change the order that things are written. The use of parentheses is called warp notation since it warps, or moves, things around. Parentheses can be added anywhere in 4RPL and will move the command that proceeded the opening parenthesis to the location of the closing parenthesis. This can be useful for making some expressions look more like functions in some other languages

12 23 100 AddCreeper
AddCreeper(12 23 100) # Does the same thing as the line above.
 
1 (2 3 +) 4  # Demonstrate wrapping affects all stack locations.
2 3 + 1 4    # This line is the same as the one above.

If statements in 4RPL consist of an if, optional else and a closing endif instruction. The if instruction pops the item from the top of the stack and evaluates it as a boolean (true or false, not 0 or 0). If the item is false, then execution jumps to the else or endif instruction in the script.

if ( GetGameUpdateCount 900 >= )
   TraceAllSp("More than 30 seconds of game time have passed")
else
   TraceAllSp("Less than 30 seconds of game time have passed")
endif

Note: See Data Types for comparison between dissimilar types and type conversion.

The stack is not the only place to store information in 4RPL, it is possible to take items from the stack and store them in variables. To store a variable from the stack, write ->varname. To write a variable back to the stack, write <-varname. Variables remember their value and can be written to the stack multiple times. Variable names are case-insensitive.

3 4 + ->result
"3 plus 4 is" <-result TraceAllSP

Note: See Data Types for comparison between dissimilar types and type conversion.

4RPL supports user-defined functions that can be called from anywhere in the script. Functions are declared at the end of a script and are formatted as :FunctionName. A call to a function is formatted as @FunctionName. Function names are case-insensitive.

4 2 @Function1 Trace  # prints "11"
@Function2            # prints "function two"
 
:function1
    add    # adds together 2 items on the stack
    5 add  # adds an extra 5 to that
 
:function2
    "function two" Trace

Read more about functions on the pages for Function Calls and Function Declarations

4RPL supports both “do/loop” and “while/repeat” looping constructs.
For an example of a do loop see: do
For an example of a while loop see: while

When a CPACK is imported, it does not overwrite any scripts that might be on disk. So if there are scripts on disk those will get jammed back into the CPACK whenever a compile is done (and a compile is done during finalization). You can look on disk at a location like this:

%HOMEPATH%\Documents\My Games\creeperworld4\creeperworld4\editor\map2\cpacks\[CPACKNAME] 92415695-49d6-4e97-852b-64493e76233b\scripts\

If you load map as a regular player and then enter edit mode, the game will stick the scripts into the _UNKNOWN project directory. If there are already matching scripts present at that location, they will not be overwritten (importing a CPACK is the only exception to this). If you export, it will take the scripts on disk. Basically, in the normal case there is a project directory on disk. When you open a project, that directory is where scripts are location on disk. When you compile, those are the ones compiled. They get placed into the exported or finalized CPACK.

The case of on-the-fly opening the editor in a map you are playing is no different -with one exception: The game doesn't know what the project directory is, so it uses “_UNKNOWN” as the directory. Everything else is the same after that.

If you want to grab the scripts from a map (like an FPS map) and you want to make sure you have the latest scripts, you should either create a project for the map and open it from the project page, or you should clean your _UNKNOWN directory before you open the map on the fly.

Basically, just deleting the _UNKNOWN directory is the easiest way to clean it

https://github.com/Arin112}Arin112 wrote a code translator that can translate in-fix ²⁾ code to the 4RPL post-fix notation.

For those struggling to master 4RPL's post-fix format, this may be a useful tool. It can be obtained from github and is accompanied by many samples. Of course, it should be noted that the code and translation will only be up-to-date as long as the repository is maintained.