How to add a stun grenade

[Fulby]

Tutorial file is available here.

The file includes the tutorial in plain text, plus the final plugin files for comparison.

 

Introduction

This tutorial will show you how to add a new grenade as an ALPine plugin. The new grenade will stun enemies rather than damaging them.

 

The tutorial assumes you already have ALPine installed and have extracted the contents of the "gamedata.vfs" archive or know how to access its files.

 

 

Step 1: Create plugin file and directory

1a.

We'll call the plugin "grenade", so create a text file in the ALPine\plugins directory called "grenade.lua", and a directory called "grenade" in the same directory.

 

1b.

Double click on "grenade.lua", and Windows should ask you which program to open the file with. Choose Notepad or your usual plain text editor; do not use Word or another full word processor unless you know how to save files in plain text format.

 

Add the following lines to "grenade.lua":

print("My grenade")

print("My grenade processed")

 

Close/save the file.

 

1c

Run ALPine and your plugin should appear at the bottom of the list with the name "grenade". Make sure it is the only plugin selected and press Apply. The following text should appear in ALPine:

Applying Plugins
Processing grenade...
Finished processing plugins

 

Close ALPine and open the file "alpine.log" in the ALPine directory. It should contain the following:

My grenade
My grenade processed

 

Any print() statement within a plugin is written to "alpine.log"; this is helpful for debugging plugins. It is customary to being a plugin by calling print("name"), and ending it with print("name processed"). Any text output produced by your plugin will then appear between those lines, making it easy to identify as belonging to your plugin.

 

Close "alpine.log" and proceed to Step 2.

 

 

Step 2: Copy weapon file to plugin directory

The simplest way to add a new item with ALPine is to create a file with the same structure as UFO: Aftermath's item file for that item type, but containing only the item you wish to add. When adding an item, it's best to modify a copy of an existing record instead of starting from scratch. Pick an existing item which closely matches the item you wish to add.

 

We'll do this by copying the weapon file and removing all the entries except the one we'll use as the base for the grenade. This will be the record for the fragmentation grenade, though you could use any other grenade if it were closer to the effect you wish to achieve.

 

2a

The weapon data is stored in the file "listofweapon.txt" in the "tactical\configs\game" directory of "gamedata.vfs". Copy this file into the "plugins\grenade" directory you created in Step 1a. Open this file in a plain text editor.

 

The weapons are stored in a list which starts after "LIST_OF_WEAPON" and ends at "END_OF_LIST_OF_WEAPON". Each weapon is contained between the lines "WEAPON" and "END_OF_WEAPON". Each line is a field of the record, the field name followed by the value. Items are uniquely identified by the field "ID". The fragmentation grenade we will use has "HG-FRAG" as its ID. Search for "HG-FRAG" (without quotes) in the file and you should see the entry for the fragmentation grenade.

 

2b

We only want this entry, so delete the other weapon entries - make sure that you are editing the copied file and not the original. The edited file should look like this:

 

; Exported from file: \\VELRYBA\ufo\Documentation\Design\Fight.xls
LIST_OF_WEAPON
 WEAPON
   ORIGIN HUMAN
   TYPE HAND_GRENADE
   SHORT_NAME "Frag"
   ID HG-FRAG
   TECH_LEVEL 1
   CLASS OTHER
   ANIM_TYPE THROW
   PRINCIPLE GRENADE
   HANDLING NORMAL
   EQUIPMENT ALL
   MAG_QUANTITY 10
   HAND 1.0
   NOTRELOAD FALSE
   WEIGHT 0.7
   AMMOID ID_GF
   ACCURACY_AIMEDA 5.0
   ACCURACY_BURSTA 0.0
   ROUNDS_USED_AIMEDU 1
   ROUNDS_USED_BURSTU 0
   POWER 1000
   DAMAGE 550
   TIMES_RELOAD 2.0
   TIMES_AIMEDT 3.0
   TIMES_BURSTT 0.0
   RANGE 11.0
   AREA 5.0
   PROJ_SPEED 5.0
   DURATION 0.0
   SEC_DAMAGE 0.0
   DTYPE "S"
   EFFECT_FRONT_AIM ""
   EFFECT_FRONT_BURST ""
   EFFECT_BACK ""
   EFFECT_IMPACT "tactical/particles/hit_effect groups/rocket_hit01.pgrp"
   EFFECT_AREA ""
   PATH_3D "tactical/models/weapons/h_hg-frag_3d.txt"
   VIDEO "strategic/models/interface/equipment/weapons/human guns/h_hg-frag_3d.txt"
   ICON "tactical/models/interface/items/weapons/h_hg-frag.txt"
   PROJECTILE ""
   PROJECTILEFIRE ""
   PROJECTILESMOKE ""
   PARTICLE ""
   SHAPE "s11"
   SOUND_NAME_A ""
   SOUND_NAME_B ""
   SOUND_NAME_RELOAD ""
   SOUND_NAME_IMPACT "share/sound/wavs/guns/explosion.wav"
 END_OF_WEAPON
END_OF_LIST_OF_WEAPON

 

Lines beginning with semi-colon are comments and can be deleted if you wish. Do not worry if you see odd block characters in places. Delete them and enter a new line in their place, so the affected lines should look like this:

    EFFECT_IMPACT "tactical/particles/hit_effect groups/rocket_hit01.pgrp"
   EFFECT_AREA ""
   PATH_3D "tactical/models/weapons/h_hg-frag_3d.txt"
   VIDEO "strategic/models/interface/equipment/weapons/human guns/h_hg-frag_3d.txt"
   ICON "tactical/models/interface/items/weapons/h_hg-frag.txt"
   PROJECTILE ""
   PROJECTILEFIRE ""
   PROJECTILESMOKE ""
   PARTICLE ""
   SHAPE "s11"
   SOUND_NAME_A ""
   SOUND_NAME_B ""
   SOUND_NAME_RELOAD ""
   SOUND_NAME_IMPACT "share/sound/wavs/guns/explosion.wav"
 END_OF_WEAPON

 

Now save the file.

 

 

Step 3: Edit weapon record stage 1

The first thing we need to change is the "ID" field to a unique name. I suggest using "GRENADE". If you use something else check that it isn't already used by another item in the game.

 

This is enough for the game to add a new item, so now we'll add the plugin code and test that everything done so far works.

 

 

Step 4: Add plugin code

4a

Open "grenade.lua" again. Although ALPine has many functions which can manipulate the game data in various ways, a new item can be added with a single statement. The function to do this with weapons is "addweapon(filename)" where filename is the file with the new weapon. Add the following line to "grenade.lua" between the two print statements:

addweapon("grenade\\listofweapon.txt")

 

Note that the path is relative to the "plugins" directory. Also note the double backslash because the backslash is the escape character in Lua. See the Lua reference manual for more details if you don't know what this means.

 

Save the file.

 

4b

Open ALPine.exe and Apply just the grenade plugin. ALPine should display the same text as it did in 1c. Some possible errors and solutions:

 

Syntax Error in plugin: plugins\grenade.lua

This is a mistake in the plugin file, check that it looks exactly like this:

print("My grenade")
addweapon("grenade\\listofweapon.txt")
print("My grenade processed")

 

Lua Error: code\files.lua:397: bad argument #1 to `lines' (No such file or directory)

stack traceback:

code\core.lua:291: in function `alpine_error_handler'

[C]: in function `lines'

code\files.lua:413: in function `loaditemse'

code\items.lua:29: in function `addweapon'

plugins\grenade.lua:2: in main chunk

This error occurs if ALPine cannot find the file you specified. On the hard drive, check the directory name and file name of your plugin. Also check that you haven't mistyped the file path or name in the plugin file. You can see that the last line of the traceback specifies the line in the plugin file which caused the error.

 

4c

Assuming the plugin was applied correctly, close ALPine and run UFO: Aftermath. Start a new game and go into the Squad screen. Click on the Other tab and there will be a new grenade there, called "GRENADE". You could start a tactical mission to test the grenade, but at the moment it acts exactly the same as the fragmentation grenade, so close the game and continue to Step 5.

 

 

Step 5: Edit weapon record stage 2

Now that we have added the new item, it's time to change its attributes. You may want to backup the "grenade\listofweapon.txt" file before proceeding.

 

We want to change the grenade so that instead of doing damage to enemies it stuns them. This is done by changing the damage type of the weapon, which is stored in the field "DTYPE". For more information on what each field means, see the Modding Reference forum at UFOaftermath.co.uk and sigget and Fnurg's UFO documentation.

 

The damage type for stun is "Z". The value needs to be enclosed in quotes, so find the line:

    DTYPE "S"

and change it to:

    DTYPE "Z"

 

We also need to give the grenade damage a duration for it to stun the enemies for more than an instant. Change the value in the "DURATION" field to "10.0".

 

Save the file, apply the plugin and run the game. Equip some of your squad with the new grenades (don't confuse them with the fragmentation grenades) and go into a tactical mission. The grenades should stun enemies within the blast radius.

 

 

Further additions

You now have a working plugin. Assuming you were going to release it, there are several things you can/should do to make it complete.

 

A readme file

This would be named "grenade readme.txt" and tells people about your plugin, every plugin should include one of these. The readme text is also displayed within the ALPine GUI. See the guidelines on writing plugin readmes and look at existing plugins for examples.

 

Its own icon

An original icon can help the player to distinguish your item from others that already exist in the game. Adding a new icon requires adding several files. The Stun Rod, TNT and WTD plugin all add icons; examine these and the original game items for examples.

 

A glossary entry and text

ALPine can add new glossary entries and text to the game, you can use these to replace the displayed name "GRENADE" with something more suitable, and to display an entry in the glossary describing your item.

 

 

Conclusion

Hopefully this tutorial has answered some questions about modding UFO: Aftermath and brought up new ones :-). You can find many modding resources at UfoAftermath.co.uk, and the modding community uses the forums there. Before posting a question, please be sure to check that it hasn't already been answered or is available in the Modding Reference or one of the modding documents.

[Aralez]

Excellent work! Keep'em coming!

[Fulby]

Updated tutorial with ALPine 3.0.1 error message display and short explanation of it.

 

Fulby