Running Scripts

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

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.

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
}

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

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