digitalizedMind's CRPL Basics

want to make custom units/enemies in CW3 but don't know where to start? try this guide! (if you're still confused afterwards, file a complaint so i can ignore it (jk feedback is always appreciated))

Get a program for writing code

The first things you should do is get an IDE. "An integrated development environment (IDE) is a software application that helps programmers develop software code efficiently." - first result on google. I mean you could just use windows notepad if you genuinely don't care, but it won't be long until you find out that's programmer masochism.

Most people who make custom content for Knuckle Cracker games will recommend Notepad++. It's free to install and very beginner friendly.
Download Notepad++[notepad-plus-plus.org]

I prefer Visual Studio Code, it's more designed for experienced programmers but has way more features.
Download VSC[code.visualstudio.com]

Which one should you use? It depends on your taste! which you can only find out by trying both IDEs. I recommend you at least try Notepad++ first, because again I think it's more beginner friendly. I used to prefer it actually, but as I learned VSC I started to use that more since it's easier to use if you understand all of the features it shoves in your face.

Adding/using scripts

CRPL towers can contain scripts which tell them what to do. All scripts need to be in a CRPL tower in order to function; you can't just have it sit in the game's background. (you can however put a script in a CRPL tower, make it invisible and let that sit in the corner of the map)

All CRPL towers execute all of their scripts every frame, or 1/30th of a second. By default scripts can't operate while the game is paused but it's possible to enable that. Pro tip: the game has a feature that lets you run 1 frame while it's paused, default keybind is N.

Creating and opening scripts

Go to Edit Map Mode -> Units tab -> Scripts
If done correctly this should appear

Click on a script's Edit button to open it in your default program for .crpl files. If you don't have a default program set for .crpl files, the game will tell you how to fix that. You can also google how to do it.

The Compile All button is essentially the Reload All Scripts button. When you edit your crpl files, cores in-game don't change until you recompile all scripts.

Adding scripts to CRPL Towers

Here is what the properties menu of a CRPL tower looks like. It appears when you're in edit map mode -> unit tab -> double click a CRPL tower.

The first bubble is some basic properties of the crpl tower that you can view/edit manually.

The second bubble is the scripts the CRPL is using and a dropdown for adding scripts. Scripts on the top are executed first, so if multiple scripts try to change the same thing on the same frame, the value applied by the last script will remain onto the next frame. A script can be used by multiple CRPL towers, and a single tower can use multiple scripts, even of the same kind.

The last bubble is input vars of the selected script in the second bubble. Instead of having multiple of the same script but each with slight differences, for say custom emitters that do the same thing but have different stats, you could program your script in a way so that values can be different for each crpl tower using the script.

Data Types

This section refers to different types of variables in crpl.

Data Type	Description	Examples
INT	Positive or negative Integer. If you try to divide two INTs, it will be rounded automatically.	4 -12
FLOAT	Number that contains a decimal.	6.7 4.0
STRING	Any text. Set strings by surrounding them with quotation marks. If numbers are strings, you can't do math with them.	"Hello World!" "why is ^ so common"
LIST	A collection of different values each with an index.	CreateList ->colors "red" "blue" <-colors AppendStackToList
FUNCTION	A block of code that can be called (used) several times in the main code.	@getUnitCoords :ddiv

Program Flow Basics

Stack Basics

The way CRPL works is that you have a stack, and can either add to that stack or do things that interact with what's in the stack.

# Current stack: empty

6

# Current stack: 6

1.4

# Current stack: 6 1.4

"Hello World!"

# Current stack: 6 1.4 "Hello World!"

ClearStack

# Current stack: empty

For now let's test our code with some debugging features. Let's add this at the bottom of our code.

ShowTraceLog
# Opens the trace log, which appears near CRPL towers using this script. It shows things like errors with scripts.

ClearTraceLog
# Empties trace log. I want to put this here since CRPL towers will run every frame, or 1/30th of a second. It would be nice to not make the log reach it's character limit in a few seconds.

TraceStack
# Inserts the current stack into the trace log without affecting the stack.

ClearStack
# Remove everything from the current stack.

If you were to copy+pase both of these code boxes into a crpl file, remove the first ClearStack and add the script to a CRPL tower, this would be the result:


(Any text followed by a # is marked as a comment for human readers and gets ignored by the game.)

Vars and Stacks

You can use arrows to set a variable equal to the item a the top of the stack and then pop said item, or push a var's value onto the stack.

5
# Current stack: 5
->numbA
# Current stack: empty
"creeper world 5 when" ->txt
# Current stack: empty
<-numbA
# Current stack: 5
7
# Current stack: 5 7
add ->numbB <-numbB
# Current stack: 12
<-txt
# Current stack: 12 creeper world 5 when

Input Variables

As I mentioned in the "Adding/using scripts" section, you can make vars that can be changed in-game, instead of having multiple copies of the same script with say 3 numbers changed.

$inputA:3.0
$inputB:5.6
$image:"Custom2_128"

<-inputA
# Current stack: 3.0 (unless the value was changed)

Trace
# This takes one item in the stack and puts it in the trace log

Operators and Functions

Interacts with the stack in various ways. Most functions require one or several inputs, many also output something.

5 4 add
# 9
dup
# 9 9
mul
# 81
ClearStack "red" "green" concat "blue" concat
# redgreenblue
CurrentCoords GetCreeper
# will push a float equal to the creeper under the crpl core
# or a negative float to represent anticreeper

Comparators and Flow Control

Compares things and returns 0 or 1 meaning "yes" or "no".

Usually in programming, these are usually called boolean values, but for some reason crpl doesn't have "true" or "false" values, it just uses the integers 0 or 1.

# Less than comparator
3 4 lt if
    # this code will be executed
endif

# Greater than or equal to comparator
6 9 gte if
    # this code will not run
endif

# Not operator
0 not if
    # will run
endif

10 0 do
    i Trace
loop
# this will trace the numbers 0-9
# first value is a limit, second value is starting value. i will start off as 0, then the code will increase i by 1 and run again until i is equal to the limit, then it will stop

while
    GetDeepestCreeperCell dup2 ->y ->x
    GetCreeper 10 gt
repeat
    <-x <-y 10 SetCreeper
endwhile
# a bit of a more complex example, this makes it impossible for a single cell to contain over 10 creeper

build-a-function!

as mentioned previously in the data types section, you can create your own functions! user created functions are called with @exampleFunction and defined with :exampleFunction. crpl has no marker for the end of a function, besides the beginning of another function or the end of a file, so put all functions at the bottom of your crpl file.

here are some examples of functions i use in my CRPL!

# short for Decimal Divide
# if you try to divide two ints, the result will also be an int
# this function avoids that by converting one number to a float before dividing
:ddiv
    0.0 add div

# combine all items in the stack into one string
# then set it as the text that appears when your cursor hover over the crpl tower
:MouseOverText
    StackSize 1 do concat loop SetPopupText

# debugging tools
:trace
    ShowTraceLog ClearTraceLog TraceStack
:traceClear
    @trace
    ClearStack

 # rounds down to 1 decimal place
:floor1
    10 mul floor 10 div

# getting unit coords too much of a tedious process? try this function!
# just give it a unit ID and it will tell you where he's at!
:getUnitCoords #(unitID) return x, y
    dup CONST_COORDX GetUnitAttribute swap CONST_COORDY GetUnitAttribute

# A more complicated function used in my unnamedgamemode.cw3 map
# input: unitID, absorbLimit (positive)
# actions: absorbs up to absorbLimit anticreeper under the unit of specified ID
# output: absorbed AC as a negative float (0 if nothing was absorbed)
:absorbAC
    -1 mul ->limit
    dup ->unit
    @getUnitCoords GetCreeper dup ->ac
    0 lt if
        <-ac <-limit max ->absorb
        <-unit @getUnitCoords <-ac <-absorb sub SetCreeper
        <-absorb return
    else
        0 return
    endif

The CRPL Reference

Link

[knucklecracker.com]
This reference sheet is your most helpful CRPL tool, as it contains descriptions of almost every var/function/whatever in CRPL. The table of contents and ctrl+f are very useful tools for finding things.

We also have plenty of dudes on the Knuckle Cracker Discord[discord.gg] that like answering crpl questions. If you're stuck on fixing an issue and feel ready to give up, you could always try asking for help in the #mapmaking-help channel!

(If invite link doesn't work, there is also one inside the game.)

Changelog

date (default format)	date (school shooting unaffordable healthcare format)	stuff that changed
28/04/2023	4/28/23	guide is getting pretty old now as well as I have significantly more crpl experience, so I decided to make some major changes. - removed a LOT of unnecessary information - corrected false/outdated/unclear info - added more helpful info - removed an example of a crpl file that was coded inefficiently - changed guide name and icon

[Neon]

It's rarely ever useful, but damn is it fun to do.

[Trazyn]

pog