The ViewCenterRule specifies how to determine the center of the world viewport.

A data type to represent the current status of the REPL.

TODO: #1044 Could also add an ObjectiveFailed constructor...

A data type to keep track of the pause mode.

Game step mode - we use the single step mode when debugging robot CESK machine.

Type for remembering which robots will be run next in a robot step mode.

Once some robots have run, we need to store RID to know which ones should go next. At SBefore no robots were run yet, so it is safe to transition to and from WorldTick.

                    tick
    ┌────────────────────────────────────┐
    │                                    │
    │               step                 │
    │              ┌────┐                │
    ▼              ▼    │                │
┌───────┐ step  ┌───────┴───┐ step  ┌────┴─────┐
│SBefore├──────►│SSingle RID├──────►│SAfter RID│
└──┬────┘       └───────────┘       └────┬─────┘
   │ ▲ player        ▲                   │
   ▼ │ switch        └───────────────────┘
┌────┴────┐             view RID > oldRID
│WorldTick│
└─────────┘

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

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).

All the robots that currently exist in the game, indexed by ID.

The names of all robots that currently exist in the game, indexed by location (which we need both for e.g. the salvage command as well as for actually drawing the world). Unfortunately there is no good way to automatically keep this up to date, since we don't just want to completely rebuild it every time the robotMap changes. Instead, we just make sure to update it every time the location of a robot changes, or a robot is created or destroyed. Fortunately, there are relatively few ways for these things to happen.

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

Get a list of all the robots that are "watching" by location.

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

The base robot, if it exists.

The names of the robots that are currently not sleeping.

The names of the robots that are currently sleeping, indexed by wake up time. Note that this may not include all sleeping robots, particularly those that are only taking a short nap (e.g. wait 1).

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

The initial seed that was used for the random number generator, and world generation.

Pseudorandom generator initialized at start.

The filepath of the currently running scenario.

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

The current rule for determining the center of the world view. It updates also, viewCenter and focusedRobot to keep everything synchronized.

The current center of the world view. Note that this cannot be modified directly, since it is calculated automatically from the viewCenterRule. To modify the view center, either set the viewCenterRule, or use modifyViewCenter.

Whether the world view needs to be redrawn.

The current robot in focus.

It is only a Getter because this value should be updated only when the viewCenterRule is specified to be a robot.

Technically it's the last robot ID specified by viewCenterRule, but that robot may not be alive anymore - to be safe use focusedRobot.

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

Discovery state of entities, commands, recipes

Info about the lay of the land

How to step the game: WorldTick or RobotStep for debugging the CESK machine.

The current RunStatus.

The number of ticks elapsed since the game started.

The maximum number of CESK machine steps a robot may take during a single tick.

Whether the game is currently paused.

A counter used to generate globally unique IDs.

All recipes the game knows about, indexed by outputs.

All recipes the game knows about, indexed by inputs.

All recipes the game knows about, indexed by requirement/catalyst.

A queue of global messages.

Note that we put the newest entry to the right.

Last time message queue has been viewed (used for notification).

A queue of global announcements. Note that this is distinct from the messageQueue, which is for messages emitted by robots.

Note that we put the newest entry to the right.

Code that is run upon scenario start, before any REPL interaction.

The current status of the REPL.

The index of the next it{index} value

Whether the repl is currently working.

Either the type of the command being executed, or of the last command

The currently installed input handler and hint text.

The list of entities that have been discovered.

The list of available recipes.

The list of available commands.

The names of entities that should be considered "known", that is, robots know what they are without having to scan them.

Map of in-game achievements that were obtained

Includes a Map of named locations and an "edge list" (graph) that maps portal entrances to exits

The current state of the world (terrain and entities only; robots are stored in the robotMap). Int is used instead of TerrainType because we need to be able to store terrain values in unboxed tile arrays.

Whether the world map is supposed to be scrollable or not.

The catalog of all entities that the game knows about.

A data type to keep track of some kind of log or sequence, with an index to remember which ones are "new" and which ones have "already been seen".

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

Record to pass information needed to create an initial GameState record when starting a scenario.

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

Create an initial game state corresponding to the given scenario.

Given a current mapping from robot names to robots, apply a ViewCenterRule to derive the location it refers to. The result is Maybe because the rule may refer to a robot which does not exist.

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.

Modify the viewCenter by applying an arbitrary function to the current value. Note that this also modifies the viewCenterRule to match. After calling this function the viewCenterRule will specify a particular location, not a robot.

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

Unfocus by modifying the view center rule to look at the current location instead of a specific robot, and also set the focused robot ID to an invalid value. In classic mode this causes the map view to become nothing but static.

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 robot to the game state, adding it to the main robot map, the active robot set, and to to the index of robots by location.

Helper function for updating the "robotsByLocation" bookkeeping

Add a concrete instance of a robot template to the game state: First, generate a unique ID number for it. Then, add it to the main robot map, the active robot set, and to to the index of robots by location. Return the updated robot.

Add a message to the message queue.

Iterates through all of the currently wait-ing robots, and moves forward the wake time of the ones that are watch-ing this location.

NOTE: Clearing TickNumber map entries from internalWaitingRobots upon wakeup is handled by wakeUpRobotsDoneSleeping

Takes a robot out of the activeRobots set and puts it in the waitingRobots queue.

Takes a robot out of the activeRobots set.

Removes robots whose wake up time matches the current game ticks count from the waitingRobots queue and put them back in the activeRobots set if they still exist in the keys of robotMap.

Makes sure empty sets don't hang around in the robotsByLocation map. We don't want a key with an empty set at every location any robot has ever visited!

Adds a robot to the activeRobots set.

Switch (auto or manually) paused game to running and running to manually paused.

Note that this function is not safe to use in the app directly, because the UI also tracks time between ticks---use safeTogglePause instead.

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.

1. 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).