RPGCode — Language Features — Basics
Contents
The Basics of Functions
When you run a computer program, your computer will perform different tasks depending on what the program is telling it to do. A program is nothing more than a set of instructions. However, the computer is dependent on you, the programmer, writing those instructions. If you don't tell the program what to do, where to do it, and when to stop, it won't do anything!
This manual will teach you the syntax of RPGCode—the scripting language used to write programs that run in the RPGToolkit's engine—assuming that you have no prior experience in any programming or scripting languages. We will start learning how to give instructions in our programs by using functions, a key part of RPGCode. So let's dig in right away with this simple script:
mwin("Hello world!");
wait();
If you run this program, you should see the text "Hello world!" appear. Pressing a key on the keyboard will end the program. So what's happening here? Well, the first thing we did was write mwin (which can be interpreted as Message Window), which is a function. Functions are used to perform specific tasks in the program when the function is called, however many times it is needed (for example, the mwin function's task is to show text in the message window). The wait function is used to pause the program until the user presses a key on their keyboard.
That's fine and dandy, but what does the other stuff do? When you write a function's name, you will also write a set of parentheses (the ( and ) characters). In the example above, we passed an argument into the mwin function by writing "Hello world!" between the parentheses. An argument is data that a function uses to work differently or provide different results (for example, the mwin function is given one argument—the message—which will be displayed on the screen). There are many different functions in RPGCode and they have different numbers of arguments that they use: Some of them use no arguments at all (as in wait()) and others may use many. In the functions revisited section, I will write more about arguments so you have a clearer understanding of them.
The semi-colon (;) at the end of the line is not part of the function itself; it is rather just a character placed at the end of a statement. It is optional, but I will be using it all throughout this manual.
Variables
Variables are placeholders for data. The types of data that they can contain are numbers (numeric values) and characters (strings or literal values). What does that mean? Let's say that you have two numbers stored in your memory right now, 4 and 8. Let's also say that we are going to refer to these numbers as number a and number b. If I told you to add the values of number a and number b together, the result will be the number 12 (4 + 8). A variable is like a label that is attached to a value and stored in your computer's memory, so we can consider number a and number b to be variables that store numeric values.
Numbers:
The same example I've just given you (addition with numbers) can be reproduced in code by using variables, and this is how:
a = 4; b = 8; c = a + b;
First, we create the variable a and assign to it the value 4. We then create another variable, b, which is 8. A final variable, c, is assigned the value returned by a + b, which is 12. The same example can be reproduced with c = a + 8, c = 4 + 8, etc. Either way, c will always end up with the value 12. Other mathematical operations such as division and multiplication are also possible:
a = 4; b = 8; c = b - a; d = a * b; e = a / b;
We have created the same two variables, a and b, but this time we are subtracting, multiplying, and dividing instead of adding. In this example, the variable c has the value 4 (4 subtracted from 8), d has the value 32 (4 multiplied by 8), and e has the value 0.5 (4 divided by 8).
It is also possible to use scientific notation when dealing with numbers (as in 1e+6 or 1e-2).
Strings:
A string is one or more characters that are enclosed in quotes. When assigning a string to a variable or using a string as an argument (as with the "Hello world!" string we used earlier in the mwin example), quotation marks must be used. Assigning a string to a variable is done the same way as assigning a numeric value:
someString = "Hello!";
The above code will produce the variable someString with the value "Hello!". Addition can also be applied to strings, as is illustrated next:
x = "Hello"; y = x + " world!";
First, we assign "Hello" to x. Then we assign x + " world!" to y. The variable y is now equal to "Hello world!". That's all there is to it!
Variables in RPGCode are not restricted to a certain data type ("duck typing"). At any time, you can assign a string value to a variable that already has a numeric value or vice versa. You can even mix the data types together (for instance, x = "Hello " + 32 will produce the string value "Hello 32"). Variable names may contain letters, numbers, and underscores and are case-insensitive.
Arrays and maps:
Arrays are groups of data that are referred to by the same identifier, whose values are accessed by using a pair of square brackets and an index. Of course, that's just one way to put it: let's look at an example so we can get a clearer picture of the actual syntax!
x[0] = 1; x[1] = 2; show(x[0]); show(x[1]); wait();
In this example, we create an array with two elements (x[0] and x[1]), assign them the values 1 and 2, then show them in the message window. Different elements of the array are accessed with the array subscript operator [], where the value between the brackets is its operand (the element of the array to access). If that sounds confusing at all, then let's look at it this way: Think of a variable identifier (such as x or y) as a box; usually, this box can only hold one thing, like the number 5. If we use an array, we can refer to more than one thing with the box using an ID or index. Simple, right?
Arrays in RPGCode may also have more than one index at a time, specified by more array subscript operators following the first. These are all valid:
things[0] = 99; things[1][0] = "Hello!"; things[1][0][0] = 32;
Maps are also allowed in RPGCode. They are basically arrays with string indexes instead of numerical indexes. They look a little something like this:
person["name"] = "OC"; person["level"] = -1; person["occupation"] = "Fun!";
Also take note that the index of an array or map can actually be any valid RPGCode expression. For example, if you have an array with the index 5, it is valid to access it like this:
someArray[5] = 10; show(someArray[3 + 2]);
Variables, functions, other arrays — anything that returns a value can be used here.
Functions revisited
Arguments:
Now that we've taken a look at what variables are, let's back-track to functions for a bit. From the first portion of this page, you learned that a function argument is a piece of data — a number or string value, like what we discussed with variables — that is written between the function's parentheses. Anything that results in a number or a string can be used as an argument. Look at this piece of code:
a = 4;
b = 8;
mwin(a);
mwin(a + b);
mwin("Testing addition: " + b);
wait();
Here, we've assigned the values 4 and 8 to the variables a and b (like we did earlier), but this time we've displayed them on the screen with the mwin function. The first time, we display the variable a, which is 4. Then we displayed 12 (a + b; the number returned by the equation was used as the argument). Lastly, we displayed the string "Testing addition: 8" (because b was tacked onto the end).
Return values:
Some functions in RPGCode return certain values. A common example of this is the wait function, which can return the key that the user pressed. Any value that a function returns is just like what was discussed in the section about arguments — it can be assigned to a variable, operated on, or used directly as an argument (you could even think of expressions like 2 + 2 as having "return values" because they produce a resulting value). The following two examples will show whatever key the user pressed on the keyboard using two different approaches:
key = wait(); mwin(key); wait(); mwinCls();
mwin(wait()); wait(); mwinCls();
The first line of code in the first example, key = wait() pauses the program until the user presses a key on their keyboard, which is then returned by the function and stored in the variable key. It is then output to the screen. The second example eliminates the need for a variable by passing wait's returned value directly into the mwin function. (mwincls(), by the way, just clears the message window from the screen.)
Comments
You are able to write comments in your programs that are ignored when the program is run. These are useful for offering insight into a particular piece of code, showing an example of how something might be used, and other things. Comments are marked by two forward slashes (//) and can appear almost anywhere in your code. For example:
// This is a comment — it's ignored at run-time!
// The following line of code won't be run because it's commented:
//mwin("Hello, world!");
As of 3.1.0, C-style comments are also allowed. Any text between /* and */ will be considered comments:
/* A single-line C-style comment. It also allows multiline comments! */