com.google.appinventor.components.runtime

Class GameClient

java.lang.Object

com.google.appinventor.components.runtime.AndroidNonvisibleComponent

com.google.appinventor.components.runtime.GameClient

All Implemented Interfaces:

Component, OnResumeListener, OnStopListener

public class GameClient
extends AndroidNonvisibleComponent
implements Component, OnResumeListener, OnStopListener

GameClient provides a way for AppInventor applications to communicate with online game servers. This allows users to create games that are coordinated and managed in the cloud. Most communication is done by sending keyed messages back and forth between the client and the server in the form of YailLists. The server and game client can then switch on the keys and perform more complex operations on the data. In addition, game servers can implement a library of server commands that can perform complex functions on the server and send back responses that are converted into YailLists and sent back to the component. For more information about server commands, consult the game server code at http://code.google.com/p/app-inventor-for-android/ Games instances are uniquely determined by a game id and an instance id. In general, each App Inventor program should have its own game id. Then, when running different instances of that program, new instance ides should be used. Players are represented uniquely by the email address registered to their phones. All call functions perform POSTs to a web server. Upon successful completion of these POST requests, FunctionCompleted will be triggered with the function name as an argument. If the post fails, WebServiceError will trigger with the function name and the error message as arguments. These calls allow for application creators to deal with web service failures and keep track of the success or failure of their operations. The only exception to this is when the return value from the server has the incorrect game id or instance id. In this case, the response is completely ignored and neither of these events will trigger.

Field Summary

Fields inherited from class com.google.appinventor.components.runtime.AndroidNonvisibleComponent

form

Fields inherited from interface com.google.appinventor.components.runtime.Component

ACCELEROMETER_SENSITIVITY_MODERATE, ACCELEROMETER_SENSITIVITY_STRONG, ACCELEROMETER_SENSITIVITY_WEAK, ALIGNMENT_CENTER, ALIGNMENT_NORMAL, ALIGNMENT_OPPOSITE, ASSET_DIRECTORY, BUTTON_SHAPE_DEFAULT, BUTTON_SHAPE_OVAL, BUTTON_SHAPE_RECT, BUTTON_SHAPE_ROUNDED, COLOR_BLACK, COLOR_BLUE, COLOR_CYAN, COLOR_DEFAULT, COLOR_DKGRAY, COLOR_GRAY, COLOR_GREEN, COLOR_LTGRAY, COLOR_MAGENTA, COLOR_NONE, COLOR_ORANGE, COLOR_PINK, COLOR_RED, COLOR_WHITE, COLOR_YELLOW, DEFAULT_VALUE_COLOR_BLACK, DEFAULT_VALUE_COLOR_BLUE, DEFAULT_VALUE_COLOR_CYAN, DEFAULT_VALUE_COLOR_DEFAULT, DEFAULT_VALUE_COLOR_DKGRAY, DEFAULT_VALUE_COLOR_GRAY, DEFAULT_VALUE_COLOR_GREEN, DEFAULT_VALUE_COLOR_LTGRAY, DEFAULT_VALUE_COLOR_MAGENTA, DEFAULT_VALUE_COLOR_NONE, DEFAULT_VALUE_COLOR_ORANGE, DEFAULT_VALUE_COLOR_PINK, DEFAULT_VALUE_COLOR_RED, DEFAULT_VALUE_COLOR_WHITE, DEFAULT_VALUE_COLOR_YELLOW, DIRECTION_EAST, DIRECTION_MAX, DIRECTION_MIN, DIRECTION_NONE, DIRECTION_NORTH, DIRECTION_NORTHEAST, DIRECTION_NORTHWEST, DIRECTION_SOUTH, DIRECTION_SOUTHEAST, DIRECTION_SOUTHWEST, DIRECTION_WEST, FONT_DEFAULT_SIZE, LAYOUT_ORIENTATION_HORIZONTAL, LAYOUT_ORIENTATION_VERTICAL, LENGTH_FILL_PARENT, LENGTH_PREFERRED, LENGTH_UNKNOWN, SLIDER_MAX_VALUE, SLIDER_MIN_VALUE, SLIDER_THUMB_VALUE, TOAST_LENGTH_LONG, TOAST_LENGTH_SHORT, TYPEFACE_DEFAULT, TYPEFACE_MONOSPACE, TYPEFACE_SANSSERIF, TYPEFACE_SERIF

Constructor Summary

Constructors

Constructor and Description
GameClient(ComponentContainer container) Creates a new GameClient component.

Method Summary

Methods

Modifier and Type	Method and Description
void	FunctionCompleted(java.lang.String functionName) Indicates that a server request from a function call has completed.
java.lang.String	GameId() Returns a string indicating the game name for this application.
void	GameId(java.lang.String id) Specifies a string indicating the family of the current game instance.
void	GetInstanceLists() Updates the current InstancesJoined and InstancesInvited lists.
void	GetMessages(java.lang.String type, int count) Retrieves messages of the specified type.
void	GotMessage(java.lang.String type, java.lang.String sender, java.util.List<java.lang.Object> contents) Indicates that a GetMessages call received a message.
void	Info(java.lang.String message) Indicates that something has occurred which the player should be somehow informed of.
void	Initialize() Ensures that the GameId was set by the game creator.
java.lang.String	InstanceId() Returns the game instance id.
void	InstanceIdChanged(java.lang.String instanceId) Indicates that InstanceId has changed due to the creation of a new instance or setting the InstanceId.
void	Invite(java.lang.String playerEmail) Invites a player to this game instance.
void	Invited(java.lang.String instanceId) Indicates a user has been invited to this game instance by another player.
java.util.List<java.lang.String>	InvitedInstances() Returns the set of game instances to which this player has been invited but has not yet joined.
java.util.List<java.lang.String>	JoinedInstances() Returns the set of game instances in which this player is participating.
java.lang.String	Leader() Returns the game's leader.
void	LeaveInstance() Requests to leave the current instance.
void	MakeNewInstance(java.lang.String instanceId, boolean makePublic) Creates a new game instance.
void	NewInstanceMade(java.lang.String instanceId) Indicates this game instance was created as specified via MakeNewInstance.
void	NewLeader(java.lang.String playerId) Indicates this game instance has a new leader.
void	onResume() Called automatically by the operating system.
void	onStop() Called automatically by the operating system.
void	PlayerJoined(java.lang.String playerId) Indicates that a player has joined this game instance.
void	PlayerLeft(java.lang.String playerId) Indicates that a player has left this game instance.
java.util.List<java.lang.String>	Players() Returns the current set of players for this game instance.
java.util.List<java.lang.String>	PublicInstances() Returns the set of game instances that have been marked public.
void	SendMessage(java.lang.String type, YailList recipients, YailList contents) Creates a new message and sends it to the stated recipients.
void	ServerCommand(java.lang.String command, YailList arguments) Submits a command to the game server.
void	ServerCommandFailure(java.lang.String command, YailList arguments) Indicates that an attempt to complete a server command failed on the server.
void	ServerCommandSuccess(java.lang.String command, java.util.List<java.lang.Object> response) Indicates that a ServerCommand completed.
java.lang.String	ServiceUrl() The URL of the game server.
void	ServiceURL(java.lang.String url) Set the URL of the game server.
void	SetInstance(java.lang.String instanceId) Specifies the game instance id.
void	SetLeader(java.lang.String playerEmail) Specifies the game's leader.
java.lang.String	UserEmailAddress() Returns the registered email address that is being used as the player id for this game client.
void	UserEmailAddress(java.lang.String emailAddress) Changes the player of this game by changing the email address used to communicate with the server.
void	UserEmailAddressSet(java.lang.String emailAddress) Indicates that the user email address property has been successfully set.
void	WebServiceError(java.lang.String functionName, java.lang.String message) Indicates that the attempt to communicate with the web service resulted in an error.

Methods inherited from class com.google.appinventor.components.runtime.AndroidNonvisibleComponent

getDispatchDelegate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.google.appinventor.components.runtime.Component

getDispatchDelegate

Constructor Detail

GameClient

public GameClient(ComponentContainer container)

Creates a new GameClient component.

Parameters:

container - the Form that this component is contained in.

Method Detail

GameId

public java.lang.String GameId()

Returns a string indicating the game name for this application. The same game ID can have one or more game instances.

GameId

public void GameId(java.lang.String id)

Specifies a string indicating the family of the current game instance. The same game ID can have one or more game instance IDs.

InstanceId

public java.lang.String InstanceId()

Returns the game instance id. Taken together, the game ID and the instance ID uniquely identify the game.

InvitedInstances

public java.util.List<java.lang.String> InvitedInstances()

Returns the set of game instances to which this player has been invited but has not yet joined. To ensure current values are returned, first invoke GetInstanceLists().

JoinedInstances

public java.util.List<java.lang.String> JoinedInstances()

Returns the set of game instances in which this player is participating. To ensure current values are returned, first invoke GetInstanceLists().

Leader

public java.lang.String Leader()

Returns the game's leader. At any time, each game instance has only one leader, but the leader may change with time. Initially, the leader is the game instance creator. Application writers determine special properties of the leader. The leader value is updated each time a successful communication is made with the server.

Players

public java.util.List<java.lang.String> Players()

Returns the current set of players for this game instance. Each player is designated by an email address, which is a string. The list of players is updated each time a successful communication is made with the game server.

PublicInstances

public java.util.List<java.lang.String> PublicInstances()

Returns the set of game instances that have been marked public. To ensure current values are returned, first invoke GetInstanceLists().

ServiceUrl

public java.lang.String ServiceUrl()

The URL of the game server.

ServiceURL

public void ServiceURL(java.lang.String url)

Set the URL of the game server.

Parameters:

url - The URL (include initial http://).

UserEmailAddress

public java.lang.String UserEmailAddress()

Returns the registered email address that is being used as the player id for this game client.

UserEmailAddress

public void UserEmailAddress(java.lang.String emailAddress)

Changes the player of this game by changing the email address used to communicate with the server. This should only be used during development. Games should not allow players to set their own email address.

Parameters:

emailAddress - The email address to set the current player id to.

FunctionCompleted

public void FunctionCompleted(java.lang.String functionName)

Indicates that a server request from a function call has completed. This can be used to control a polling loop or otherwise respond to server request completions.

Parameters:

functionName - The name of the App Inventor function that finished.

Initialize

public void Initialize()

Ensures that the GameId was set by the game creator.

GotMessage

public void GotMessage(java.lang.String type,
              java.lang.String sender,
              java.util.List<java.lang.Object> contents)

Indicates that a GetMessages call received a message. This could be invoked multiple times for a single call to GetMessages.

Parameters:

type - The type of the message received.

contents - The message's contents. Consists of a list nested to arbitrary depth that includes string, boolean and number values.

InstanceIdChanged

public void InstanceIdChanged(java.lang.String instanceId)

Indicates that InstanceId has changed due to the creation of a new instance or setting the InstanceId.

Parameters:

instanceId - The id of the instance the player is now in.

Invited

public void Invited(java.lang.String instanceId)

Indicates a user has been invited to this game instance by another player.

Parameters:

instanceId - The id of the new game instance.

NewLeader

public void NewLeader(java.lang.String playerId)

Indicates this game instance has a new leader. This could happen in response to a call to SetLeader or by the side effects of a server command performed by any player in the game. Since the current leader is sent back with every server response, NewLeader can trigger after making any server call.

Parameters:

playerId - The email address of the new leader.

NewInstanceMade

public void NewInstanceMade(java.lang.String instanceId)

Indicates this game instance was created as specified via MakeNewInstance. The creating player is automatically the leader of the instance and the InstanceId property has already been set to this new instance.

Parameters:

instanceId - The id of the newly created game instance.

PlayerJoined

public void PlayerJoined(java.lang.String playerId)

Indicates that a player has joined this game instance.

Parameters:

playerId - The email address of the new player.

PlayerLeft

public void PlayerLeft(java.lang.String playerId)

Indicates that a player has left this game instance.

Parameters:

playerId - The email address of the player that left.

ServerCommandFailure

public void ServerCommandFailure(java.lang.String command,
                        YailList arguments)

Indicates that an attempt to complete a server command failed on the server.

Parameters:

command - The command requested.

arguments - The arguments sent to the command.

ServerCommandSuccess

public void ServerCommandSuccess(java.lang.String command,
                        java.util.List<java.lang.Object> response)

Indicates that a ServerCommand completed.

Parameters:

command - The key for the command that resulted in this response.

response - The server response. This consists of a list nested to arbitrary depth that includes string, boolean and number values.

UserEmailAddressSet

public void UserEmailAddressSet(java.lang.String emailAddress)

Indicates that the user email address property has been successfully set. This event should be used to initialize any web service functions. This separate event was required because the email address was unable to be first fetched from the the UI thread without causing programs to hang. GameClient will now start fetching the user email address in its constructor and trigger this event when it finishes.

Info

public void Info(java.lang.String message)

Indicates that something has occurred which the player should be somehow informed of.

Parameters:

message - the message.

WebServiceError

public void WebServiceError(java.lang.String functionName,
                   java.lang.String message)

Indicates that the attempt to communicate with the web service resulted in an error.

Parameters:

functionName - The name of the function call that caused this error.

message - the error message

GetInstanceLists

public void GetInstanceLists()

Updates the current InstancesJoined and InstancesInvited lists. If the player has been invited to new instances an Invited event will be raised for each new instance.

GetMessages

public void GetMessages(java.lang.String type,
               int count)

Retrieves messages of the specified type. Requests that only messages which have not been seen during the current session are returned. Messages will be processed in chronological order with the oldest first, however, only the count newest messages will be retrieved. This means that one could "miss out" on some messages if they request less than the number of messages created since the last request for that message type. Setting type to the empty string will fetch all message types. Even though those message types were not specifically requested, their most recent message time will be updated. This keeps players from receiving the same message again if they later request the specific message type. Note that the message receive times are not updated until after the messages are actually received. Thus, if multiple message requests are made before the previous ones return, they could send stale time values and thus receive the same messages more than once. To avoid this, application creators should wait for the get messages function to return before calling it again.

Parameters:

type - The type of message to retrieve. If the empty string is used as the message type then all message types will be requested.

count - The maximum number of messages to retrieve. This should be an integer from 1 to 1000.

Invite

public void Invite(java.lang.String playerEmail)

Invites a player to this game instance. Players implicitly accept invitations when they join games by setting the instance id in their GameClient. Invitations remain active as long as the game instance exists.

Parameters:

playerEmail - a string containing the email address of the player to become leader. The email should be in one of the following formats:
"Name O. Person <name.o.person@gmail.com>"
"name.o.person@gmail.com".

LeaveInstance

public void LeaveInstance()

Requests to leave the current instance. If the player is the current leader, the lead will be passed to another player. If there are no other players left in the instance after the current player leaves, the instance will become unjoinable. Upon successful completion of this command, the instance lists will be updated and InstanceId will be set back to the empty string. Note that while this call does clear the leader and player lists, no NewLeader or PlayerLeft events are raised.

MakeNewInstance

public void MakeNewInstance(java.lang.String instanceId,
                   boolean makePublic)

Creates a new game instance. The instance has a unique instanceId, and the leader is the player who created it. The player that creates the game automatically joins it without being sent an invitation. The actual instance id could differ from the instanceId specified because the game server will enforce uniqueness. The actual instanceId will be provided to AppInventor when a NewInstanceMade event triggers upon successful completion of this server request.

Parameters:

instanceId - A string to use as for the instance id. If no other instance exists with this id, the new instance will have this id. However, since the id must be unique, if another instance exists with the same one, then a number will be appended to the end of this prefix.

makePublic - A boolean indicating whether or not the instance should be publicly viewable and able to be joined by anyone.

SendMessage

public void SendMessage(java.lang.String type,
               YailList recipients,
               YailList contents)

Creates a new message and sends it to the stated recipients.

Parameters:

type - A "key" for the message. This identifies the type of message so that when other players receive the message they know how to properly handle it.

recipients - If set to an empty list, the server will send this message with a blank set of recipients, meaning that all players in the instance are able to retrieve it. To limit the message receipt to a single person or a group of people, recipients should be a list of the email addresses of the people meant to receive the message. Each email should be in one of the following formats:
"Name O. Person <name.o.person@gmail.com>"
"name.o.person@gmail.com"

contents - the contents of the message. This can be any AppInventor data value.

ServerCommand

public void ServerCommand(java.lang.String command,
                 YailList arguments)

Submits a command to the game server. Server commands are custom actions that are performed on the server. The arguments required and return value of a server command depend on its implementation. For more information about server commands, consult the game server code at: http://code.google.com/p/app-inventor-for-android/

Parameters:

command - The name of the server command.

arguments - The arguments to pass to the server to specify how to execute the command.

SetInstance

public void SetInstance(java.lang.String instanceId)

Specifies the game instance id. Taken together, the game ID and the instance ID uniquely identify the game.

Parameters:

instanceId - the name of the game instance to join.

SetLeader

public void SetLeader(java.lang.String playerEmail)

Specifies the game's leader. At any time, each game instance has only one leader, but the leader may change over time. Initially, the leader is the game instance creator. Application inventors determine special properties of the leader. The leader can only be set by the current leader of the game.

Parameters:

playerEmail - a string containing the email address of the player to become leader. The email should be in one of the following formats:
"Name O. Person <name.o.person@gmail.com>"
"name.o.person@gmail.com".

onResume

public void onResume()

Called automatically by the operating system. Currently does nothing.

Specified by:

onResume in interface OnResumeListener

onStop

public void onStop()

Called automatically by the operating system. Currently does nothing.

Specified by:

onStop in interface OnStopListener