Intro
cs_script is a JavaScript based scripting system for Counter-Strike maps.
It is a virtual machine for scripting which exposes various Source2 engine functionality and Counter-Strike specific info such as listening to events, accessing player data, firing I/O events, getting data about gamemodes, etc.
script_zoo.vmap
is a Valve made map to demonstrate basic functionality of the system, it can be found in
Counter-Strike Global Offensive\content\csgo\maps\editor\zoo\script_zoo.vmap
A significant amount of documentation on this page is taken from Counter-Strike Global Offensive\content\csgo\maps\editor\zoo\point_script.d.ts
Counter-Strike Global Offensive\content\csgo\maps\editor\zoo\point_script.d.ts
documents the JavaScript API for cs_script scripts attached to point_script entities.
This file is a TypeScript Declaration file.
This file can be used by various editors to provide tooling while editing JavaScript. Next to this file is a tsconfig.json
file configured for editing JavaScript targetting the current version used by CS2.
Place copies of these two files, point_script.d.ts
and tsconfig.json
, next to your scripts and some editors will begin providing tooling without further configuration. These two files will be maintained as the cs_script API changes or the JavaScript version in CS2 is updated.
"cs_script/point_script"
is the module provided to scripts loaded for point_script entities.
The are projects offering full TypeScript wrappers over the current JavaScript API, such as cs_script_boilerplate however
this page will not focus on that.
Setup
- Create a JavaScript file (.js) that imports this module.
- See
hello.js
for an example.
- See
- Create a point_script entity in your map and set its cs_script field to reference your JavaScript file as a vjs asset.
- See
Counter-Strike Global Offensive\content\csgo\maps\editor\zoo\script_zoo.vmap
. There is a point_script entity in there named "hello_cs_script" that runshello.js
. There are a handful of other examples as well.
- See
Execution
- The compiled version of your script (.vjs_c) will be loaded during map load.
- When the point_script entity is spawned it will execute all code at the top level scope of your script.
- Register callbacks on
Instance
to setup code that executes at various times throughout the lifetime of the map.- A function passed to
Instance.OnActivate
will be invoked when the point_script entity is activated. - A function passed to
Instance.OnPlayerJump
will be invoked when any player in the map jumps.
- A function passed to
Tips
- Entity variables are stable. Two variables referring to the same entity will be reference equals (===).
- Extra values attached to an entity variable will still be there if the variable is fetched again.
- A map can have multiple point_script entities. Each script will run with its own Instance, set of globals, and set of entity variables.
Tools Mode
- In tools mode, saving changes to your script will recompile your file, clear all registered callbacks, and re-run the top level scope of your script.
- Global variables and instances of entity variables will persist across reloads.
- Beware. This is an avenue for holding references to code from previous iterations of your script. This is only a concern in tools mode.
- See
Instance.OnScriptReload
for a tool to handle edge cases around reloading.