Skip to main content

Intro

cs_script is a JavaScript iconJavaScript 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.

info

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.

note

The are projects offering full TypeScript iconTypeScript 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.
  • 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 runs hello.js. There are a handful of other examples as well.

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.

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.