Script Fundamentals

This documentation covers some fundamental aspects of scripts in Sven Co-op that apply to all types of scripts.

Built-in hooks

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.

---

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.

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.

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
}

---

Console commands

There are a few console commands that apply to all scripts:

Command name	Purpose	Admin only?
as_generate_config	Outputs a file that contains the entire API as a config. Defaults to "asconfig"	Yes
as_generate_includes	Outputs the automatically included headers for a given module type to a file	Yes
as_globals	Outputs a list of global variables that exist in the API to a file. Defaults to "asglobals"	Yes
as_showversioninfo	Shows Angelscript version info	No

Variadic arguments

Certain functions in the API support the use of variadic arguments. This allows you to pass a varying number of arguments to a function. For instance, snprintf allows you to format a string using a variable number of arguments:

snprintf( szResult, "format string", argument1, argument2, argument3 );

This same function can take, 0, 1, 2, 3 or more arguments.

All variadic functions are easy enough to spot, since they always use the special argument type "?& in" for variadic arguments. Typically you see several versions of the same function listed with a varying number of these arguments.

In our API, all variadic functions support up to 8 variadic arguments.