TELECOM ITALIA GROUP
AMUSE
Agent-based Multi User Social Environment
Agenda
►
►
►
Overview
Main features
Developing amuse-based applications
API Overview
Quick startup guide
►
Current limitations and future works
TELECOM ITALIA
AMUSE
 A software platform that facilitates the development of distributed multiuser applications where users compete/cooperate to achieve private or
common goals.
 The primary focus is on multi-player on-line games
 Based on JADE and on its extension WADE
 Communication and discovery
 Administration mechanisms of the server-side components
 Open source since the 5th of December 2013
 0.9-alpha version
 Experimental version
 http://jade.tilab.com/amuse
 In this first version supports Android clients only
 There is a lot to do  Whoever is interested in contributing to the
Community is very welcome
3
TELECOM ITALIA
Architecture
Application1
client
Amuse client lib
Application1
client
Amuse client lib
JadeAndroid
JadeAndroid
User-1
User-2
Application1 server
components
...
Android
Play Store
- Register
- Install
- Configure
- Start
ApplicationM server
components
Amuse server components
Wade Distributed Runtime
DB
PaaS
approach
Appl Admin
Interface
Application
developer
Development
environment
Application types
host-1
host-D
host-N
 Server-based
 Client-only
4
TELECOM ITALIA
Core Features
 User Management
 Registration/authentication of application users
 Basic user profile management
 Text Message exchange
 With automatic store-and-forward support
 Peer-to-peer Pipe Management
 Establishment of a direct connection between two clients
 Transfer of application specific information over that connection
 Raw clock synchronization
 Support for performing actions at the same time
5
TELECOM ITALIA
B
PROPOSE
Gaming Features
REFUSE
 Peer-to-Peer Match Coordination
PROPOSE
A
 1-to-1 matches
C
ACCEPT
 Match organization based on the
Invitation metaphor
 Match info are kept locally and
asynchronously persisted on server
INFORM (B, C)
REQUEST
(GetRandomUsers)
UpdateMatch
UpdateMatch
AMUSE Server
 Supports Client-only applications
 Centralized Match Coordination
 N-players matches
 Support for players joining
leaving an ongoing match
and
 Match organization based on the
Table metaphor
 Require Server-based applicatins
6
TELECOM ITALIA
Gaming Features
 Peer-to-Peer Match Coordination
 1-to-1 matches
 Match organization based on the
Invitation metaphor
 Match info are kept locally and
asynchronously persisted on server
 Supports Client-only applications
 Centralized Match Coordination
B
 N-players matches
 Support for players joining
leaving an ongoing match
and
 Match organization based on the
Table metaphor
A
INFORM
(MatchStarting)
INFORM
(MatchStarting)
REQUEST
(JoinTable)
C
REQUEST
(CreateTable)
 Require Server-based applicatins
INFORM
(MatchStarting)
REQUEST
(JoinTable)
AMUSE Server
7
TELECOM ITALIA
Gaming Features
 Peer-to-Peer Match Coordination
 1-to-1 matches
 Match organization based on the
Invitation metaphor
 Match info are kept locally and
asynchronously persisted on server
 Supports Client-only applications
 Centralized Match Coordination
B
 N-players matches
 Support for players joining
leaving an ongoing match
and
 Match organization based on the
Table metaphor
REQUEST
(Move)
A
C
INFORM
(Result)
INFORM
(PlayerMoved)
INFORM
(PlayerMoved)
 Require Server-based applicatins
AMUSE Server
8
TELECOM ITALIA
AMUSE Client API
 com.amuse.client package
 Entry point: com.amuse.client.android.AmuseClient
 Connection with the AMUSE server platform (method connect())
 User authentication (method setLoginManager())
 Server clock synchronization (method serverCurrentTimeMillis())
 Access to features (method getFeature())
 Features
 Core (com.amuse.client.features.core)
 UserManagementFeature
 TextMessageFeature
 PipeManagementFeature
 Gaming (com.amuse.client.features.gaming)
 MatchCoordinationFeature (peer-to-peer match coordination)
 GamesRoomFeature (centralized match coordination)
9
TELECOM ITALIA
AMUSE Server API
 Only needed for server-based applications
 Required to implement the server-side logics of a game managed by
means of the centralized coordination approach (GamesRoomFeature)
 Entry point: com.amuse.agents.gra.GamesRoomAgent
 A JADE Agent that must be extended to redefine a set of callback methods
that are invoked
 When clients create tables (handleTableCreated())
 When a sufficient number of player joined a table and the match can start
(handleMatchStartup())
 When
players
Join/Leave
a
table
with
an
(handlePlayerJoined(), handlePlayerLeft())
ongoing
match
 When a player moves (handleMove())
 When activating the server side logics several GRA agents can be started each
one implementing a Games Room that contains many Tables.
10
TELECOM ITALIA
Startup guide: Amuse server platform - Installation
 Download required packages
 Amuse platform
 WADE 3.3 + PersistenceAdd-on
 Install (unzip) WADE and Amuse
...
|--wadeSuite/
|--wade/
|--add-ons/
|--...
|--amuse/
|--platform/
|--cfg/
(all amuse configurations)
|--lib/
(amuse libraries)
|--log/
(amuse logs will be produced here)
|--src/
(amuse sources)
|--tools/ (amuse administration tools)
|--...
11
TELECOM ITALIA
Startup guide: Amuse server platform – DB Configuration
 Configure and start the Amuse DB
 H2 (full Java Open Source DB), but other DBs should work as well
 Start the H2 DB server
 wadeSuite/wade/add-ons/persistence/lib
 java -jar h2-1.2.123.jar
 Configure Amuse to use H2
 Create a suitable directory to hold DB files (e.g. amuse/H2)
 amuse/platform/cfg/hibernate.cfg.xml
 Create the Amuse schema
 amuse/platform/tools
 ant create-db
 Require ANT 1.7.0
12
TELECOM ITALIA
Startup guide: Amuse server platform - Activation
 Configure the single-application-mode
 amuse/platform/cfg/types.xml
<properties>
<Property name="singleApplicationName" value="Test"/>
<Property name="singleApplicationType" value="CLIENT_ONLY"/>
...
 Tell WADE where to find amuse
wadeSuite/wade/projects/
project-home=
|--default.properties
|--amuse.properties
amuse/platform
 Activate the WADE Bootdaemon and the Amuse Main Container
 wadeSuite/wade/bin/
 startBootdaemon
 startMain amuse
13
TELECOM ITALIA
Startup guide: Client part
 The client part of an amuse-based application is an Android App
 Create an Android project in Eclipse
 Download the Amuse Android Client and unzip it locally
 Create a lib/ directory in your Android project, copy the libraries
 JadeAndroid.jar
 amuseCommons.jar
 amuseAndroidClient.jar
from amuse/android-client/lib/ directory to the lib/ directory in
your project
 Add the above libraries to your project build path
14
TELECOM ITALIA
Startup guide: Android manifest hints
 Amuse based clients interact with the Amuse platform and with other
clients
 Give the Android App the INTERNET permission
<manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >
...
<uses-permission android:name="android.permission.INTERNET" />
...
 All communications are carried out by JADE
 Declare the Jade MicroRuntime service
<application android:name="MyApplication" ....>
<service android:name="jade.android.MicroRuntimeService" />
...
15
TELECOM ITALIA
Startup guide: Platform connection code snippet (1/2)
Properties pp = new Properties();
String ip = getResources().getString(R.string.amuse_host);
pp.setProperty(MicroRuntime.HOST_KEY, ip);
By default
2099
String port = getResources().getString(R.string.amuse_port);
pp.setProperty(MicroRuntime.PORT_KEY,
port);
amuseClient = new AmuseClient(getResources().getString(R.string.app_name),
getApplicationContext());
amuseClient.setConnectionProperties(pp);
amuseClient.setLoginManager(new LoginManager() {
@Override
public void askLoginInformation(Callback<LoginInfo> callback) {
// This is the first time the user logs in with this terminal --> Show
// a form to let him type in his username and password.
// When done, invoke the callback onSuccess() method passing login
// information in the LoginInfo object
...
}
});
16
TELECOM ITALIA
Startup guide: Platform connection code snippet (2/2)
amuseClient.connect(new Callback<Void>() {
@Override
public void onSuccess(Void arg0) {
// Connection to the Amuse platform OK
// From now on it is possible to access and use features
...
}
@Override
public void onFailure(Throwable thr) {
if (thr instanceof LoginError) {
// Wrong username/password or, for new accounts, username already
// in use or not valid. Show a suitable message to the user
...
}
else {
// Connection error. Show a suitable message to the user
...
}
}
});
17
TELECOM ITALIA
Startup guide: Server part (1/2)
 The server part of an amuse-based application is a WADE application
 Create an Eclipse Project for a WADE application following the instruction
in the WADE Development Tutorial
 Copy the amuse.jar e amuseCommons.jar libraries to the lib/
directory of the created project and add them to the project build path
 Develop a class that extends GameRoomAgent
 Create the applications.xml file in the cfg/ directory of the created
project
<Application>
<agents>
<Agent name="room1" className="myPackage.MyGRAExtensionClass"/>
</agents>
</Application>
18
TELECOM ITALIA
Startup guide: Server part (2/2)
 Create a Run Configuration with
 Use that Run Configuration to
run and debug the server-side
 Main class: com.amuse.StartApp
logics of your application
 Program arguments: <application-name>
19
TELECOM ITALIA
Current limitations and future works
 Amuse Platform
 Uncompleted Application sand-box
 Missing Graphical Application Management interface
 Amuse client
 Ready-made activities to manage common views (login, list of friends ...)
 Services to manage asynchronous events when the application is not in
foreground
 Support for other technologies
 Additional functionality
 Achievements support
 Integration with main Social Networks
 Support to define virtual players
 Development support
 Examples
 Eclipse Plug-in to facilitate the development of server-side logics
20
TELECOM ITALIA
Thanks for the attention
 Amuse web site – http://jade.tilab.com/amuse
 Distribution package download
 SVN access
 Amuse Startup Guide
 Support – jade-develop@avalon.tilab.com
 You must subscribe to the mailing list
21