com.threerings.puzzle.client
Class PuzzleController

java.lang.Object
  com.samskivert.swing.Controller
      com.threerings.crowd.client.PlaceController
          com.threerings.parlor.game.client.GameController
              com.threerings.puzzle.client.PuzzleController

All Implemented Interfaces:

InvocationCodes, AttributeChangeListener, ChangeListener, PuzzleCodes, ActionListener, EventListener

public abstract class PuzzleController
extends GameController
implements PuzzleCodes

The puzzle game controller handles logical actions for a puzzle game.

Nested Class Summary

static interface	PuzzleController.ClearPender Used by fireWhenActionCleared(com.threerings.puzzle.client.PuzzleController.ClearPender).
protected class	PuzzleController.Updater A special frame participant that handles the sending of puzzle progress updates.

Nested classes/interfaces inherited from class com.threerings.crowd.client.PlaceController

PlaceController.DelegateOp

Nested classes/interfaces inherited from class com.samskivert.swing.Controller

Controller.ActionInvoker

Field Summary

protected int	_astate The current action state of the puzzle.
protected boolean	_chatting A flag indicating that we're in chatting mode.
protected ObserverList<PuzzleController.ClearPender>	_clearPenders The action cleared penders.
protected List<Integer>	_events The list of relevant game events since the last progress update.
protected KeyListener	_globalKeyListener A key listener that currently just toggles pause in the puzzle.
protected ElementUpdateListener	_kolist Listens for players being knocked out.
protected AttributeChangeListener	_mlist Listens for various attribute changes.
protected PuzzlePanel	_panel The puzzle panel.
protected Board	_pboard The puzzle board data.
protected PuzzleContext	_pctx A casted reference to the client context.
protected int	_pidx Our player index in the game.
protected PuzzleObject	_puzobj A reference to our puzzle game object.
protected PuzzleBoardView	_pview The puzzle board view.
protected List<Board>	_states Board snapshots that correspond to board state after each event has been applied.
protected com.threerings.puzzle.client.PuzzleController.Unpauser	_unpauser The mouse jockey for unpausing our puzzles.
protected PuzzleController.Updater	_updater Handles the sending of puzzle progress updates.
protected static int	ACTION_CLEARED A _astate constant.
protected static int	ACTION_GOING A _astate constant.
protected static int	CLEAR_PENDING A _astate constant.
protected static long	DEFAULT_PROGRESS_INTERVAL The delay in milliseconds between progress update intervals.
static String	TOGGLE_CHATTING The action command to toggle chatting mode.

Fields inherited from class com.threerings.parlor.game.client.GameController

_config, _ctx, _gameOver, _gobj

Fields inherited from class com.threerings.crowd.client.PlaceController

_delegates, _plobj, _view

Fields inherited from class com.samskivert.swing.Controller

DISPATCHER

Fields inherited from interface com.threerings.puzzle.data.PuzzleCodes

DEBUG_PUZZLE, DEFAULT_DIFFICULTY, PUZZLE_MESSAGE_BUNDLE

Fields inherited from interface com.threerings.presents.data.InvocationCodes

ACCESS_DENIED, E_ACCESS_DENIED, E_INTERNAL_ERROR, GLOBAL_GROUP, INTERNAL_ERROR

Constructor Summary

PuzzleController()

Method Summary

protected void	actionWasCleared() Called when the action was actually cleared, but before the action observers are notified.
protected void	actuallyClearAction() Performs the actual process of clearing the action for this puzzle.
void	addProgressEvent(int event, Board board) Adds the given progress event and a snapshot of the supplied board state to the set of progress events and associated board states for later transmission to the server.
void	attributeChanged(AttributeChangedEvent event)
protected void	boardActionCleared() This method is called by the PuzzleBoardView when all action on the board has finished.
protected boolean	canClearAction() Returns whether or not it is safe to clear the action.
protected boolean	canStartChatting() Can we start chatting at this juncture?
protected void	clearAction() Called when the game has ended or when it is going to reset and when the client leaves the game "room".
protected PuzzleController.Updater	createUpdater() Create the updater to be used in this puzzle.
protected void	didInit()
void	didLeavePlace(PlaceObject plobj) Removes our listener registration from the game object and cleans house.
protected void	fireWhenActionCleared(PuzzleController.ClearPender pender) Queues up code to be invoked when the action is completely cleared (including all remaining interesting sprites and animations on the puzzle board).
protected void	gameWillReset() Called to give derived classes a chance to display animations, send a final packet, or do any other business they care to do when the game is about to reset.
protected void	generateNewBoard() Signal the game to generate and distribute a new board.
Board	getBoard() Returns the board associated with the puzzle.
int	getEventCount() Returns the number of progress events currently queued up for sending to the server with the next progress update.
String	getPauseString() Get the (untranslated) string to display when the puzzle is paused.
int	getPlayerIndex() Returns the player's index in the list of players for the game.
protected long	getProgressInterval() Returns the delay in milliseconds between sending each progress update event to the server.
boolean	handleAction(ActionEvent action) Handles basic game controller action events.
boolean	hasAction() Returns true if the puzzle has action, false if the action is cleared or it is suspended.
protected boolean	isActionPuzzle() Puzzles that do not have "action" that starts and stops (via startAction() and clearAction()) when the puzzle starts and stops can override this method and return false.
boolean	isChatting() Returns true if the puzzle has been defocused because the player is doing some chatting.
protected boolean	isSyncingBoards() Are we syncing boards for this puzzle?
protected void	maybeClearAction() Called to effect the actual clearing of our action if we've received some asynchronous trigger that indicates that it may well be safe now to clear the action.
void	mayLeavePlace(PlaceObject plobj)
protected abstract Board	newBoard() Creates and returns a new board model.
protected void	playerKnockedOut(int pidx) Called when a player is knocked out of the game to give the puzzle a chance to perform any post-knockout actions that may be desired.
protected void	safeStartAction() If it is not known whether the puzzle board view has finished animating its final bits after a previous call to clearAction(), this method should be used instead of startAction() as it will wait until the action is confirmedly over before starting it anew.
void	sendProgressUpdate() Sends the server a game progress update with the list of events, as well as board states if PuzzlePanel.isSyncingBoards() is true.
void	setBoard(Board board) Called when a new board is set.
void	setChatting(boolean chatting) Sets whether we're focusing on the chat window rather than the puzzle.
void	setGameOver(boolean gameOver) Sets the client game over override.
protected void	startAction() Derived classes should override this method and do whatever is necessary to start up the action for their puzzle.
protected boolean	startActionImmediately() Indicates whether the action should start immediately as a result of GameController.gameDidStart() being called.
protected boolean	supportsActionPause() Derived classes should override this and return false if their action should not be paused when the user switches control to the chat area.
void	willEnterPlace(PlaceObject plobj) Adds this controller as a listener to the game object (thus derived classes need not do so) and lets the game manager know that we are now ready to go.

Methods inherited from class com.threerings.parlor.game.client.GameController

gameDidEnd, gameDidStart, gameWasCancelled, getMatchType, getSessionId, init, isGameOver, playerReady, resetGame, stateDidChange, systemMessage

Methods inherited from class com.threerings.crowd.client.PlaceController

addDelegate, applyToDelegates, createPlaceView, createPlaceView, getPlaceConfig, getPlaceView

Methods inherited from class com.samskivert.swing.Controller

actionPerformed, configureAction, createActionButton, generateArguments, handleAction, handleAction, handleAction, postAction, postAction, postAction, setControlledPanel, wasAdded, wasRemoved

Methods inherited from class java.lang.Object

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

Field Detail

TOGGLE_CHATTING

public static final String TOGGLE_CHATTING

The action command to toggle chatting mode.

See Also:

Constant Field Values

_unpauser

protected com.threerings.puzzle.client.PuzzleController.Unpauser _unpauser

The mouse jockey for unpausing our puzzles.

_updater

protected PuzzleController.Updater _updater

Handles the sending of puzzle progress updates.

_kolist

protected ElementUpdateListener _kolist

Listens for players being knocked out.

_mlist

protected AttributeChangeListener _mlist

Listens for various attribute changes.

_pctx

protected PuzzleContext _pctx

A casted reference to the client context.

_pidx

protected int _pidx

Our player index in the game.

_panel

protected PuzzlePanel _panel

The puzzle panel.

_puzobj

protected PuzzleObject _puzobj

A reference to our puzzle game object.

_pview

protected PuzzleBoardView _pview

The puzzle board view.

_pboard

protected Board _pboard

The puzzle board data.

_events

protected List<Integer> _events

The list of relevant game events since the last progress update.

_states

protected List<Board> _states

Board snapshots that correspond to board state after each event has been applied.

_chatting

protected boolean _chatting

A flag indicating that we're in chatting mode.

_astate

protected int _astate

The current action state of the puzzle.

_clearPenders

protected ObserverList<PuzzleController.ClearPender> _clearPenders

The action cleared penders.

_globalKeyListener

protected KeyListener _globalKeyListener

A key listener that currently just toggles pause in the puzzle.

DEFAULT_PROGRESS_INTERVAL

protected static final long DEFAULT_PROGRESS_INTERVAL

The delay in milliseconds between progress update intervals.

See Also:

Constant Field Values

ACTION_CLEARED

protected static final int ACTION_CLEARED

A _astate constant.

See Also:

Constant Field Values

CLEAR_PENDING

protected static final int CLEAR_PENDING

A _astate constant.

See Also:

Constant Field Values

ACTION_GOING

protected static final int ACTION_GOING

A _astate constant.

See Also:

Constant Field Values

Constructor Detail

PuzzleController

public PuzzleController()

Method Detail

didInit

protected void didInit()

Overrides:

didInit in class PlaceController

newBoard

protected abstract Board newBoard()

Creates and returns a new board model.

getBoard

public Board getBoard()

Returns the board associated with the puzzle.

getPlayerIndex

public int getPlayerIndex()

Returns the player's index in the list of players for the game.

setGameOver

public void setGameOver(boolean gameOver)

Description copied from class: GameController

Sets the client game over override. This is used in situations where we determine that the game is over before the server has informed us of such.

Overrides:

setGameOver in class GameController

hasAction

public boolean hasAction()

Returns true if the puzzle has action, false if the action is cleared or it is suspended.

setChatting

public void setChatting(boolean chatting)

Sets whether we're focusing on the chat window rather than the puzzle.

getPauseString

public String getPauseString()

Get the (untranslated) string to display when the puzzle is paused.

supportsActionPause

protected boolean supportsActionPause()

Derived classes should override this and return false if their action should not be paused when the user switches control to the chat area.

canStartChatting

protected boolean canStartChatting()

Can we start chatting at this juncture?

isChatting

public boolean isChatting()

Returns true if the puzzle has been defocused because the player is doing some chatting.

willEnterPlace

public void willEnterPlace(PlaceObject plobj)

Description copied from class: GameController

Adds this controller as a listener to the game object (thus derived classes need not do so) and lets the game manager know that we are now ready to go.

Overrides:

willEnterPlace in class GameController

mayLeavePlace

public void mayLeavePlace(PlaceObject plobj)

Overrides:

mayLeavePlace in class PlaceController

didLeavePlace

public void didLeavePlace(PlaceObject plobj)

Description copied from class: GameController

Removes our listener registration from the game object and cleans house.

Overrides:

didLeavePlace in class GameController

isActionPuzzle

protected boolean isActionPuzzle()

Puzzles that do not have "action" that starts and stops (via startAction() and clearAction()) when the puzzle starts and stops can override this method and return false.

startActionImmediately

protected boolean startActionImmediately()

Indicates whether the action should start immediately as a result of GameController.gameDidStart() being called. If a puzzle wishes to do some beginning of the game fun stuff, like display a tutorial screen, they can veto the action start and then start it themselves later.

attributeChanged

public void attributeChanged(AttributeChangedEvent event)

Specified by:

attributeChanged in interface AttributeChangeListener

Overrides:

attributeChanged in class GameController

gameWillReset

protected void gameWillReset()

Description copied from class: GameController

Called to give derived classes a chance to display animations, send a final packet, or do any other business they care to do when the game is about to reset.

Overrides:

gameWillReset in class GameController

setBoard

public void setBoard(Board board)

Called when a new board is set.

startAction

protected void startAction()

Derived classes should override this method and do whatever is necessary to start up the action for their puzzle. This could be called when the user is already in the "room" and the game starts, or immediately upon entering the room if the game is already started (for example if they disconnected and reconnected to a game already in progress).

safeStartAction

protected void safeStartAction()

If it is not known whether the puzzle board view has finished animating its final bits after a previous call to clearAction(), this method should be used instead of startAction() as it will wait until the action is confirmedly over before starting it anew.

clearAction

protected void clearAction()

Called when the game has ended or when it is going to reset and when the client leaves the game "room". This method does not always immediately clear the action, but may mark the clear as pending if the action cannot yet be cleared (as indicated by canClearAction()). The action will eventually be cleared which will result in a call to actuallyClearAction() which is what derived classes should override to do their action clearing business.

boardActionCleared

protected void boardActionCleared()

This method is called by the PuzzleBoardView when all action on the board has finished.

fireWhenActionCleared

protected void fireWhenActionCleared(PuzzleController.ClearPender pender)

Queues up code to be invoked when the action is completely cleared (including all remaining interesting sprites and animations on the puzzle board).

canClearAction

protected boolean canClearAction()

Returns whether or not it is safe to clear the action. The default behavior is to not allow the action to be cleared until all interesting sprites and animations in the board view have finished. If derived classes or delegates wish to postpone the clearing of the action, they can return false from this method, but they must then be sure to call maybeClearAction() when whatever condition that caused them to desire to postpone action clearing has finally been satisfied.

maybeClearAction

protected void maybeClearAction()

Called to effect the actual clearing of our action if we've received some asynchronous trigger that indicates that it may well be safe now to clear the action.

actuallyClearAction

protected void actuallyClearAction()

Performs the actual process of clearing the action for this puzzle. This is only called after it is known to be safe to clear the action. Derived classes can override this method and clear out anything that is not needed while the puzzle's "action" is not going (timers, etc.). Anything that is cleared out here should be recreated in startAction().

actionWasCleared

protected void actionWasCleared()

Called when the action was actually cleared, but before the action observers are notified.

handleAction

public boolean handleAction(ActionEvent action)

Description copied from class: GameController

Handles basic game controller action events. Derived classes should be sure to call super.handleAction for events they don't specifically handle.

Overrides:

handleAction in class GameController

getProgressInterval

protected long getProgressInterval()

Returns the delay in milliseconds between sending each progress update event to the server. Derived classes may wish to override this to send their progress updates more or less frequently than the default.

generateNewBoard

protected void generateNewBoard()

Signal the game to generate and distribute a new board.

getEventCount

public int getEventCount()

Returns the number of progress events currently queued up for sending to the server with the next progress update.

isSyncingBoards

protected boolean isSyncingBoards()

Are we syncing boards for this puzzle? By default, we defer to the PuzzlePanel and its runtime config.

addProgressEvent

public void addProgressEvent(int event,
                             Board board)

Adds the given progress event and a snapshot of the supplied board state to the set of progress events and associated board states for later transmission to the server.

sendProgressUpdate

public void sendProgressUpdate()

Sends the server a game progress update with the list of events, as well as board states if PuzzlePanel.isSyncingBoards() is true.

playerKnockedOut

protected void playerKnockedOut(int pidx)

Called when a player is knocked out of the game to give the puzzle a chance to perform any post-knockout actions that may be desired. Derived classes may wish to override this method but should be sure to call super.playerKnockedOut().

createUpdater

protected PuzzleController.Updater createUpdater()

Create the updater to be used in this puzzle.