Package megamek.common.force

Class Forces

java.lang.Object
megamek.common.force.Forces
All Implemented Interfaces:
Serializable
public final class Forces extends Object implements Serializable
Manages a collection of Forces for a game. The game only needs to hold one Forces object. Like in Campaign.java in MHQ this is mainly a map of id to Force along with many utility functions. Force management and changes are directed through this object.
See Also:

  • Constructor Details

    • Forces

      public Forces(IGame g)

  • Method Details

    • addTopLevelForce

      public int addTopLevelForce(Force force, @Nullable Player owner)
      Adds a top-level force with the provided name and the provided owner. Verifies the name and the force before applying the change. Returns the id of the newly created Force or Force.NO_FORCE if no force was created.

    • addSubForce

      public int addSubForce(Force force, Force parent)
      Adds the provided sub force to the provided parent. Verifies the name and the force before applying the change.
      Returns:
      the id of the newly created Force or Force.NO_FORCE if no new sub force was created.

    • forcelessEntities

      public List<ForceAssignable> forcelessEntities()
      Returns a list of all the game's entities that are not part of any force.

    • getTopLevelForceCount

      @Deprecated(since="0.51.0", forRemoval=true) public int getTopLevelForceCount()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Returns the number of top-level forces present, i.e. forces with no parent force.

    • getTopLevelForces

      public List<Force> getTopLevelForces()
      Returns a List of the top-level forces.

    • contains

      public boolean contains(@Nullable Force force)
      Returns true if the provided force is part of the present forces either as a top-level or a sub force.

    • contains

      public boolean contains(int forceId)
      Returns true if the provided forceId is part of the present forces either as a top-level or a sub force.

    • getForce

      public Force getForce(int id)
      Returns the force with the given force id or null if there is no force with this id.

    • addEntity

      public ArrayList<Force> addEntity(ForceAssignable entity, int forceId)
      Adds the provided Entity to the provided force. Does nothing if the force doesn't exist or if the entity is already in the targeted force. Removes the entity from any former force. Returns a list of all changed forces, i.e. the former force, if any, and the new force. The list will be empty if no actual change occurred.

    • removeEntityFromForces

      public LinkedHashSet<Force> removeEntityFromForces(Collection<? extends ForceAssignable> entities)
      Removes the provided entities from their current forces, if any. Does nothing if an entity is already force-less (forceId == Force.NO_FORCE). Returns a list of all changed forces. The list will be empty if no actual change occurred.

    • removeEntityFromForces

      public ArrayList<Force> removeEntityFromForces(ForceAssignable entity)
      Removes the provided Entity from its current force, if any. Does nothing if the entity is already force-less (forceId == Force.NO_FORCE). Returns a list of all changed forces, i.e. the former force, if any. The list will be empty if no actual change occurred.

    • removeEntityFromForces

      public HashSet<Force> removeEntityFromForces(int entityId)
      Removes the provided entity ID from its current force, if any. Does nothing if the entity is already force-less (forceId == Force.NO_FORCE). Returns a list of all changed forces, i.e. the former force, if any. The list will be empty if no actual change occurred.

    • renameForce

      public void renameForce(String name, int forceId)
      Renames the Force with forceId to the provided name. The provided values are fully verified before applying the change. A null name or empty name can safely be passed. Duplicate names may be given; forces are identified via id.

    • verifyForceName

      public boolean verifyForceName(String name)
      Returns true if the provided name can be used as a Force name. It cannot be empty or contain "|" or "\".

    • getOwnerId

      public int getOwnerId(Force force)
      Returns:
      the force owner's id

    • getOwner

      public Player getOwner(Force force)
      Returns:
      the owner of this force.

    • getOwner

      public Player getOwner(int forceId)
      Returns:
      the owner of this force.

    • getForce

      @Nullable public Force getForce(ForceAssignable entity)
      Returns the Force that the provided entity is a direct part of. E.g., If it is part of a lance in a company, the lance will be returned. If it is part of no force, returns null.

    • getForcesInternalRepresentation

      public HashMap<Integer,Force> getForcesInternalRepresentation()

    • getForceId

      public int getForceId(ForceAssignable entity)
      Returns the id of the force that the provided entity is a direct part of. E.g., If it is part of a lance in a company, the lance id will be returned. If it is part of no force, returns Force.NO_FORCE.

    • getForceId

      public int getForceId(int id)
      Returns the id of the force that the provided entity (id) is a direct part of. E.g., If it is part of a lance in a company, the lance id will be returned. If it is part of no force, returns Force.NO_FORCE.

    • parseForceString

      public static List<Force> parseForceString(ForceAssignable entity)
      Parses the force string of the provided entity. Returns a List of Force stubs in the order of highest to lowest force. The Force stubs cannot be added to a Forces object directly! They contain only the name and id and have no parent and no owner and the passed entity is not added to them!

    • getFullSubForces

      public ArrayList<Force> getFullSubForces(Force force)
      Returns a list of all subForces of the provided force, including subForces of subForces to any depth.

    • getAvailableForces

      @Deprecated(since="0.51.0", forRemoval=true) public ArrayList<Force> getAvailableForces(Player player)
      Deprecated, for removal: This API element is subject to removal in a future version.
      For the given player, returns a list of forces that are his own or belong to his team.

    • forceStringFor

      public String forceStringFor(ForceAssignable entity)

    • forceChain

      public ArrayList<Force> forceChain(ForceAssignable entity)
      Returns a ArrayList of Forces that make up the chain of forces to the provided entity. The list starts with the top-level force containing the entity and ends with the force that the entity is an immediate member of.

    • forceChain

      public ArrayList<Force> forceChain(Force force)
      Returns a ArrayList of Forces that make up the chain of forces to the provided force. The list starts with the top-level force containing the provided force and ends with (includes!) the provided force itself.

    • replace

      public void replace(int forceId, Force force)
      Overwrites the previous force mapped to forceId with the provided force or adds it if no force was present with that forceId. Only used when the server sends force updates.

    • setGame

      public void setGame(IGame g)
      Sets the game reference to the provided Game. Used when transferring the forces between client and server.

    • clone

      public Forces clone()
      Returns a clone of this Forces object, including clones of all contained forces.
      Overrides:
      clone in class Object

    • isValid

      public boolean isValid()
      Returns true if this Forces object is valid.
      See Also:

    • isValid

      public boolean isValid(Collection<ForceAssignable> updatedEntities)
      Returns true if this Forces object is valid. If any updatedEntities are given, the validity check will test these instead of the current game's.
      See Also:

    • correct

      public void correct()
      Corrects this Forces object as much as possible. Also corrects entities when necessary (wrong forceId).
      • Incorrect links (false IDs, nonexistent or dual entities or forces)
      • Enemy force/entity connections
      • Incorrect links
      See Also:

    • deleteForce

      @Deprecated(since="0.51.0", forRemoval=true) public ArrayList<Force> deleteForce(int forceId)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Removes the given force from these forces if it is empty. Returns a list of affected forces which contains the parent if the deleted force was a sub force and is empty otherwise.

    • deleteForces

      public ArrayList<Force> deleteForces(Collection<Force> delForces)
      Removes the given forces and all their subForces from these Forces. Returns a list of affected surviving forces. This method does not check if the forces are empty.

      NOTE: Any entities in the removed forces are NOT updated by this method! It is necessary to update any entities' forceId unless these are deleted as well.

    • getAllForces

      public ArrayList<Force> getAllForces()
      Returns a list of all forces and subForces in no particular order.

    • attachForce

      public ArrayList<Force> attachForce(Force force, Force newParent)
      Attaches a force to a new parent. The new parent force cannot be a sub force of the force and cannot belong to an enemy of its owner. Returns a list of affected forces. This may be empty and may contain up to three forces (the force, the new parent and the former parent).

    • isSubForce

      public boolean isSubForce(Force force, Force possibleSubForce)
      Returns true when possibleSubForce is one of the subForces (in any depth) of the given force.

    • promoteForce

      public ArrayList<Force> promoteForce(Force force)
      Promotes a force to top-level (unattaches it from its parent force if it has one). Returns a list of affected forces which may be empty.

    • assignForceOnly

      public ArrayList<Force> assignForceOnly(Force force, Player newOwner)
      Changes the owner of the given force to the given newOwner without affecting anything else. Will only do something if the new owner is a teammate of the present owner. Returns a list of affected forces containing the force if it was changed, empty otherwise.

    • assignFullForces

      public void assignFullForces(Force force, Player newOwner)
      Changes the owner of the given force and all subForces to the given newOwner. Promotes the force to top-level if the parent force is now an enemy force. Returns a list of affected forces.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getFullEntities

      public List<ForceAssignable> getFullEntities(@Nullable Force force)
      Returns a list of all entities of the given force and all its subForces to any depth.

    • moveUp

      public ArrayList<Force> moveUp(ForceAssignable entity)
      Moves up the given entity in the list of entities of its force if possible. Returns true when an actual change occurred.

    • moveDown

      public ArrayList<Force> moveDown(ForceAssignable entity)
      Moves down the given entity in the list of entities of its force if possible. Returns true when an actual change occurred.

    • moveUp

      public ArrayList<Force> moveUp(Force subForce)
      Moves up the given sub force in the list of subForces of its parent if possible. Returns true when an actual change occurred.

    • moveDown

      public ArrayList<Force> moveDown(Force subForce)
      Moves down the given sub force in the list of subForces of its parent if possible. Returns true when an actual change occurred.