Package megamek.common.universe

Class Faction2

java.lang.Object
megamek.common.universe.Faction2
public class Faction2 extends Object
This is a Faction class that unifies MHQ's Faction and the RATGenerator's FactionRecord and makes it available to all project parts. The class encompasses both factions such as the Lyran Alliance or Clan Ghost Bear as well as commands such as the Capellan Brigade or the Hesperus Guards as both are used to generate RATs and both could potentially be used as a playable faction. It may be that later on, commands and factions will be separated.

To limit the changes, the original Faction and FactionRecord classes are - at least for now - kept largely unchanged, but they now use the data of this class instead of loading their own data.

The alternate faction codes and parent factions properties of the two original faction types have been lumped together. They were sometimes equal, sometimes not. Both were used for RAT generation purposes. The alternate names feature (independent of year) of MHQ factions has been dropped as it was not used anywhere. Currency codes are currently not part of this Faction class as there was no data for it

Notes for future improvements: There are multiple fallback factions. This may be useful for providing entertaining fallback RATs but a single chain of parent factions may be more useful for other data. Commands could be given a list of specific camos. Specific dates could be used instead of years. Rating levels could be gathered from fallback to avoid repetition.

  • Constructor Details

    • Faction2

      public Faction2()

  • Method Details

    • getRatingLevels

      public List<String> getRatingLevels()

    • getSubunits

      public Map<String,Faction2> getSubunits()
      Returns the subordinate formations declared inside this faction's own file, keyed by the short identifier used in the YAML file rather than by their full key. A command such as the St. Ives Lancers declares its regiments here instead of each regiment needing a separate file: 
       key: CC.SIL
 name: St. Ives Lancers
 subunits:
   1st:
     name: 1st St. Ives Lancers

      Subunits are a file-organisation convenience only. At load time SubunitRegistrar registers each one as a full faction in its own right under the composed key CC.SIL.1st, so everything that consumes factions - the lobby, RAT generation, MekHQ - sees a flat list and needs no knowledge of the nesting.

      Returns:
      The subunits declared in this faction's file, in declaration order. Never null.

    • getParentCommand

      @Nullable public String getParentCommand()
      Returns the key of the command that declared this faction as one of its subunits, if any.

      This is set only for factions that came from inside another faction's file, such as the 1st St. Ives Lancers declared inside CC.SIL. A command written in its own file returns null even when it falls back to another command, because falling back is not the same as being declared inside it.

      Returns:
      The declaring command's key, or null when this faction has its own file

    • isSubunit

      public boolean isSubunit()
      Returns whether this faction was declared inside another faction's file rather than having a file of its own.

      Useful where only whole commands should be offered rather than their individual regiments - the Force Generator's sub-faction list, for example, shows the St. Ives Lancers but not their seven regiments.

      Returns:
      true if this faction is a subunit of another

    • getKey

      public String getKey()

    • getName

      public String getName()

    • getName

      public String getName(int year)

    • getSucsCodes

      public Set<String> getSucsCodes()
      Returns the SUCS (Sarna Unified Cartography Kit) faction codes that map to this MegaMek faction. A single MegaMek faction may correspond to multiple SUCS codes when SUCS uses different identifiers across historical eras of the same political entity (e.g. LC for the Lyran Commonwealth and LA for its successor the Lyran Alliance, both of which map to MegaMek's LA).

      Used by SUCS data import tooling to translate SUCS faction codes into MegaMek codes. An empty set means no SUCS equivalent has been identified.

      Returns:
      The SUCS codes that map to this faction, in insertion order. Never null.

    • getTags

      public Set<FactionTag> getTags()

    • getYearsActive

      public List<FactionRecord.DateRange> getYearsActive()

    • getBackground

      public String getBackground()

    • getBackground

      public String getBackground(int year)
      Returns the faction's background image path for the given year, honoring any era-based background changes. Falls back to the base background when no change applies for the year.
      Parameters:
      year - the game year to resolve the background for
      Returns:
      the era-appropriate background image path, or the base background when none applies

    • getBackgroundChanges

      public NavigableMap<Integer,String> getBackgroundChanges()

    • getLogo

      public String getLogo()

    • getLogo

      public String getLogo(int year)
      Returns the faction's logo image path for the given year, honoring any era-based logo changes. Falls back to the base logo when no change applies for the year. Used to keep a consolidated rename lineage (for example Clan Goliath Scorpion becoming the Escorpion Imperio in 3080) visually era-correct after its faction files are merged into one.
      Parameters:
      year - the game year to resolve the logo for
      Returns:
      the era-appropriate logo image path, or the base logo when none applies

    • getLogoChanges

      public NavigableMap<Integer,String> getLogoChanges()

    • getEraMods

      public int[] getEraMods()

    • getSuccessor

      public String getSuccessor()

    • getCapital

      public String getCapital()

    • getColor

      public Color getColor()

    • getNameGenerator

      public String getNameGenerator()

    • getPreInvasionHonorRatingDirect

      public HonorRating getPreInvasionHonorRatingDirect()
      Returns the pre-invasion honor rating assigned to this faction, if any.

      This method provides direct access to the stored HonorRating value representing the faction's honor rating before the invasion period. No default or fallback value is applied.

      Usage: this method is for directly retrieving the value stored in preInvasionHonorRating, generally you'll want to use getPreInvasionHonorRating() instead, as that includes essential fallback values.

      Returns:
      the pre-invasion HonorRating, or null if not set

    • getPreInvasionHonorRating

      public HonorRating getPreInvasionHonorRating()
      Calculates and returns the effective pre-invasion honor rating for this faction.

      For Clan factions, returns the stored honor rating if it is set and not HonorRating.NONE; otherwise, returns HonorRating.STRICT as the default. For non-Clan factions, this simply returns the stored honor rating, which will likely be HonorRating.NONE.

      Usage: this method is the primary way to retrieve a faction's pre-invasion honor rating. However, as it includes fallback values, if you want to directly access the value stored in preInvasionHonorRating you will want to call getPreInvasionHonorRatingDirect(), instead.

      Returns:
      the effective pre-invasion HonorRating for the faction

    • getPostInvasionHonorRatingDirect

      public HonorRating getPostInvasionHonorRatingDirect()
      Returns the post-invasion honor rating assigned to this faction, if any.

      This method provides direct access to the stored HonorRating value representing the faction's honor rating after the invasion period. No default or fallback value is applied.

      Usage: this method is for directly retrieving the value stored in postInvasionHonorRating, generally you'll want to use getPostInvasionHonorRating() instead, as that includes essential fallback values.

      Returns:
      the pre-invasion HonorRating, or null if not set

    • getPostInvasionHonorRating

      public HonorRating getPostInvasionHonorRating()
      Calculates and returns the effective post-invasion honor rating for this faction.

      For Clan factions, returns the stored honor rating if it is set and not HonorRating.NONE; otherwise, returns HonorRating.OPPORTUNISTIC as the default. For non-Clan factions, this simply returns the stored honor rating, which will likely be HonorRating.NONE.

      Usage: this method is the primary way to retrieve a faction's post-invasion honor rating. However, as it includes fallback values, if you want to directly access the value stored in postInvasionHonorRating you will want to call getPostInvasionHonorRatingDirect(), instead.

      Returns:
      the effective post-invasion HonorRating for the faction

    • getCamosFolder

      public String getCamosFolder(int year)

    • getCamosChanges

      public NavigableMap<Integer,String> getCamosChanges()

    • getNameChanges

      public NavigableMap<Integer,String> getNameChanges()

    • getAliases

      public NavigableMap<Integer,String> getAliases()
      Returns the historical faction-code aliases for this faction, keyed by the year each alias became active. When a faction is the consolidation of an earlier faction that was renamed (for example Clan Goliath Scorpion becoming the Escorpion Imperio in 3080), the retired faction code is kept here as an alias of the surviving key, so that saved games, planetary ownership and RAT availability tables that still reference the old code continue to resolve to this faction.

      Aliases are for rename lineages only - a single entity renamed over time, with disjoint date ranges. They must not be used for a merger of two distinct factions (for example Clan Snow Raven and the Outworlds Alliance both becoming the Raven Alliance); those relationships belong in getFallBackFactions() instead.

      Returns:
      The alias codes keyed by the year each became active, in ascending year order. Never null.

    • getCapitalChanges

      public NavigableMap<Integer,String> getCapitalChanges()

    • getUsesMercenaries

      public NavigableMap<Integer,Boolean> getUsesMercenaries()

    • getAresConventionsSignatory

      public NavigableMap<Integer,Boolean> getAresConventionsSignatory()

    • getFallBackFactions

      public Set<String> getFallBackFactions()

    • getFormationBaseSize

      public int getFormationBaseSize()
      Returns the size of the lowest formation type (lance). If this faction gives the size directly (formationBaseSize) this value is returned. Otherwise, the fallback Factions are called recursively. When there is no callback Faction, 5 is returned for a clan faction and 4 otherwise.

      This means that the Word of Blake Faction will give a value of 6 and WoB subcommands do not have to give any value as long as their fallback Faction is WoB.

      Returns:
      The size of a lance, point or analogous formation type

    • getFormationGrouping

      public int getFormationGrouping()
      Returns the grouping multiplier for accumulated formations such as company, galaxy or level 3. If this faction gives the value directly (formationGrouping) this value is returned. Otherwise, the fallback Factions are called recursively. When there is no callback Faction, 5 is returned for a clan faction and 3 otherwise (3 lances form a company, 3 companies form a battalion etc.)

      This means that the Word of Blake Faction will give a value of 6 and WoB subcommands do not have to give any value as long as their fallback Faction is WoB.

      Returns:
      How many formations form a formation of a higher type (e.g., lances in a company)

    • getRankSystem

      public String getRankSystem()
      Retrieves the rank system identifier for this faction.

      The method checks the `rankSystem` field; if it is set and not null, its value is returned directly.

      If the rank system is unspecified but there are fallback factions, the method iterates through each fallback faction, returning the first available rank system found among them.

      If no fallback faction provides a rank system, the method returns a default value based on whether the faction is a clan or not.

      Returns:
      the rank system identifier for this faction, or a default value (DEFAULT_RANK_SYSTEM_CLAN for Clan factions, DEFAULT_RANK_SYSTEM_INNER_SPHERE for non-Clan factions) if not specified.
      Since:
      0.50.07

    • getFactionLeaders

      public List<FactionLeaderData> getFactionLeaders()
      Returns the list of leaders for this faction.
      Returns:
      a list containing all FactionLeaderData objects associated with this faction
      Since:
      0.50.07

    • setFactionLeaders

      public void setFactionLeaders(List<FactionLeaderData> factionLeaders)
      Sets the list of leaders for this faction.
      Parameters:
      factionLeaders - the list of FactionLeaderData to associate with this faction
      Since:
      0.50.07

    • getFactionLeaderForYear

      @Nullable public FactionLeaderData getFactionLeaderForYear(int year)
      Retrieves the faction leader in power during the specified year.
      Parameters:
      year - the year to check for a valid leader
      Returns:
      the FactionLeaderData for the leader valid in the given year, or null if none found
      Since:
      0.50.07

    • isClan

      public boolean isClan()

    • isPeriphery

      public boolean isPeriphery()

    • isMinorPower

      public boolean isMinorPower()

    • is

      public boolean is(FactionTag tag)

    • isActiveInYear

      public boolean isActiveInYear(int year)
      Returns:
      True when this faction is active in the given year.

    • saveToFile

      public void saveToFile(File file) throws IOException
      Writes this faction as YAML to the given file.
      Parameters:
      file - The file to write to.
      Throws:
      IOException - When an error occurs

    • saveToFile

      public void saveToFile() throws IOException
      Writes this faction as YAML to the standard directories in data/universe/factions or data/universe/commands with the standard name (key).yml, depending on whether the key contains a "."
      Throws:
      IOException - When an error occurs

    • saveToFile

      public void saveToFile(FactionRecord updatedRecord) throws IOException
      Writes this faction with updates from a changed FactionRecord as YAML to the given file. This method is hopefully temporary; it is used for RatGeneratorEditor changes while FactionRecord stays a separate class. Note that this method applies the changes to the "real" faction and keeps the change for the present runtime.
      Parameters:
      updatedRecord - A FactionRecord with changes to apply to the present faction and save to file
      Throws:
      IOException - When an error occurs

    • performsBatchalls

      public boolean performsBatchalls()
      Returns:
      True if this faction performs BatchAlls.

    • isAggregate

      public boolean isAggregate()
      Returns:
      true if the faction is an aggregate of independent 'factions', rather than a singular organization.

      For example, "PIR" (pirates) is used to abstractly represent all pirates, not individual pirate groups.

      Since:
      0.50.07

    • isUsesMercenaries

      public Boolean isUsesMercenaries(int year)

    • isAresConventionsSignatory

      public boolean isAresConventionsSignatory(int year)
      Whether this faction was a signatory of the Ares Conventions - and thus observed their restrictions on targeting population centers - in the given year. Defaults to false for years with no recorded signatory status.
      Parameters:
      year - the year to check
      Returns:
      true if the faction observed the Ares Conventions in that year

    • toString

      public String toString()
      Overrides:
      toString in class Object