-
Notifications
You must be signed in to change notification settings - Fork 6
Environment
This document will aim to explain how an environment is defined in Presage2 and how to create an environment to match your specification.
Interactions with the environment in Presage2 are defined with three interfaces:
- EnvironmentConnector: This is an agent's view of the environment, allowing registration, deregistration and the performing of actions.
- EnvironmentSharedStateAccess: This is an access layer to 'shared state'. This consists of state of agents or the environment which can be accessed by others.
- EnvironmentServiceProvider: This is an interface for retrieving EnvironmentServices. These are an abstraction layer on top of the shared state access. We will go into more detail on this later in this section.
While you can implement all these yourself we have a general implementation which handles all of these: AbstractEnvironment. In the majority of cases simply extending this will suffice. In this document we will assume that you do so.
In the majority of Multi-agent systems there is some concept of shared state. It generally refers to things which the agent can observe in the environment or about other agents. As it can be observed then it is not something that needs to be asked for via messaging etc, it should be simply accessable directly at any time. In Presage2 we wanted to create an API which mimiced these properties in a high level manner.
In Presage2 we have the low level shared state API as defined by EnvironmentSharedStateAccess. We then build EnvironmentServices on top of this. The benefits of this are that code is easier to understand as the services have simple, readable APIs and also it makes the agents' code less platform specific. By providing the same APIs in a real world environment or on another platform we can easily move agent code across.
EnvironmentServices can be split into two different types:
- Global: One instance for the environment. Can be provided by EnvironmentServiceProvider interface.
- Participant: One instance per participant. Provided in the EnvironmentRegistrationResponse. This is for services which will respond differently depending on the agent's state.
In AbstractEnvironment they are initialised as follows:
- Global: initialiseGlobalEnvironmentServices() generates the set of global environment services at environment initialisation time.
- Participant: generateServices(EnvironmentRegistrationRequest request) generates environment services to send in the EnvironmentRegistrationResponse to an agent's request to register with the environment. This is called at the time the request is sent.
There are several services already provided in the source to handle common uses:
- EnvironmentMembersService - UUID's of registered participants in the environment.
- LocationService - Locations of agents in the environment.
- ParticipantLocationService - Extension of LocationService to limit the agents an individual can get locations of by a perception range. Agent must implement HasPerceptionRange.
- CommunicationRangeService - Get communication range of agents. Used for some network implementations. Agents must implement HasCommunicationRange.
- AreaService - Get the simulation Area. Environment must implement [HasArea][].
In order to ensure the environment is always aware of agents who are acting within it, and to ensure that agent actions cannot be spoofed we require that agents register and deregister with the environment when they enter and leave respectively.
The register function in EnvironmentConnector requires an EnvironmentRegistrationRequest. This requires the participant's ID, the Participant object itself, and optionally a set of ParticipantSharedState. EnvironmentServices should provide functions to simplify the generation of the shared state they require.
The registration will return an EnvironmentRegistrationResponse. This contains an authkey. This is a shared secret between the environment and participant which will be used to authenticate further interactions between agent and environment and should be saved by the participant. Secondly it has a set of EnvironmentServices.
You can act on the environment by calling EnvironmentConnector.act() with an Action, your actor ID and authkey (received during registration). The environment must have an associated ActionHandler which can handle the Action or it will throw an ActionHandlingException, otherwise the action will be processed by the environment.
In the case an incorrect authkey is provided an InvalidAuthkeyException will be thrown.