I. SummaryThis mod is contains the backend logic for combat boarding, first used in
Kingdom of Royal Azalea. This mod is only a
utility. It does not add nor remove any content from your game by itself.
Why is this a separate mod?So I don't need to copy and paste the same backend to all of my mods when I want to add boarding for them as well.
Can I also add boarding to my mod using this backend?Sure, if you want. I'll add a short explanation of how boarding works below.
II. Boarding MechanicsAny boarding instance has two important properties -
Boarding Level and
Duration.
When a boarding action commences, the defending ship will have a random chance
twice every second to suffer negative events for the duration of the boarding action. Moreover, when a ship that is currently being boarded is boarded again, then the boarders will be
reinforced. That means the boarding level and duration of the second boarding party is added to the current boarders. This can continue until the boarders have been
defeated entirely (the duration runs out). Thus, it is possible to stack boarding level by repeatedly boarding the same ship to both increase its boarding level and extend its duration. *
Only the first boarding ship is considered to be the attacking ship, even if more of the boarders come from a different ship. The attacking ship will only change after the boarders are defeated.A Mora losing CR as a result of a boarding action The chance for a negative event is influenced by many different things:
First and most significant is the
Boarding Level. Each boarding level increases the chance that a negative event will occur.
Next is whether the
defending ship has greater CR than the attacking ship. If so, the crew is considered to be "holding on" and event chance is slashed by
half.
And lastly, whether the defending ship's crew is
focused on resisting. The mod abstracts this state as being the same as the
0-flux boost. The reasoning being, if you're not shooting, maintaining a shield, or actively engaging with fighters, then your crew has time to fight off the boarders. And so, if your crew is
focused on resisting, the chances for negative events will be further slashed by
half, and the more dangerous negative events will not occur.
There are four negative events that can occur if the event roll succeeds.
- Minor Damage - A small explosion will erupt somewhere on the ship. This ignores shields and causes minimal HIGH EXPLOSIVE and EMP damage.
- CR Loss - The ship can lose a small amount of CR. No damage is taken. This is essentially a gatekeeper event as it will eventually lead to the more powerful effects below if allowed to continuously happen. This event won't trigger if 'focused on resisting'.
- Weapon Destroyed - One weapon mount is disabled for the duration of the battle. This event won't trigger if CR is above 50%. This event also won't trigger if 'focused on resisting'.
- Engine Destroyed - One engine (one exhaust plume) is disabled for the duration of the battle. This event won't trigger if CR is above 50%. This event also won't trigger if 'focused on resisting'.
A Mora losing a Light Autocannon (permanently) as a result of a boarding actionNote that its CR has been reduced to 42% from prolonged boarding. There are finer, more minor details to the probability calculation and conditions for advanced events to occur, but this is all you need to know to use boarding actions effectively.
III. How to Use (Modding)A boarding instance can be created by a single line call...
yrutl_BoardingPlugin.addBoarding((Vector2f)location, (ShipAPI)target, (ShipAPI)ship, (float)visualFXSize, (int)boardingLevel, (float)boardingDuration);
The
location here is the point on the ship where the boarders first make contact. It's only important for a single explosion effect on impact, don't worry about it.
target is the ship being boarded.
ship is the ship doing the boarding action.
visualFXSize is the size of the explosions going off on the ship. Only the first boarder will set this. And
boardingLevel and
duration have been explained above.
Take this example inside a EveryFrameWeaponEffectPlugin class...
Example code
ShipAPI ship = weapon.getShip();
ShipAPI target = ship.getShipTarget();
...
yrutl_BoardingPlugin.addBoarding(target.getLocation(), target, ship, 50f, weapon.getAmmo(), 10f);
The above example adds a boarding instance at the level of the ammo of the weapon (so it can be adjusted up and down easily by simply changing the ammo count of the weapon), and a duration of 10 seconds.
You can also add your own custom boarding sounds using the same call, but filling in 5 extra fields at the end...
yrutl_BoardingPlugin.addBoarding( ... , (float)boardingDuration, (string) sfxStart, (string)sfxMinorDamage, (string)sfxCRLoss, (string)sfxDisableWeapon, (string)sfxDisableEngine);