A to Z Scripting: Script addons for players

Script addons for players

Script addons are additional custom scripts that players can download in order to modify their gameplay in all missions. Examples might be a script for players with arachnophobia that kills and hides all spiders at map start, or a script that automatically adds a custom item to the player's inventory at the start of every mission, such as a scroll displaying statistics about the current mission.

These are the steps in creating an addon:

• 1) Create a .script file in the "script" folder and write your script(s) into it.
• 2) Use a file in the format tdm_user_addons_*.script to #include your .script file (similarly to tdm_custom_scripts.script). You can also get your script called at map start here.
• 3) Package your files into a .pk4.

Example addon: kill & hide all spiders for players with arachnophobia

Writing the script

The first thing to do is find all entities that are spiders. You will need to find a spawnarg value which is used only by spiders: I've decided to check if the entity has got an "ik_foot8" spawnarg, since having 8 legs is a unique feature of spiders.

As shown in the Special Methods section, do + while() is well suited for going through all entities that match a certain spawnarg. Once the entity has been found, we can run kill() and hide() on it:

void destroy_spiders()
{
	ai spider;

	do
	{
		spider = sys.getNextEntity("ik_foot8", "right_leg_4_4", spider);	//find the next entity with a valid "ik_foot8" spawnarg
		
		if(spider)						//if a valid entity has been found, kill and hide it
		{
			spider.kill();
			spider.hide();
		}

	}	while (spider);						//keep going for as long as getNextEntity finds valid entities
}

(Note: you might want to add a second do + while() block for finding & hiding spiders that start as ragdolls.)

#include your .script files and call scripts at map start

As of version 2.12, TDM automatically finds and #includes all .script files that begin with the prefix "tdm_user_addons_" and are in the "script" folder. In this case you could name your script file "tdm_user_addons_spiders.script" and put it in the "script" folder.

You will probably also want some way to call your script at map start, even if it's just to give the player a custom-scripted tool or weapon. TDM v2.12 now automatically calls all script functions that begin with the prefix "user_addon_init_" about one or two frames after map start. For example:

void user_addon_init_spiders()
{
	thread destroy_spiders();	//call the script to find & destroy & hide all spiders in the map
}

Note that only one script file and function must follow the above naming conventions. You can #include further script files in your tdm_user_addons_* file, and you can call further functions from your user_addon_init_* function.

Package into a .pk4

Package your /script folder into a .zip archive, then change the extension to .pk4. If your addon contains further files that you want to overwrite core asset files with, then your addon .pk4 name should sort alphabetically after tdm_base01.pk4, for example z_arachnophobia.pk4. Otherwise the .pk4 name no longer matters as of TDM 2.12.

You can now upload this to a file sharing website and post a link to the forums. The .pk4 can simply be dropped into the user's main installation folder with no need to unpack.

Using multiple addons

As of TDM 2.12 users can use as many addons as they want. However, addons that have files, script functions or .pk4s with the same name will not be compatible. It's therefore advisable to use unique names for all of these, for example by having them include the creator's username.

Next / previous article

• Next article: A to Z Scripting: Troubleshooting
• Previous article: A to Z Scripting: Scriptobjects
• Table of contents: A to Z Scripting