Package megamek.client.ratgenerator

Class FormationType

java.lang.Object
megamek.client.ratgenerator.FormationType
public class FormationType extends Object
Defines a Campaign Operations formation type (e.g., Battle Lance, Assault Lance, Aerospace Superiority Squadron), its composition rules, and the logic for generating or validating sets of units against those rules.

Each instance represents one named formation: its allowed unit types, weight class bounds, ideal role, main filter (getMainCriteria()), secondary FormationType.Constraints (getOtherCriteria()), and an optional FormationType.GroupingConstraint for paired or matched-chassis subsets. Instances are registered in a static lookup table populated lazily on first access by createFormationTypes(); client code retrieves a formation by name through getFormationType(String) or iterates all of them with getAllFormations().

The two main entry points are:

See Also:

  • Field Details

  • Constructor Details

    • FormationType

      protected FormationType(String name)
      Constructs a formation whose category is the same as its name (used for top-level formations that are not a variant of another). Subclasses populate the remaining fields by direct access before registering.
      Parameters:
      name - the formation name; also used as the category

    • FormationType

      protected FormationType(String name, String category)
      Constructs a formation with an explicit category. Used for variants (e.g., "Heavy Battle" in category "Battle"). Subclasses populate the remaining fields by direct access before registering.
      Parameters:
      name - the formation name
      category - the parent/grouping category for organizational purposes

  • Method Details

    • getFormationType

      public static FormationType getFormationType(String key)
      Returns the formation registered under the given name, lazily initializing the registry on first call.
      Parameters:
      key - the formation name (e.g., "Assault", "Recon", "Aerospace Superiority Squadron")
      Returns:
      the matching FormationType, or null if no formation is registered under that name

    • getAllFormations

      public static Collection<FormationType> getAllFormations()
      Returns every registered formation, lazily initializing the registry on first call. The returned collection is backed by the registry; callers should treat it as read-only.
      Returns:
      all registered formation types

    • getName

      public String getName()
      Returns:
      the formation's display name (e.g., "Heavy Battle").

    • getCategory

      public String getCategory()
      Returns:
      the formation's category, which groups variants (e.g., "Battle" for "Heavy Battle"). Top-level formations have a category equal to their name.

    • isAllowedUnitType

      public boolean isAllowedUnitType(int ut)
      Tests whether the given UnitType value is included in this formation's allowed unit types.
      Parameters:
      ut - a UnitType constant (the int value, not a FLAG_* mask)
      Returns:
      true if units of that type may participate in this formation

    • isGround

      public boolean isGround()
      Returns:
      true if this formation does not allow aerospace fighters; that is, it is a ground formation. Convenience for distinguishing ground lances from aerospace squadrons.

    • getNameWithFaction

      public String getNameWithFaction()
      Returns:
      the formation name, suffixed with the faction key in parentheses if the formation is exclusive to a single faction (e.g., "Anvil (FWL)"). Returns just the name if not faction-exclusive.

    • getTooltipKey

      public String getTooltipKey()
      Returns a stable resource-bundle key for this formation's tooltip text, suitable for lookup in megamek.client.messages. The key has the form FormationType.<sanitizedName>.tooltip, where spaces and forward slashes in the formation name are replaced with underscores so the key is a valid properties identifier.

      UI code is expected to call Messages.getString(ft.getTooltipKey()) (with a missing-key fallback) rather than constructing the key inline. This keeps FormationType ignorant of the UI Messages bundle while letting per-formation tooltip strings live in messages.properties.

      Returns:
      the resource-bundle key for this formation's tooltip

    • getMinWeightClass

      public int getMinWeightClass()
      Returns:
      the minimum allowed EntityWeightClass for units in this formation; 0 (no minimum) by default

    • getMaxWeightClass

      public int getMaxWeightClass()
      Returns:
      the maximum allowed EntityWeightClass for units in this formation; EntityWeightClass.WEIGHT_COLOSSAL (no maximum) by default

    • getMissionRoles

      public Set<MissionRole> getMissionRoles()
      Returns:
      mission roles applied to RAT generation for this formation. Some formations admit units in normally non-combat roles (e.g., MissionRole.MIXED_ARTILLERY for Anti-Air and Artillery Fire Lances).

    • getIdealRole

      public UnitRole getIdealRole()
      Returns:
      the ideal UnitRole for this formation. If every unit in a candidate force has this role, the formation's other constraints are bypassed (CamOps "ideal role" loophole). Returns UnitRole.UNDETERMINED for formations without an ideal role.

    • getMainCriteria

      public Predicate<MekSummary> getMainCriteria()
      Returns:
      the predicate every unit must satisfy to participate in this formation.

    • getMainDescription

      public String getMainDescription()
      Returns:
      a human-readable description of the main criteria (e.g., "Armor 105+"), suitable for UI display. May be null if no main criteria are imposed.

    • getOtherCriteria

      public Iterator<FormationType.Constraint> getOtherCriteria()
      Returns:
      an iterator over secondary FormationType.Constraints — count, percent, and paired-OR rules that a portion of the force must satisfy

    • getGroupingCriteria

      public FormationType.GroupingConstraint getGroupingCriteria()
      Returns:
      the optional FormationType.GroupingConstraint for paired or matched-chassis subsets, or null if this formation does not impose grouping

    • getReportMetricKeys

      public Iterator<String> getReportMetricKeys()
      Returns:
      iterator over the keys of report-metric extractors registered for this formation. Used by UI to display per-unit diagnostic columns alongside the formation's qualifications report.

    • getReportMetric

      public Function<MekSummary,?> getReportMetric(String key)
      Parameters:
      key - a report-metric key from getReportMetricKeys()
      Returns:
      the function that extracts the metric value for a given unit, or null if no such metric is registered

    • generateFormation

      public List<MekSummary> generateFormation(Parameters params, int numUnits, int networkMask, boolean bestEffort)
      Convenience overload of generateFormation(List, List, int, boolean, int, int) for formations whose units all share a single set of Parameters (the common single-unit-type case).
      Parameters:
      params - the RAT generation parameters
      numUnits - the number of units to generate
      networkMask - C3/C3i/Nova network requirement (use ModelRecord.NETWORK_NONE for no requirement)
      bestEffort - if true, returns a partial result when not all constraints can be met
      Returns:
      the generated units, or an empty list if the formation could not be built and bestEffort is false

    • generateFormation

      public List<MekSummary> generateFormation(List<Parameters> params, List<Integer> numUnits, int networkMask, boolean bestEffort)
      Overload of generateFormation(List, List, int, boolean, int, int) that uses the formation's own grouping configuration without per-call overrides.
      Parameters:
      params - one Parameters per unit-type group
      numUnits - one count per Parameters, parallel to params
      networkMask - C3/C3i/Nova network requirement
      bestEffort - if true, returns a partial result when not all constraints can be met
      Returns:
      the generated units, or an empty list if the formation could not be built and bestEffort is false

    • generateFormation

      public List<MekSummary> generateFormation(List<Parameters> params, List<Integer> numUnits, int networkMask, boolean bestEffort, int groupSize, int nGroups)
      Builds a list of units that satisfy this formation's rules, sampled from UnitTables derived from the provided parameters. Handles paired-OR constraints, network role distribution (C3 master/slave, C3i, Nova), mixed unit types via parallel parameter sets, and movement-mode resolution for vehicles/infantry whose mode is left unspecified.

      If the formation defines an ideal role and direct generation falls short of all constraints, falls back to attempting an all-ideal-role formation (CamOps loophole).

      Parameters:
      params - one Parameters per unit-type group; size must match numUnits
      numUnits - the count of units to generate per parameter group
      networkMask - the C3/C3i/Nova network requirement encoded as a ModelRecord NETWORK_* bitmask; pass ModelRecord.NETWORK_NONE to skip network requirements
      bestEffort - if true, returns whatever could be generated when constraints cannot be fully met; if false, returns an empty list on failure
      groupSize - override for the formation's grouping constraint group size; pass -1 to use the formation's own value
      nGroups - override for the formation's grouping constraint group count; pass -1 to use the formation's own value
      Returns:
      the generated units (concatenated across parameter groups, in input order), or an empty list on failure when bestEffort is false
      Throws:
      IllegalArgumentException - if params and numUnits have different sizes or are empty

    • qualifies

      public boolean qualifies(List<MekSummary> units)
      Tests whether a list of units qualifies for the formation type. Note that unit roles are not available for all units.
      Parameters:
      units - A list of units to test
      Returns:
      Whether the list of units meets the qualifications for this formation.

    • qualificationReport

      public String qualificationReport(List<MekSummary> units)
      Tests whether a list of units qualifies for the formation type. Note that unit roles are not available for all units.
      Parameters:
      units - A list of units to test
      Returns:
      Whether the list of units meets the qualifications for this formation.

    • createFormationTypes

      public static void createFormationTypes()
      Initializes (or reinitializes) the static registry of all known formation types, registering each formation defined by the create*Lance() / create*Squadron() factories below. Called lazily by getFormationType(String) and getAllFormations() on first access; rarely invoked directly.