ISource2ModScripts

CS2 runs map and mode logic in JavaScript through point_script entities (import { Instance } from "cs_script/point_script"). This interface lets a plugin run scripts of its own and talk to them:

run a compiled script asset (.vjs) the way a map does -- this needs no signature and keeps working through game updates;
run raw JavaScript source, or a .js file straight from the server's disk, and run it again after an edit (hot reload);
fire an input a script listens for with Instance.OnScriptInput(...) (native -> script);
receive what a script sends with Instance.ServerCommand(...) (script -> native);
keep a script alive across round restarts and map changes.

A script sends a message with

Instance.ServerCommand("source2mod_script mychannel " + encodeURIComponent(JSON.stringify(data)));

and every handler registered for mychannel receives everything after the channel name. The line goes through the server's command buffer: it arrives on a later tick, a ; or a newline in it would split it into two commands, and it is cut at the buffer's line limit -- encode the payload (as above) and keep it short. Only the server itself can run source2mod_script; a client typing it is ignored.

Everything here belongs on the main thread.

Runs cs_script scripts for plugins and carries messages both ways.

A script is known by a name the plugin picks, which is also the targetname of its point_script entity; running a script under a name already in use replaces the old one. Every script and every message handler belongs to the plugin that created it and goes away when that plugin unloads.

Interface id ISource2ModScripts002 (SOURCE2MOD_SCRIPTS_INTERFACE) · Global g_pSource2ModScripts · Header source2mod/ISource2ModScripts.h

Types

`Source2ModScriptMessageHookId`

using Source2ModScriptMessageHookId = Source2ModHookId;

A cs_script message hook (HookScriptMessage).

`ScriptMessageHandler`

using ScriptMessageHandler = Source2ModCallback<void(const char* pszChannel, const char* pszPayload)>;

Called with a message a script sent through source2mod_script.

Methods

`CanRunSource`

virtual bool CanRunSource() = 0;

Whether raw source can be run (RunSource, RunFile).

Needs the game's script loader (gamedata "CSScript::RunScript") and the script component inside point_script. LoadAsset() works without both.

`LoadAsset`

virtual CEntityHandle LoadAsset(PluginId owner, const char* pszName, const char* pszAsset, bool bPersistent) = 0;

Runs a compiled script asset, exactly as a map's point_script does.

Parameter	Type	Description
`owner`	`PluginId`	Owning plugin
`pszName`	`const char*`	Name to refer to the script by
`pszAsset`	`const char*`	Resource path of the compiled script, e.g. "scripts/myplugin/main.vjs"
`bPersistent`	`bool`	Spawn it again after a round restart or a map change

Returns CEntityHandle — The point_script entity, or an invalid handle on failure

`RunSource`

virtual CEntityHandle RunSource(PluginId owner, const char* pszName, const char* pszVirtualPath, const char* pszSource, bool bPersistent) = 0;

Runs raw JavaScript source in a new point_script.

A script that does not compile is reported by the game in the server console; the entity exists regardless.

Parameter	Type	Description
`owner`	`PluginId`	Owning plugin
`pszName`	`const char*`	Name to refer to the script by
`pszVirtualPath`	`const char*`	Path the script goes by in errors and stack traces, e.g. "scripts/myplugin.js"
`pszSource`	`const char*`	The source, an ES module importing "cs_script/point_script"
`bPersistent`	`bool`	Run it again after a round restart or a map change

Returns CEntityHandle — The point_script entity, or an invalid handle when the source cannot be run

`RunFile`

virtual CEntityHandle RunFile(PluginId owner, const char* pszName, const char* pszFilePath, bool bPersistent) = 0;

Runs a JavaScript file from the server's disk.

Parameter	Type	Description
`owner`	`PluginId`	Owning plugin
`pszName`	`const char*`	Name to refer to the script by
`pszFilePath`	`const char*`	Absolute path, or relative to the game directory (`game/csgo`)
`bPersistent`	`bool`	Run it again after a round restart or a map change; the file is read again every time, so edits are picked up

Returns CEntityHandle — The point_script entity, or an invalid handle when the file cannot be read or run

`Reload`

virtual CEntityHandle Reload(const char* pszName) = 0;

Throws the script's entity away and runs the script again.

A file is read again, which makes this the hot reload after an edit; source and assets run as they were given.

Parameter	Type
`pszName`	`const char*`

Returns CEntityHandle — The new entity, or an invalid handle when there is no script by that name or it cannot be run

`Remove`

virtual void Remove(const char* pszName) = 0;

Removes the script and its entity. Unknown names are ignored.

Parameter	Type
`pszName`	`const char*`

`Find`

virtual CEntityHandle Find(const char* pszName) = 0;

The script's point_script entity, or an invalid handle.

Parameter	Type
`pszName`	`const char*`

`FireInput`

virtual bool FireInput(const char* pszName, const char* pszInput) = 0;

Fires the callback the script registered with Instance.OnScriptInput(pszInput, ...).

This is the game's RunScriptInput entity input. Only the input name reaches the script; data travels the other way (see HookScriptMessage()), or stays on the script side.

Parameter	Type
`pszName`	`const char*`
`pszInput`	`const char*`

Returns bool — false when there is no live script by that name

`HookScriptMessage`

virtual Source2ModScriptMessageHookId HookScriptMessage(const char* pszChannel, ScriptMessageHandler handler) = 0;

Receives what scripts send on a channel through source2mod_script.

Several handlers may hook one channel, from one plugin or more; each gets every message.

Whose it is, the core reads off the handler (see Source2ModCallback); what a plugin still holds at unload the core drops for it.

Parameter	Type
`pszChannel`	`const char*`
`handler`	`ScriptMessageHandler`

Returns Source2ModScriptMessageHookId — The id UnhookScriptMessage(id) takes

`UnhookScriptMessage`

virtual bool UnhookScriptMessage(const char* pszChannel, const ScriptMessageHandler& handler) = 0;
virtual bool UnhookScriptMessage(Source2ModScriptMessageHookId id) = 0;

Drops the hook with this handler -- a function or an object and a method; a lambda goes by its id.

Drops the hook HookScriptMessage() returned the id for.

Parameter	Type
`pszChannel`	`const char*`
`handler`	`const ScriptMessageHandler&`
`id`	`Source2ModScriptMessageHookId`

Returns bool — true when one was found

Macros

`SCRIPTS_LOAD_ASSET`

#define SCRIPTS_LOAD_ASSET(name, asset, persistent) g_pSource2ModScripts->LoadAsset(g_PluginID, name, asset, persistent)

Shorthand accessors via g_pSource2ModScripts.

Other macros

Macro	Expands to
`SCRIPTS_RUN_SOURCE(name, path, source, persistent)`	`g_pSource2ModScripts->RunSource(g_PluginID, name, path, source, persistent)`
`SCRIPTS_RUN_FILE(name, file, persistent)`	`g_pSource2ModScripts->RunFile(g_PluginID, name, file, persistent)`
`SCRIPTS_FIRE_INPUT(name, input)`	`g_pSource2ModScripts->FireInput(name, input)`
`HOOK_SCRIPT_MESSAGE(channel, handler)`	`g_pSource2ModScripts->HookScriptMessage(channel, handler)`
`UNHOOK_SCRIPT_MESSAGE(channel, handler)`	`g_pSource2ModScripts->UnhookScriptMessage(channel, handler)`

On this page