Keyboard Specification

Last modification on 2019-02-07


This document briefly explains the user interface handles any key presses made by the user. It also contains a list of the default key bindings.

Key Terms and Concepts

agent_idAn argument referencing a specific breed of agent specified in the config file
CommandA message sent to the simulation allowing the user to interact with it
Command prompt bufferA piece of memory storing temporary text which has been inputted into the command prompt
HJKLA method of communicating directional data with the h, j, k and l keys of a keyboard
Insert modeA mode which allows users to input commands to be ran by the program
Normal bufferA piece of memory storing key presses made by the user in normal mode
Normal modeThe mode in which the user can interact with the program via various key binds
Parent commandThe command which forced the user interface to enter into select mode
Positional dataTwo numbers representing a 2D location in the simulations environment
Regular keyKeys that are bound to various commands
Select countHow many times a parent command will request positional data from select mode
Select modeThe mode which allows the user to specify positional data
Selecting functionThe function which handles select mode
Special keyKeys that are essential to the mechanics of the programs user interface
Yank bufferA buffer in which references to all agents yanked are stored


The only way of interfacing with Ecosim is via the keyboard. By pressing keys, the user is able to manually type commands, or quickly run one via a key bind. Keys behave differently in different modes:

Within the program there are special keys, such as <Esc> and <Return> and which do not map to any command. These keys are special as they're essential to the users ability to interact with the user interface. Other keys, such as d and i are regular keys, as they aren't essential to the user interface, they are simply used to control the simulation.

Key Handling in Normal Mode

In normal mode, the user hits the key binding for a command, then any arguments, without pressing return, for example pressing: "i3" tells the program to insert agents of agent_id 3 into the environment.

For any command requiring positional data, such as where to insert the new agents, the user interface will enter select mode as soon as the key binding has enough arguments to fully execute the command.

  1. Create an empty normal buffer
  2. Wait for a key press...
  3. Add the key to the normal buffer
  4. Look up the key. Is it valid?
    • No: Display error, go to step 1
    • Yes: Check the argument count and select count for the key and continue
  5. Check if there are enough arguments in the normal buffer to execute the command
    • Yes: Enter select mode as many times as needed as per the select count then execute the command and return to step 1
    • No: Continue
  6. Wait for a key press...
  7. Add the key to the normal buffer
  8. Go to step 5
Note: Pressing the special key <Esc> at any time in normal mode will clear the normal buffer

Key Handling in Insert Mode

In insert mode, any keys pressed are stored in the command prompt buffer and drawn onto the screen in the command prompt area. This allows the user to type commands in a typical fashion.

  1. Create an empty command prompt buffer
  2. Wait for a key press...
  3. Is the key <Return> or <Esc>?
    • <Return>: Attempt to run parse the command in the command prompt buffer
    • <Esc>: Enter normal mode
    • No: Add the key to the command prompt buffer and continue
  4. Go to step 2

Key Handling in Select Mode

The purpose of select mode is to allow the user to select a point in 2D space to be used as an argument for a command by using HJKL. Once return is pressed, the selected location is returned as a co ordinate to the parent command.

  1. Create x and y variables
  2. Wait for a key press...
  3. What type is the key?
    • Directional: Update relevant dimension variable, continue
    • <Esc>: Return to normal mode
    • <Return>: Return x and y to the parent command
  4. Go to step 2

Key bindings

Below is a list of all default key bindings in the simulation. Note that any positional data arguments to command functions aren't included in the arguments column. If no mode is specified assume the key binding is for normal mode.

KeyFunctionArgumentsSelect CountDescription
<Esc>N/AN/A0Clear the normal buffer in normal mode, enter normal mode in any other mode
<Return>N/AN/A0Confirm selection in select mode, confirm command in insert mode
<Space>PauseN/A0Pause the simulation in normal mode
:N/AN/A0Enter insert mode
cChangeagent_id2Change the selected agents into agents associated with the agent_id argument
dDeleteN/A2Delete the selected agents
hN/AN/A0Left in select mode
iInsertagent_id1Insert the agents specified by the agent_id argument at the selected location
jN/AN/A0Down in select mode
kN/AN/A0Up in select mode
lN/AN/A0Right in select mode
pPasteN/A1Paste agents from yank buffer into selected location
qQuitN/A0Quit the simulation
rReloadN/A0Reload the simulation
yYankN/A2Copy selected agents into the yank buffer

For a full list of commands and command arguments, please see the command specification.