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 tdm_user_addons.script to #include your .script file (works the same way as tdm_custom_scripts.script). You can also get your script called at map start here.
• 3) Package your files into a .pk4, named to sort alphabetically after existing TDM .pk4's.

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

1) Write 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", spider); //find the next entity which has an "ik_foot8" spawnarg (no value specified, because it doesn't matter in this case)

									//also, continue the search from the previously discovered spider entity
		
		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.)

2) Use tdm_user_addons.script to #include your .script file (works the same way as tdm_custom_scripts.script). You can also get your script called at map start here.

tdm_user_addons.script works the same way as tdm_custom_scripts.script, but its purpose is to be used for addons rather than FM-specific scripts. An important difference is that it also contains an empty script which gets called at map start. This can be used to get your scripts called when the map starts.

You can either create this file from scratch or extract it from tdm_base01.pk4 > tdm_user_addons.script.

First, #include your .script file. I've decided to call it tdm_arachnophobia.script:

#include "script/tdm_arachnophobia.script"

Then, if your addon needs it, let the void user_addon_init() script call your script. This works the same as the void main() script in a map .script:

void user_addon_init()			//If any of your addon scripts need to be initialised at map start, add their init function here. See the line that has been commented out with // for an example.
{
	sys.waitFrame();		//wait one frame so all entities can be spawned
	thread destroy_spiders();	//call the script to find & destroy & hide all spiders in the map
}

3) Package your files into a .pk4, named to sort alphabetically after existing TDM .pk4's.

Package your /script folder (containing tdm_user_addons.script and tdm_arachnophobia.script) into a .zip archive, then change the extension to .pk4. The name should sort alphabetically after tdm_base01.pk4, for example z_arachnophobia.pk4. This ensures that your tdm_user_addons.script overwrites the stock version, not the other way around.

You can now upload this to a file sharing website and post a link to the forums. The .pk4 doesn't need to be extracted on the user's end.

Compatibility with other addons

There can only be one tdm_user_addons.script, so if a player wants to use multiple addons these files need to get merged. It's quite straightforward: extract all addons, merge the #include lines and the contents oft the user_addon_init() script, place the "script" folder in the base installation.

Alternatively, you can do this for them for some popular combinations of addons.

Next / previous article

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