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

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.)

Use tdm_user_addons.script to #include your .script, optionally call scripts at map start

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, if needed.

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
}

Package into a .pk4

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.

Using multiple 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, so it could be left to them with these instructions:

• Extract all addon .pk4 archives, which are just renamed .zips, into their own folders.
• Go to the /script subfolders and move all the tdm_user_addons.script to a separate location.
• Combine all the tdm_user_addons.script files into a single file as follows:
  • try to open the first one: set Notepad or a similar program as your standard program for opening .script files
  • transfer the lines beginning with #include.
  • transfer what's inside the curly brackets that are below user_addon_init().
• Merge all the extracted addons together into a single folder, then insert your custom tdm_user_addons.script into the /script subfolder.
• Turn the addon into a .pk4 again: select all subfolders, compress them in a .zip and change the extension to .pk4. The name should begin with z, or anything else that sorts after "tdm".

You may want to offer premade combinations of your addon with some existing popular addons.

Next / previous article

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