Ship Equipment Overhaul - EquipSet v2

[Web-eWorks]

Creating as WIP PR for visibility and collaboration purposes. No guarantees this runs or is fully functional at this juncture, though I've tried to ensure I have a working test case during most of development.

This branch is the culmination of several years of sporadic design discussion about Pioneer's current equipment system and the problems it presents for certain important gameplay systems we'd like to enable.

We've been laying the groundwork for a replacement system on IRC and in the dev docs for quite some time, and enough ducks lined up in a row to be able to put fingers to keyboard and start writing the replacement for the existing system.

The Problems

1. It's very difficult to support more than one weapon per ship, since there's no concept of where an equipment slot is, or which individual slot within a type (e.g. laser_front) an item is installed in
2. Equipment items aren't unique instances - there's no way to have two shield modules installed but only have one of them turned on, damaged, etc. without writing a separate system to handle each equipment state
3. Since equipment items are "all the same", you can't buy a repaired / slightly damaged equipment module off the secondhand market for cheap. You're buying the exact same module you buy from the ship dealer, down to the table identity. It also makes things more complicated to handle storing purchased equipment items at a station when unequipped but not sold (when we get to that point).

The Solution

We've settled on a logical extension to the slot-based design of the prior equipment system, but allowed players to interact with the individual slots on their ship as first class features rather than hidden constraints.

Slots have type and size constraints (potentially extended to resource availability, e.g. power/ammo in the future) which limit the types of equipment that can be installed and allow some additional stratification of ship roles; an AC33 is probably not going to be happy with a shield generator designed for a Pumpkinseed, and a 20MW pulsecannon cannot physically be connected to a Coronatrix no matter how much you shuffle around the insides.

To complement this system, all equipment items that are installed on ships are now thin instances of equipment item "prototypes". This allows for very easy future support for individual equipment item state, like damage/wear, power on/off, and "tuning" equipment items to be better in specific capabilities (at the expense of others).

Status

This branch is by no means feature complete. As of time of writing, the diff is 4k lines added, 1.8k lines removed, and quite a bit more is expected. I'm creating this PR now to collaborate with other contributors and to seek some feedback from interested parties on anything I might be forgetting.

The overall effort to move to the new equipment system is broken down into three stages:

1. (This PR) Convert existing equipment items and code to use the new system, and provide very basic slot configurations for all existing ships to get everything playable. 80% of the effort.
2. Replace legacy systems that were constrained by the old equipment semantics with replacements that enable additional gameplay (e.g. GunManager to support multiple weapons/weapon sets per ship). Add new equipment items to fill the gaps created by diversifying ships according to role and size.
3. Create totally new features like storing purchased equipment items in cargo or on station, adding wear and power mechanics, and more.

Obviously, there's a lot of work to do, far more than I can accomplish on my own in a reasonable timeframe. I likely won't have as much time to dedicate to Pioneer moving forwards as I did this year, so I hope other developers can help share the load and move towards getting this feature complete.

TODOs:

• Update new game window to support new equipment system DEFERRED
• Non-empty slots -> STAGE2
• Slot equipment whitelists -> STAGE2
• Default equipment for purchased ships -> STAGE2
• More intelligent handling of missiles -> STAGE2
• Fractional ship masses for ShipDef -> STAGE3 Armor Rework
• Split scoops into non-slot cargo hold scoop and separate fuel scoop slots -> STAGE2
• Provide equipment slot layouts for all ships
• Combine ShipBuilder and ShipSpawner debug tabs
• Documentation pass
  • EquipSet.lua
  • EquipType.lua
  • ShipBuilder.lua
• Cleanup
  • Remove ShipDef.equipSlotCapacity
  • Remove EquipSetCompat
  • Remove commented-out code in Ship
  • Quick pass on FIXMEs and TODOs
  • Remove old Equipment lists
• Convert station equipment stock to new Equipment
• Convert individual module ship outfitting code to use the central ShipBuilder API
• Remove Ship:AddEquip()
• Handle multi-count equipment items
  • Support flexible-quantity / less-than-maximum slots, e.g. missile racks
  • Support fixed-quantity slots, e.g. engines/maneuvering thrusters
• Extend the ShipBuilder API to support moddable loadouts or plans for ships (e.g. mods can tweak balance of provided plans)

Equipment list spreadsheet

---

CC @JonBooth78 @Gliese852 @bszlrd for feedback and collaboration.

[JonBooth78]

Hey @Web-eWorks , this looks like a big step in the right direction.

Your ShipBuilder API is similar to what I started doing on my pirates branch but I think I called it ShipOutfitter. However, with the equipment changes it looks more straightforward.

As such I've been thinking in that area for a while so I'm very happy to pick up the TODO's around using this throughout the missions and then also extending it, if that works for you.

If you're happy with that, can I send PR's to your working branch?

[Web-eWorks]

As such I've been thinking in that area for a while so I'm very happy to pick up the TODO's around using this throughout the missions and then also extending it, if that works for you.

If you're happy with that, can I send PR's to your working branch?

That would be absolutely excellent, thank you! I'll double-check the settings on my fork but you should be able to open PRs there. I'll try to squash together the fixup commits sometime tonight and see if I can rebase this on the current release.

EDIT: you should be able to open PRs to my fork from this page, just select the correct branch on your end. Web-eWorks/pioneer@equip-v2...JonBooth78:pioneer:master

[Web-eWorks]

Rebased onto 2024-02-03, will rebase onto current master soon:tm: once we push the last hotfix for the year out.

[Web-eWorks]

We're now approaching the home stretch on this PR, with most of the ShipBuilder and EquipSet APIs fleshed out and more-or-less set in stone. The remaining work items before this branch gets merged are to fully migrate the remaining mission modules to use the new ShipBuilder API, provide slot layouts for our shipdefs, and do various cleanup tasks (like fully deprecating the old slots JSON object).

I'm most likely going to defer the new-game-window migration to Stage2, which means there will be a period after this PR is merged in which the only valid start will be the Mars start and the custom start interface will be... less than functional. I do not intend to leave the master branch in that state, and I consider it an acceptable breakage in the name of getting the equipment refactor finished.

[impaktor]

there will be a period after this PR is merged in which the only valid start will be the Mars start and the custom start interface will be... less than functional.

I assume the non-functional start options are then commented out / disabled, rather than crashing?

[Web-eWorks]

there will be a period after this PR is merged in which the only valid start will be the Mars start and the custom start interface will be... less than functional.

I assume the non-functional start options are then commented out / disabled, rather than crashing?

Not currently but I can do that before merge.

[Web-eWorks]

This branch is now officially testable! All S1 ships (Bowfin, Coronatrix, Lunar Shuttle, Mola Mola, Pumpkinseed) have received an initial slot layout pass and have functional cargo and equipment capacity numbers. This should provide enough ship variety for most combat and non-combat missions.

Most of the mentioned ships above have changed in hull mass and cargo volume; consequentially, deltaV will have changed for most ships with common equipment loadouts. Feedback on the changes to ship performance would be quite nice if anyone feels so inclined!

Note that selecting any start other than Mars is non-functional and may error, and you'll need to use the debug tools to cheat money and switch ships rather than using the new game window.

You can find screenshots of the new ship debug tool here if you're confused as to how it works.

[mwerle]

I did a rough pass over this PR; it's a biggy! Sorry, mostly just nitpicks/minor comments/issues.

[Web-eWorks]

All review feedback addressed - per @impaktor (paraphrased) "merge it while it's hot"!