Class FormationIconBuilder

java.lang.Object
mekhq.campaign.universe.commandGeneration.ratgen.FormationIconBuilder

public final class FormationIconBuilder extends Object
Builds layered formation icons for the Force Generator pipeline, covering every FormationLevel the engine can produce — not just the lance / company pair the legacy AbstractCompanyGenerator supported.

For each non-leaf Formation, the icon stacks three layers:

  • TYPE — a weight-class-based 'Mek silhouette computed from the units in the formation's subtree (Light / Medium / Heavy / Assault / Super-Heavy).
  • FORMATION — a shape file matching the formation's FormationLevel and faction family (IS / Clan / ComStar). All echelons from Team / Point / Level I up through Brigade / Galaxy / Level VI are covered.
  • BACKGROUND — the faction's standard background, when defined.

The campaign root Formation additionally gets a LOGO layer (or a generic-'Mek TYPE fallback) driven by CommandGenerationOptions.isUseOriginNodeFormationIconLogo().

This is the spiritual replacement for AbstractCompanyGenerator.createLayeredFormationIcon scaled up to the full FormationLevel space.

  • Method Details

    • applyIcons

      public static void applyIcons(Formation root, Faction forceFaction, Function<UUID,Unit> unitLookup, @Nullable Formation supportCommand, int gameYear, CommandGenerationOptions options)
      Walks the campaign's Formation tree rooted at root and applies a layered icon to every non-leaf Formation. Honors the icon-related toggles on CommandGenerationOptions: if isGenerateFormationIcons() is off, returns immediately.
      Parameters:
      root - the force's top-level Formation (typically force.getFormations())
      forceFaction - the faction the force is organised as, used unless the options name another
      unitLookup - resolves the unit ids in the formations, whose units feed the weight-class math
      supportCommand - the force's Support Command formation, or null if it has none
      gameYear - the current year, which picks the faction logo for the origin node
      options - the options driving icon-generation toggles
    • applyIconsToSubtree

      public static int applyIconsToSubtree(@Nullable Formation root, @Nullable Faction iconFaction, @Nullable Function<UUID,Unit> unitLookup, @Nullable Formation supportCommand)
      Decorates one existing formation and everything under it, using the force's own faction.

      The generation pass above needs CommandGenerationOptions because it also decides the origin node's icon. Support teams organized after generation - a campaign that switched the option on - have no generation options to consult, but their formations should look like the generated ones, so this is the same builder without the origin-node question.

      Parameters:
      root - the formation to decorate, along with its subtree
      iconFaction - the faction the force is organised as, which sets the shape set and background
      unitLookup - resolves the unit ids in the formations
      supportCommand - the force's Support Command formation, or null if it has none
      Returns:
      the number of formations decorated
    • applyIconsToFormations

      public static int applyIconsToFormations(List<Formation> formations, @Nullable Faction iconFaction, @Nullable Function<UUID,Unit> unitLookup, @Nullable Formation supportCommand)
      Decorates the named formations and everything under them, using the force's own faction.

      Used by the support-team conversion, which knows exactly which formations it created and must not touch the player's own - their icons are their business.

      Parameters:
      formations - the formations to decorate, each along with its subtree
      iconFaction - the faction the force is organised as, which sets the shape set and background
      unitLookup - resolves the unit ids in the formations
      supportCommand - the force's Support Command formation, or null if it has none
      Returns:
      the number of formations decorated
    • refreshEchelonPiece

      public static boolean refreshEchelonPiece(@Nullable Formation formation, @Nullable Faction iconFaction)
      Brings the echelon symbol on a formation's icon into line with its level, and leaves the rest of the icon alone.

      Support formations are re-sized as their teams and vehicles change, long after their icons were drawn. A Medical section drawn while it held one MASH truck kept the Team symbol after ten more trucks made it a company. Only an icon whose formation layer is a single echelon shape from this builder's folder is touched, so an icon the player designed is never overwritten.

      Parameters:
      formation - the formation whose icon may be stale
      iconFaction - the faction the force is organised as, whose family decides the shape set
      Returns:
      true if the symbol was changed
    • decorateUndecorated

      public static int decorateUndecorated(@Nullable Formation root, @Nullable Faction iconFaction, @Nullable Function<UUID,Unit> unitLookup, @Nullable Formation supportCommand)
      Draws the icon of root and every formation under it that still carries the blank default icon, and leaves every other icon alone.

      Support formations granted mid-campaign - a convoy when StratCon is switched on, canteens under fatigue, the security detail - were filed with no icon at all, because only command generation and the Support Teams conversion drew them. A formation already decorated, by this builder or by the player, is never redrawn.

      Parameters:
      root - the formation to decorate, along with its subtree
      iconFaction - the faction the force is organised as, which sets the shape set and background
      unitLookup - resolves the unit ids in the formations
      supportCommand - the force's Support Command formation, or null if it has none
      Returns:
      the number of formations decorated
    • refreshIcons

      public static int refreshIcons(@Nullable Formation root, @Nullable Faction iconFaction, @Nullable Function<UUID,Unit> unitLookup, @Nullable Formation supportCommand)
      Brings every icon this builder drew under root into line with its formation, and draws the ones still blank.

      This is the on-demand version of what command generation does, for a TOE that has grown since: new formations get their icon, a lance that became a company gets the company symbol, and a lance whose 'Meks were traded for tanks loses the 'Mek silhouette. Icons the player designed are left alone.

      Parameters:
      root - the formation to refresh, along with its subtree
      iconFaction - the faction the force is organised as, which sets the shape set and background
      unitLookup - resolves the unit ids in the formations
      supportCommand - the force's Support Command formation, or null if it has none
      Returns:
      the number of formations whose icon was drawn or changed
    • refreshTypePiece

      public static boolean refreshTypePiece(@Nullable Formation formation, @Nullable Faction iconFaction, @Nullable Function<UUID,Unit> unitLookup, @Nullable Formation supportCommand)
      Redraws the unit-type silhouette on a formation's icon to match the units it holds now, and leaves the rest of the icon alone.

      A Mek lance whose 'Meks were sold for tanks, or a medium company that bought heavies, kept the silhouette it was drawn with. Only an icon this builder drew is touched: its formation layer must be the builder's echelon shape and every type piece one the builder draws, so an icon the player designed is never overwritten.

      Parameters:
      formation - the formation whose icon may be stale
      iconFaction - the faction the force is organised as, whose family decides the shape set
      unitLookup - resolves the unit ids in the formation
      supportCommand - the force's Support Command formation, or null if it has none
      Returns:
      true if the silhouette was changed