Game Service Provider Interface |
Think-and-Link |
Contents
System Overview
Service Provider Guidelines
The Game SPI provides a mechanism for providers of gaming services
to register with the system. When the system requires services for
a particular type of game, it searches the registry for a provider
that supports that game type. The system then requests the given
service of the found service provider. Service providers do not
need to worry about the mechanics of how a game request is made,
but are free to concentrate on handling the request.
In particular, the TAL software handles:
- Receiving moves from a remote player.
- Sending validated moves to a remote player.
- Capturing move actions from the local player.
- Short-term and long-term game state persistence.
- Determining which game view (if any) to show.
The vendor-supplied software must handle:
- Game State initialization.
- Validating moves received from a remote player.
- Validating move actions from the local player.
- Manufacturing suitable game views.
For a vendor implementation to be used, the service classname
must appear in the feature list at startup. The corresponding GameService object must
register itself with the GameManager as a service provider in its constructor.
As with all features, there must be only one constructor.
for the service to ever be requested, there must be a player in
the players list that uses that service. This allows the players
to specify which type of game to play, but the feature list to
independently specify which vendors will be used, and also to
provide any initialization parameters to the vendor's classes.
The following guidelines apply to all third-party game
service providers.
Each vendor package must contain the following implementation classes:
- Service Class (talx.games.GameService) - Provides
information about the supported game type and a factory
for game instances of that type. The supported game type
should be either a reference to a known standard or a
vendor specific reference because two service classes that
support identical game types are expected to provide identical
interpretations of the state objects. For example, if
the class edu.uoregon.talgames.AccessibleCheckers
claims to support game types of "checkers" and
com.gamesRus.CheckerKing claims to support game
types of "checkers", then a game state generated by an
AccessibleCheckers game instance must be understandable by
a CheckerKing game instance.
Unless either organization knows that it is working with
an accepted, published standard, they should adopt game types
of "edu.uoregon.checkers" and "com.gamesRus.checkers",
respectively.
- Game Class (talx.games.Game) - Provides factory methods
for game views and game handler
objects. Game instances are produced by the system from
the service class's handler method as needed.
- Game View Class (talx.games.GameView) - Provides visual
representation of game state object interpreted for this
type of game. The game view must respond to controller
change events by placing itself in or removing itself from
the desktop when the GUI state indicates that this game's
player is or is not the current player. The game view must
also respond to game events by updating its visual state
as appropriate. The system produces game views from the
game class's view factory method as needed.
- Game Handler Class (talx.games.GameHandler) - Provides
basic game play. The game handler is responsible for
producing game states suitable for the start of a game,
deciding whether a move is legal, and deciding when
restarting the game is appropriate. The system obtains
game handlers from the game's handler factory as needed.
Game handlers are expected to be stateless singleton objects.
Note: The model.GameState class is a general purpose class that
must be used as is by the vendor classes. Each game type can use
the get and put methods to insert and read any type of information
needed by the game, but the GameState class itself should not be
extended by vendors.
Information about the state of the instatiated vendor classes can
be divided into two categories: initialization parameters that
control the factory methods and volatile game state that describes
the current state of play in a particular game.
Initialization parameters are passed to the service class at
creation time. The service class is free to pass any necessary
initialization parameters to the Game objects. Similarly, the
Game objects can pass any required parameters to the game view
objects. However, the game handler objects are expected to be
stateless. Therefore, any information about rule sets, for
example, should be realized in the form of differing handler
instances returned from the handler factory methods.
Typical initialization parameters would be to specify accessibilty
features of the view, such as whether drag and drop should be
supported, alert systems, confirmation dialogs, etc. It is not
appropriate for the view to cache the volatile game state.
At its whim, the system may replace the view with another,
so state cannot be kept in the visual controls.
Volatile game state is kept solely in the game state objects and
passed to the game handlers and game views as appropriate.
Volatile game state includes such data as which player is
allowed to move next, the location of pieces on the board, etc.
The game state object must include all data used by the game
view class to render the visual description of the view, and by
the game handler class to validate player actions.
Volatile game context is stored in the GUI state object owned
by the controller. This is normally limited to the current game
and the start game button captions. The current game is managed
by the system and should not be altered by the game handlers.
However, when a game view sees that it is the current game, it
should make sure that it is showing on the desktop. Conversely,
when a game view detects that it is not the current game, it must
remove itself from the desktop.
The GUI state object also holds the start game button caption
list. The captions for each game are managed by the corresponding
game handlers and changed in response to game state changes. While
the game handler can manage these in a vendor specific way, the
general expectation is that the captions would reflect which
player is expected to make the next move. The captions are
available from the GUI state object using the key stored in the
talx.model.GUIStateConstants.INBOX_PLAYER_CAPTIONS constant.
This will return a StringValueMap. Each caption is stored in
that map using the GameManager's UniqueID for the player.
To the system, a game has begun when there is a request for a
game state ID that is unknown to the system.
Games can be started either in response to a StartGame
control being activated on the local machine, or a game message
being received from a remote machine. In either case, the system
finds the appropriate game service and activates the game factory.
If the game was started on the local machine, the game's handler
factory is used to provide a game state suitable for a new game,
and the game's view factory is used to provide a game view. The
associated player is added to the GUI state as the current player.
This requires the newly created view to add itself to the desktop.
Whether the game state is newly initialized or generated remotely,
the system automatically caches it in response to the game handler
firing the appropriate model change to the game listeners.
As remote move messages arrive, the game's handler factory is used
to access the handler's handleRemoteAction method. The handler is
expected to validate the move against the current game state, update
the state and fire the game's remote model change event. The game
handler may also choose to update the caption associated with the
game's start game button in the GUI state.
As the user generates game control actions on the local machine,
the games handler factory is used to access the handler's
handleLocalAction method. The handler is expected to obtain the
current game state from the game control's game and validate the
move against the state, update the state and fire the game's local
model change event. The game handler may also choose to update the
caption associated with the game's start game button in the GUI
state.
When a game handler detects the end of a game, it is expected to
leave the game in a state that the user will recognize as finished.
This can involve setting information in the game state object that
the game view will use to indicate a win or loss status, changing
the start game button caption to reflect the win or loss status, or
simply leaving the game visuals in the final state, which the player
will recognize as a finished game. However, under no circumstances
should the game handler process the game ending event by disposing
the game state and beginning a new game.
Once the handler has processed the end of game move, it should
put enough information into the game state object that will enable
it to respond to a GameStart activation (handleStartGame)
by starting a new game
During play, the user may activate a start game control for the
game. Usually, this just indicates that the user wants this game
to become the current game. The system will update the GUI state
to make this the current game. The activation is then passed
along to the game handler's handleStartGame() method. The handler
can either detect that a game is in progress, and completely ignore
the call, detect that a game is not in progress and start a new game,
or ask for confirmation that the user wants to end the current game
and begin another. The last course of action is not recommended.
Game vendors are highly encouraged to detect whether or not a game
is in progress and react accordingly.
© 2001-2005 University of Oregon.
Eugene OR 97403, U.S.A. All Rights Reserved.