Script Addon Authoring

Creating your First Script Addon

Before creating your first script addon, it is highly recommended that you watch the 7-minute MugMod script screencast:

• Tutorial: Make a MugMod in Minutes <-- This link is broken

This guide assumes you are roughly familiar with how EventScripts works, though overtime it will evolve to include new scripter information.

This walkthrough will take you from start to finish in creating an example addon, and will also help in converting an existing (old-style) script pack to an addon.

Addon scripts are stored in the cstrike/addons/eventscripts directory in a folder based on the name of the addon.

In this example, our addon will be called 'myaddon'.

1. Create Your Addon's File

First, create a folder in cstrike/addons/eventscripts labeled 'myaddon':

cstrike/addons/eventscripts/myaddon

Then, create a blank text file in that directory labeled 'es_myaddon.txt':

cstrike/addons/eventscripts/myaddon/es_myaddon.txt

2. Learn about Events and Blocks

Events are easy. If you had a file called 'player_say.cfg', then you would use 'event player_say' in your es_myaddon.txt instead.

Blocks are pretty easy too - they're the non-event .cfg's of an addon. They can be called much the same way .cfg's are called, but instead of using 'exec events/myfile.cfg', you would use 'es_doblock myaddon/myblock'. For example, if your original script pack had something like this:

• cstrike/cfg/events/player_say.cfg

 if (event_var(text) equalto "test") then exec events/test_win.cfg
 if (event_var(text) notequalto "test") then exec events/test_lose.cfg

• cstrike/cfg/events/test_win.cfg

 es_xmsg Hooray, you said test!

• cstrike/cfg/events/test_lose.cfg

 es_xmsg You didn't say test.

...then the new format in es_myaddon.txt would be like this:

• es_myaddon.txt

 event player_say
 {
 	if (event_var(text) equalto "test") then es_doblock myaddon/test_win
 	if (event_var(text) notequalto "test") then es_doblock myaddon/test_lose
 }
 
 block test_win
 {
 	es_xmsg Hooray, you said test!
 }
 
 block test_lose
 {
 	es_xmsg You didn't say test.
 }

However, one beautiful thing about using an addon instead of a scriptpack is that you can use things like 'do' and 'else' as well. This allows you to skip an 'if', which improves the performance of the script:

• es_myaddon.txt

 event player_say
 {
 	if (event_var(text) equalto "test") do
 	{
 		es_doblock myaddon/test_win
 	}
 	else do
 	{
 		es_doblock myaddon/test_lose
 	}
 }
 
 block test_win
 {
 	es_xmsg Hooray, you said test!
 }
 
 block test_lose
 {
 	es_xmsg You didn't say test.
 }

This does tend to make the script more complicated for the writer, though - so if you are uncomfortable with this you can stick to 'if/then' until you get more comfortable using if/do/else.

3. Make Your First Blocks

The load block of an addon executes when the addon is loaded. It is analogous to the 'server.cfg' file of a script pack.

• es_myaddon.txt

 block load
 {
 	es_xsetinfo myaddon 1
 	es_makepublic myaddon
 }

You can also use create an 'unload' block. This block is executed whenever the script addon is unloaded. You can use this to zero out variables that are no longer needed (frees up memory if you have long strings stored in variables), delete unnecessary keys, keygroups, etc. Be a responsible scripter and free up as much memory as you can. ;)

• es_myaddon.txt

 block load
 {
 	es_xsetinfo myaddon 1
 	es_makepublic myaddon
 }
 
 block unload
 {
 	es_xsetinfo myaddon 0
 }

4. Write Events For Your Script Addon

Add events to your script addon just as you would to a .cfg - just remember not to use a .cfg at the end of the event name. ;)

• es_myaddon.txt

 block load
 {
 	es_xsetinfo myaddon 1
 	es_makepublic myaddon
 }
 
 block unload
 {
 	es_xsetinfo myaddon 0
 }
 
 event player_say
 {
 	if (event_var(text) equalto "test") do
 	{
 		es_doblock myaddon/test_win
 	}
 	else do
 	{
 		es_doblock myaddon/test_lose
 	}
 }
 
 event player_jump
 {
 	es_msg Player event_var(es_username) jumped!
 }

5. Write Blocks For Your Script Addon

Now you can write in blocks that you referred to in your events. Just for the sake of clarity later, you should add your blocks in the same order they're referred to in your events. That said, it really doesn't matter what order events and blocks are put into the file.

• es_myaddon.txt

 block load
 {
 	es_xsetinfo myaddon 1
 	es_makepublic myaddon
 }
 
 block unload
 {
 	es_xsetinfo myaddon 0
 }
 
 event player_say
 {
 	if (event_var(text) equalto "test") do
 	{
 		es_doblock myaddon/test_win
 	}
 	else do
 	{
 		es_doblock myaddon/test_lose
 	}
 }
 
 event player_jump
 {
 	es_msg Player event_var(es_username) jumped!
 }
 
 block test_win
 {
 	es_xmsg Hooray, you said test!
 }
 
 block test_lose
 {
 	es_xmsg You didn't say test.
 }

6. Check Your Syntax

The BIGGEST thing you'll run into when using script addons is syntax problems. Brackets, tabs, unreachable code, parenthesis, and quotes can all be checked by using a VERY handy tool that Chun has made available here:

Eventscripts Optimiser by Chun

Don't load your code without running it through this first. It'll save you and your players a lot of headaches.

7. Get Your Script Addon Running

Script addons are loaded and unloaded by using the 'es_load' and 'es_unload' commands. The script is called by using the following command/syntax:

 es_load myaddon

Note that there are no directory names in here - the script is loaded simply by referring to the name of your script due to the directory/file structure of script addons.

Your script addon can also be unloaded (even while running) by using the following command/syntax:

 es_unload myaddon

If you want to leave your plugin loaded, but you want to temporarily disable it, you can use:

 es_disable myaddon

...and enable it later with:

 es_enable myaddon

This is perfect for scripts you want to disable that track data with strings or keygroups you don't want to lose - i.e. when a 'fun' map is loaded, you may want to disable a script without losing the data so you can enable it again the following map and have it pick up where it left off.

There are a few different situations that apply to loading a script addon:

Situation 1: "I want this script ALWAYS running."

• Add 'es_load myaddon' to your autoexec.cfg file.

Situation 2: "I only want this script to run for certain maps."

• Add 'es_load myaddon' to the map .cfg's you want it to run on
• Add 'es_unload myaddon' to the server.cfg.

Since server.cfg is executed before the map-specific .cfg, it will unload each time a new map starts, then load if you've added 'es_load myaddon' to the map's .cfg.

Situation 3: "I want this script to run whenever another script pack / script addon calls it."

• Add 'es_load myaddon' to the script pack / script addon in the appropriate place. Don't forget to give yourself a way to unload the plugin with 'es_unload myaddon'.

Situation 4: "I want to run this script manually."

If you want to execute this from rcon:

• Bind a key to 'rcon es_load myaddon' by typing the following in your client console:

bind x "rcon es_load myaddon"

• Bind another key to 'es_unload myaddon' by typing the following in your client console:

bind x "rcon es_unload myaddon"

• You can optionally bind a key to pause/unpause the script addon by using:

bind x "rcon es_disable myaddon"

and

bind x "rcon es_enable myaddon"

Or to use Mani's rcon:

• Bind a key to 'es_load myaddon' by typing the following in your client console:

bind x "ma_rcon es_load myaddon"

• Bind another key to 'es_unload myaddon' by typing the following in your client console:

bind x "ma_rcon es_unload myaddon"

• You can optionally bind a key to pause/unpause the script addon by using:

bind x "ma_rcon es_disable myaddon"

and

bind x "ma_rcon es_enable myaddon"

Relevent Links

Original forum post for EventScripts v1.0 that added Script Addon support

--Faaip 20:39, 16 July 2006 (EDT)