The main record holding the state for the game itself (as distinct from the UI). See the lenses below for access to its fields.

To answer the question of what belongs in the GameState and what belongs in the UIState, ask yourself the question: is this something specific to a particular UI, or is it something inherent to the game which would be needed even if we put a different UI on top (web-based, GUI-based, etc.)? For example, tracking whether the game is paused needs to be in the GameState: especially if we want to have the game running in one thread and the UI running in another thread, then the game itself needs to keep track of whether it is currently paused, so that it can know whether to step independently of the UI telling it so. For example, the game may run for several ticks during a single frame, but if an objective is completed during one of those ticks, the game needs to immediately auto-pause without waiting for the UI to tell it that it should do so, which could come several ticks late.

Is the user in creative mode (i.e. able to do anything without restriction)?

How to determine whether the player has won.

How to win (if possible). This is useful for automated testing and to show help to cheaters (or testers).

Whether statistics for the current scenario have been saved to disk *upon scenario completion*. (It should remain False whenever the current scenario has not been completed, either because there is no win condition or because the player has not yet achieved it.) If this is set to True, we should not update completion statistics any more. We need this to make sure we don't overwrite statistics if the user continues playing the scenario after completing it (or even if the user stays in the completion menu for a while before quitting; see #1932).

In this stage in the UI pipeline, both fields have already been validated, and Nothing means that the field is simply absent.

Aspects of the temporal state of the game

State and data for assigning identifiers to robots

Collection of recipe info

Message info

Controls, including REPL and key mapping

Inputs for randomness

Discovery state of entities, commands, recipes

Info about the lay of the land

Info about robots

Registry for caching output of the path command

Create an initial, fresh game state record when starting a new scenario.

Get a list of all the robots at a particular location.

Get all the robots within a given Manhattan distance from a location.

The base robot, if it exists.

The base robot environment.

The base robot store, or the empty store if there is no base robot.

Get the notification list of messages from the point of view of focused robot.

The filepath of the currently running scenario.

This is useful as an index to the scenarios collection, see scenarioItemByPath.

Note that it is possible for this to be missing even with an active game state, since the game state can be initialized from sources other than a scenario file on disk.

We keep a reference to the possible path within the GameState, however, so that the achievement/progress saving functions do not require access to anything outside GameState.

Whether the world view needs to be redrawn.

Whether the repl is currently working.

Recalculate the view center (and cache the result in the viewCenter field) based on the current viewCenterRule. If the viewCenterRule specifies a robot which does not exist, simply leave the current viewCenter as it is. Set needsRedraw if the view center changes.

Given a width and height, compute the region, centered on the viewCenter, that should currently be in view.

Find out which robot has been last specified by the viewCenterRule, if any.

Type for describing how far away a robot is from the base, which determines what kind of communication can take place.

Check how far away the focused robot is from the base. Nothing is returned if there is no focused robot; otherwise, return a RobotRange value as follows.

• If we are in creative or scroll-enabled mode, the focused robot is always considered Close.

• Otherwise, there is a "minimum radius" and "maximum radius".

  • If the robot is within the minimum radius, it is Close.
  • If the robot is between the minimum and maximum radii, it is MidRange, with a Double value ranging linearly from 0 to 1 proportional to the distance from the minimum to maximum radius. For example, MidRange 0.5 would indicate a robot exactly halfway between the minimum and maximum radii.
  • If the robot is beyond the maximum radius, it is Far.
• By default, the minimum radius is 16, and maximum is 64.

• Device augmentations

  • If the focused robot has an antenna installed, it doubles both radii.
  • If the base has an antenna installed, it also doubles both radii.

Get the min/max communication radii given possible augmentations on each end

Clear the robotLogUpdated flag of the focused robot.

Add a message to the message queue.

Reconciles the possibilities of log messages being omnipresent and robots being in different worlds

Returns a list of robots, ordered by decreasing preference to serve as the "base".

Rules for selecting the "base" robot:

What follows is a thorough description of how the base choice is made as of the most recent study of the code. This level of detail is not meant to be public-facing.

For an abbreviated explanation, see the "Base robot" section of the Scenario Authoring Guide.

Precedence rules

1. Prefer those robots defined with a loc (robotLocation) in the scenario file

   1. If multiple robots define a loc, use the robot that is defined first within the scenario file.
   2. Note that if a robot is both given a loc AND is specified in the world map, then two instances of the robot shall be created. The instance with the loc shall be preferred as the base.

2. Fall back to robots generated from templates via the map and palette.

   1. If multiple robots are specified in the map, prefer the one that is defined first within the scenario file.
   2. If multiple robots are instantiated from the same template, then prefer the one with a lower-indexed subworld. Note that the root subworld is always first.
   3. If multiple robots instantiated from the same template are in the same subworld, then prefer the one closest to the upper-left of the screen, with higher rows given precedence over columns (i.e. first in row-major order).

Get the entity (if any) at a given location.

Provide an entity accessor via the MTL transformer State API. This is useful for the structure recognizer.

Perform an action requiring a World state component in a larger context with a GameState.

Perform an action requiring a Robots state component in a larger context with a GameState.