Module Tutorial

Creating a module is pretty easy and even if you didn’t understand how the framework works, I advise you to just follow this tutorial step by step and eventually you’ll get the AHA!-effect. Learning by doing! Before you can start coding though, you must have the compiler installed and ready to use. Once you have that, continue reading.

The goal of this tutorial is to create a basic module which has a function that sends a welcome message to a specific player on the server. It will be more complex than just a simple “SendMessage” command ;)

With that in mind, let’s get started!

---

Module structure setup

The compiler reads all the available modules from the “modules” directory. So this is where you have to start: Navigate to the location on your PC where you installed the compiler, into the “modules” folder. As you can see there are already a few modules in there.

1. We are going to call our module “Hello”. So now you have to create a new folder called “Hello” right next to the other module folders.
2. Inside the “Hello” folder, we need two more folders called “methods” and “vars”; create them!
3. And finally, we need a file called: module.ini. This file is needed for the compiler.

If you did everything right, you should now have the following structure in place:

• /modules/Hello/
• /modules/Hello/methods/
• /modules/Hello/vars/
• /modules/Hello/module.ini

---

Module ini file

Before we head on to the methods and variables, let’s start with the easiest and most important part of the module. The module ini file is used by the compiler to identify the module and its underlying methods. It includes everything from names to descriptions and parameters; everything must be registered here first. You’re essentially defining what’s inside the module and what it does.

Go ahead and open the blank file, then copy the following code template into it. Note that the lines starting with a semi-colon (;) are comments – please read them!

; Basic package information
;     Note: You may use "\n" in the description to create a new line
; 
;     Very important: All information entered in this file is case sensitive.
;     Make sure you write everything correctly! Case sensitive means that
;     "Hello" is not equal "hello".
; 
[module]
name    = "Hello"
desc    = "Module to send a custom message to a specific player."
author  = "eaxs"
version = "1.0.0"
date    = "12-29-2011"
website = "https://github.com/eaxs/K2-Scripting-Framework"


; Module dependencies
;     List the names of the modules which are used by this module
;     You dont have to list K2 and Array here as they are part of the core
; 
[dependencies]
module[] = ""


; Module method list
;     List all public methods including description, except magic functions.
;     Magic functions are: "__construct", "__exec" and "__destruct".
;     Please make sure you have description for each method! You can use "\n"
;     to create a new line.
;
;     Example:
;         name[] = "myMethod"
;         desc[] = "This is my method"
; 
[methods]
name[] = "message"
desc[] = "Sends a message to a player"


; Module options list
;     For each of your public methods, list the available options
;     including name, description, type, and required.
;     For each method, you have to create a new section.
; 
;     Example:
;         [opt:myMethod]
;         name[] = "-p"
;         desc[] = "This is the -p option and is not optional"
;         type[] = "string"
;         req[]  = "0"
;         ... repeat ...
;  
[opt:message]
name[] = "message"
desc[] = "The message to send"
type[] = "string"
req[]  = "1"

name[] = "-p"
desc[] = "The player id to which to send the message to"
type[] = "int"
req[]  = "1"


; Config variables
;    List all config variables that are used in your module including:
;    name, description and default value
;    You may use "\n" in the description to create a new line
;
[config]
name[] = "hello_checkdouble"
desc[] = "Set this to 0 if you want to avoid sending the message twice"
value[] = "1"

The code in this file follows the INI-file guidelines and has a number of sections for grouping:

• [module]
• [dependencies]
• [methods]
• [opt:x]
• [config]

If you look at the code, you’ll see that I’ve already registered a method called “message” for you. The method takes two parameters: “message” and “-p” (see [opt:message]). Both of these parameters are mandatory (req[] = “1”).

If this doesn’t make any sense to you now, maybe this will help (we’ll get to that more in-depth later): In the Savage 2 console or in your script code, you can call the method like this:

ExecScript K2 Hello.message "Welcome to my server!" -p 0

I’ve also created a configuration variable for you: hello_checkdouble. We will use this later in the tutorial to set whether to avoid sending the same message to the same person twice or not. All config variables are available just like regular script variables. The example below will print out “1” in the console:

Echo #hello_checkdouble#

---

Private variables

Now that we have the module defined, lets continue setting up our private variables by creating a file called “priv.cfg” in the “vars” folder. Once you have that, open the file and copy the following code:

#$# hello_message_sent "hello_message_sent";
#$# hello_message_sent_datatype "array";
#$# hello_message_sent_idx -1;

This code creates 3 variables to form an empty array object called “hello_message_sent”. Normally we would create arrays using the “Array.new” method (this is part of the Array module); but due to technical reasons we can’t call this method in this file. So we have to create the object manually. An array is essentially a variable that holds a list of values. For example a list of fruits: Apple, Banana, Orange, etc.. We need this particular array “hello_message_sent” later in our code to check if we are sending a message no more than once to a player.

Note that variables you declare here will be reset after each map change. Also note that you should prefix your variables with “module_method_” (“hello_message_” in this example) to prevent conflicts with other modules!

---

Method code

Now comes the biggest part, the method code! If you haven’t understood much of the tutorial yet, this is the part where everything comes together and hopefully makes sense – so read carefully! If the code looks odd to you, note that I’m using shorthand variables (the #$# and #$e#’s).

Navigate to the “methods” folder of your Hello module and create a new file called “message.cfg”.

To be continued…