soc.client
Interface PlayerClientListener

All Known Implementing Classes:

SOCPlayerInterface.ClientBridge

public interface PlayerClientListener

A listener on the SOCPlayerClient to decouple the presentation from the networking. This presents the facade of the UI to the networking layer. The game data (SOCGame, SOCPlayer methods) will be updated before these methods are called, so you can call game-object methods for more details on the new event.

The classic presentation implementing this interface is SOCPlayerInterface.ClientBridge.

Since:

2.0.00

Author:

paulbilnoski

Nested Class Summary

static class

PlayerClientListener.UpdateType Player data update types for playerElementUpdated(SOCPlayer, UpdateType).

Method Summary

void	boardLayoutUpdated()
void	boardPotentialsUpdated()
void	boardReset(SOCGame newGame, int newSeatNumber, int requestingPlayerNumber)
void	boardResetVoteCast(SOCPlayer voter, boolean vote)
void	boardResetVoteRejected()
void	boardResetVoteRequested(SOCPlayer requestor)
void	boardUpdated()
void	buildRequestCanceled(SOCPlayer player)
void	debugFreePlaceModeToggled(boolean isEnabled)
void	devCardDeckUpdated()
void	diceRolled(SOCPlayer player, int resultSum) Receive a notification that the current player has rolled the dice.
void	diceRolledResources(java.util.List<java.lang.Integer> pnum, java.util.List<SOCResourceSet> rsrc) Receive a notification that the dice roll resulted in players gaining resources.
void	gameDisconnected(java.lang.String errorMessage)
void	gameEnded(java.util.Map<SOCPlayer,java.lang.Integer> scores)
void	gameStarted() Game play is starting (leaving state SOCGame.NEW).
void	gameStateChanged(int gameState) Update interface after game state has changed.
void	invItemPlayRejected(int type, int reasonCode) Client player's request to play a special SOCInventoryItem was rejected by the server.
void	largestArmyRefresh(SOCPlayer old, SOCPlayer potentialNew) The largest army might have changed, so update
void	longestRoadRefresh(SOCPlayer old, SOCPlayer potentialNew) The longest road might have changed, so update
void	membersListed(java.util.Collection<java.lang.String> names) The current game members (players and observers) are listed, and the game is about to start.
void	messageBroadcast(java.lang.String message)
void	messageSent(java.lang.String nickname, java.lang.String message) A game text message was received from server, or a chat message from another player.
void	pieceValueUpdated(SOCPlayingPiece piece) A playing piece's value was updated: _SC_CLVI village cloth count, or _SC_PIRI pirate fortress strength.
void	playerCanCancelInvItemPlay(SOCPlayer player, boolean canCancel) A player is playing or placing a special SOCInventoryItem, such as a gift trade port in scenario _SC_FTRI.
void	playerDevCardUpdated(SOCPlayer player, boolean addedPlayable) A player is drawing or playing a development card, or a card or special SOCInventoryItem has been added or removed from their hand's inventory.
void	playerElementUpdated(SOCPlayer player, PlayerClientListener.UpdateType utype) Update one part of the player's status, such as their number of settlements remaining.
void	playerFaceChanged(SOCPlayer player, int faceId) A player has changed their face icon.
void	playerJoined(java.lang.String nickname) A client (us or someone else) has joined the game.
void	playerLeft(java.lang.String nickname, SOCPlayer player) A client player or observer is leaving the game.
void	playerPickSpecialItem(java.lang.String typeKey, SOCGame ga, SOCPlayer pl, int gi, int pi, boolean isPick, int coord, int level, java.lang.String sv) Show the results of a player's PICK of a known Special Item, or the server's DECLINE of the client player's pick request.
void	playerPieceMoved(SOCPlayer player, int sourceCoordinate, int targetCoordinate, int pieceType) A player has moved a piece on the board.
void	playerPiecePlaced(SOCPlayer player, int coordinate, int pieceType) A player has placed a piece on the board.
void	playerPieceRemoved(SOCPlayer player, int pieceCoordinate, int pieceType) A player's piece has been removed from the board.
void	playerResourcesUpdated(SOCPlayer player) A player's total resource count has been updated.
void	playerSetSpecialItem(java.lang.String typeKey, SOCGame ga, SOCPlayer pl, int gi, int pi, boolean isSet) Show the results of a player's SET or CLEAR of a known Special Item.
void	playerSitdown(int playerNumber, java.lang.String nickname) A client has sat down to become an active player.
void	playerStats(java.util.EnumMap<PlayerClientListener.UpdateType,java.lang.Integer> stats) A player's game stats, such as resource totals received from dice rolls, should be displayed.
void	playerSVPAwarded(SOCPlayer player, int numSvp, java.lang.String awardDescription) A player has been awarded Special Victory Point(s).
void	playerTurnSet(int playerNumber) Game's current player has changed.
void	requestedChoosePlayer(java.util.List<SOCPlayer> choices, boolean isNoneAllowed) This player must choose a player for robbery.
void	requestedChooseRobResourceType(SOCPlayer player)
void	requestedDiceRoll()
void	requestedDiscard(int countToDiscard) The game requests that the client player discard a particular number of resource cards.
void	requestedGoldResourceCountUpdated(SOCPlayer player, int countToSelect) This player must pick this many gold-hex resources, or no longer needs to pick them.
void	requestedResourceSelect(int countToSelect) The client player gets some free resources of their choice.
void	requestedSpecialBuild(SOCPlayer player)
void	requestedTrade(SOCPlayer offerer)
void	requestedTradeClear(SOCPlayer offerer)
void	requestedTradeRejection(SOCPlayer rejecter)
void	requestedTradeReset(SOCPlayer playerToReset)
void	robberMoved()
void	scen_SC_PIRI_pirateFortressAttackResult(boolean wasRejected, int defStrength, int resultShipsLost) In scenario _SC_PIRI, present the server's response to a Pirate Fortress Attack request from the current player (the client or another player), which may be: Rejected, Lost, Tied, or Won.
void	seatLockUpdated()
void	simpleAction(int pn, int acttype, int value1, int value2) A "simple action" has occurred in the game and should be displayed.
void	simpleRequest(int pn, int reqtype, int value1, int value2) A player's "simple request" has been sent to the entire game, or the server has replied to our own simple request, and this should be displayed.

Method Detail

diceRolled

void diceRolled(SOCPlayer player,
                int resultSum)

Receive a notification that the current player has rolled the dice. Call this after updating game state with the roll result. After a call to diceRolled, diceRolledResources(List, List) is often called next.

Parameters:

player - May be null if the current player was null when the dice roll was received from the server.

resultSum - The sum of the dice rolled. May be -1 for some game events.

diceRolledResources

void diceRolledResources(java.util.List<java.lang.Integer> pnum,
                         java.util.List<SOCResourceSet> rsrc)

Receive a notification that the dice roll resulted in players gaining resources. Call this after updating player resources with the gains. Often follows a call to diceRolled(SOCPlayer, int).

Parameters:

pnum - Player numbers, same format as SOCDiceResultResources.playerNum

rsrc - Resources gained by each pn, same format as SOCDiceResultResources.playerRsrc

playerJoined

void playerJoined(java.lang.String nickname)

A client (us or someone else) has joined the game. They will be an observer until playerSitdown(int, String) is called, then they will be an active player.

Parameters:

nickname - New client's player/observer name

playerLeft

void playerLeft(java.lang.String nickname,
                SOCPlayer player)

A client player or observer is leaving the game.

Parameters:

nickname - The player name. Will not be null

player - May be null if the current player is an observer.

playerSitdown

void playerSitdown(int playerNumber,
                   java.lang.String nickname)

A client has sat down to become an active player. playerJoined(String) was called earlier on this client. SOCGame.addPlayer(String, int) has just been called.

Parameters:

playerNumber - New player's playerNumber in the game; the seat number they've sat down at

nickname - New player's name

playerTurnSet

void playerTurnSet(int playerNumber)

Game's current player has changed. Update displays.

Parameters:

playerNumber - New current player number whose turn it is.

playerPiecePlaced

void playerPiecePlaced(SOCPlayer player,
                       int coordinate,
                       int pieceType)

A player has placed a piece on the board.

Parameters:

pieceType - A piece type identifier, such as SOCPlayingPiece.CITY

playerPieceMoved

void playerPieceMoved(SOCPlayer player,
                      int sourceCoordinate,
                      int targetCoordinate,
                      int pieceType)

A player has moved a piece on the board. Most pieces are not movable. SOCShip pieces can sometimes be moved. Not used when the robber or pirate is moved; see robberMoved().

Parameters:

pieceType - A piece type identifier, such as SOCPlayingPiece.CITY

playerPieceRemoved

void playerPieceRemoved(SOCPlayer player,
                        int pieceCoordinate,
                        int pieceType)

A player's piece has been removed from the board. Updates game state and refreshes the game board display. Currently, only ships can be removed, in game scenario _SC_PIRI.

Parameters:

player - Player who owns the ship

pieceCoordinate - Ship's node coordinate

pieceType - The piece type identifier SOCPlayingPiece.SHIP

playerSVPAwarded

void playerSVPAwarded(SOCPlayer player,
                      int numSvp,
                      java.lang.String awardDescription)

A player has been awarded Special Victory Point(s).

Parameters:

player - The player awarded special victory points. Will not be null

numSvp - The count of how many new special victory points were awarded

awardDescription - A user-display message describing the reason for the award

playerDevCardUpdated

void playerDevCardUpdated(SOCPlayer player,
                          boolean addedPlayable)

A player is drawing or playing a development card, or a card or special SOCInventoryItem has been added or removed from their hand's inventory.

If this inventory update comes from playing a special SOCInventoryItem, call playerCanCancelInvItemPlay(SOCPlayer, boolean) after calling this method.

Parameters:

player - The player

addedPlayable - True if the update added a dev card or item that's playable now

playerCanCancelInvItemPlay

void playerCanCancelInvItemPlay(SOCPlayer player,
                                boolean canCancel)

A player is playing or placing a special SOCInventoryItem, such as a gift trade port in scenario _SC_FTRI. Set a flag that indicates if this play or placement can be canceled (returned to player's inventory).

It makes sense to call this for only the client player, since we don't cancel other players' item plays.

Parameters:

player - The player

canCancel - True if SOCInventoryItem.canCancelPlay

playerFaceChanged

void playerFaceChanged(SOCPlayer player,
                       int faceId)

A player has changed their face icon.

Parameters:

player - The player

faceId - New face icon number; 1 and higher are human face images, 0 is the default robot, -1 is the smarter robot.

playerElementUpdated

void playerElementUpdated(SOCPlayer player,
                          PlayerClientListener.UpdateType utype)

Update one part of the player's status, such as their number of settlements remaining.

Parameters:

player - May be null

utype - The type of element to update

playerResourcesUpdated

void playerResourcesUpdated(SOCPlayer player)

A player's total resource count has been updated.

Parameters:

player - The player

playerStats

void playerStats(java.util.EnumMap<PlayerClientListener.UpdateType,java.lang.Integer> stats)

A player's game stats, such as resource totals received from dice rolls, should be displayed. Called at end of game, or when the player uses the *STATS* command.

Parameters:

stats - Player statistic details

requestedDiscard

void requestedDiscard(int countToDiscard)

The game requests that the client player discard a particular number of resource cards.

Parameters:

countToDiscard - Must choose and discard this many cards

requestedResourceSelect

void requestedResourceSelect(int countToSelect)

The client player gets some free resources of their choice. Used with "Year of Plenty"/"Discovery" cards, and the Gold Hex.

Parameters:

countToSelect - Must choose this many resources

See Also:

requestedGoldResourceCountUpdated(SOCPlayer, int)

requestedGoldResourceCountUpdated

void requestedGoldResourceCountUpdated(SOCPlayer player,
                                       int countToSelect)

This player must pick this many gold-hex resources, or no longer needs to pick them. Informational only: do not ask the client player to pick resources, requestedResourceSelect(int) is used for that.

Parameters:

player - The player

countToSelect - Number of free resources they must pick, or 0 if they've just picked them

requestedChoosePlayer

void requestedChoosePlayer(java.util.List<SOCPlayer> choices,
                           boolean isNoneAllowed)

This player must choose a player for robbery.

Parameters:

choices - The potential victim players to choose from

isNoneAllowed - If true, player can choose to rob no one (game scenario SC_PIRI)

See Also:

SOCPlayerClient.GameManager.choosePlayer(SOCGame, int)

requestedChooseRobResourceType

void requestedChooseRobResourceType(SOCPlayer player)

requestedTrade

void requestedTrade(SOCPlayer offerer)

requestedTradeClear

void requestedTradeClear(SOCPlayer offerer)

Parameters:

offerer - May be null

requestedTradeRejection

void requestedTradeRejection(SOCPlayer rejecter)

requestedTradeReset

void requestedTradeReset(SOCPlayer playerToReset)

Parameters:

playerToReset - May be null to clear all seats

requestedSpecialBuild

void requestedSpecialBuild(SOCPlayer player)

requestedDiceRoll

void requestedDiceRoll()

largestArmyRefresh

void largestArmyRefresh(SOCPlayer old,
                        SOCPlayer potentialNew)

The largest army might have changed, so update

longestRoadRefresh

void longestRoadRefresh(SOCPlayer old,
                        SOCPlayer potentialNew)

The longest road might have changed, so update

membersListed

void membersListed(java.util.Collection<java.lang.String> names)

The current game members (players and observers) are listed, and the game is about to start.

Parameters:

names - Game member names; to see if each is a player, call SOCGame.getPlayer(String).

boardLayoutUpdated

void boardLayoutUpdated()

boardUpdated

void boardUpdated()

pieceValueUpdated

void pieceValueUpdated(SOCPlayingPiece piece)

A playing piece's value was updated: _SC_CLVI village cloth count, or _SC_PIRI pirate fortress strength. Repaint that piece (if needed) on the board.

Parameters:

piece - Piece that was updated, includes its new value

boardPotentialsUpdated

void boardPotentialsUpdated()

boardReset

void boardReset(SOCGame newGame,
                int newSeatNumber,
                int requestingPlayerNumber)

boardResetVoteRequested

void boardResetVoteRequested(SOCPlayer requestor)

boardResetVoteCast

void boardResetVoteCast(SOCPlayer voter,
                        boolean vote)

boardResetVoteRejected

void boardResetVoteRejected()

robberMoved

void robberMoved()

devCardDeckUpdated

void devCardDeckUpdated()

seatLockUpdated

void seatLockUpdated()

gameStarted

void gameStarted()

Game play is starting (leaving state SOCGame.NEW). Next move is for players to make their starting placements.

Call SOCGame.setGameState(int) before calling this method. Call this method before calling gameStateChanged(int).

gameStateChanged

void gameStateChanged(int gameState)

Update interface after game state has changed. Please call SOCGame.setGameState(int) first.

If the game is now starting, please call in this order:

   game.setGameState(newState);
   gameStarted();
   gameStateChanged(int);

Parameters:

gameState - One of the codes from SOCGame, such as SOCGame.NEW

gameEnded

void gameEnded(java.util.Map<SOCPlayer,java.lang.Integer> scores)

gameDisconnected

void gameDisconnected(java.lang.String errorMessage)

messageBroadcast

void messageBroadcast(java.lang.String message)

messageSent

void messageSent(java.lang.String nickname,
                 java.lang.String message)

A game text message was received from server, or a chat message from another player.

Parameters:

nickname - Player's nickname, or null for messages from the server itself

message - Message text

simpleRequest

void simpleRequest(int pn,
                   int reqtype,
                   int value1,
                   int value2)

A player's "simple request" has been sent to the entire game, or the server has replied to our own simple request, and this should be displayed. This method lets us display simple things from the server without defining a lot of small similar methods.

If other game data messages are sent (resource gains/loss, etc), or other client code must update that data based on info in the SOCSimpleRequest, this method will be called only after other game data is updated. Some SimpleRequest reqtypes update the game data: Client must call SOCDisplaylessPlayerClient.handleSIMPLEREQUEST(Map, soc.message.SOCSimpleRequest) to update game before calling this method.

Parameters:

pn - The player number requesting or acting, or -1 if our own request was declined

reqtype - The request type, from SOCSimpleRequest constants for simplicity

value1 - First optional detail value, or 0

value2 - Second optional detail value, or 0

See Also:

simpleAction(int, int, int, int)

simpleAction

void simpleAction(int pn,
                  int acttype,
                  int value1,
                  int value2)

A "simple action" has occurred in the game and should be displayed. This method lets us show simple things from the server without defining a lot of small similar methods.

This will be called only after other game data is updated (number of dev cards, resource gains/loss, etc).

Parameters:

pn - The player number acting or acted on

acttype - The action type, from SOCSimpleAction constants for simplicity

value1 - First optional detail value, or 0

value2 - Second optional detail value, or 0

See Also:

simpleRequest(int, int, int, int)

buildRequestCanceled

void buildRequestCanceled(SOCPlayer player)

invItemPlayRejected

void invItemPlayRejected(int type,
                         int reasonCode)

Client player's request to play a special SOCInventoryItem was rejected by the server.

Parameters:

type - Item type from SOCInventoryItem.itype

reasonCode - Optional reason code for the SOCInventoryItemAction.CANNOT_PLAY action, corresponding to SOCGame.canPlayInventoryItem(int, int) return codes, or 0

playerPickSpecialItem

void playerPickSpecialItem(java.lang.String typeKey,
                           SOCGame ga,
                           SOCPlayer pl,
                           int gi,
                           int pi,
                           boolean isPick,
                           int coord,
                           int level,
                           java.lang.String sv)

Show the results of a player's PICK of a known Special Item, or the server's DECLINE of the client player's pick request.

To see which scenario and option typeKeys pick Special Items, and scenario-specific usage details, see the SOCSpecialItem class javadoc.

coord and level are sent for convenience, and sometimes may not be from the Special Item you need; see SOCSetSpecialItem.OP_PICK for details.

Parameters:

typeKey - Item's typeKey, as described in the SOCSpecialItem class javadoc

ga - Game containing pl and special items

pl - Player who picked: Never null when isPick, is null if server declined our player's request

gi - Picked this index within game's Special Item list, or -1

pi - Picked this index within pl's Special Item list, or -1

isPick - True if calling for PICK, false if server has DECLINEd the client player's request

coord - Optional coordinates on the board for this item, or -1. An edge or a node, depending on item type

level - Optional level of construction or strength, or 0

sv - Optional string value from SOCSpecialItem.getStringValue(), or null

See Also:

playerSetSpecialItem(String, SOCGame, SOCPlayer, int, int, boolean), SOCSpecialItem.playerPickItem(String, SOCGame, SOCPlayer, int, int)

playerSetSpecialItem

void playerSetSpecialItem(java.lang.String typeKey,
                          SOCGame ga,
                          SOCPlayer pl,
                          int gi,
                          int pi,
                          boolean isSet)

Show the results of a player's SET or CLEAR of a known Special Item.

To see which scenario and option typeKeys set or clear Special Items, and scenario-specific usage details, see the SOCSpecialItem class javadoc.

Parameters:

typeKey - Item's typeKey, as described in the SOCSpecialItem class javadoc

ga - Game containing pl and special items

pl - Requesting player; never null

gi - Set or clear this index within game's Special Item list, or -1

pi - Set or clear this index within pl's Special Item list, or -1

isSet - True if player has set, false if player has cleared, this item index

See Also:

playerPickSpecialItem(String, SOCGame, SOCPlayer, int, int, boolean, int, int, String), SOCSpecialItem.playerSetItem(String, SOCGame, SOCPlayer, int, int, boolean)

scen_SC_PIRI_pirateFortressAttackResult

void scen_SC_PIRI_pirateFortressAttackResult(boolean wasRejected,
                                             int defStrength,
                                             int resultShipsLost)

In scenario _SC_PIRI, present the server's response to a Pirate Fortress Attack request from the current player (the client or another player), which may be: Rejected, Lost, Tied, or Won.

This will be called only after other game pieces are updated (fortress strength, player's ships lost).

Parameters:

wasRejected - True if the server rejected our player's request to attack

defStrength - Pirate defense strength, unless wasRejected

resultShipsLost - Result and number of ships lost by the player: 0 if player won (or if rejected); 1 if tied; 2 if player lost to the pirates.

debugFreePlaceModeToggled

void debugFreePlaceModeToggled(boolean isEnabled)