Screen System

The Screen system simulates different dialogs and pause menus in the game. For example, when pausing to access the inventory, or when selling items by talking to a shop keeper.

Most of the time, the simulator can switch between screens automatically depending on the actions, so the effect of this system should be transparent to those who are used to previous versions of the simulator.

Understanding this system could be useful, if you want to explicitly control when you open a screen, which can be helpful when optimizing and verifying IST setups.

Game State

While not technically a screen, the Game itself can also have 2 different states: Running and, well, not Running (closed).

The initial state of the simulation is similar to a new game. When executing most commands, the game will keep running, unless:

• You manually closed the game with the close-game command.
• The game crashes.

Whenever the game is closed in the middle of a simulation (either closed manually or crashed), it will not automatically restart. You have to use either of the commands below:

• new-game to start a new game
• reload or reload SAVE_NAME to start the game and reload a save
  • SAVE_NAME is the name of the save, see Save Files

Screen Types

While in game, there are 4 screens that are simulated:

• Overworld:
  • The default state when you start a game.
  • Player is able to move
  • You can get/drop items
  • … all the other things you can do in the overworld
• Inventory:
  • When you pause the game with the + button
  • Player can interact with items in the inventory
• Shop Selling:
  • When talking to a shop owner to sell items
  • Player can select items in the inventory to sell
• Shop Buying:
  • When talking to Beedle or some other NPC to buy items
  • Player can select from a list of items to buy

The Screen system works like a state machine; when an action needs a certain screen, it will try to transition to that screen state if possible, and display an error if it couldn’t. The transition looks something like this:

             Overworld
         /---------|---------\
        /          |          \
       /           |           \
Inventory     Shop Buying  ---  Shop Selling

For example, if you are in the inventory menu and need to talk to a shop owner to sell something (i.e. to execute the sell command):

• The simulator first checks if you are already in the Shop Selling screen
• Since you are in the inventory screen, the simulator must return to Overworld by closing the inventory menu
• Then, it simulates talking to a shop owner by transitioning to the Shop screen
• Finally, it sells the item
• After all of that, it will stay in the Shop screen until it has to transition again

That all happens in a single sell command!

Manually switching screens

The following actions count as manually switching the screen. If the screen has been manually switched, the simulator will prevent certain automatic screen switches.

• Inventory:
  • pause to open the inventory
    • No automatic screen switches can happen until returned to overworld
  • unpause to close the inventory and return to overworld
• Shop (buying and selling):
  • talk-to NPC to start buying or selling (NPC can be any - or _ connected word)
    • Screen can be automatically switched between Buying and Selling, but not to Overworld
    • When returned to overworld, screen can be automatically switched again to all types
  • untalk or close-dialog to return to overworld

Note that annotations for screen switching like :pause-during get do not count as manually switching screens, and the simulator will still automatically switch screens afterward.