SobGroup

💡 This definition is pulled from a larger tutorial.

A SobGroup (or just 'sobgroup'), is an in-engine collection of ships. As a modder, you cannot interact directly with ships, only sobgroups. As such, most functions which can manipulate ships during gametime are prefixed with SobGroup_. In reality you never truly interact with sobgroups either; all we really get is a string with the name of the group:

SobGroup_Create("my-sobgroup");

Here we named a new group, 'my-sobgroup'. Further sobgroup calls will need this name in order to know which group they need to interact with.

-- its useful to store a name in a variable so we can reuse it without typing it out exactly:
local name = "my-sobgroup";

SobGroup_Create(name); -- make the new group
SobGroup_FillShipsByType(name, "Player_Ships0", "hgn_torpedofrigate"); -- fill it with player 0 ships of this type
SobGroup_SetHealth(name, 0.1); -- set the health of all ships in the group to 0.1 (10% health)
-- etc..

💡 "Player_Ships0" is a predefined group

Trying to select a ship instead of a group

You can use SobGroup_FillShipsByIndexRange to split a group of ships into a table. Alternatively, the first argument in a call to a customcode hook will contain the individual callee ship (unless that ship is in a squadron i.e Hiigaran interceptors).

• A framework like modkit
  • modkit works by forcing every ship to have customcode hooks, and keeps a global record of these ships, removing the need to manually split sobgroups into ship tables
  • modkit also extends the sobgroup library with very useful functions like SobGroup_Split, SobGroup_ToShips, and SobGroup_FromShips

Common Pitfalls

Performing actions on groups instead of individual ships:

Let's say we want repair vettes to automatically repair allied units in a given radius around themselves.

We might try:

-- creates a new sobgroup called 'player_repairs'
SobGroup_Create("player_repairs");
-- fill group 'player_repairs' with ships from player '0', of type 'kus_repaircorvette'
Player_FillShipsByType("player_repairs", 0, "kus_repaircorvette");

-- creates a new sobgroup called 'closeby_player_ships'
SobGroup_Create("closeby_player_ships");
-- get player ships within 2000 units of 'player_repairs', store them in 'closeby_player_ships'
Player_FillProximitySobGroup("closeby_player_ships", 0, "player_repairs", 2000);
-- give them the repair command (they will start repairing any damaged ships)
SobGroup_RepairSobGroup("player_repairs", "closeby_player_ships");

Sounds good on paper, but there is a fatal flaw: we selected all the player repair vettes, and put them into a SobGroup.

The flaw was this:

Player_FillProximitySobGroup("closeby_player_ships", 0, "player_repairs", 2000);

This function will return damaged player ships in a 2000 unit radius... of the centerpoint of the whole sobgroup!. This is likely somewhere totally unrelated to what you had in mind, or any individual repair vette.

There are a few methods of achieving the second situation:

• You can use Custom Code to run functions for individual ships
  • Custom code is the only place you can grab a ship's ID; you will need to use it if you want to store information about a specific ship over multiple script calls
• You can split a group into a table using SobGroup_FillShipsByIndexRange
  • Or consider the friendlier SobGroup_Split
• A framework like modkit