A to Z Scripting: Script addons for players - Revision history

Dragofer at 23:09, 17 November 2023

2023-11-17T23:09:03Z

← Older revision		Revision as of 23:09, 17 November 2023
Line 4:		Line 4:
	These are the steps in creating an addon:		These are the steps in creating an addon:
	*1) Create a .script file in the "script" folder and write your script(s) into it.		*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.		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~~, named to sort alphabetically after existing TDM .pk4's~~.		*3) Package your files into a .pk4.


Line 32:		Line 32:
	(Note: you might want to add a second do + while() block for finding & hiding spiders that start as ragdolls.)		(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.

	~~=== Use tdm_user_addons.script~~ to ~~#include~~ your .script~~, optionally call scripts~~ at map start ~~===~~		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:
	~~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.~~		void user_addon_init_spiders()

	~~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		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 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~~.		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 ~~doesn't need to~~ be ~~extracted on~~ the user's ~~end~~.		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 ==		== 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:~~		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.

	* 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 / previous article ==

Datiswous at 17:06, 24 November 2022

2022-11-24T17:06:27Z

← Older revision		Revision as of 17:06, 24 November 2022
Line 76:		Line 76:

	[[Category:Scripting]]		[[Category:Scripting]]
			{{Addons}}

Dragofer: /* Next / previous article */

2020-12-27T19:46:38Z

Next / previous article

← Older revision		Revision as of 19:46, 27 December 2020
Line 72:		Line 72:

	*Next article: [[A to Z Scripting: Troubleshooting]]		*Next article: [[A to Z Scripting: Troubleshooting]]
	*Previous article: [[A to Z Scripting: ~~Utility scripts~~]]		*Previous article: [[A to Z Scripting: Scriptobjects]]
	*Table of contents: [[A to Z Scripting]]		*Table of contents: [[A to Z Scripting]]

	[[Category:Scripting]]		[[Category:Scripting]]

Dragofer: /* Using multiple addons */

2020-12-27T18:33:03Z

Using multiple addons

← Older revision		Revision as of 18:33, 27 December 2020
Line 67:		Line 67:
	* 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".		* 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 ~~addons~~ with some existing popular addons.		You may want to offer premade combinations of your addon with some existing popular addons.

	== Next / previous article ==		== Next / previous article ==

Dragofer: /* Using multiple addons */

2020-12-27T18:31:24Z

Using multiple addons

← Older revision		Revision as of 18:31, 27 December 2020
Line 59:		Line 59:

	* Extract all addon .pk4 archives, which are just renamed .zips, into their own folders.		* Extract all addon .pk4 archives, which are just renamed .zips, into their own folders.
	* Go to the /script ~~folders~~ and move all the tdm_user_addons.script to a separate location		* 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:		* 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		** 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 the lines beginning with #include.
	** transfer what's inside the curly brackets that are below user_addon_init().		** transfer what's inside the curly brackets that are below user_addon_init().
	* Merge all the extracted addons together, then insert your custom tdm_user_addons.script into the /script ~~folder~~.		* 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".		* 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 addons with some existing popular addons.		You may want to offer premade combinations of your addons with some existing popular addons.


	== Next / previous article ==		== Next / previous article ==

Dragofer: /* Use tdm_user_addons.script to #include your .script, optionally call scripts at map start */

2020-12-27T18:28:43Z

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

← Older revision		Revision as of 18:28, 27 December 2020
Line 40:		Line 40:
	First, #include your .script file. I've decided to call it tdm_arachnophobia.script:		First, #include your .script file. I've decided to call it tdm_arachnophobia.script:
	#include "script/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:		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:
Line 47:		Line 48:
	thread destroy_spiders(); //call the script to find & destroy & hide all spiders in the map		thread destroy_spiders(); //call the script to find & destroy & hide all spiders in the map
	}		}


	=== Package into a .pk4 ===		=== Package into a .pk4 ===

Dragofer at 18:28, 27 December 2020

2020-12-27T18:28:24Z

← Older revision		Revision as of 18:28, 27 December 2020
Line 8:		Line 8:


	=== Example addon: kill & hide all spiders for players with arachnophobia ===		== Example addon: kill & hide all spiders for players with arachnophobia ==
	~~1) Write~~ the script		=== 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.		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.

Line 33:		Line 33:


	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.~~		=== 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.		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.		You can either create this file from scratch or extract it from tdm_base01.pk4 > tdm_user_addons.script.
Line 49:		Line 49:


	3) Package ~~your files~~ into a .pk4~~, named to sort alphabetically after existing TDM .pk4's.~~		=== 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.		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.		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.		== 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 folders 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, then insert your custom tdm_user_addons.script into the /script folder.
			* 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 addons with some existing popular addons.

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

2020-12-27T18:13:43Z

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

← Older revision		Revision as of 18:13, 27 December 2020
Line 19:		Line 19:
	do		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)~~		spider = sys.getNextEntity("ik_foot8", "right_leg_4_4", spider); //find the next entity with a valid "ik_foot8" spawnarg
	~~//also, continue the search from the previously discovered spider entity~~

	if(spider) //if a valid entity has been found, kill and hide it		if(spider) //if a valid entity has been found, kill and hide it
Line 54:		Line 53:

	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.		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 ===		=== Compatibility with other addons ===

Dragofer: /* Next / previous article */

2020-12-23T23:49:29Z

Next / previous article

← Older revision		Revision as of 23:49, 23 December 2020
Line 67:		Line 67:
	*Previous article: [[A to Z Scripting: Utility scripts]]		*Previous article: [[A to Z Scripting: Utility scripts]]
	*Table of contents: [[A to Z Scripting]]		*Table of contents: [[A to Z Scripting]]

			[[Category:Scripting]]

Dragofer at 11:10, 21 December 2020

2020-12-21T11:10:09Z

← Older revision		Revision as of 11:10, 21 December 2020
Line 16:		Line 16:
	{		{
	ai spider;		ai spider;

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

	if(spider) //if a valid entity has been found, kill and hide it		if(spider) //if a valid entity has been found, kill and hide it
	{		{
	spider.kill();		spider.kill();
	spider.hide();		spider.hide();
	}		}

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