Skip to content

Scripting Modules

Jump to bottom
Dreamy Cecil edited this page Oct 25, 2026 · 2 revisions

A guide to scripting custom modules using Squirrel scripting language.

Custom script modules

You can create special script modules full of functions that will be executed upon specific events in the game.

These modules can be defined as singular .nut scripts inside the Scripts/Squirrel/Custom/ directory that are automatically loaded and executed once upon starting the game. If you wish to add/remove script modules during the game or modify any existing ones, they have to be reloaded using the scr_ReloadCustomScripts() shell command.

Additionally, any extra modules can be loaded by using the scr_LoadCustomScript() shell command.

Warning

Upon reloading script modules with scr_ReloadCustomScripts(), any custom scripts that have been loaded from outside the modules directory will have to be manually loaded in again using the scr_LoadCustomScript() command.

Script hooks

By default, any code outside functions is executed as soon as the custom script module is loaded. But certain functions may be defined as hooks that will be called at specific points in time.

Processing

Timed events that execute upon specific tick updates.

OnStep()

Executed after each tick of the world simulation, essentially synchronized with the current game. Affected by real time factor.

Return value: null

OnFrame(surface)

Executed after rendering an entire frame of the game window.

Arguments:

  • surface - CDrawPort to draw on.

Return value: null

Rendering

Events that execute upon rendering the "game" part of the game.

OnPreDraw(surface)

Executed before drawing a frame of the current game.

Arguments:

  • surface - CDrawPort to draw on.

Return value: null

OnPostDraw(surface)

Executed after drawing a frame of the current game.

Arguments:

  • surface - CDrawPort to draw on.

Return value: null

OnRenderView(viewer, surface)

Executed after rendering a world from a certain viewpoint.

Arguments:

  • viewer - CEntityPointer with the entity that's currently viewing the world (may be none).
  • surface - CDrawPort to draw on.

Return value: null

Networking

Events that execute upon certain network packets received by the client in a game.

OnAddPlayer(entity, local)

Executed upon adding a new player to the game.

Arguments:

  • entity - CEntityPointer with the player that has just been added to the game.
  • local - Whether this player entity belongs to the client running the script and not to some other client.

Return value: null

OnRemovePlayer(entity, local)

Executed upon removing a player from the game.

Arguments:

  • entity - CEntityPointer with the player that has just been added to the game.
  • local - Whether this player entity belongs to the client running the script and not to some other client.

Return value: null

Packets

Events that execute upon certain network packets received by the currently running server.

OnCharacterConnect(client, character)

Executed upon a specific client trying to connect a new player to the game. The passed player character may be modified before applying it to the new player.

Arguments:

  • client - Index of the client that's trying to connect with a specific player character.
  • character - CPlayerCharacter with the player profile of the connecting player.

Return value: null

OnCharacterChange(client, player, character)

Executed upon a specific client trying to change the player character of one of their players (e.g. set a new name or a player model). The passed player character may be modified before applying it to the specified player.

Arguments:

  • client - Index of the client that requests a character change.
  • player - Index of the player in the game that requests a character change (may be different for the same client index if the client is connected in split screen).
  • character - CPlayerCharacter with the new player profile that the player wants to change to.

Return value: bool with whether the character is allowed to be changed.

OnPlayerAction(client, player, action, resent)

Executed upon receiving a player action from a specific player with new controls that need to applied. The passed player action may be modified before applying it to the specified player (e.g. to disable specific keys or modify movement/rotation speed).

Note

These player actions are sent every single simulation tick regardless of whether the player applied any input or not. This may be used in order to execute specific actions on player's behalf, such as make them walk in some direction or fire a weapon without them ever perfoming those actions themselves.

Caution

Player actions may be sent multiple times at once, each one using a different resent index. If you intend on executing singular actions upon specific player actions (such as sending packets for modifying entities), make sure to always check for resent index of -1 and exiting the function if it's not equal to it!

Arguments:

  • client - Index of the client that sent the player action.
  • player - Index of the player in the game that needs to apply the new player action.
  • action - CPlayerAction with the action to apply to the specified player.
  • resent - Index of the buffered action that needs to be reapplied. Index of the original unbuffered action is always -1.

Return value: null

OnChatMessage(client, from_mask, to_mask, message)

Executed upon receiving a chat message from the specified client but before sending it out to the destination players.

Arguments:

  • client - Index of the client that sent the chat message.
  • from_mask - Integer with the bit mask of players that are sending the chat message.
  • to_mask - Integer with the bit mask of players that are supposed to receive the chat message.
  • message - String with the chat message.

Return value: bool with whether the chat message can be forwarded to the requested players instead of simply processed and discarded.

OnChatOutput(from_mask, from_name, sender, message)

Executed upon receiving a chat message from the server to be displayed in chat for this client locally.
The function may optionally return an array with two strings that will modify the way the chat message will be printed out in the console. If the sender name or the message are set to empty strings (""), the chat message will not be printed out. If the return value isn't an array or doesn't contain two strings, it is ignored.

Arguments:

  • from_mask - Integer with the bit mask of players that sent the chat message to this client.
  • from_name - String with the symbolic name of the chat sender (e.g. "Server", "Client 1", "Client 2" etc.).
  • sender - String with the names of the chat message senders (may be the same as from_name if there are no physical players that sent the message).
  • message - String with the chat message.

Return value: array with two strings:

  1. New sender name (set it to sender to keep it the same)
  2. New chat message (set it to message to keep it the same)

Game events

Events that execute upon game logic.

OnGameStart()

Executed after starting any game.

Return value: null

OnChangeLevel()

Executed after changing levels during the game.

Return value: null

OnGameStop()

Executed after stopping the game.

Return value: null

OnGameSave(file)

Executed after saving the game into the specified save file.

Arguments:

  • file - String with the path to the save file.

Return value: null

OnGameLoad(file)

Executed after loading the game from the specified save file.

Arguments:

  • file - String with the path to the save file.

Return value: null

Demo events

Events that execute upon demo logic.

OnDemoPlay(file)

Executed after starting playing the specified demo file.

Arguments:

  • file - String with the path to the demo file.

Return value: null

OnDemoStart(file)

Executed after starting recording the specified demo file.

Arguments:

  • file - String with the path to the demo file.

Return value: null

OnDemoStop()

Executed after stopping recording a demo file.

Return value: null

Listeners

Events that execute upon specific entity logic.

OnSendGenericEvent(entity, event, args)

Executed upon sending some generic event to some entity.

Arguments:

  • entity - CEntityPointer with the entity that's supposed to receive the event.
  • event - Event code of the sent event.
  • args - Array of event arguments depending on the event code.

Return value: null

OnSendEnemyEvent(entity, event, args)

Executed upon sending some enemy event to some enemy (EnemyBase).

Arguments:

Return value: null

OnSendPlayerEvent(entity, event, args)

Executed upon sending some player event to some player entity (Player or PlayerWeapons).

Arguments:

Return value: null

OnReceiveGenericEvent(entity, event, args)

Executed upon receiving some generic event by some entity during its procedure logic.
Depending on specific entity logic, it may not always trigger, even if the same event triggered OnSendGenericEvent.

Arguments:

Return value: null

OnReceiveEnemyEvent(entity, event, args)

Executed upon receiving some enemy event by some enemy (EnemyBase) during its procedure logic.
Depending on specific entity logic, it may not always trigger, even if the same event triggered OnSendEnemyEvent.

Arguments:

Return value: null

OnReceivePlayerEvent(entity, event, args)

Executed upon receiving some player event by some player entity (Player or PlayerWeapons) during its procedure logic.
Depending on specific entity logic, it may not always trigger, even if the same event triggered OnSendPlayerEvent.

Arguments:

Return value: null

OnPlayerItem(entity, event, args, picked)

Executed upon any player receiving a new item.

Arguments:

  • entity - CEntityPointer with the entity that's receiving the item.
  • event - Event code of the received item.
  • args - Array of event arguments depending on the event code.
  • picked - Whether the item has been successfully picked up by the player instead of simply passing through it.

Return value: null

OnDamage(caller, target, inflictor, damage_type, damage_amount, hit_point, direction)

Executed upon any entity receiving any sort of damage.

Arguments:

  • caller - CEntityPointer with the entity that called the function to deal damage.
  • target - CEntityPointer with the target that receives damage.
  • inflictor - CEntityPointer with the entity that dealt the damage (may be different from caller or even none).
  • damage_type - Damage type from the DMT enum.
  • damage_amount - Amount of damage that was supposed to be dealt.
  • hit_point - FLOAT3D with the absolute position of the physical point of damage.
  • direction - FLOAT3D with the normalized direction away from the source of damage (e.g. in the opposite direction from the explosion).

Return value: null

Timer events

Timed events that execute globally across the entire game.

OnTick()

Executed each game tick regardless of the current world at a constant tickrate of 20 TPS.

Return value: null

OnSecond()

Executed each second regardless of the current world (right after the first tick at 20 TPS).

Return value: null

Event arguments

Reference table for arrays of arguments that are passed into listener functions depending on the event code.

OnSendGenericEvent / OnReceiveGenericEvent

Event codes that may be passed to OnSendGenericEvent() or OnReceiveGenericEvent() with their respective arguments.

Event code (event) Arguments array (args) Argument types
EVENTCODE.EInternal [] None
EVENTCODE.EVoid [] None
EVENTCODE.EReturn [] None
EVENTCODE.EBegin [] None
EVENTCODE.ETimer [] None
EVENTCODE.ETouch [other, this_moved, collision] CEntityPointer, bool, FLOATplane3D
EVENTCODE.EPass [other, this_moved] CEntityPointer, bool
EVENTCODE.EBlock [other, collision] CEntityPointer, FLOATplane3D
EVENTCODE.EWouldFall [] None
EVENTCODE.ETeleport [] None
EVENTCODE.EPreLevelChange [user_data] integer
EVENTCODE.EPostLevelChange [user_data] integer
EVENTCODE.EFirstWorldBase [] None
EVENTCODE.EDamage [inflictor, direction, hit_point, damage, damage_type] CEntityPointer, FLOAT3D, FLOAT3D, float, integer (DMT enum)
EVENTCODE.EDeath [inflictor, direction, hit_point, damage, damage_type] CEntityPointer, FLOAT3D, FLOAT3D, float, integer (DMT enum)
EVENTCODE.ETakingBreath [breath_delay] float
EVENTCODE.EActivate [] None
EVENTCODE.EDeactivate [] None
EVENTCODE.EEnvironmentStart [] None
EVENTCODE.EEnvironmentStop [] None
EVENTCODE.ETeleportMovingBrush [] None
EVENTCODE.EEnd [] None
EVENTCODE.EStop [] None
EVENTCODE.EStart [caller] CEntityPointer
EVENTCODE.ETrigger [caller] CEntityPointer
EVENTCODE.EReminder [value] integer
EVENTCODE.EScroll (only in TSE) [start, sender] bool, CEntityPointer
EVENTCODE.ETextFX (only in TSE) [start, sender] bool, CEntityPointer
EVENTCODE.EHudPicFX (only in TSE) [start, sender] bool, CEntityPointer
EVENTCODE.ECredits (only in TSE) [start, sender] bool, CEntityPointer

OnSendEnemyEvent / OnReceiveEnemyEvent

Event codes that may be passed to OnSendEnemyEvent() or OnReceiveEnemyEvent() with their respective arguments.

Event code (event) Arguments array (args) Argument types
EVENTCODE.EStartAttack [] None
EVENTCODE.EStopAttack [] None
EVENTCODE.EStopBlindness [] None
EVENTCODE.EStopDeafness [] None
EVENTCODE.EHitBySpaceShipBeam [] None
EVENTCODE.ERestartAttack [] None
EVENTCODE.EReconsiderBehavior [] None
EVENTCODE.EForceWound [] None
EVENTCODE.ESound [sound_type, target] integer, CEntityPointer

OnSendPlayerEvent / OnReceivePlayerEvent

Event codes that may be passed to OnSendPlayerEvent() or OnReceivePlayerEvent() with their respective arguments.

Event code (event) Arguments array (args) Argument types
EVENTCODE.EKilledEnemy [] None
EVENTCODE.ESecretFound [] None
EVENTCODE.EWeaponChanged (only in TSE) [] None
EVENTCODE.EBoringWeapon [] None
EVENTCODE.EFireWeapon [] None
EVENTCODE.EReleaseWeapon [] None
EVENTCODE.EReloadWeapon [] None
EVENTCODE.ECenterMessage [message, length, sound_type] string, float, integer
EVENTCODE.EComputerMessage [message_file] string
EVENTCODE.EVoiceMessage [sound_file] string
EVENTCODE.EReceiveScore [points] integer
EVENTCODE.ESelectWeapon [weapon_slot] integer

OnPlayerItem

Event codes that may be passed to OnPlayerItem() with their respective arguments.

Event code (event) Arguments array (args) Argument types
EVENTCODE.EAmmoItem [ammo_type, quantity] integer, integer
EVENTCODE.EAmmoPackItem (TFE) [shells, bullets, rockets, grenades, electricity, iron_balls] integer, integer, integer, integer, integer, integer
EVENTCODE.EAmmoPackItem (TSE) [shells, bullets, rockets, grenades, napalm, electricity, iron_balls, sniper_bullets] integer, integer, integer, integer, integer, integer, integer, integer
EVENTCODE.EArmor [amount, over_top_armor] float, bool
EVENTCODE.EHealth [amount, over_top_health] float, bool
EVENTCODE.EKey [key_type] integer
EVENTCODE.EMessageItem [message_file] string
EVENTCODE.EPowerUp (only in TSE) [powerup_type] integer
EVENTCODE.EWeaponItem [weapon_type, ammo_quantity, dropped] integer, integer, bool

Designed and developed by Dreamy Cecil since 2022

https://github.com/SamClassicPatch

Links

Quick guide

New in-game options

New commands

Classics Patch development

Other

Clone this wiki locally