FlockEngine
FlockEngine
is the main class of the framework and needs to be implemented by every Activity using it.
You can instantiate FlockEngine
in two ways:
- Extending
FlockActivity
instead ofActivity
. This will automatically instantiateFlockEngine
as the local objectFlock
(accessible viaFlock.*
). FlockActivity is a small wrapper to simplify developing with the engine. - Instantiating
FlockEngine
manually (have a look inside FlockActivity.java for a reference implementation).
- See Also:
FlockActivity
, Examples, Tutorial
Summary
Nested Class Summary | |
---|---|
static interface |
FlockEngine.FlockEngineConnectedCallback
Callback used for instantiating FlockEngine manually, which will be invoked when the Activity is bound to the background service and ready to communicate. |
static interface |
FlockEngine.FlockEventCallback
Interface definition for a callback to be invoked when a status-event is received from the engine. |
Field Summary | |
---|---|
static int |
LOG_ALL
|
static int |
LOG_CRITICAL
|
static int |
LOG_NOTHING
|
UserManager |
User
Class used by developers for authenticating the local user, creating accounts, checking whether user is currently authenticated, etc. |
Constructor Summary | |
---|---|
FlockEngine(Context context)
Constructor of main class, which checks the settings (dev-id, etc.), starts the service if it's not running and binds to Service |
|
FlockEngine(Context context,
FlockEngine.FlockEngineConnectedCallback callbackWhenBound)
Constructor of main class including a callback which is started when successfully bound to the service. |
Method Summary | |
---|---|
boolean |
connect(java.lang.String groups,
int playersPerGame)
Start connection with game-server (with test-server if setTestServer(true) ). |
DBQueryBuilder |
createDBQueryBuilder()
Create a new database query builder (eg for displaying highscore, etc.). |
UserAttributeSyncer |
createUserAttributeSyncer()
Create an AttributeSyncer to save up to 250 attributes for the local user to the global database. |
void |
disconnect()
Immediately disconnect the socket connection if established. |
Participant[] |
getAllParticipants()
Array with all Participants of the current session, even those who have quit. |
Participant |
getLocalParticipant()
Participant object of the local user. |
int |
getLocalUserId()
Get the id of the local user in the current session [0..n]. |
Participant |
getParticipant(int user_id)
Get one Participant via it's user-id. |
boolean |
isAnonymousSession()
Check whether anonymous or authenticated session. |
boolean |
isConnected()
Check whether the socket connection is active or not. |
boolean |
isGameActive()
Check whether the framework is in a game (session), and not just in the lobby. |
boolean |
prioritizeActivity()
Priorize the current Activity's callback at the service. |
void |
requestUserAttributeNumber(java.lang.String key,
long defValue)
Numeric attribute to include automatically for all participants when the game starts. |
void |
requestUserAttributeString(java.lang.String key,
java.lang.String defValue)
String attribute to include automatically for all participants when the game starts. |
boolean |
sendChatMessage(java.lang.String msg)
Send this chat message to all other participants, which will receive FlockEvent.NEW_CHATMESSAGE |
boolean |
sendMessage(java.lang.String msg)
Send this message to all other participants, which will receive FlockEvent.NEW_MESSAGE with this user's id as sender-id and the String msg |
void |
setAnonymousSession(boolean anonymous)
Set the engine to start sessions with anonymous participants (default=false). |
void |
setLogLevel(int loglevel)
|
void |
setOnEventListener(FlockEngine.FlockEventCallback listener)
Register a callback to be invoked when a new event arrives from the engine/server. |
void |
setTestServer(boolean useTestServer)
If you want to use the test-servers, set this to true before authenticating, creating accounts or connecting. |
void |
unbind()
Remove this Activity's connection to the background service. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Details
Field Detail |
---|
LOG_ALL
public static final int LOG_ALL
- See Also:
- Constant Field Values
LOG_CRITICAL
public static final int LOG_CRITICAL
- See Also:
- Constant Field Values
LOG_NOTHING
public static final int LOG_NOTHING
- See Also:
- Constant Field Values
User
public UserManager User
- Class used by developers for authenticating the local user, creating
accounts, checking whether user is currently authenticated, etc.
- See Also:
UserManager
Constructor Detail |
---|
FlockEngine
public FlockEngine(Context context)
- Constructor of main class, which checks the settings (dev-id, etc.),
starts the service if it's not running and binds to Service
FlockEngine
public FlockEngine(Context context, FlockEngine.FlockEngineConnectedCallback callbackWhenBound)
- Constructor of main class including a callback which is started
when successfully bound to the service.
Method Detail |
---|
unbind
public void unbind()
- Remove this Activity's connection to the background service. Service keeps running as
long as at least one Activity is still bound.
Automatically done by FlockActivity at onDestroy!
prioritizeActivity
public boolean prioritizeActivity()
Priorize the current Activity's callback at the service. FlockEvents are always sent _only_ to 1 Activity; either the latest with onCreate(), or the latest with prioritize(). FlockActivity automatically prioritizes at onResume().
Helpful at onResume of first Activity, before that happens before the other Activity's onStop event.- Returns:
- true if service accepted prioritize, false if not bound to service (eg. at onCreate; but there it will be automatically prioritized on binding), or too high id
setOnEventListener
public void setOnEventListener(FlockEngine.FlockEventCallback listener)
- Register a callback to be invoked when a new event arrives from the engine/server.
- Parameters:
listener
- The callback to handle the events
isConnected
public boolean isConnected()
- Check whether the socket connection is active or not.
- Returns:
- true if connecting or connected, false if disconnected
isGameActive
public boolean isGameActive()
- Check whether the framework is in a game (session), and not just in the lobby.
- Returns:
- true if in a game, false if disconnected, connecting or in lobby
connect
public boolean connect(java.lang.String groups, int playersPerGame)
- Start connection with game-server (with test-server if
setTestServer(true)
).Possible responses via FlockEventListener:
CONNECTION_FAILED ........ Technical problem with connection
CONNECTION_ESTABLISHED ... Connection established; waiting for other participants
Before connecting, the user has to be authenticated, or
setAnonymousSession
has to be set to true.- Parameters:
groups
- One or more groups where players shall be matched (separated with comma (',')). Example groups = "beginners,experts". Trailing comma will be ignored.playersPerGame
- Number of required players for starting the game- Returns:
- true if connecting in background, false if [has already an active connection, user is not authenticated/not anonymous mode/anonymous mode + username not long enough
- See Also:
#setTestServer(boolean)}
,#setAnonymousSession(boolean)}
,UserManager#createAccount(String, String, String)}
,UserManager#createAccount(String, String, String)}
,UserManager#setUsername(String)} '
disconnect
public void disconnect()
- Immediately disconnect the socket connection if established.
Possible responses via FlockEventListener:
CONNECTION_CLOSED
requestUserAttributeString
public void requestUserAttributeString(java.lang.String key, java.lang.String defValue)
- String attribute to include automatically for all participants when the game starts.
You need to set it before calling Flock.connect(). Useful for string-attributes such
as achievements, preferences, etc.
It does not do anything instantly, but includes those attributes for all players
at SESSION_STARTS.
- Parameters:
key
- Id of attributedefValue
- Default value- See Also:
requestUserAttributeNumber(String, long)
, Examples
requestUserAttributeNumber
public void requestUserAttributeNumber(java.lang.String key, long defValue)
- Numeric attribute to include automatically for all participants when the game starts.
You need to set it before calling Flock.connect(). Useful for attributes such as points,
level, wins, losses, etc.
It does not do anything instantly, but includes those attributes for all players
at SESSION_STARTS.
- Parameters:
key
- Id of attributedefValue
- Default value- See Also:
requestUserAttributeString(String, String)
, Examples
getAllParticipants
public Participant[] getAllParticipants()
Array with all Participants of the current session, even those who have quit. The array-index matches the user-id's available in the Participants objects and as arguments when receiving an event. Only available after being bound to service and after receiving the GAME_STARTS event.
- Returns:
- Array with all participants; if not bound or not in a session, array with size 0.
- See Also:
Participant
getParticipant
public Participant getParticipant(int user_id)
- Get one Participant via it's user-id. Only available after being bound
to service and after receiving the GAME_STARTS event.
- Returns:
- before GAME_STARTS event: null, after GAME_STARTS event: either found Participant or null (eg if too high id)
- See Also:
Participant
getLocalParticipant
public Participant getLocalParticipant()
- Participant object of the local user.
- Returns:
- before GAME_STARTS event: null, after GAME_STARTS event: either found Participant or null
- See Also:
Participant
getLocalUserId
public int getLocalUserId()
- Get the id of the local user in the current session [0..n].
- Returns:
- user id [0..n], or -1 not in a game
setAnonymousSession
public void setAnonymousSession(boolean anonymous)
Set the engine to start sessions with anonymous participants (default=false). Must be set before connecting / authenticating.
Anonymous sessions have the following characteristics:
- All username/password combinations are be accepted by server
- No usernames can be registered
- No attributes can be saved or retrieved for the users
- Set local username with
Flock.User.setUsername(String)
For non-anonymous sessions, the user can create an account with an unique username, or sign in to an existing account. Developers can store up to 250 attributes per authenticated user.
- Parameters:
anonymous
- true if session shall be anonymous, false if not- See Also:
UserManager.setUsername(String)
,UserManager#setUsernameMinlength(int)
,UserManager.createAccount(String, String, String)
,UserManager.authenticate(String, String)
,createUserAttributeSyncer()
isAnonymousSession
public boolean isAnonymousSession()
- Check whether anonymous or authenticated session.
- Returns:
- true if anonymous session set, false if not anonymous session (default)
createUserAttributeSyncer
public UserAttributeSyncer createUserAttributeSyncer()
Create an AttributeSyncer to save up to 250 attributes for the local user to the global database.
Please use this object for adding as many objects as you want at once, instead of creating many small syncs! If two syncs follow too soon, we will get write-write collisions and overwrites in the database. Therefore always store as many attributes as you like at once, and leave at least 1 second between syncs.
- Returns:
- UserAttributeSyncer class
sendMessage
public boolean sendMessage(java.lang.String msg)
- Send this message to all other participants, which will receive FlockEvent.NEW_MESSAGE
with this user's id as sender-id and the String msg
- Parameters:
msg
- Message which will be received by all other participants- Returns:
- true if sent to others, false if not in a game
sendChatMessage
public boolean sendChatMessage(java.lang.String msg)
- Send this chat message to all other participants, which will receive FlockEvent.NEW_CHATMESSAGE
- Parameters:
msg
-- Returns:
- true if sent to others, false if not in a game
setTestServer
public void setTestServer(boolean useTestServer)
If you want to use the test-servers, set this to true before authenticating, creating accounts or connecting.
The test-server accepts all developer-id's and supports anonymous as well as authenticated sessions just as a dedicated gameserver.
The test-servers have the following limitations:
- Shared user database with all other developers using testservers
- Maximum of 10 simultaneous connected clients (can be adjusted on request)
Default: false
- Parameters:
useTestServer
-
createDBQueryBuilder
public DBQueryBuilder createDBQueryBuilder()
Create a new database query builder (eg for displaying highscore, etc.). If you are using the test-servers, be sure to use
Flock.setAnonymousSession(true)
before creating the query builder.The builder returns a HTTP GET URL which you can pass to the WebView, or you can request the results in JSON format.
Steps to build a query:
- Create builder with primary key
- Set options and add other keys
- call
.toQueryURI()
to get the URL of the query
- Parameters:
search_attribute_key
- primary key where the items will be sorted for- Returns:
DBQueryBuilder
- See Also:
DBQueryBuilder
setLogLevel
public void setLogLevel(int loglevel)