[SCRIPTING] Ship linking

As some of you may know, I have been trying to work out how to make the Taiidan Republic platforms link together in a reliable way. The current solution is far from ideal. This thread is to chart my re-write of the linking scripts with (hopefully) community input.

The Goal

  1. Platforms that link together in a ring of three
  2. Platforms that are already deployed cannot move to link with another platform
  3. Once platforms are linked, they cannot move
  4. The player should not be allowed to do anything silly:
    a) It should not be possible to command a platforms to link with a platform that is already “full” of neighbours
    b) It should not be possible to command two platforms to link with the same target platform
  5. The linking process should not disrupt the game by cancelling orders or resetting things:
    a) Any fighters docking/docked/launching from a platform should not be affected by the linking operation
    b) The health/targets/attackers/guarders of the platforms should not be affected by the linking operation
  6. When a linked platform is destroyed, its neighbours should become available for linking again
  7. Linked platforms should have health/functionality bonuses for being linked

The current solution

The current solution uses the vanilla docking function managed through customcode. When created, platforms can dock and be docked with. As soon as a platform docks, its “parent” is swapped for an identical HOD with no dockpaths, to prevent it being docked with again. This only happens on docking, so it does not prevent a player from order multiple platforms to dock with the same target. Nor does it prevent commands to dock with the moving platform, which confuses things (or maybe it should be possible)… On docking, the “child” platform is swapped with an identical HOD that is “immovable”, so it stays put and does not drift away from its parent.

The problems are:

  • No management of docking commands - it is always possible to dock with a “booked” platform until the moment of docking. This is because it is impossible to know the target of a ship that is docking until it has docked.
  • Spurious bugs when docking lead to misalignments.
  • Health/targets/attackers are not retained due to HOD-swapping (although this could be worked in by logging the health/targets/attackers and re-applying them after HOD-swap)


  1. Use the “form hyperspace gate” command to link the platforms. This command would momentarily link the platforms as hyperspace gates (to pair them). The script would then remove the ability to hyperspace, and order the platform to dock.
  2. A custom command with its own icon - I’m not even sure if this is possible…
1 Like

Should be relatively easy to test. Adding a button in the “command panel” doesn’t take long.
Ask if you need help :wink:


Thanks, I wouldn’t know where to start. It’s not just the button though, is how to link it to some code that can identify the link subject and target platforms. The drone frigate is the only example of custom command that I can find. The problem is that it is a bit “passive” in that it doesn’t refer directly to other ships.

I’ve never used custom code, so I won’t be of any help on this specific part unfortunately :confused:

Custom code isn’t to difficult to use. First is the calling function within the ship file
addCustomCode(NewShipType, "a","b","c","d","e","f",g)

  • a = path to lua file
  • b = load function (Loaded when the hod is loaded or just prior to the gamerules oninit [which ever is later])
  • c = create function (Called when the unit is built [CustomGroup does NOT contain the unit])
  • d = update function (Called on interval set by ‘g’)
  • e = destroy function (Called when unit enter’s death phase [Unit still exists and does exist in CustomGroup])
  • f = the string name of the sobgroup
  • g = Interval in seconds (Used to determine when update function is called)

[Begin Edit]
Forgot to write more on the custom code.

Most of the function calls have the same 3 arguments CustomGroup, playerIndex, shipID
CustomGroup is used as the sobgroup name for functions like SobGroup_OwnedBy
playerIndex is self explanatory.
shipID is rather useless… though it’s a unique number for that perticular ships custom code, so it’s does in it’s own way have a use.

The load function only has 1 argument, playerIndex.

The scope of the custom code contains all the same functions as the gamerules scope, and the sobgroups are the same between them.
[End Edit]

Custom command is something different. Not much information is known about it, though there has be talk of it
.Custom Code Examination
.CustomCommand Demystified!...mostly...sorta

There is also another function SobGroup_CustomCommandTargets, but am unsure how that works.

Also, SobGroup_GetCommandTargets might be useful with COMMAND_Dock & COMMAND_Custom but have read that it only works with COMMAND_Attack & COMMAND_Guard.

Other units that use CommandCommand are the HW1 Scouts (For the speed burst) and the Gravity wells.

Depending on how SobGroup_CustomCommandTargets works, could try using it to redo the dock function for the platforms.

1 Like

I am familiar with custom code - that is how my current solution works.

Unfortunately customcommandtargets takes the target as an input. What I need is to get the target into my custom code from the UI. That is why hyperspace gates are my favoured option at the moment. As you say, it is possible to get the targets of the attack and guard commands directly, but not others.

I don’t remember, but is there a way to set the selected ships into a sobgroup ?
If yes, then it’s possible to call this function when you click on the button, and use the created sobgroup in the customcode. Or did I completely misunderstood ?

I think you misunderstood. In an ideal world I would like a command icon and cursor. When the player uses this command to target another platform, I need to get a sob group containing the target platform so that I can mage the code work.

If this is not possible, perhaps the custom command could hijack the guard or form hyperspace gate commands?

Ahhh, ok, and yes, I completely misunderstood ^^
That’s ATI stuff, not UI stuff, and I’m pretty sure that it’s not possible to add a new command there (I could be wrong though, but I didn’t see any new things concerning this subject in HWrm compared to HW2).

OK, so a custom command can be used to trigger a ship action, like the gravwell or drone frigate, but not too do something actively to another ship?

Don’t know.
Adding a command button in the bottom-right corner of the UI is definitely possible (and adding some code to execute to it too). But the cursor thing is (from what I know) not possible.

I’m unable to test this, but there are 2 arguments with CustomCommand that I don’t know if we know what they do.


From the example above, the arguments in question are the 5th and 6th ones 1,0. From the info found in Custom Code Examination, these arguments are always 1 & 0 respectively. (The first example in the link does show 1 & 1, but that is the kus_dronefrigate and the next example shows 1 & 0 and is again, the kus_dronefrigate…)

(I did check the list shown in Custom Code Examination and these don’t show the arguments in question)

I am wondering if changing one of these arguments allows for the custom command to have a targeting action (Like attack, guard, dock, etc)

Thinking about it, if setting one of the above values to it’s opposite does allow for the custom command to target another unit, then it could be SobGroup_CustomCommandTargets(<a>,<b>) that allows the code to detect who was targeted.

SobGroup_CustomCommandTargets(<CustomGroup>, <sOutputSobGroup>)
1 Like

I hope you are right, but I suspect not. It was a gearbox Dev who confirmed to us that it was only functional for guard and attack:

EDIT: sorry, I now realise that you are talking about a slightly different function…

tested changing the values of addAbility. changing the 5th value from 1 to 0 had no noticeable effect and changing the 6th value from 0 to 1 caused the game to crash when the unit is spawned. also SobGroup_CustomCommandTargets appeats to toggle the custom command state.

Oh well, thanks for trying!

SobGroup_CustomCommandTargets invokes the command and gives it a target. What I need is the other way round, to get a target…

The “form hyperspace gate” command forces the platforms to rotate to face each other… I cannot find how to override this… Any ideas?

Disabling AB_Steering did the trick:

SobGroup_AbilityActivate(CustomGroup, AB_Steering, 0) -- disable_steering

However, my next problem is how to “break” the hyperspace gate link. Once linked, two gates are permanently linked, it seems. Even removing the ability to form a hyperspace gate will not break it. The only ways I can find to break the link are:

  • Destroy one of the gates
  • Link with another gate

I don’t want to have to despawn a platform and spawn another if I can help it. I would prefer a cleaner way…

how about replace the old gates with new ones?

That’s why.

It’s a slightly hack-y workaround, and not super intuitive, but you could use SobGroup_GetCommandTargets(<sOutputSobGroup>, <sSobGroupDoingTargetting>, COMMAND_Guard) with some custom code.

Each platform that is unlinked would check to see if it is assigned to guard a platform/platform group, and if so, change that into a dock command.

Of course, it could get ugly if you band-select guard and a platform is in the band selection. You could pair this with a SobGroup_IsDoingAbility(<sSobGroup>, AB_Dock) check to see if the (scripted) dock command was cancelled…

Some thoughts.