Q's Practical Guide to KAG Modding #1: Setting up

Q's Practical Guide to KAG Modding #1: Setting up
Written: Build 1435, 2015-03-29​

In this guide we will focus on setting up a quick and efficient way to develop, test, and debug mods locally. By the conclusion of this tutorial, you will be able to download any mod and run it on your client without hassle.

What mods are, and how they work​

Mods are stored in the "../Mods/" directory, one level deeper than your main KAG directory.

Each folder in "../Mods/" corresponds to a mod. The configuration file "../mods.cfg" determines which mods are loaded.

Mods overwrite or supplement the default game resources in "../Base", which are always loaded. The customary way is to internally 'emulate' the structure of "../Base/" in your mods folder, although this is not strictly necessary. For specifics, peruse the "../Base/" directory on your local install.

Mods are customarily collections of four file types: ".as", ".cfg", ".png" and ".ogg", arranged in the aforementioned directory pattern. They perform the following functions:

• .as: These are Angelscript files, which determine most of the logic and behavior of the game.
• .cfg: These are 'blob' configuration files, which define the sprite filename, animations, inventory settings, and internal name of everything except tiles.
• .png: These are image files, which define the graphics of menus, sprites, tiles, map backgrounds, and more.
• .ogg: These are sound files, which define sound effects, background music, and menu sounds, and more.

If there are file collisions between mods, the mod lowest in mods.cfg has highest priority.

I mentioned 'blobs', but did not define them. This involves how the game, on a fundamental level, works:

How the game works​

In the game itself, every executable object is classed into the following categories:

• blob: Blobs are 'things' on the map, that can be moved, held, or placed. Some examples are: characters, projectiles, buildings, tents, and vehicles. There are also hidden blobs, such as the one that controls sound. Things that you place, but which are not an actual part of the map grid, are blobs: ladders, trap blocks, team bridges, etc. Every blob has one or more 'scripts'.

• tile: Tiles are what are placed onto the map, as a builder. They are not 'objects' themselves, in that they don't run any scripts themselves. All functionality of tile blocks is controlled by the map.

• script: Scripts encapsulate all of the logic and behavior of all blobs, rules, and the gamemode. They themselves have certain properties, such as under what conditions they execute, or how often they tick. If associated with a blob, every script may have 'onInit(CBlob@ this)' and/or 'onTick(CBlob@ this)' function hook, as well as other hooks, like onThisPutInInventory(CBlob@ this, CBlob@ inventoryblob). Hook functions are functions that the underlying game engine call under various conditions

There are other objects, e.g. CMap, CRules, and CInventory, but they only serve to give scripts access to the underlying game engine, and their behavior is hard-coded.

By default, the vanilla KAG client does not load any mods. For this reason, we must run a 'local server' instead:

How to configure your local server​

To run mods locally, we need to start a 'local server'. The local server is ran by executing "runlocalhost.bat". Before we do that, though, we need to set up the local server configuration:

Gamemode:
To make sure the gamemode is appropriate for the mod you are developing, open up autoconfig.cfg (found in the main directory) and look for the 'sv_gamemode' key. By default, it is "TDM", but you'll probably want it "Sandbox". If you are developing a custom gamemode, well, that is covered elsewhere, perhaps.

Chat commands (sv_test):
If you set "sv_test" to 1, you will be able to spawn any blob with the chat command !<blob_name> e.g. !mat_wood, !mat_stone, !knightshop. You can even spawn unused, or new, blobs, e.g. !satchel and !fireplace.

Now that we have the gamemode and settings of our local server configured, we can install our mods:

How to install and run mods​

Installing and running mods is an easy three-step process:

• Move the mod folder to "../Mods/".
• Add a line to "../mods.cfg", containing the name of the mod folder.
• Run "../runlocalhost.bat"

For practice, I've attached a small mod, "Flying_Knight". Using the above steps, install and run it on your local server.

While developing mods, it can get tedious restarting your local server every time you make a change. For this reason, there is a method to do so without completely restarting:

How to modify mods without restarting your local server​

In "../Mods/Flying_Knight/Entities/Characters/Knight/KnightLogic.as", on line 142, is the following code:

Code:

    // BEGIN Flying_Knight MODIFICATIONS
    bool pressed_V = this.isKeyPressed(key_taunts); // key_taunts is unused, and defaults to the 'V' key

    if (pressed_V)
    {
        this.setPosition(aimpos);
        this.setVelocity(Vec2f_zero);
    }
    // END Flying_Knight MODIFICATIONS

The code, which consist the entire functionality of the mod, reads as follows:

"If we're currently pressing V, set the position of the knight to the cursor position, and set the velocity of the knight to zero"

If we wished, we could replace "key_taunts" with "key_use". This would change the key to fly from 'V' to 'E'. Using your preferred text editor, do so now.

To then reload the script on your local server, run the command "rebuild" in the console, which is accessed by the home key.

If you did so, the key which enables flight has changed from 'V' to 'E' without restarting the server. This allows speedy mod development, and is very useful for debugging broken scripts.

To load modified sprites in a running server/game, use the console command "/restartserver" instead, instead of "rebuild".

How do I learn how to write my own mods?​

The Wiki and official docs both have a large database of object types, built-in functions, variables, and syntax rules. However, neither are completely correct or complete.

Ultimately, perusing the "../Base/" scripts is the best way to learn. As well, a useful technique for discovering undocumented functionality is the "find-in-directory" feature in Notepad++ and other text editors. This allows you to perform searches like "void on" to get an exhaustive list of every hook function that does not return a value.

You should now have a rudimentary development environment to begin developing your mod. Good luck!

If you found this guide useful, give me a like or say so in the comments. That's the only source of initiative for me in continuing this series.​