AMUSE USER GUIDE
A M U S E S TA RT- U P G U I D E
USAGE RESTRICTED ACCORDING TO LICENSE AGREEMENT.
Last update: 08-Dicembre-2014 – Amuse 1.0
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."
1
AMUSE USER GUIDE
TABLE OF CONTENTS
1
OVERVIEW .................................................................................................................. 3
2
AMUSE FEATURES .................................................................................................... 4
3
AMUSE PLATFORM SETUP ....................................................................................... 5
3.1
4
Configuring the single-application mode ............................................................................. 7
APPLICATION DEVELOPMENT ENVIRONMENT SETUP ......................................... 7
4.1
Client part ............................................................................................................................... 7
4.1.1 Amuse client APIs overview................................................................................................ 8
4.1.2 Android client manifest file ................................................................................................. 9
4.2
Server part .............................................................................................................................. 9
2
AMUSE USER GUIDE
1 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.
The AMUSE platform is a WADE based system and uses the underlying WADE/JADE runtime to
manage all communication and component management issues.
Figure 1 shows an overview of the AMUSE platform architecture. All AMUSE-based applications
comprise a client that provides the user interface plus any application specific client-side logics.
The application 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.
Application1
client
Amuse client lib
Application1
client
Amuse client lib
Android App
Android App
JadeAndroid
JadeAndroid
User-1
User-2
- Register
- Install
- Configure
- Start
Application1 server
components
...
Wade Distributed Runtime
host-1
Application
developer
ApplicationM server
components
Development
environment
Amuse server components
DB
Amuse Admin
Interface
PaaS
approach
host-N
host-D
Figure 1. Amuse Architecture overview
In many cases an AMUSE-based application also involves application specific logics to be executed
server side. In the AMUSE terminology we refer to them 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 applications 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.
3
AMUSE USER GUIDE
The Amuse Application Administration Interface allows registering an application and then
installing, configuring and starting its server-side specific components. Once the application is up
and running clients can connect and users can start exploiting them.
In other cases the application does not need any specific logics running server side. In the AMUSE
terminology we refer to such applications as client-only applications. Once registered, client-only
applications are always considered active.
2 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 Administration Interface accessible via Web at http://amuse.dmi.unipr.it/amuseConsole.
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
4
AMUSE USER GUIDE
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.
3 Amuse platform setup
As mentioned the AMUSE platform where clients need to connect before they can exploit AMUSE
features and where applications server-side logics (if any) run is available online at
amuse.dmi.unipr.it.
In many cases, however, it can be useful to have a local installation of the AMUSE platform. This
section describes how to setup it.
The AMUSE platform software can be retrieved either from the download area of the AMUSE web
site (http://jade.tilab.com/amuseproject/download/amuse) or, in source form, from the SVN
repository (http://jade.tilab.com/amuseproject/developers/source-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.
5
AMUSE USER GUIDE
- 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-localpath/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) 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 projecthome 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
6
AMUSE USER GUIDE
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.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 Interface 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.
<platform>
<properties>
...
<Property name="singleApplicationName" value="myAppName"/>
<Property name="singleApplicationType" value="SERVER_BASED"/>
<Property name="checkApplication" value="false"/>
<properties>
...
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
Agent
Agent
Agent
ama
ama
ama
ama
--------------------------------------------------------------- AMUSE Platform working in SINGLE APPLICATION MODE
---- APPLICATION is myAppName
------------------------------------------------------------
4 Application development environment setup
This section briefly describes how to setup the development environment for an Amuse-based
application. We will refer to the most general case of a server-based application that comprises both
a client and a server part. For client-only applications the server part is not relevant.
4.1 Client part
The client part of an Amuse-based application is an Android App that includes among its libraries
- The JadeAndroid.jar library. This jar file is necessary to manage all communications with
the server. It should be noticed that even if an Amuse-based application is structured as a clientonly application, it requires interacting with the server-side Amuse Platform anyway.
7
AMUSE USER GUIDE
- The amuseCommons.jar and amuseAndroidClient.jar libraries. These jar files include
all amuse specific classes required to access amuse features from an Android App.
As a consequence, in order to create the client part of an Amuse-based application it is sufficient to
- Create an Eclipse Android project
- Add the libraries mentioned above to the project build path.
NOTE: It should be noticed that, though the Amuse Platform is a WADE-based system, the client
part of an Amuse-based application does not depend on WADE, but on JADE only.
NOTE: Amuse does not provide any support for clients distribution/updating. On the other hand
application clients are expected to be distributed on the relevant distribution platforms. Considering
that in this version only Android based clients are supported, we expect amuse clients to be
distributed on the Android market.
4.1.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. Once connected features are retrieved
by means of the getFeature() method of the 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<LoginInfo> 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<Void>() {
@Override
public void onSuccess(Void arg) {
// Connection OK. From now on it is possible to access features
...
}
8
AMUSE USER GUIDE
@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 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);
4.1.2 Android client manifest file
The Android App that realizes the client part of an Amuse-based application used the Jade
MicroRuntimeService to communicate with other client Apps and with the Amuse Platform.
As a consequence
- It must be given the INTERNET permission
- It must declare the MicroRuntimeService
Furthermore it uses the AmuseService by means of which it is possible to retrieve an instance of
the AmuseClinet.
The following snippet provides an example.
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.telecom.battlespheres"
android:versionCode="3"
android:versionName="1.2" >
<uses-sdk android:minSdkVersion="10" android:targetSdkVersion="15" />
<uses-permission android:name="android.permission.INTERNET" />
<application
android:name="com.telecom.battlespheres.BattleSpheres"
android:allowBackup="true"
android:icon="@drawable/icon"
android:label="@string/app_name"
android:theme="@style/AppTheme" >
<service android:name="jade.android.MicroRuntimeService"
<service android:name="com.amuse.client.android.AmuseService" />
...
4.2 Server part
The server part of an Amuse-based application (relevant for server-based applications only) is very
similar to a WADE-based application. As a consequence in order to create it, it is necessary to
setup an Eclipse Project as described in chapter 2 of the WADE Installation Guide. The main
difference is related to the initial creation of the project default structure and therefore we suggest
the following procedure.
9
AMUSE USER GUIDE
1) Follow steps 1 to 5 described in Chapter 2 of the WADE Installation Guide. These leed you to
the creation of a Wade Project for your code in Eclipse.
2) Unless already done download the Amuse Platform distribution package and unzip it somewhere
on your disk (this will produce a directory structure similar to that presented at the beginning of
section 3).
3) Setup the project default structure as below:
- Copy the build.xml and build.properties files from the utility/ directory of your
local AMUSE installation to the home directory of your project.
- Edit the build.properties file specifying the name and version of your application and the
locations of WADE and AMUSE as exemplified below.
# Application name
application-name=MyAmuseApp
# Application version
version=1.0
# The directory where WADE is installed
wade-home=C:/develop/wadeSuite/wade
# The directory where AMUSE Platform is installed
amuse-home=C:/develop/amuse/platform
- Open a shell, move to the home directory of your project and type
ant setup
This requires Apache ANT 1.7 or later.
4) Configure your project as described in step 6 of Chapter 2 of the WADE Installation Guide,
without making Wolf create the project default structure for you: the correct structure was already
created in previous step.
The server-side logics of an Amuse-based application is structured as a set of WADE Agents. Once
developed (as outlined in next section), such agents can be tried and debugged following the steps
below.
1) Edit the application.xml file that was created in the cfg/ directory of your project during
the setup phase and declare the agents you want to start as exemplified below
<Application>
<agents>
<Agent name="a1" className="myPackage.MyAgentClass1"/>
<Agent name="a2" className="myPackage.MyAgentClass2"/>
</agents>
</Application>
2) Create a Run Configuration associated to your project using com.amuse.StartApp as main
class (Figure 2 [a]) and the name of your application as program argument (Figure 2 [b]).
10
AMUSE USER GUIDE
a)
b)
Figure 2. The Run Configuration to try the server part of an AMUSE application
3) Use the created Run Configuration to run and debug the server-side components of your
application.
4.2.1 Amuse server APIs overview
In the current version of AMUSE, the server APIs are limited to the implementation of the serverside logics of games managed using a centralized approach by means of the
GamesRoomFeature. In order to do that it is necessary to create an agent class that extends the
com.amuse.agents.gra.GamesRoomAgent base class and implements a set of callback
methods that are invoked when relevant events occur such as
 a client creates a table (handleTableCreated())
 a sufficient number of player joined a table and the match can start
(handleMatchStartup())
 a player Join/Leave a table with an ongoing match (handlePlayerJoined(),
handlePlayerLeft())
 a player moves (handleMove())
Each instance of the created agent class represents a Room where Tables to play matches can be
created. The name of the room corresponds to the name of the agent. For instance defining an
application.xml file as that below would result in having two rooms called red and green
respectively.
<Application>
<agents>
<Agent name="red" className="myPackage.MyGamesRoomAgentExtension"/>
<Agent name="green" className="myPackage.MyGamesRoomAgentExtension"/>
</agents>
</Application>
11
AMUSE USER GUIDE
4.2.2 Creating the server-side logics installation package
Once you are confident that the server side logics of your application is stable enough you can
create the installation package ready to be deployed on the Amuse runtime platform.
Assuming you have copied the build.xml and build.properties files from the
utility/ directory of your local AMUSE installation to the home directory of your project and
you have properly edited the build.properties file as described at the beginning of section
4.2, open a shell, move to the home directory of your project and type
ant rebuild
This requires Apache ANT 1.7 or later.
The installation package will be produced in the dist/ subdirectory of your project.
12