Scripting

Introduction

This is the documentation for H2-Mod's scripting API.
This documentation is complementary to IW6x' scripting API so be sure to check out their wiki first if you are not familiar with it.

Example script

Because this is singleplayer there are no notifies like "connected" or "spawned_player" like there are in multiplayer, instead all scripts are loaded once the player has spawned which is accessible through the global player variable:

-- Script loaded and player spawned

-- Let the game's GSC scripts initialize first
game:ontimeout(function()
    player:setorigin(vector:new(10000, 10000, 10000)
end, 0)

Note that the player spawns as soon as the map loads but not after the loading screen cinematic ends so your script will start even if you aren’t yet "in-game".
To fix this wait for another server frame before running your code:

game:ontimeout(function()
    game:ontimeout(function()
        player:setorigin(vector:new(10000, 10000, 10000)
    end, 0)
end, 0)

-- This should also work fine:

game:ontimeout(function()
    player:setorigin(vector:new(10000, 10000, 10000)
end, 100)

Extra features

H2-Mod's scripting API includes features that are either not documented or don't exist on IW6x

Entity damage callbacks

You can 'hook' the game's entity damage function in order to modify the damage using the game:onentitydamage function:

-- When you (the player) get damaged the entity that actually gets damage 
-- first isn't the global `player` entity but the entity of number `1` and classname `scriptable`

local scriptableplayer = game:getentbynum(1)

game:onentitydamage(function(_self, inflictor, attacker, damage, mod, weapon, dir, hitloc)
    if (_self == scriptableplayer) then
        -- If the victim is you (the player) set the damage to 0
        return 0
    end
end)

Arrays