Function; addCustomCode - HWRM/KarosGraveyard GitHub Wiki

addCustomCode

💡 Also see this tutorial on custom scripting

addCustomCode(<ship_type>, <path_to_script>, <load_fn>, <create_fn>, <update_fn>, <destroy_fn>, <custom_group_name>, <update_interval>)
addCustomCode(NewShipType, "path/to/script.lua", "onLoad", "onCreate", "onUpdate", "onDestroy", "kus_interceptor", 2)

Description

⚠️ This function may only be called once per .ship definition; In order to call multiple scripts, you will need to create a new script which uses dofilepath to import other scripts.

Allows custom Lua code to be run when certain lifecycle hooks are triggered for a given ship type.

addCustomCode is called in a .ship file, kus_dronefrigate.ship contains an example of this.

These are:

  • load: Generally not so useful, load accepts no parameters and appears to run during the loading screen. The best we can do here is to create a sobgroup or something.
  • create: The first of the big three, create is called when a level finishes loading and a ship is spawned, or when a ship is constructed, or is manually spawned in through a script, etc.
  • update: Possibly the most useful of all, update is called periodically for every living squadron of the given ship type (the interval is the final parameter <update_interval>, and recieves the same parameters as create
  • destroy: Finally, destroy is called only when a ship dies, and again receives the same params.

The script passed as the second argument should contain the functions referenced afterward.

Example

-- ship/kus_repaircorvette/kus_repaircorvette.lua

function update(group, player_index, ship_id)
  SobGroup_CreateIfNotExist("closeby_player_ships");
  Player_FillProximitySobGroup("closeby_player_ships", 0, group, 2000);
  SobGroup_RepairSobGroup(group, "closeby_player_ships");
end
-- ship/kus_repaircorvette/kus_repaircorvette.ship

addCustomCode(NewShipType, "data:ship/kus_repaircorvette/kus_repaircorvette.lua", "", "", "update", "", "kus_repaircorvette", 1);

You'll notice we don't need to provide all the hooks if we don't plan to use them. We can also name the hooks and the sobgroup anything we like:

-- ship/kus_repaircorvette/kus_repaircorvette.lua

function myUpdateFunction()
  -- ...
end
-- ship/kus_repaircorvette/kus_repaircorvette.ship

addCustomCode(NewShipType, "data:ship/kus_repaircorvette/kus_repaircorvette.lua", "", "", "myUpdateFunction", "", "kus_repvette", 1);

Arguments

Param Type Description
ship_type UserData This should probably always be NewShipType.
path_to_script string A path to the Lua script containing the hook functions. Paths are like "data:scripts/my-script.lua". See this tutorial on file paths.
load_fn string The name of a function globally defined somewhere in the script referenced by path_to_script.
create_fn string See load_fn. Additionally, this function will be passed three parameters: a custom SobGroup containing the newly created squadron of ships, the player index of the player who owns the new group, and the unique ship id used by the squad (squads usually only contain one ship, only HW2 strike break this rule).
update_fn string Same as create_fn.
destroy_fn string Same as create_fn.
custom_group_name string The string name of the group passed as the first param for the create, update, and destroy functions.
update_interval number The interval (in seconds) between update_fn calls. The lowest value this can be is 0.1.

Scope

⚠️ **GitHub.com Fallback** ⚠️