GameData.php

<?php
declare(strict_types=1);

###
# Class GameData
# Handles reading, writing, and manipulating game state data from a primary data file.

# __construct(string $filePath)
#   Initializes the object and reads data from the specified data file.
#   Arguments: $filePath – path to the data file
#   Output: none
#   Access: public

# readFromFile(string $file): void
#   Reads the data file, decodes JSON-like sections, and populates object properties.
#   Arguments: $file – path to the data file
#   Output: none
#   Access: public

# writeToFile(string $file): void
#   Encodes object properties into the file format and writes back to the data file.
#   Arguments: $file – path to the [new] data file. Uses original data file if left blank
#   Output: none
#   Access: public

# buildIndexes(): void
#   Creates the lookup tables used by the lookup methods of the class
#   Arguments: None
#   Output: None
#   Access Private

# calculateSystemIncome(): int
#   Calculates income for a colony based on population, RAW, and status notes (Opposition/Rebellion)
#   Arguments: $name - colony name
#   Output: integer
#   Access: public

# calculatePurchaseExpense(): int
#   Calculates all of the cost from purchases made on this data sheet. Note that construction is considered a purchase
#   Arguments: None
#   Output: integer
#   Access: public

# checkBlockaded(string $name): bool
#   Determines if the named colony is blockaded
#   Arguments: $name – colony name
#   Output: boolean yes/no
#   Access: public

# checkColonyNotes(string $colonyName, string $note): bool
#   Determines if the named colony has the given note
#   Arguments: $name – colony name
#              $note - the note to search for
#   Output: boolean yes/no
#   Access: public

# checkUnitNotes(string $unitName, string $note): bool
#   Determines if the named unit has the given note
#   Arguments: $name – colony name
#              $note - the note to search for
#   Output: boolean yes/no

# getUnitsAtLocation(string $location): array
#   Returns all units present at a given location, including colonies, fleets, and mothballs.
#   Arguments: $location – name of colony or sector
#   Output: array of unit strings. Multiple unit strings if there is more than one quantity. Unit strings are the same as $this->unitList[]['ship']
#   Access: public

# getFleetByName(string $name): ?array
#   Returns a fleet array by its name.
#   Arguments: $name – fleet name
#   Output: fleet array or null if not found
#   Access: public

# getFleetByLocation(string $location): ?array
#   Returns all fleets found in the fleet array by its location.
#   Arguments: $name – colony name
#   Output: fleet array or null if not found
#   Access: public

# getColonyByName(string $name): ?array
#   Returns a colony array by its name.
#   Arguments: $name – colony name
#   Output: colony array or null if not found
#   Access: public

# getUnitByName(string $ship): ?array
#   Returns a unit object from unitList by ship designation.
#   Arguments: $ship – ship designation
#   Output: unit array or null if not found
#   Access: public

# findPath(string $start, string $end, bool $excludeRestricted = false): array
#   Finds a path and distance between two systems using BFS, ignoring "Unexplored" and optionally "Restricted" links.
#   Arguments: $start – starting system, $end – ending system, $excludeRestricted – ignore restricted links if true
#   Output: array, where 'path' is the list of systems and 'distance' is the number of links
#   Access: public
# Example out: ["path" => ["Frigga","Olympus","Priam"], "distance" => 2]

# fleetHasAbility(string $fleet, string $ability): string
#   Determines if a fleet has a unit with a certain ability. e.g. is a scout fleet?
#   Arguments: $fleet – fleet to check, $ability – the ability keyword to check
#   Output: string - The unit name with this ability. False if none

# getErrors(): array
#   Returns any errors encountered during file read/write or decoding.
#   Arguments: none. Optionally erase the errors if true
#   Output: array of error messages
#   Access: public

# locationHasAbility(string $location, string $ability): bool
#   Determines if a location has a unit with a certain ability. e.g. is a scout fleet?
#   Arguments: $location – locaiton to check, $ability – the ability keyword to check
#   Output: string - The unit name with this ability. False if none

# syncUnitStates(): void
#   Synchronizes unitsNeedingRepair and unitStates with current units in colonies, fleets, and mothballs.
#   Arguments: none
#   Output: none
#   Access: public

# parseUnitQuantity(string $unit): array
#   Parses a unit string like "3xDD-II" into quantity and unit name.
#   Arguments: $unit – string unit identifier
#   Output: array [quantity:int, name:string]
#   Access: public

# atLeastPoliticalState(string $treatyState, string $stateCheck): bool
#   Determines if one treaty type is more hostile than another
#   Example: "Do we have at least a trade treaty with them?"
#     atLeastPoliticalState($ourTreaty, 'Trade'); // true if $ourTreaty is 'Trade' or 'Mutual Defense' or 'Alliance'
#   Arguments: $treatyState – string Current treaty state
#              $stateCheck - string Treaty type to check against
#   Output: boolean yes/no
#   Access: public

# atLeastShipSize(string $shipDesign, string $designCheck): bool
#   Determines if one hull type (design type) is larger than another
#   Example: "Is this ship at least a CL"
#     atLeastShipSize($ourShipDesign, 'CL'); // true if $ourShipDesign is 'CL' or 'CW' or 'CA' or 'NCA' etc...
#   Arguments: $shipDesign – string Current design type
#              $designCheck - string Design type to check against
#   Output: boolean yes/no
#   Access: public

# traceSupplyLines(string $start, int $distance): ?array
#   Finds one or more paths where supply can be traced to the given location
#   Supply locations includes supply ships, supply depots, and colonies
#   Arguments: $start – string The loction to check the supply status on
#              $distance - integer An optional amount of hops to trace 
#   Output: array [paths:array, source:string] - A collection of paths that satisfy supply. Source is 'colony' or 'supply ship'
#   Access: public

# rollDie(): int
#   Rolls a single D10 die
#   Arguments: None
#   Output: Integer - A randome number from 1 to 10
#   Access: public

# isInState(string $stateArray, string $shipName, string $fleetName): ?int
#   Determines if an entry is in the given unit-state-array. Returns the index to the array of the first matching entry found.
#   unit-state-arrays are arrays who's unit string is in the format {unit name}+" w/ "+{fleet or colony name}
#   Arguments: string - The unit state array to access. Either 'unitStates' or 'unitsNeedingRepair'
#              string - The unit name to search for. Blank if unknown
#              string - The fleet or colony name to search for. Blank if unknown
#   Output: Integer - The index to the given array. False if an error or not found
#   Access: public

# getLinkStatus($a, $b): bool|string
#   Get the map connection status between two systems. Returns false if they aren't neighboring
#   Arguments: String - Colony name
#              String - Neighboring colony name
#   Output: String - Connection status or false
#   Access: public

# addUnitsToFleet (string $fleetName, string $unitString): void
#   Add units (string entries like "3xAvenger" or "Avenger") to a fleet. Merges quantities when designs match. 
#   Arguments: String - Fleet name
#              String - Unit name (possibly with quantity. e.g. "3xDD")
#   Output: None

# removeUnitsFromFleet (string $fleetName, string $unitString): bool
#   Remove specific quantity of design from fleet. returns true if removed, false if insufficient
#   Arguments: String - Fleet name
#              String - Unit name (possibly with quantity. e.g. "3xDD")
#   Output: True if successful. False if not

# addUnitsToColony (string $colonyName, string $unitString): void
#   Add units (string entries like "3xAvenger" or "Avenger") to a colony. Merges quantities when designs match. 
#   Arguments: String - Colony name
#              String - Unit name (possibly with quantity. e.g. "3xDD")
#   Output: None

# removeUnitsFromColony (string $colonyName, string $unitString): bool
#   Remove specific quantity of design from a colony. returns true if removed, false if insufficient
#   Arguments: String - Colony name
#              String - Unit name (possibly with quantity. e.g. "3xDD")
#   Output: True if successful. False if not

# Public properties, as defined by the data file specification:
# array $colonies
# array $empire
# array $events
# array $fleets
# array $game
# array $intelProjects
# array $mapConnections
# array $mapPoints
# array $offeredTreaties
# array $orders
# array $otherEmpires
# array $purchases
# array $treaties
# array $underConstruction
# array $unitsInMothballs
# array $unitsNeedingRepair
# array $unitStates
# array $unknownMovementPlaces
# array $unitList

# Misc property for reading/writing object to disk
# string $fileName

# Private properties, used for temporary record keeping
# $this->index = array();
#   ['coloniesByName'][$name]		= index of $this->colonies
#   ['fleetsByLocation'][$location]	= array of indices of $this->fleets
#   ['fleetsByName'][$name]		= index of $this->fleets
#   ['fleetsHasAbility'][$name]		= array of ability traits by fleet name
#   ['locationsHasAbility'][$name]	= array of $this->unitList[]['notes'] elements
#   ['unitsAtLocation'][$location]	= array of $this->unitList[]['ship'] elements
#   ['unitsByName'][$name]		= index of $this->unitList
#   ['fleetUnitWithAbility'][$name][$ability]	= a $this->unitList[]['ship'] element
###

###
# Class GameData
# Handles reading, writing, and manipulating game state data from a primary data file.
###
class GameData
{
  // Properties
  public array $colonies = [];
  public array $empire = [];
  public array $events = [];
  public array $fleets = [];
  public array $game = [];
  public array $intelProjects = [];
  public array $mapConnections = [];
  public array $mapPoints = [];
  public array $offeredTreaties = [];
  public array $orders = [];
  public array $otherEmpires = [];
  public array $purchases = [];
  public array $treaties = [];
  public array $underConstruction = [];
  public array $unitsInMothballs = [];
  public array $unitsNeedingRepair = [];
  public array $unitStates = [];
  public array $unknownMovementPlaces = [];
  public array $unitList = [];

  public string $fileName = "";

  private array $errors = [];
  private array $writeVars = ['colonies','empire','events','fleets','game','intelProjects','mapConnections',
                              'mapPoints','offeredTreaties','orders','otherEmpires','purchases','treaties',
                              'underConstruction','unitStates','unitsInMothballs','unitsNeedingRepair',
                              'unknownMovementPlaces','unitList'
                             ];

###
#   Initializes the object and reads data from the specified data file.
#   Arguments: $filePath – path to the data file
#   Output: none
###
  public function __construct(string $filePath)
  {
    $this->readFromFile ($filePath);
    $this->fileName = $filePath;
  }

###
#   Reads the data file, decodes JSON-like sections, and populates object properties.
#   Arguments: $file – path to the data file
#   Output: none
###
  public function readFromFile(string $file): void
  {
    if (!file_exists($file)) {
      $this->errors[] = "File not found: {$file}";
      return;
    }

    $content = file_get_contents($file);
    if ($content === false) {
      $this->errors[] = "Failed to read file: {$file}";
      return;
    }

    // Remove "var " assignments and semicolons for JSON decode
    $pattern = '/var\s+(\w+)\s*=\s*(.*?);(\s*\/\/.*)?(?=\r?\n|$)/s';
    if (preg_match_all($pattern, $content, $matches, PREG_SET_ORDER)) {
      foreach ($matches as $match) {
        $key = $match[1];
        $jsonStr = trim($match[2]);
        $decoded = json_decode($jsonStr, true);
        if ($decoded === null && json_last_error() !== JSON_ERROR_NONE) {
          $this->errors[] = "JSON decode error for key '{$key}': " . json_last_error_msg();
          continue;
        }
        if (property_exists($this, $key))
          $this->$key = $decoded;
      }
    }
    // ensure that the important data-sheet keys will exist
    foreach ($this->writeVars as $jsonKey) {
      if (!isset($this->$jsonKey))
        $this->$jsonKey = [];
    }
  }

###
#   Encodes object properties into the file format and writes back to the data file.
#   Arguments: $file – path to the [new] data file. Uses original data file if left blank
#   Output: none
###
  public function writeToFile(string $file = ""): void
  {
    $tempFileName = substr(rtrim(strtr(base64_encode(random_bytes(3)), '+/', '-_' ),'=' ), 0, 4 );
    // copy data into $dataArray. Only include named keys in $this->writeVars
    $dataArray = array_filter(
        get_object_vars($this),
        fn($key) => in_array($key, $this->writeVars, true),
        ARRAY_FILTER_USE_KEY
    );

    // Custom sort: sort all keys alphabetically, then move 'unitList' to the end
    $unitListValue = null;
    if (array_key_exists('unitList', $dataArray)) {
      $unitListValue = $dataArray['unitList'];
      unset($dataArray['unitList']);
    }
    ksort($dataArray); // Sort remaining keys alphabetically
    $dataArray['unitList'] = $unitListValue; // Append 'unitList' at the end

    $outputLines = [];

    foreach ($dataArray as $key => $value) {
        // Ensure key is a valid JS variable name
        if (!preg_match('/^[A-Za-z_][A-Za-z0-9_]*$/', $key))
            $this->errors[] = "Invalid JS variable name: {$key}";

        // Encode JSON safely
        $json = json_encode($value, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
        if ($json === false)
            $this->errors[] = "Could not encode JSON for key '{$key}': " . json_last_error_msg();
        $outputLines[] = "var $key = $json;";
    }

    // Combine all lines with newlines
    $output = implode("\n", $outputLines) . "\n";

    // Add extra newlines for readability in arrays of objects
    $output = preg_replace('/},\s*{/', "},\n   {", $output);

    if ($file == "") // if the argument is empty, write the original filename
      $file = $this->fileName;
    else // if the argument is given, treat that as our original filename
      $this->fileName = $file;

    // Write the file
    if (file_put_contents($tempFileName, $output) === false)
      $this->errors[] = "Failed to write file: {$tempFileName}";
    if (chmod($tempFileName,0777) === false )
      $this->errors[] = "Failed to modify file '{$tempFileName}' to be written.";
    if (rename( $tempFileName, $this->fileName) === false)
      $this->errors[] = "Failed to rename file '{$tempFileName}' to '{$this->fileName}'";
  }

###
# Creates the lookup tables used by the lookup methods of the class
#   Arguments: None
#   Output: None
# $this->index = array();
#   ['coloniesByName'][$name]		= index of $this->colonies
#   ['fleetsByLocation'][$location]	= array of indices of $this->fleets
#   ['fleetsByName'][$name]		= index of $this->fleets
#   ['fleetsHasAbility'][$name]		= array of ability traits by fleet name
#   ['locationsHasAbility'][$name]	= array of $this->unitList[]['notes'] elements
#   ['unitsAtLocation'][$location]	= array of $this->unitList[]['ship'] elements
#   ['unitsByName'][$name]		= index of $this->unitList
#   ['fleetUnitWithAbility'][$name][$ability]	= a $this->unitList[]['ship'] element
###
  private function buildIndexes(): void
  {
    $this->index = [];

  # Colonies By Name
    $this->index['coloniesByName'] = [];
    foreach ($this->colonies as $i => $c) {
      $this->index['coloniesByName'][$c['name']] = $i;
    }

  # Fleets By Location
  # Fleets By Name
    $this->index['fleetsByLocation'] = [];
    $this->index['fleetsByName'] = [];
    foreach ($this->fleets as $key => $f) {
      $this->index['fleetsByLocation'][$f['location']][] = $key;
      $this->index['fleetsByName'][$f['name']] = $key;
    }
  # Units By Name
    $this->index['unitsByName'] = [];
    foreach ($this->unitList as $key=>$u) {
      $this->index['unitsByName'][$u['ship']] = $key;
    }
  # Fleet Has Ability
    $this->index['fleetsHasAbility'] = [];
    $this->index['fleetUnitWithAbility'] = [];
    foreach ($this->fleets as $f) {
      $traits = [];
      foreach ($f['units'] as $u) {
        [$qty, $name]= $this->parseUnitQuantity($u);
        $index = $this->index['unitsByName'][$name];
        $unitData = $this->unitList[$index];
        if (!empty($unitData['notes'])) {
          // Split comma-separated notes, trim spaces
          $notes = array_map('trim', explode(',', $unitData['notes']));

          // Strip any "(N)" suffix where N is a number
          $notes = array_map(function ($note) {
            return preg_replace('/\s*\(\d+\)$/', '', $note);
          }, $notes);

          $traits = array_merge($traits, $notes);

          // write $this->index['fleetUnitWithAbility'] while we have this data queued
          $this->index['fleetUnitWithAbility'][$f['name']] ??= [];
          foreach ($notes as $unitTrait) {
            $this->index['fleetUnitWithAbility'][$f['name']][$unitTrait] = $unitData['ship'];
          }
        }
      }
      // Store unique traits per fleet
      $this->index['fleetsHasAbility'][$f['name']] = array_values(array_unique($traits));
    }
  # Location Has Ability
    $this->index['locationsHasAbility'] = [];
    foreach ($this->colonies as $c) {
      $traits = [];
      foreach ($c['fixed'] as $u) {
        [$qty, $name]= $this->parseUnitQuantity($u);
        $index = $this->index['unitsByName'][$name];
        $unitData = $this->unitList[$index];
        if (!empty($unitData['notes'])) {
          // Split comma-separated notes, trim spaces
          $notes = array_map('trim', explode(',', $unitData['notes']));

          // Strip any "(N)" suffix where N is a number
          $notes = array_map(function ($note) {
            return preg_replace('/\s*\(\d+\)$/', '', $note);
          }, $notes);

          $traits = array_merge($traits, $notes);
        }
      }
      $fleetTraits = [];
      if (!isset($this->index['fleetsByLocation'][$c['name']])) $this->index['fleetsByLocation'][$c['name']] = [];
      foreach ($this->index['fleetsByLocation'][$c['name']] as $fleetIndex){
        $f = $this->fleets[$fleetIndex];
        $fleetTraits = array_merge($this->index['fleetsHasAbility'][$f['name']], $fleetTraits);
      }
      // Store unique traits per fleet
      $this->index['locationsHasAbility'][$c['name']] = array_values(array_unique(array_merge($traits, $fleetTraits)));
    }
  # Units At Location
    $this->index['unitsAtLocation'] = [];
    foreach ($this->colonies as $c) {
      if (!isset($this->index['unitsAtLocation'][$c['name']])) $this->index['unitsAtLocation'][$c['name']] = [];
      foreach ($c['fixed'] as $u) {
        [$qty, $name]= $this->parseUnitQuantity($u);
        $this->index['unitsAtLocation'][$c['name']] = array_merge($this->index['unitsAtLocation'][$c['name']], array_fill(0, $qty, $name));
      }
    }
    foreach ($this->fleets as $f) {
      if (!isset($this->index['unitsAtLocation'][$f['location']])) $this->index['unitsAtLocation'][$f['location']] = [];
      foreach ($f['units'] as $u) {
        [$qty, $name]= $this->parseUnitQuantity($u);
        $this->index['unitsAtLocation'][$f['location']] = array_merge($this->index['unitsAtLocation'][$f['location']], array_fill(0, $qty, $name));
      }
    }
    // Note that unitsAtLocation() is counting unitsInMothballs. Is it supposed to?
    // Examine where it is used. Determine if those steps care about mothballs
    foreach ($this->unitsInMothballs as $f) {
      if (!isset($this->index['unitsAtLocation'][$f['location']])) $this->index['unitsAtLocation'][$f['location']] = [];
      foreach ($f['units'] as $u) {
        [$qty, $name]= $this->parseUnitQuantity($u);
        $this->index['unitsAtLocation'][$f['location']] = array_merge($this->index['unitsAtLocation'][$f['location']], array_fill(0, $qty, $name));
      }
    }

  }

###
#   Calculates income for a colony based on population, RAW, and status notes (Opposition/Rebellion)
#   Arguments: $name - colony name
#   Output: integer
###
# No Blockade check here
# This output value may affect other rules outside of being blockaded.
# In addition, this allows us to fund in-system items, despite the blockade
  public function calculateSystemIncome( $name ): int
  {
    $colony = $this->getColonyByName($name);
    if (!$colony) {
      $this->errors[] = "Missing colony '{$name}' in calculateSystemIncome()";
      return 0;
    }
    $output = $colony['population'] * $colony['raw'];
    $name = $colony['name'] ?? '';
    if ($this->checkColonyNotes($name, 'rebellion'))
      $output = 0;
    elseif ($this->checkColonyNotes($name, 'opposition')) {
      // Martial law restores full productivity, at the cost of making it likely to rebel
      // So if not Martial Law but is in opposition, then reduce output
      if ($this->checkColonyNotes($name, 'Martial Law') === false)
        $output = ceil($output / 2);
    }
    return $output;
  }

###
#   Calculates all of the cost from purchases made on this data sheet. Note that construction is considered a purchase
#   Arguments: None
#   Output: integer
###
# No lookup table for this. It's value changes as we process the construction 
# phase. This allows us to purchase everything up to a point where the player
# runs out of funds.
  public function calculatePurchaseExpense(): int
  {
    $output = 0;
    foreach ($this->purchases as $purchase) {
        $output += $purchase['cost'];
    }
    return $output;
  }

###
# checkBlockaded(string $name): boolean
#   Determines if the named colony is blockaded
#   Arguments: $name – colony name
#   Output: boolean yes/no
###
  function checkBlockaded(string $name): bool
  {
    $colony = $this->getColonyByName($name);
    if (!$colony) {
      $this->errors[] = "Failure to get colony {$name} in checkBlockaded().";
      return true;
    }
    if ($this->checkColonyNotes($name, 'blockaded'))
      return true;
    return false;
  }

###
#   Determines if the named colony has the given note
#   Arguments: $name – colony name
#              $note - the note to search for
#   Output: boolean yes/no
###
  function checkColonyNotes(string $colonyName, string $note): bool
  {
    $colony = $this->getColonyByName($colonyName);
    if (!$colony) {
      $this->errors[] = "Failure to get colony {$colonyName} in checkColonyNotes().";
      return true;
    }
    if (strpos(strtolower($colony['notes']) ?? '', strtolower($note)) !== false)
      return true;
    return false;
  }
###
#   Determines if the named colony has the given note
#   Arguments: $name – colony name
#              $note - the note to search for
#   Output: boolean yes/no
###
  function checkUnitNotes(string $unitName, string $note): bool
  {
    $unit = $this->getUnitByName($unitName);
    if (!$unit) {
      $this->errors[] = "Failure to get unit {$unitName} in checkUnitNotes().";
      return true;
    }
    if (strpos(strtolower($unit['notes']) ?? '', strtolower($note)) !== false)
      return true;
    return false;
  }

###
#   Returns all units present at a given location, including colonies, fleets, and mothballs.
#   Arguments: $location – name of colony or sector
#   Output: array of unit strings. Multiple unit strings if there is more than one quantity. Unit strings are the same as $this->unitList[]['ship']
###
  public function getUnitsAtLocation(string $location): array
  {
    if (! isset($this->index) || !isset($this->index['unitsAtLocation']))
      $this->buildIndexes();
    $i = $this->index['unitsAtLocation'][$location] ?? '';
    return $i;
  }

###
#   Returns a fleet array by its name.
#   Arguments: $name – fleet name
#   Output: fleet array or null if not found
###
  public function getFleetByName(string $name): ?array
  {
    if (! isset($this->index) || !isset($this->index['fleetsByName']))
      $this->buildIndexes();
    $i = $this->index['fleetsByName'][$name] ?? null;
    return $i === null ? null : $this->fleets[$i];
  }

# getFleetByLocation(string $location): ?array
#   Returns all fleets found in the fleet array by its location.
#   Arguments: $name – colony name
#   Output: fleet array or null if not found
#   Access: public
  public function getFleetByLocation(string $location): ?array
  {
    // $this->index['fleetsByLocation'][] is an array of indices to $this->fleets

    if (! isset($this->index) || !isset($this->index['fleetsByLocation']))
      $this->buildIndexes();
    $i = $this->index['fleetsByLocation'][$location] ?? null;
    if ($i == null) return null;
    $fleetOut = [];
    foreach ($i as $f) {
      $fleetOut[] = $this->fleets[$f];
    }
    return $fleetOut;
  }

###
#   Returns a colony array by its name.
#   Arguments: $name – colony name
#   Output: colony array or null if not found
###
  public function getColonyByName(string $name): ?array
  {
    if (! isset($this->index) || !isset($this->index['coloniesByName']))
      $this->buildIndexes();
    $i = $this->index['coloniesByName'][$name] ?? null;
    return $i === null ? null : $this->colonies[$i];
  }

###
#   Returns a unit object from unitList by ship designation.
#   Arguments: $ship – ship designation
#   Output: unit array or null if not found
###
  public function getUnitByName(string $ship): ?array
  {
    if (! isset($this->index) || !isset($this->index['unitsByName']))
      $this->buildIndexes();
    $i = $this->index['unitsByName'][$ship] ?? null;
    return $i === null ? null : $this->unitList[$i];
  }

###
#   Finds a path and distance between two systems using BFS, ignoring "Unexplored" and optionally "Restricted" links.
#   Arguments: $start – starting system, $end – ending system, $excludeRestricted – ignore restricted links if true
#   Output: array, where 'path' is the list of systems and 'distance' is the number of links
###
  public function findPath(string $start, string $end, bool $excludeRestricted = false): array
  {
    $graph = [];
    foreach ($this->mapConnections as $conn) {
      [$from, $to, $status] = $conn;
      if ($status === 'Unexplored') continue;
      if ($excludeRestricted && $status === 'Restricted') continue;

      if (!isset($graph[$from])) $graph[$from] = [];
      if (!isset($graph[$to])) $graph[$to] = [];
      $graph[$from][] = $to;
      $graph[$to][] = $from;
    }

    $queue = [[$start]];
    $visited = [$start => true];

    while ($queue) {
      $path = array_shift($queue);
      $node = end($path);
      if ($node === $end)
        return ['path' => $path, 'distance' => count($path) - 1];
      foreach ($graph[$node] ?? [] as $neighbor) {
        if (!isset($visited[$neighbor])) {
          $visited[$neighbor] = true;
          $queue[] = array_merge($path, [$neighbor]);
        }
      }
    }
    return ['path' => [], 'distance' => -1];
  }

###
#   Determines if a fleet has a unit with a certain ability. e.g. is a scout fleet?
#   Arguments: $fleet – fleet to check, $ability – the ability keyword to check
#   Output: boolean - Yes/no answer
###
  public function fleetHasAbility(string $fleet, string $ability): bool
  {
    if (! isset($this->index) || !isset($this->index['fleetsHasAbility']))
      $this->buildIndexes();
    if (array_search($ability, $this->index['fleetsHasAbility'][$fleet]) !== false)
     return true;
    return false;
  }

###
#   Finds and returns a fleet unit with a certain ability. e.g. find a scout in fleet
#   Arguments: $fleetName – fleet to check, $ability – the ability keyword to check
#   Output: string - The unit designator that has the ability
###
  public function fleetUnitWithAbility(string $fleet, string $ability): bool
  {
    if (! isset($this->index) || !isset($this->index['fleetUnitWithAbility']))
      $this->buildIndexes();
    if (!isset($this->index['fleetUnitWithAbility'][$fleet]) || !isset($this->index['fleetUnitWithAbility'][$fleet][$ability]))
     return false;
    return $this->index['fleetUnitWithAbility'][$fleet][$ability];
  }

###
#   Returns any errors encountered during file read/write or decoding.
#   Arguments: none. Optionally erase the errors if true
#   Output: array of error messages
###
  public function getErrors(bool $eraseErrors = false): array
  {
    if (!$eraseErrors)
      return $this->errors;
    // Temporarily store errors in another variable
    $errors = $this->errors;
    // Erase the errors array
    $this->errors = [];
    return $errors;
  }

###
# locationHasAbility(string $location, string $ability): string
#   Determines if a location has a unit with a certain ability. e.g. is a scout?
#   Arguments: $location – locaiton to check, $ability – the ability keyword to check
#   Output: string - The unit name with this ability. Empty if none
###
  public function locationHasAbility(string $location, string $ability): string
  {
    $units = $this->getUnitsAtLocation($location); // get units
    if (empty($units)) return '';
    foreach ($units as $u) { // get each unit of the fleet
      $unitData = $this->getUnitByName($u); // get the named unit
      if ($this->checkUnitNotes($u, $ability)) // if the named unit has the ability, end here
        return $u;
    }
    return ''; // we didn't find the ability in the location
  }

###
#   Synchronizes unitsNeedingRepair and unitStates with current units in colonies, fleets, and mothballs.
#   Arguments: none
#   Output: none
###
  public function syncUnitStates(): void
  {
    // Reset unitsNeedingRepair and unitStates
    $repair = [];
    $states = [];
    foreach ($this->colonies as $colony) {
      $units = array_merge($colony['fixed'] ?? []);
      foreach ($units as $u) {
        [$qty, $name] = $this->parseUnitQuantity($u);
        $unitStateKey = $this->isInState('unitsNeedingRepair', $name, $colony['name']);
        if ($unitStateKey !== false)
          $repair[] = $this->unitsNeedingRepair[$unitStateKey];
        $unitStateKey = $this->isInState('unitStates', $name, $colony['name']);
        if ($unitStateKey !== false)
          $states[] = $this->unitStates[$unitStateKey];
      }
    }
    foreach ($this->fleets as $fleet) {
      $units = $fleet['units'] ?? [];
      foreach ($units as $u) {
        [$qty, $name] = $this->parseUnitQuantity($u);
        $unitStateKey = $this->isInState('unitsNeedingRepair', $name, $fleet['name']);
        if ($unitStateKey !== false)
          $repair[] = $this->unitsNeedingRepair[$unitStateKey];
        $unitStateKey = $this->isInState('unitStates', $name, $fleet['name']);
        if ($unitStateKey !== false)
          $states[] = $this->unitStates[$unitStateKey];
      }
    }
    $this->unitsNeedingRepair = array_unique($repair);
    $this->unitStates = array_unique($states, SORT_REGULAR);
  }

###
#   Parses a unit string like "3xDD-II" into quantity and unit name.
#   Arguments: $unit – string unit identifier
#   Output: array [quantity:int, name:string]
###
  public function parseUnitQuantity(string $unit): array
  {
    if (preg_match('/^(\d+)x(.+)$/', $unit, $matches)) {
      return [(int)$matches[1], trim($matches[2])];
    }
    return [1, $unit];
  }

###
#   Determines if one treaty type is more hostile than another
#   Example: "Do we have at least a trade treaty with them?"
#     atLeastPoliticalState($ourTreaty, 'Trade'); // true if $ourTreaty is 'Trade' or 'Mutual Defense' or 'Alliance'
#   Arguments: $treatyState – string Current treaty state
#              $stateCheck - string Treaty type to check against
#   Output: boolean yes/no
###
  public function atLeastPoliticalState(string $treatyState, string $stateCheck): bool
  {
    $treatyOrder = ['War', 'Hostilities', 'Neutral', 'Non-Aggression', 'Trade', 'Mutual Defense', 'Alliance'];
    $treatyIdx = array_search($treatyState, $treatyOrder);
    $checkIdx = array_search($stateCheck, $treatyOrder);
    // False if the current treaty is unknown or the treaty to check is unknown or the current treaty is more hostile than the treaty to check
    if ($treatyState === false || $treatyState === false || $treatyIdx < $checkIdx)
      return false;
    return true;
  }

###
#   atLeastShipSize(string $shipDesign, string $designCheck): bool
#   Determines if one hull type (design type) is larger than another
#   Example: "Is this ship at least a CL"
#     atLeastShipSize($ourShipDesign, 'CL'); // true if $ourShipDesign is 'CL' or 'CW' or 'CA' or 'NCA' etc...
#   Arguments: $shipDesign – string Current design type
#              $designCheck - string Design type to check against
#   Output: boolean yes/no
###
  public function atLeastShipSize(string $shipDesign, string $designCheck): bool
  {
    // sorted by size. "New" hull versions considered larger than standard versions.
    // "War" versions considered smaller than "Heavy" versions: CWs considered smaller than CAs
/*
    $hullOrder = [ 'LF','MF','HF','SHF','AB','BOOM','FT',
                   'SAux','POL','FF','NFF','FFW','FFH','DD','NDD','DDH','DW','HDW',
                   'LAux','CL','CW','CWH','CA','TUG','NCA','CCH','BC','BCH',
                   'DNL','DNW','DN','DNH','BB'
                 ];
    // VBAM Hulls only
    $hullOrder = [ 'LF','MF','HF','SHF','AB','CT','FF','DD','CL','CW','CA','BC','BB','DN','SD','TN'];
*/
    // Both lists, combined. Note that VBAM puts a 'DN' as larger than a 'BB', which is switched in SFB. The SFB version is used here.
    $hullOrder = [ 'LF','MF','HF','SHF','AB','BOOM','FT',
                   'CT','SAux','POL','FF','NFF','FFW','FFH','DD','NDD','DDH','DW','HDW',
                   'LAux','CL','CW','CWH','CA','TUG','NCA','CCH','BC','BCH',
                   'DNL','DNW','DN','DNH','BB','SD','TN'
                 ];
    $designIdx = array_search($shipDesign, $hullOrder);
    $checkIdx = array_search($designCheck, $hullOrder);
    // False if the current treaty is unknown or the treaty to check is unknown or the current treaty is more hostile than the treaty to check
    if ($treatyState === false || $treatyState === false || $designIdx < $checkIdx)
      return false;
    return true;
  }

###
#   traceSupplyLines(string $start, int $distance): ?array
#   Finds one or more paths where supply can be traced to the given location.
#   Supply locations includes supply ships, supply depots, and colonies
#   Arguments: $start – string The loction to check the supply status on
#              $distance - integer An optional amount of hops to trace 
#   Output: array [paths:array, source:string] - A collection of paths that satisfy supply. Source is 'colony' or 'supply ship'
###
  public function traceSupplyLines(string $start, int $distance=3): ?array
  {
    $output = array();
    // Identify Supply Sources
    $supplySources = [];
    foreach ($this->colonies as $colony) {
      if ($colony['owner'] != $this->empire['empire']) continue;

      $isCore = ($colony['population'] >= 5);
      $isGoodOrder = ($colony['morale'] >= ($colony['population'] / 2));
      $hasDepot = false;

      if ($this->locationHasAbility($colony['name'], 'Supply Depot') === true)
          $hasDepot = true;

      if (($isCore && $isGoodOrder) || $hasDepot)
        $supplySources[] = [$colony['name'],'colony'];
    }
    // Any unit with "Supply" in its notes can resupply units in the same location that cannot otherwise trace supply.
    foreach ($this->fleets as $fleet) {
      if (!$this->fleetHasAbility($fleet['name'], 'Supply')) continue;
      $supplyShip = $this->fleetUnitWithAbility($fleet['name'], 'Supply');
      if ($supplyShip !== '') {
        $isExhausted = false;
        $unitStateKey = $this->isInState("unitStates",$supplyShip,$fleet['name']);
        if ($unitStateKey !== false && $this->unitStates[$unitStateKey][1] === 'Exhausted')
          $isExhausted = true;
        // Skip fleet if its supply unit is exhausted
        if ($isExhausted) continue;

        $supplySources[] = [$fleet['location'],'fleet'];
      }
    }
    // Identify paths
    foreach ($supplySources as $key=>$place) {
      $paths = $this->findPath($start, $place[0], true);
      if ($paths['distance'] > $distance) continue;
      $isBad = false;
      foreach($paths['path'] as $intermediate) {
        if ($intermediate == $start) continue; // skip if looking at the start location (it can be blockaded)
        if ($this->checkBlockaded($intermediate) !== true) continue;
        // intermediate is blockaded
        $isBad = true;
      }
      if (!$isBad)
        $output[] = ['paths'=>$paths,'source'=>$place[1]];
    }
    return $output;
  }

###
# rollDie(): int
#   Rolls a single D10 die
#   Arguments: None
#   Output: Integer - A random number from 1 to 10
###
  public function rollDie(): int
  {
    return mt_rand(1,10);
  }

###
# isInState(string $stateArray, string $shipName, string $fleetName): ?int
#   Determines if an entry is in the given unit-state-array. Returns the index to the array of the first matching entry found.
#   unit-state-arrays are arrays who's unit string is in the format {unit name}+" w/ "+{fleet or colony name}
#   Arguments: string - The unit state array to access. Either 'unitStates' or 'unitsNeedingRepair'
#              string - The unit name to search for. Blank if unknown
#              string - The fleet or colony name to search for. Blank if unknown
#   Output: Integer - The index to the given array. False if an error or not found
###
  public function isInState(string $stateArray, string $shipName, string $fleetName): bool|int
  {
    if ($shipName == '' && $fleetName == '')
      return false;
    if (strtolower($stateArray) == "unitstates")
      foreach ($this->unitStates as $key => $state) {
        if ($shipName == '' && strpos($state[0]," w/ {$fleetName}") !== false)
          return $key;
        if ($fleetName == '' && strpos($state[0],"{$shipName} w/ ") === 0)
          return $key;
        if ($shipName !== '' && $fleetName !== '' && $state[0] == "{$shipName} w/ {$fleetName}")
          return $key;
      }
    if (strtolower($stateArray) == "unitsneedingrepair")
      foreach ($this->unitsNeedingRepair as $key => $state) {
        if ($shipName == '' && strpos($state," w/ {$fleetName}") !== false)
          return $key;
        if ($fleetName == '' && strpos($state,"{$shipName} w/ ") === 0)
          return $key;
        if ($shipName !== '' && $fleetName !== '' && $state == "{$shipName} w/ {$fleetName}")
          return $key;
      }
    return false;
  }

###
# getLinkStatus($a, $b): bool|string
#   Get the map connection status between two systems. Returns false if they aren't neighboring
#   Arguments: String - Colony name
#              String - Neighboring colony name
#   Output: String - Connection status  or false
###
  public function getLinkStatus($a, $b): bool|string
  {
    foreach ($this->mapConnections as $conn) {
      [$from, $to, $status] = $conn;
      if (($from === $a && $to === $b) || ($from === $b && $to === $a)) return ucFirst($status);
    }
    return false;
  }

###
# addUnitsToFleet (string $fleetName, string $unitString): void
#   Add units (string entries like "3xAvenger" or "Avenger") to a fleet. Merges quantities when designs match. 
#   Arguments: String - Fleet name
#              String - Unit name (possibly with quantity. e.g. "3xDD")
#   Output: None
###
  public function addUnitsToFleet (string $fleetName, string $unitString): void
  {
    [$qty, $design] = $this->parseUnitQuantity($unitString);
    $fleetIndex = $this->index['fleetsByName'][$fleetName] ?? null;
    if (!$fleetIndex) {
      $errors[] = "Could not find '{$fleetName}' in addUnitsToFleet.";
      return;
    }
    // attempt to merge with existing unit entry
    foreach ($this->fleets[$fleetIndex]['units'] as $idx => $entry) {
      [$eQty, $eDesign] = $this->parseUnitQuantity($entry);
      if ($eDesign === $design) {
        $this->fleets[$fleetIndex]['units'][$idx] = ($eQty + $qty) . 'x' . $design;
        return;
      }
    }
    // not found, append
    if ($qty === 1) $this->fleets[$fleetIndex]['units'][] = $design;
    else $this->fleets[$fleetIndex]['units'][] = $qty . 'x' . $design;
  }

###
# removeUnitsFromFleet (string $fleetName, string $unitString): bool
#   Remove specific quantity of design from a fleet. returns true if removed, false if insufficient
#   Arguments: String - Fleet name
#              String - Unit name (possibly with quantity. e.g. "3xDD")
#   Output: True if successful. False if not
###
  public function removeUnitsFromFleet (string $fleetName, string $unitString): bool
  {
    [$reqQty, $design] = $file->parseUnitQuantity($unitString);
    $fleetIndex = $this->index['fleetsByName'][$fleetName] ?? null;
    if (!$fleetIndex) {
      $errors[] = "Could not find '{$fleetName}' in removeUnitsFromFleet.";
      return false;
    }
    foreach ($this->fleets[$fleetIndex]['units'] as $idx => $entry) {
      [$eQty, $eDesign] = $file->parseUnitQuantity($entry);
      if ($eDesign === $design) {
        if ($eQty < $reqQty) return false; // not enough
        $newQty = $eQty - $reqQty;
        if ($newQty === 0) array_splice($this->fleets[$fleetIndex]['units'], $idx, 1);
        else $this->fleets[$fleetIndex]['units'][$idx] = $newQty . 'x' . $design;
        return true;
      }
    }
    return false;
  }

###
# addUnitsToColony (string $colonyName, string $unitString): void
#   Add units (string entries like "3xAvenger" or "Avenger") to a colony. Merges quantities when designs match. 
#   Arguments: String - Colony name
#              String - Unit name (possibly with quantity. e.g. "3xDD")
#   Output: None
###
  public function addUnitsToColony (string $colonyName, string $unitString): void
  {
    [$qty, $design] = $this->parseUnitQuantity($unitString);
    $colonyIndex = $this->index['coloniesByName'][$colonyName] ?? null;
    if (!$colonyIndex) {
      $errors[] = "Could not find '{$colonyName}' in addUnitsToColony.";
      return;
    }
    // attempt to merge with existing unit entry
    foreach ($this->colonies[$colonyIndex]['fixed'] as $idx => $entry) {
      [$eQty, $eDesign] = $this->parseUnitQuantity($entry);
      if ($eDesign === $design) {
        $this->colonies[$colonyIndex]['fixed'][$idx] = ($eQty + $qty) . 'x' . $design;
        return;
      }
    }
    // not found, append
    if ($qty === 1) $this->colonies[$colonyIndex]['fixed'][] = $design;
    else $this->colonies[$colonyIndex]['fixed'][] = $qty . 'x' . $design;
  }

###
# removeUnitsFromColony (string $colonyName, string $unitString): bool
#   Remove specific quantity of design from a colony. returns true if removed, false if insufficient
#   Arguments: String - Colony name
#              String - Unit name (possibly with quantity. e.g. "3xDD")
#   Output: True if successful. False if not
###
  public function removeUnitsFromColony (string $colonyName, string $unitString): bool
  {
    [$reqQty, $design] = $file->parseUnitQuantity($unitString);
    $colonyIndex = $this->index['coloniesByName'][$colonyName] ?? null;
    if (!$colonyIndex) {
      $errors[] = "Could not find '{$colonyName}' in removeUnitsFromColony.";
      return false;
    }
    foreach ($this->colonies[$colonyIndex]['fixed'] as $idx => $entry) {
      [$eQty, $eDesign] = $file->parseUnitQuantity($entry);
      if ($eDesign === $design) {
        if ($eQty < $reqQty) return false; // not enough
        $newQty = $eQty - $reqQty;
        if ($newQty === 0) array_splice($this->colonies[$colonyIndex]['fixed'], $idx, 1);
        else $this->colonies[$colonyIndex]['fixed'][$idx] = $newQty . 'x' . $design;
        return true;
      }
    }
    return false;
  }
}