1



AMUSE START-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

1 Overview 3

2 Amuse features 4

3 Development environment setup 5

3.1 The Development Environment VM 5

3.1.1 Requirements 5

3.1.2 Operating System and login 6

3.1.3 Installed software overview 6

3.2 AMUSE platform step-by-step installation 7

3.2.1 Configuring the single-application mode 8

4 Creating your first AMUSE based game 9

4.1 Client part 9

4.1.1 Amuse client APIs overview 10

4.1.2 Android client manifest file 11

4.2 Server part 12

4.2.1 Activating the game server part locally 13

4.2.2 Amuse server APIs overview 14

4.2.3 Creating the server-side logics installation package 14

Overview

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. Throughout this document we will use the terms game and application as synonyms.

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 1 shows 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.

[pic]

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-only games. Once registered, client-only games are always considered active.

Amuse 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.

Centralized match 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.

Development 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.

1 The 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).

1 Requirements

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

2 Operating 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 Installed software overview

Figure 2 shows the desktop of the Development Environment VM.

[pic]

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.

2 AMUSE 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 () or, 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 see a 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 setup the Amuse Platform in your local development environment it is necessary to perform the following steps.

1) Install WADE and the Persistence Add-On in 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 /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

jdbc:h2:tcp://localhost/full-local-path/AMUSE

amuse

amuse

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 Guide make 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 that open a shell, go to the bin directory inside your local WADE installation and start the WADE BootDaemon

startBootDaemon

and the Amuse Platform 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.

1 Configuring 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 ------------------------------------------------------------

Creating 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.

1 Client 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.jar and RANMonitor.jar libraries. 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.

NOTE: The Development Environment VM presented in section 3.1 includes a ready-made Android Studio installation that can be used to develop the game client. However, since no AMUSE specific configuration is required (a part from including the right jar files), developers are free to use their own Android Studio installation if they prefer.

1 Amuse client APIs overview

The Android App that realizes the client part of an Amuse-based application is expected to implement all application specific client-side logics as well as to provide all graphical user interfaces required by the application to interact with a user. This will be done creating suitable Android Activities and exploiting the usual Android APIs (refer to the Android documentation for details).

The client App will then use the Amuse client APIs to perform all “social activities” required by the application such as logging in, searching for other users and interacting with them in appropriate forms.

The Amuse client APIs are organized in features each one realizing a consistent set of functionality and accessible by means of a well defined interface. Before accessing features the client App must connect to the Amuse Platform by means of the connect() method of the com.amuse.client.android.AmuseClient class. The following code snippet exemplifies the connection phase.

private AmuseClient amuseclient;

...

String ip = getResources().getString(R.string.amuse_host);

Properties pp = new Properties();

pp.setProperty(MicroRuntime.HOST_KEY, ip);

String port = getResources().getString(R.string.amuse_port);

pp.setProperty(MicroRuntime.PORT_KEY, port);

amuseClient.setConnectionProperties(pp);

amuseClient.setLoginManager(new LoginManager() {

@Override

public void askLoginInformation(Callback loginCallback) {

// Show a form to let the user type in username and password

// When done, call the loginCallback onSuccess() method passing

// the inserted username and password in the LoginInfo object.

...

}

});

amuseClient.connect(new Callback() {

@Override

public void onSuccess(Void arg) {

// Connection OK. From now on it is possible to access features

...

}

@Override

public void onFailure(Throwable thr) {

// Connection failed. Show a proper message to the user

...

}

});

NOTE: By default the port where the AMUSE platform accepts connections from application clients is 2099.

The following code snippet shows how to get the AmuseClient instance

String gameName = “MyAmuseGame”;

AmuseClient.getInstance(gameName, this, new Callback() {

@Override

public void onSuccess(AmuseClient c) {

// AmuseClient successfully retrieved

amuseclient = c;

...

}

@Override

public void onFailure(Throwable t) {

// AmuseClient retrieval error

...

}

});

Once connected, features are retrieved by means of the getFeature() method of the AmuseClient class. The following code snippet exemplifies how to access a feature. Refer to the API Javadoc for details about how to exploit each feature.

MatchCoordinationFeature mcf = amuseClient.getFeature(MatchCoordinationFeature.class);

For more information on how to actually develop an AMUSE based game we suggest reading the AMUSE Tutorial available at .

2 Android client manifest file

AMUSE client side logics rely on two Android Services (the AmuseService and the RANMonitorService) that must be declared in the manifest file of your Android App.

Similarly the following Android permissions must be specified:

INTERNET

ACCESS_COARSE_LOCATION,

ACCESS_FINE_LOCATION

ACCESS_NETWORK_STATE

ACCESS_WIFI_STATE

READ_PHONE_STATE

The following snippet provides an example (AMUSE specific stuff highlighted in bold).

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download