Developing a Connector

Owned by Hindriks, K.V. (Koen)
Dec 17, 2016

Creating your own Environment Interface

Introduction to EIS

In order to create your own interface, it's important to understand the basics of what an Environment Interface is and does. We will discuss some terms below;

  • Environment: examples of Environments are games, rooms, etc. Everything that can be observed/controlled by something can be classified as being an Environment.
  • Entity: an controllable Entity is an 'object' that can be controlled in the Environment. The object can (normally) 'sense' what is happening (changes to the Environment) and it can perform actions in that Environment (in order to change it). An example would be a (controllable) character in a game or the gripper in the blocksworld (see eishub/blocksworld).
  • Agent: an agent is a computer program that's able to make decisions on what to do. They can respond to changes in the Environment, interact with other agents, pursue goals over time, etc. An agent can control an Entity in the Environment. Information received from the Environment can be returned to the agent through the Entity again, and the agent can use the information to make a new decision.

The picture below shows a high level view how the EIS environment interface glues together your environment to a GOAL system. Agents control EIS entities, to get their percepts and execute actions. The agent platform - GOAL for instance - also communicates with EIS but at a higher level, eg to initialize or reset a complete environment. The Adapter implements the EIS environment interface and glues it to your environment.

EIS general structure

Both the EIS management and the EIS entity functionality are defined in the EnvironmentInterfaceStandard.java file.

In a client-server or distributed environment, such as Blocksworld For Teams, the connection between the Adapter and your environment may be using network connections such as RMI.

The connections are as follows

  • from agents to EIS: to enable an Agent to act and perceive in the environment
  • from the Agent Platform to EIS: to enable manipulating the environment state
  • from EIS to the Agent Platform: to report about new or killed agents, and state changes.
  • from EIS to Agent: to report agents about new percepts.

Sharing the JVM

Depending on the agent system, your environment may share the Java Virtual Machine (JVM) and the graphics system (Java AWT thread) with other components. At least, there will be some extra java threads in the JVM where your environment runs, implementing details of EIS and managing the connection to the agent platform.

Therefore your environment should play nice when it comes to using these shared resources. Here are a few of guidelines to keep your environment compatible :

  1. Terminate your environment through EIS, by removing the entities and setting the environment's run mode to KILLED. Particularly , do not kill the JVM.
  2. Realize that calls to AWT may only be handled AFTER your code has returned control to EIS. So for example, do not call SwingUtilities.invokeAndWait (or Frame.dispose() which does the same).

Environment states

An environment can be in several states (defined in eis.iilang.EnvironmentState), we will discuss them briefly below;

  • INITIALIZING; this state is used when the Environment is being launched. The environment isn't ready to start (yet).
  • RUNNING; this state is used when the Environment is completely launched, information is flowing and actions can be performed (depending on the circumstances in the environment that is).
  • PAUSED; this state indicates that the Environment is 'frozen'. No new actions will be performed until the environment is resumed (transition to the RUNNING state).
  • KILLED; this state is used when the Environment is closed / terminated. No new actions can be performed, and there won't be any new information to process. Unless PAUSED, this is a final state, you can only launch the Environment again by restarting the whole process.

In the Default EIS implementation the state transitions are allowed in the following directions:

State transitions between Environment States

Perceiving

An environment can provide the Agent with information that the entity can get from the environment. The environment sends its information using so called 'Percepts' through the Environment Interface to the Agent. This could be any kind of information; like the current position of the entity, artefacts that the entity can see from its current position, etc.

There are three ways to implement the perceiving process in the entity:

  1. passive sensing, where the Agent calls getAllPercepts to get the entity's current percepts
  2. active sensing, where the Agent first has to execute an action to trigger/enable/aim a sensor
  3. automatic sensing, where the entity triggers callbacks to an agent actively

Passive sensing is the most common form used in environments.

Acting

The entity can affect its environment by executing actions. The Agent controls the entity's action through an executeAction call to the entity. So the agent decides what action has to be performed with the current knowledge, and passes this to the entity. This could result in some Percepts about the changes in the environment. Notice that the action requested by the agent can be 'high level', for example 'go to the bath room', and that the entity then executes a list of lower-level actions such as path planning the route to the bath room, navigating around new obstacles, opening doors etc.