Usage Restricted According to License Agreement

AMUSE User Guide

AMUSESTART-UP GUIDE

USAGE RESTRICTED ACCORDING TO LICENSE AGREEMENT.

Last update: 27-April-2016–Amuse 1.6

Authors: Giovanni Caire (Telecom Italia S.p.A)

AMUSE (Agent-based Multi-User Social Environment) is a software platform that facilitates the development of distributed social applications involving users that cooperate/compete to achieve common or private goals. Within this scope the primary focus of Amuse is on multi player on-line games.

This guide refers to the very first experimental version of the Amuse platform. Comments, suggestions and contributions are very welcome to help Amuse evolve and become as robust and usable as possible.

The AMUSE library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, version 2.1 of the License.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Java and HotJava are trademarks of Sun Microsystems, Inc., and refer to Sun's Java programming language and HotJava browser technologies. The AMUSE platform is not sponsored by or affiliated with SUN Microsystems, Inc."

TABLE OF CONTENTS

1Overview

2Amuse features

3Development environment setup

3.1The Development Environment VM

3.1.1Requirements

3.1.2Operating System and login

3.1.3Installed software overview

3.2AMUSE platform step-by-step installation

3.2.1Configuring the single-application mode

4Creating your first AMUSE based game

4.1Client part

4.1.1Amuse client APIs overview

4.1.2Android client manifest file

4.2Server part

4.2.1Activating the game server part locally

4.2.2Amuse server APIs overview

4.2.3Creating the server-side logics installation package

1Overview

The AMUSE platform is a WADE based system and uses the underlying WADE/JADE (see runtime to manage all communication and component management issues.Being familiar with WADE and JADE is not strictly necessary to create AMUSE based games. Some knowledge of JADE Agent programming, however, can help in the development of server-side components of the game.

Figure 1shows an overview of the AMUSE platform architecture. All AMUSE-based games comprise a client that provides the user interface plus any game specific client-side logics. The game client makes use of the Amuse client library to interact with other users clients and with the server. In this very first version, the AMUSE platform supports Android-based clients only and therefore the client has the form of an Android App.

Figure 1. Amuse Architecture overview

NOTE: AMUSE does not provide any mechanism to distribute game client Apps. The Google PlayStore should be used for that purpose.

In many cases an AMUSE-based game also involves game specific logics to be executed server side. In the AMUSE terminology we refer to such games as server-based applications. The AMUSE platform provides a PaaS (Platform as a Service) environment to run such logics. That is server-side components of AMUSE-based games are not aware about all the details related to hardware, operating systems and the like. On the other hand they are deployed on a cloud-like environment and AMUSE takes care of ensuring they have sufficient resources to do their job.

The Amuse Application Administration Console allows registering a game and then installing, configuring and starting its server-side specific components. Once the game is up and running clients can connect and users can start exploiting them.

In other cases the game does not need any specific logics running server side. In the AMUSE terminology we refer to such games as client-onlygames. Once registered, client-only games are always considered active.

2Amuse features

AMUSE provides a set of core features not strictly related to the gaming domain. Such features are listed below.

Application management –This feature concerns the possibility of registering, installing, configuring, activating and controlling applications. These operations are made available through the Amuse Application Administration Console accessible via Web at In general developers never deal with this feature programmatically.

User Management– This feature concerns the registration and authentication of application users as well as a minimal support for managing user profiles in the form of a set of application specific properties. The client API provided by the com.amuse.client.features.core.UserManagementFeature interface allows retrieving user information on the basis of their names and properties as well as on a random basis.

Clock synchronization – This feature provides a raw synchronization that allows clients of an application running on different terminals to perform actions at the same time (this is particularly important for instance for real-time games, where a match must start at the same time for all players).

Text message exchange – This feature concerns the possibility of sending and receiving textual messages to/from other users within a given application. It is accessible by means of the client API provided by the com.amuse.client.features.core.TextMessageFeature interface. In case the receiver is not connected at the time a message is sent, the message is authomatically stored server-side and will be delivered to the receiver as soon as it connects again.

Peer-to-peer pipe management – This feature concerns the possibility of establishing a direct connection (pipe) between the clients of two users and exchange application specific objects over that pipe. It is accessible by means of the client API provided by the com.amuse.client.features.core.PipeManagementFeature interface.

Furthermore Amuse provides two additional features specifically designed to support the organization and management of game matches.

Peer-to-peer match coordination – This feature (accessible by means of the client API provided by the com.amuse.client.features.gaming.MatchCoordinationFeature interface) supports the organization of possibly persistent (if the games allows that, a user can turn off its terminal and join the match again at a later time) one-to-one matches. Match organization is based on the invitation metaphor: the match organizer invites the opponent explicitly specifying his name or asking the Amuse platform to randomly select one. The opponent is notified about the invitation and can accept or reject it. If the opponent accepts the invitation the match starts.

Game applications based on this approach do NOT require game-specific logics running server side and therefore can be built as client-only applications.

Centralizedmatch coordination – This feature (accessible by means of the client API provided by the com.amuse.client.features.gaming.GamesRoomFeature interface) supports the organization of matches involving 2 ore more players possibly joining and leaving the match while it is ongoing.. Match organization is based on the table metaphor: the match organizer creates a table where players can join. As soon as the minimum number of players required by the game joined the table, the match starts. Tables are organized in rooms that players must enter before they can create/join tables.

Game applications based on this approach require game-specific logics running server side and therefore can only be built as server-based applications. More in details such logics must be implemented extending the com.amuse.agents.gra.GamesRoomAgent class that provides the basic mechanisms to manage tables inside a room and to coordinate matches played on tables.

3Development environment setup

As mentioned, the AMUSE platform where clients need to connect before they can exploit AMUSE features and where games server-side logics (if any) run, is available online at amuse.dmi.unipr.it. We will refer to this as the Official AMUSE PaaS Platform.

Of course, when creating an AMUSE based game, it is useful to have a local installation of the AMUSE platform to try and debug your code before making it available in the Official AMUSE PaaS Platform.

In order to facilitate the setup of this local development environment, a Virtual Machine that can be run by means of any VM player (e.g. the VmWare Player or Virtual Box) is provided with all the software already installed and configured. Section 3.1 describes how to use it. Section 3.2 on the other hand describes the steps necessary to manually install an AMUSE platform from scratch; this section is mainly for information purpose and typically developers do not need to care about that.

3.1The Development Environment VM

The AMUSE Development Environment VM with all the necessary software to develop AMUSE based games already installed and configured can be downloaded from the AMUSE web site at

Once downloaded, the Development Environment VM can be executed by means of any VM player (e.g. the VmWare Player or Virtual Box).

3.1.1Requirements

The following minimal requirements must be taken into account.

Host PC

- Memory: 4 GB (minimal) 8 GB (recommended)

- Processors: 4

- Disk: 20GB

Development Environment VM

- Memory:

- 2 GB (server-part only: NO Android Studio)

- 3 GB (minimal to use Android Studio)

- 4 GB (recommended)

- Processors: 2

3.1.2Operating System and login

The Development Environment VM is equipped with the Ubuntu 14.04.2 LTS (64 bit) operating system and comes with a preconfugured user with administration rights:

Username: amuse

Password: jade2016

3.1.3Installed software overview

Figure 2 shows the desktop of the Development Environment VM.

Figure 2. Configuring the project

The Development Environment VM already hosts an installation of both WADE, AMUSE and the MTris game provided as sample in the AMUSE distribution. Such installation can be updated at any time clicking on the Update WADE, Update AMUSE and Update MTris shortcuts.

The local AMUSE platform can be activated and deactivated by clicking on the Start AMUSE and Stop AMUSE shortcuts.

The Development Environment VM also contains preinstalled IDEs to let you develop the client part (Android Studio) and the server part (Eclipse) of your AMUSE based games. Click on the Eclipse and Android Studio shortcuts to activate such IDEs.

Suitable projects to inspect and possibly modify the client part and server part of the MTris sample game are preconfigured in the two IDEs.

3.2AMUSE platform step-by-step installation

In this section all the steps necessary to manually install the AMUSE platform from scratch are described.

The AMUSE platform software can be retrieved either from the download area of the AMUSE web site ( in source form, from the SVN repository (

The Amuse Platform is a WADE based system, and as such,

- it is installed and started as whatever WADE based system as described in the WADE Installation Guide.

- it has the typical structure of a WADE based system: when you get the Amuse Platform software (from the SVN repository or from the distribution package)you should seea directory structure similar to that reported below.

...

|--amuse/

|--...

|--platform/

|--cfg/

|--lib/

|--log/

|--src/

|--tools/

|--utility/

|--...

|--build.properties

|--build.xml

Having done that, in order to setupthe Amuse Platform in your local development environment it is necessary to perform the following steps.

1) Install WADEand the Persistence Add-Onin your local machine (see steps 3 and 4 of section 2 in the WADE Installation Guide).

2) Build the Amuse libraries.

This step is not necessary if you got the Amuse Platform from the distribution package since this package already contains the pre-built amuse libraries.

- Edit the build.properties file and set the wade-home property to point to the home directory of your local WADE installation.

- Then open a shell and type (this requires Apache ANT to be installed in your environment)

ant lib

As a result the amuse jar files should be produced in the lib directory.

3) Configure and activate the Amuse DB. Amuse makes use of a Relational DB to store information related to applications, users, matches and the like. Therefore a suitable DBMS must be installed and activated before trying Amuse. In this very first version, tests have been performed using the H2 DB and therefore this section focuses on it. However we do not expect problems with other DBMS supporting standard SQL such as MySql or Oracle.

H2 is already included in the WADE Persistence Add-On and therefore, unless you want to use a different DBMS, you don’t need to download and install anything.

- To start H2 just open a shell, move to the <wade-home>/add-ons/persistence/lib/ directory and type

java –jar h2-1.2.123.jar

- To tell the Amuse Platform where to find its DB, open the hibernate.cfg.xml file (Amuse use Hibernate to access the DB) in the amuse/platform/cfg/ directory and edit the DB URL as below

<property name="connection.url">jdbc:h2:tcp://localhost/full-local-path/AMUSE</property>

<property name="connection.username">amuse</property>

<property name="connection.password">amuse</property>

where full-local-path indicates the full path of a directory that must exist and where H2 will store DB data and AMUSE is the name of the DB schema that will be created to store Amuse data.

- Finally move to the amuse/platform/tools directory, compile the Amuse administration tools (really a few stuff in this early version) by typing

ant lib

and then create the Amuse DB schema by typing

ant create-db

4) Configure and activate MongoDB

TBD

5) Start the Amuse platform

Consistently with step 7 of Section 2 in the WADE Installation Guidemake a copy of the default.properties file inside the projects directory of your local WADE installation. Call it amuse.properties. Then open the amuse.properties file and edit the project-home and project-classes properties to reflect where amuse is in your local disk (full path of the amuse/platform directory).

- After thatopen a shell, go to the bin directory inside your local WADE installation and start the WADE BootDaemon

startBootDaemon

and the AmusePlatform Main Container

startMain amuse

Amuse is configured in the automatic-startup mode and therefore the whole Amuse platform should directly start when you launch the Main Container.

3.2.1Configuring the single-application mode

As mentioned Amuse-based applications must be registered and (if they are server-based applications) started by means of the Amuse Application Administration Console before application clients can actually connect. During the development phase of an Amuse-based application however, taking into account that the platform must likely be switched off and on again several times (as usual when developing code), such steps can be quite annoying. Therefore it is possible to configure the Amuse Platform to work in single-application mode. That is, the Amuse Platform gets the name and type of the application that is been developed as configuration properties and assumes that application has already been registered and started.

In order to configure the Amuse Platform in single application mode open the platform/cfg/types.xml files and enable the singleApplicationName and singleApplicationType global properties specifying the name and type of your application. Furthermore set the checkApplication property to false as shown below.

...

...

If already active, the Amuse Platform must be stopped and started again for these configurations to take effect.

Some lines similar to those below should appear in the BootDaemon output indicating that the single-application-mode has been successfully activated.

Agent ama ------

Agent ama ---- AMUSE Platform working in SINGLE APPLICATION MODE

Agent ama ---- APPLICATION is myAppName

Agent ama ------

4Creating your first AMUSE based game

This section shows how to create the client and server part of an AMUSE based game (for client-only applications the server part is not relevant). Furthermore a minimal overview of the AMUSE API is provided.

4.1Client part

As mentioned the client part of an AMUSE based game is an Android App and, as such, it is developed creating a project in Android Studio.

Having done that it is sufficient to add the AMUSE related libraries to the libs directory of your project:

- The JadeAndroid.jar library. This jar file is necessary to manage all communications with both the AMUSE platform and other clients. It should be noticed that even if an AMUSE based game is structured as a client-only application, it requires interacting with the server-side AMUSE Platform anyway.

- The amuseCommons.jar,amuseAndroidClient.jarand RANMonitor.jarlibraries. These jar files include all amuse specific classes required to access amuse features from an Android App.

Even though this is not really elegant (in future releases a better mechanism to manage AMUSE related libraries will be provided) the easiest way to get all the AMUSE related libraries is to copy them from the client of the MTris game provided as example within the AMUSE distribution. More precisely, assuming you are working with the Development Environment VM described in 3.1, the AMUSE related libraries can be copied from the /home/amuse/amuseEnvironment/amuse/applications/MTrisClient/app/libs/ directory.