Running Scripts

Sven Co-op allows you to install scripts into the game through two main ways: map scripts and plugins.

• Map scripts run when a map is launched and terminate when a map ends
• Plugins run when the server is launched and continues to run until the server closes

Some API methods are exclusive to map scripts and some are exclusive to plugins.

1 Execution

Scripts that are executed by the game have a few standard hooks in it that let you react to state changes in the game. These state changes cover the loading of maps, not gameplay state changes.

Note: These methods can not be used inside a class or namespace.

1.1 MapInit

When a new map is started, all scripts are initialized by calling their MapInit function.

It has the following signature:

void MapInit()
{
	// Code here
}

MapInit is called after all entities in the map have been created and spawned, but before they are activated. The sound list isn't written until after activation, which allows MapInit to precache sounds.

You cannot trigger entities in MapInit: not all entities created by other entities have been spawned yet. After MapInit has executed, the engine runs 2 frames of game logic and physics to start things up properly.

For this reason, if you want to trigger entities, either use MapStart, or use the scheduler to schedule a function for execution after the required amount of time. In this function you can trigger any entities you want.

If you're writing a map script and have any hooks you want to register, MapInit is where you should do it. It isn't required, but it's guaranteed to happen before any hooks are called.

If you have any custom entities to register or content to precache, it should be done in MapInit.

1.2 MapActivate

Like MapInit, only called after all mapper placed entities have been activated and the sound list has been written. It has the following signature:

void MapActivate()
{
	// Code here
}

From this point onwards you are unable to register entities, or precache anything else as the sound list and resource list are already written and are ready to be sent to the player as soon as they connect.

1.3 MapStart

Called after 0.1 seconds of game activity, this is used to simplify the triggering on map start. Think of it as trigger_auto, only as a script function. It has the following signature:

void MapStart()
{
	// Code here
}

2 Map Scripts

Sven Co-op allows maps to use scripts. A map script is active as long as the map itself is active, and can manipulate just about everything in the map.

2.1 A Simple Map Script

The simplest map script is an empty script, since there are no required parts to it. As covered by the Script fundamentals documentation, there are a few functions that are automatically called. Here's a script that will output "Hello World!" without quotes to the console when the script is initialized:

void MapInit()
{
	g_Game.AlertMessage( at_console, "Hello World!\n" );
}

Where to place map scripts Map scripts must be placed in the scripts/maps directory. You can place them in a subdirectory if you want, but be aware that using long paths can cause issues, so avoid using deeply nested paths and long directory names.

It is recommended that you use directories to group scripts together to avoid cluttering the main directory, and to avoid using the same name as other scripts. Using the name of the map or map series you're making the script(s) for will usually suffice.

How to load map scripts There are 2 ways to load map scripts: by specifying it in the map cfg, or in a trigger_script entity. The starting directory is scripts/maps.

When using a map cfg to specify it, you must use the map_script command. You can use this command multiple times to specify multiple scripts.

For example:

map_script HLSP

When using a trigger_script, specifying a script name in "Script to load" (m_iszScriptFile) will load it as though it were specified in the map cfg.

Console commands There are a few console commands that apply to map scripts:

Command name Purpose Admin only? as_listmapscriptinfo Outputs map script information No as_scriptbaseclasses Shows the custom entity base class implementations (Warning: creates a substantial amount of console output!) Yes API availability Most of the API is available for map scripts to use, but there are a few things that are exclusive to them:

Entity user data: only map scripts can use this to avoid plugins altering the behavior of map scripts. Custom entities: both map scripts and plugins can define and use custom entities. In the past this used to be available only for map scripts to avoid plugins from altering the gameplay of a map, and to avoid creating problems when plugins are (re)loaded while a map is active, this is no longer the case. Entity loader: since this behaves like the map loading process, only map scripts can access it to prevent plugins from altering gameplay. map and map temp directories in the filesystem: Ability to read/write files in these directories is restricted to map scripts.

• trigger_script

Hooks:

• PrimaryAttack
• SecondaryAttack
• TertiaryAttack
• PlayerUse
• PlayerPreThink
• PlayerPostThink
• GetPlayerSpawnSpot

Consult the documentation for the respective features for more information. For information on which parts of the API are exclusive to other script types, consult their documentation.

3 Plugins

Sven Co-op supports the use of plugins for servers. This allows you to write scripts that run as long as the server is active, allowing you to do almost as much you can do in a map script.

3.1 A Simple Plugin

The minimum requirements for a plugin are that it provides a PluginInit function, and properly sets up the author and contact info fields. This is to prevent plugins with no known source from existing.

void PluginInit()
{
	g_Module.ScriptInfo.SetAuthor( "Sven Co-op Development Team" );
	g_Module.ScriptInfo.SetContactInfo( "www.svencoop.com" );
}

In order to prevent malicious scripts from altering this information, you can only set this information from PluginInit itself. It should be the first thing you do in PluginInit, to avoid any confusion.

3.2 Where to place plugins

Plugins must be placed in the scripts/plugins directory. You can place them in a subdirectory if you want, but be aware that using long paths can cause issues, so avoid using deeply nested paths and long directory names.

It is recommended that you use directories to group scripts together to avoid cluttering the main directory, and to avoid using the same name as other scripts.

3.3 Plugin List File

The plugin list file is a text file, using the Keyvalues format, that contains a list of all plugins that the server will load.

The list uses the following format:

"plugins"
{
	"plugin"
	{
		"name" "PluginName"
		"script" "PluginScriptName"
		"adminlevel" "<admin level>"
		"concommandns" "pluginns"
	}
}

Each plugin has its own plugin block, which contains 2 required keyvalues: name and script. These define the name of the plugin (case insensitive, no duplicates allowed) and the main script file to include.

The adminlevel keyvalue is optional, and defines the minimum admin level required for players to use console commands and hooks that have the admin flag set, such as the ClientSay hook. You must choose one of these possible values:

Name	Who can use commands
ADMIN_NO	All players
ADMIN_YES	Only admins and the server owner
ADMIN_OWNER	Only the server owner

The concommandns keyvalue is also optional, and defines the console command namespace used for plugin console commands (see console command system documentation).

The list file also allows the use of single line commands that start with "//".

Note: if your plugin is located in a subdirectory of the main plugin directory, you must also include that subdirectory in the script path. For instance, if your script is named "myplugin.as" and is located in "scripts/plugins/wip/", you will need to write the script name as wip/myplugin.

3.4 Console commands

There are a few console commands that apply to plugins:

Command name	Purpose	Admin only?
as_listplugins	Shows a list of all plugins currently active on this server	No
as_reloadplugin	Reloads a plugin that is in the list of plugins	Yes
as_reloadplugins	Reloads all plugins from the plugin list file	Yes
as_removeplugin	Removes a plugin from the plugin list	Yes
as_removeplugins	Removes all plugins	Yes

3.5 API availability

Most of the API is available for plugins to use, but there are a few things that are exclusive to them:

• CAdminControl: administrative control for actions such as penalizing, killing, kicking, and banning players.
• Plugin and plugin temp directories in the filesystem: Ability to read/write files in these directories is restricted to plugins.

Hooks:

• CanPlayerUseReservedSlot
• ClientConnected

Consult the documentation for the respective features for more information. For information on which parts of the API are exclusive to other script types, consult their documentation.

4 Importing scripts

Other script files can be imported if you wish to use components from them via the #include directive:

#include "path/to/another/script"

This is inserted to the top of the script file above any code.

The path is relative to this script file, so if the script file you wish to import is in the same folder simply specify the filename. Otherwise you must set the path to the subfolder that the script file exists in.