soc.game
Class SOCPlayer

java.lang.Object
  soc.game.SOCPlayer

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, SOCDevCardConstants

public class SOCPlayer
extends java.lang.Object
implements SOCDevCardConstants, java.io.Serializable, java.lang.Cloneable

A class for holding and manipulating player data. The player exists within one SOCGame, not persistent between games like SOCPlayerClient or SOCClientData.

At the start of each player's turn, SOCGame.updateAtTurn() will call updateAtTurn(), then call the current player's updateAtOurTurn().

The player's hand holds resource cards, unplayed building pieces, and an inventory of development cards and sometimes scenario-specific items.

For more information about the "legal" and "potential" road/settlement/city terms, see page 61 of Robert S Thomas' dissertation. Briefly: "Legal" locations are where pieces can be placed, according to the game rules. "Potential" locations are where pieces can be placed soon, based on the current state of the game board. For example, every legal settlement location is also a potential settlement during initial placement (game state START1A through START3A. Once the player's final initial settlement is placed, all potential settlement locations are cleared. Only when they build 2 connected road segments, will another potential settlement location be set.

If the board layout changes from game to game, as with SOCBoardLarge / SOCBoard.BOARD_ENCODING_LARGE, use these methods to update the player's board data after SOCBoard.makeNewBoard(Map), in this order:

• getPlayerNumber().setLandHexCoordinates(int[])
• setPotentialAndLegalSettlements(Collection, boolean, HashSet[])
• Optionally, setRestrictedLegalShips(int[])

On the large sea board, our list of the player's roads also contains their ships. They are otherwise treated separately.

Author:

Robert S Thomas

See Also:

Serialized Form

Nested Class Summary

static class

SOCPlayer.SpecialVPInfo Holds details of getSpecialVP().

Field Summary

private int	addedLegalSettlement The most recently added node from addLegalSettlement(int, boolean), or 0.
private boolean	askedSpecialBuild In 6-player mode, is the player asking to build during the Special Building Phase?
private boolean	boardResetAskedThisTurn this is true if the player asked to reset the board this turn
private int	buildingVP the number of victory points for settlements and cities
private boolean	builtInRobotFlag Is this robot connection the built-in robot (not a 3rd-party), with the original AI?
private java.util.Vector<SOCCity>	cities a list of this player's cities in play
private SOCTradeOffer	currentOffer this is the current trade offer that this player is making, or null if none
private int	faceId which face image this player is using
private int	finalTotalVP the final total score (pushed from server at end of game), or 0 if no score has been forced.
private SOCFortress	fortress For scenario option _SC_PIRI, the "pirate fortress" that this player must defeat to win.
private SOCGame	game the game that this player is in
private boolean	hasSpecialBuiltThisTurn In 6-player mode, has the player already built during the Special Building Phase?
private SOCInventory	inventory The development cards this player holds, along with occasional scenario-specific items.
private SOCVillage	isTradeRouteFarEndClosed_foundVillage Set by isTradeRouteFarEndClosed(SOCShip, int, HashSet, List) if it finds a village at any far end.
(package private) SOCResourceSet	lastActionBankTrade_get For use at server by SOCGame, if the player's previous action this turn was a bank trade, the resources involved.
(package private) SOCResourceSet	lastActionBankTrade_give For use at server by SOCGame, if the player's previous action this turn was a bank trade, the resources involved.
protected int	lastRoadCoord The edge coordinate of our most recent road or ship.
protected int	lastSettlementCoord The node coordinate of our most recent settlement.
private java.util.HashSet<java.lang.Integer>	legalRoads a list of edges where it is legal to place a road.
private java.util.HashSet<java.lang.Integer>	legalSettlements a set of nodes where it is legal to place a settlement.
private java.util.HashSet<java.lang.Integer>	legalShips a list of edges where it is legal to place a ship.
private java.util.HashSet<java.lang.Integer>	legalShipsRestricted A list of edges if the legal sea edges for ships are restricted by the game's scenario (_SC_PIRI), or null if all sea edges are legal for ships.
private int	longestRoadLength length of the longest road for this player
private java.util.Vector<SOCLRPathData>	lrPaths list of longest road / longest trade-route paths
private java.lang.String	name the name of the player
private boolean	needToDiscard this flag is true if the player needs to discard and must pick which resources to lose.
private int	needToPickGoldHexResources If nonzero, waiting for player to pick this many gold-hex resources, after a dice roll or placing their final initial settlement.
private int	numCloth For some game scenarios, how many cloth does this player have? Every 2 pieces of cloth is worth 1 VP.
private int	numKnights how many knights this player has in play
private int[]	numPieces the number of pieces not in play.
private int	numWarships For scenario option _SC_PIRI, the number of SOCShips that are converted to warships.
private SOCPlayerNumbers	ourNumbers the numbers that our settlements are touching
private java.util.Vector<SOCPlayingPiece>	pieces a list of this player's pieces in play (does not include any fortress).
private boolean	playedDevCard this is true if the player played a development card this turn
private int	playerNumber The integer id for this player (0 to n-1).
private boolean[]	ports a boolean array stating wheather this player is touching a particular kind of port.
private java.util.HashSet<java.lang.Integer>	potentialCities a set of nodes where a city could be placed on the next turn.
private java.util.HashSet<java.lang.Integer>	potentialRoads a set of edges where a road could be placed on the next turn.
private java.util.HashSet<java.lang.Integer>	potentialSettlements a set of nodes where a settlement could be placed on the next turn.
private java.util.HashSet<java.lang.Integer>	potentialShips a set of edges where a ship could be placed on the next turn.
private SOCResourceSet	resources how many of each resource this player has
private int[]	resourceStats server-only total count of how many of each known resource the player has received this game from dice rolls.
private java.util.Hashtable<java.lang.Integer,int[]>	roadNodeGraph A graph of what adjacent nodes are connected by this player's roads and ships.
private java.util.Vector<java.lang.Integer>	roadNodes all of the nodes that this player's roads and ships touch; this is used to calculate longest road / longest trade route.
private java.util.Vector<SOCRoad>	roads a list of this player's roads and ships in play.
private boolean	robotFlag this is true if this player is a robot
private SOCResourceSet	rolledResources Resources gained from dice roll of the current turn.
private int	scenario_playerEvents_bitmask Track one-time player events for scenarios on the large sea board.
private int	scenario_svpFromEachLandArea_bitmask For some scenarios on the large sea board, bitmask: true if the player has been given a Special Victory Point for placing a settlement in a given new land area.
private java.util.Vector<SOCSettlement>	settlements a list of this player's settlements in play
static int	SHIP_COUNT Number of ships a player can build (15) if SOCGame.hasSeaBoard.
private int	specialVP The number of Special Victory Points (SVPs), which are awarded in certain game scenarios on the large sea board.
private java.util.HashMap<java.lang.String,java.util.ArrayList<SOCSpecialItem>>	spItems Player's SOCSpecialItems, if any, by type.
private int	startingLandArea1 The land area(s) of the player's initial settlements, if SOCGame.hasSeaBoard and the board defines Land Areas (null != SOCBoardLarge.getLandAreasLegalNodes()).
private int	startingLandArea2 The land area(s) of the player's initial settlements, if SOCGame.hasSeaBoard and the board defines Land Areas (null != SOCBoardLarge.getLandAreasLegalNodes()).
private java.util.ArrayList<SOCPlayer.SpecialVPInfo>	svpInfo The details behind the total SVP count in specialVP, or null if none.

Fields inherited from interface soc.game.SOCDevCardConstants

CAP, DESTROY, DISC, KNIGHT, KNIGHT_FOR_VERS_1_X, LIB, MAXPLUSONE, MIN, MIN_KNOWN, MONO, ROADS, SWAP, TEMP, TOW, UNIV, UNKNOWN, UNKNOWN_FOR_VERS_1_X, VERSION_FOR_NEW_TYPES

Constructor Summary

SOCPlayer(int pn, SOCGame ga)
Create a new player for a new empty board.

SOCPlayer(SOCPlayer player)
create a copy of the player

Method Summary

void	addLegalSettlement(int node, boolean checkAdjacents) Add this node to the player's legal settlement coordinates, for future possible placement.
void	addRolledResources(SOCResourceSet rolled) Add to this player's resources and resource-roll totals.
void	addSpecialVPInfo(int svp, java.lang.String desc) Add details on Special Victory Points (SVP) just awarded.
int	calcLongestRoad2() Calculates the longest road / longest trade route for this player
boolean	canBuildInitialPieceType(int pieceType) Can this player build this piece type now, based on their pieces so far? Initial placement order is Settlement, Road/Ship, Settlement, Road/Ship.
boolean	canMoveShip(SOCShip sh) Can we move this ship, based on our trade routes and settlements/cities near its current location?
boolean	canPlaceSettlement(int node) Can a settlement be placed at this node? Calls isPotentialSettlement(int).
private java.util.Vector<SOCShip>	checkTradeRouteFarEndClosed(SOCShip newShipEdge, int edgeFarNode) Follow a trade route (a line of SOCShips) away from a newly closed end, to determine if the other end is closed or still open, and close this route if necessary.
void	clearPotentialCity(int node) Set this node to not be a potential city.
void	clearPotentialRoad(int edge) Set this edge to not be a potential road.
void	clearPotentialSettlement(int node) Set this node to not be a potential settlement.
void	clearPotentialSettlements() At start of normal game play, set all nodes to not be potential settlements.
void	clearPotentialShip(int edge) Set this edge to not be a potential ship.
private void	clearScenarioPlayerEvent(SOCScenarioPlayerEvent spe) Clear a certain scenario player event flag.
void	destroyPlayer() set vars to null so gc can clean up
private boolean	doesTradeRouteContinuePastEdge(int edge, boolean wantShip) For road/ship building, does this edge have a piece of ours adjacent to it (settlement, city, or same road/ship type as wantShip)?
private boolean	doesTradeRouteContinuePastNode(SOCBoard board, boolean wantShip, int rsEdge, int ignoreEdge, int node) Does this trade route (ships only, or roads only) continue past an unoccupied node?
void	forceFinalVP(int score) If game is over, server can push the final score for each player to the client.
int	getAddedLegalSettlement() Get the legal-settlement location, if any, added by addLegalSettlement(int, boolean).
java.util.Vector<SOCCity>	getCities()
int	getCloth() For some game scenarios, get how many cloth this player currently has.
SOCTradeOffer	getCurrentOffer()
int	getFaceId() get the face image id.
SOCFortress	getFortress() For scenario option _SC_PIRI, the "pirate fortress" that this player must defeat to win.
SOCGame	getGame()
SOCInventory	getInventory() Get the player's inventory of SOCDevCards and other occasional items.
int	getLastRoadCoord() Get the location of this player's most recent road or ship.
int	getLastSettlementCoord() Get the location of this player's most recent settlement.
int	getLongestRoadLength() Get the length of this player's longest road or trade route, as calculated by the most recent call to calcLongestRoad2().
java.util.Vector<SOCLRPathData>	getLRPaths() Get our longest road paths.
SOCShip	getMostRecentShip() Get this player's most recently placed ship, if any.
java.lang.String	getName()
boolean	getNeedToDiscard()
int	getNeedToPickGoldHexResources() Get the number of gold-hex resources this player must now pick, after a dice roll or placing their 2nd initial settlement.
SOCPlayerNumbers	getNumbers()
int	getNumKnights()
int	getNumPieces(int ptype) Get the number of one piece type not in play and available to place.
int	getNumWarships() For scenario option _SC_PIRI, the number of SOCShips that have been converted to warships to defend against the pirate fleet and attack the SOCFortress.
java.util.Vector<SOCPlayingPiece>	getPieces() Get this player's pieces on the board.
int	getPlayerNumber() Get the player's seat number in the game.
boolean	getPortFlag(int portType)
boolean[]	getPortFlags()
java.util.List<java.lang.Integer>	getPortMovePotentialLocations(boolean all) For scenario option _SC_FTRI, calculate if the player has any coastal settlement or city where they can place a moved "gift" port without it being adjacent to another port, and the edges where it could be placed next to such settlements or cities.
int[]	getPotentialSettlements_arr() Get this player's current potential settlement nodes.
java.util.HashSet<java.lang.Integer>	getPotentialSettlements() Get this player's current potential settlement nodes.
int	getPublicVP() This player's number of publicly known victory points.
int[]	getResourceRollStats() On server, get the current totals of resources received by dice rolls by this player.
SOCResourceSet	getResources() Get the resources currently held in the player's hand.
java.util.HashSet<java.lang.Integer>	getRestrictedLegalShips() A list of edges where the player can build ships, if the legal sea edges for ships are restricted by the game's scenario (_SC_PIRI), or null if all sea edges are legal for ships.
java.util.Vector<java.lang.Integer>	getRoadNodes()
SOCRoad	getRoadOrShip(int edge) Get this player's road or ship on an edge.
java.util.Vector<SOCRoad>	getRoads() Get this player's roads and ships on the board.
SOCResourceSet	getRolledResources() Resources gained from dice roll of the current turn.
int	getScenarioPlayerEvents() Gets one-time player events for scenarios on the large sea board.
int	getScenarioSVPLandAreas() For scenarios on the large sea board, get this player's bitmask of land areas for tracking Special Victory Points (SVP).
java.util.Vector<SOCSettlement>	getSettlements()
SOCSpecialItem	getSpecialItem(java.lang.String typeKey, int idx) Get a special item of a given type, by index within the list of all items of that type held by the player.
java.util.ArrayList<SOCSpecialItem>	getSpecialItems(java.lang.String typeKey) Get a list of all special items of a given type held by the player.
int	getSpecialVP() Get the number of Special Victory Points (SVPs) awarded to this player.
java.util.ArrayList<SOCPlayer.SpecialVPInfo>	getSpecialVPInfo() Get the details, if known, behind this player's getSpecialVP() total.
int	getStartingLandAreasEncoded() For scenarios on the large sea board, get this player's starting settlement land areas, encoded to send over the network from server to client.
int	getTotalVP()
boolean	hasAskedBoardReset()
boolean	hasAskedSpecialBuild() In 6-player mode's Special Building Phase, this player has asked to build.
boolean	hasLargestArmy()
boolean	hasLongestRoad()
boolean	hasPlayedDevCard()
boolean	hasPotentialCity()
boolean	hasPotentialRoad()
boolean	hasPotentialSettlement()
boolean	hasPotentialShip() Does this player have a potential edge to place a ship on, in a game using the large sea board?
boolean	hasScenarioPlayerEvent(SOCScenarioPlayerEvent spe) Does this player have a certain scenario player event flag? Flag bits are set as per-player events occur during a game.
boolean	hasSpecialBuilt() In 6-player mode's Special Building Phase, this player has already built this turn.
boolean	hasUnplayedDevCards()
void	incrementNumKnights() increment the number of knights in play
boolean	isBuiltInRobot() Is this robot player the built-in robot (not a 3rd-party), with the original AI? False if unknown.
boolean	isConnectedByRoad(int node1, int node2) Are these two adjacent nodes connected by this player's road/ship?
boolean	isLegalRoad(int edge)
boolean	isLegalSettlement(int node) Is this node to a legal settlement?
boolean	isLegalShip(int edge) Is this edge a legal ship placement?
boolean	isPotentialCity(int node) Is this node a potential city? True if we currently have a settlement there.
boolean	isPotentialRoad(int edge) Is this edge a potential road? True if the location is legal, currently not occupied, and we have an adjacent road, settlement, or city.
boolean	isPotentialSettlement(int node) Is this node a potential settlement? True if the location is legal, currently not occupied, no settlement is currently on an adjacent node, and we have an adjacent road or ship.
boolean	isPotentialShip(int edge) Is this edge a potential ship? True if the location is legal, currently not occupied, we have an adjacent ship, settlement, or city, and SOCGame.hasSeaBoard, Does not check getNumPieces(SHIP).
boolean	isPotentialShipMoveTo(int toEdge, int fromEdge) Is this edge coordinate a potential place to move a ship, even if another ship edge was not? Used by SOCGame.canMoveShip(int, int, int) to check the ship's requested new location.
boolean	isRobot() Is this player a robot AI (built-in or 3rd-party)?
private java.util.Vector<SOCShip>	isTradeRouteFarEndClosed(SOCShip edgeFirstShip, int edgeFarNode, java.util.HashSet<java.lang.Integer> alreadyVisited, java.util.List<java.util.Vector<java.lang.Object>> encounteredSelf) Recursive call for checkTradeRouteFarEndClosed(SOCShip, int).
java.lang.StringBuffer	numpieces(java.lang.StringBuffer sb) for debug prints; appends to sb or creates it, returns it
private void	putPiece_roadOrShip_checkNewShipTradeRouteAndSpecialEdges(SOCShip newShip, SOCBoardLarge board, boolean isTempPiece) Check this new ship for adjacent settlements/cities/villages, to see if its trade route will be closed.
private void	putPiece_roadOrShip(SOCRoad piece, SOCBoard board, boolean isTempPiece) For putPiece, update road/ship-related info, roadNodes, roadNodeGraph and lastRoadCoord.
private void	putPiece_settlement_checkScenarioSVPs(SOCSettlement newSettle, int newSettleArea, boolean isTempPiece) Does the player get a Special Victory Point (SVP) for reaching a new land area? Call when a settlement has been placed in a land area different from startingLandArea1 and startingLandArea2.
private void	putPiece_settlement_checkTradeRoutes(SOCSettlement newSettle, SOCBoard board) Check this new settlement for adjacent open ships, to see their its trade route will be closed.
void	putPiece(SOCPlayingPiece piece, boolean isTempPiece) Put a piece into play.
void	removePiece(SOCPlayingPiece piece, SOCPlayingPiece replacementPiece) remove a player's piece from the board, and put it back in the player's hand.
private void	removePieceUpdateSpecialVP(SOCPlayingPiece p) As part of removePiece(SOCPlayingPiece, null), update player's specialVP and related fields.
void	setAskedBoardReset(boolean value) set the flag indicating if the player asked to reset the board this turn
void	setAskedSpecialBuild(boolean set) In 6-player mode's Special Building Phase, set or clear the flag for this player asking to build.
void	setCloth(int numCloth) Set how many cloth this player currently has.
void	setCurrentOffer(SOCTradeOffer of) set the current offer for this player
void	setFaceId(int id) set the face image id
void	setLongestRoadLength(int len) set the longest road / longest trade route length
void	setLRPaths(java.util.Vector<SOCLRPathData> vec) set the longest paths vector
void	setName(java.lang.String na) set the name of the player
void	setNeedToDiscard(boolean value) set the "need to discard" flag
void	setNeedToPickGoldHexResources(int numRes) Set the number of gold-hex resources this player must now pick, after a dice roll or placing their 2nd initial settlement.
void	setNumKnights(int nk) set the number of knights in play
void	setNumPieces(int ptype, int amt) set the amount of pieces not in play for a particular type of piece
void	setNumWarships(int count) For scenario option _SC_PIRI, set the player's number of warships.
void	setPlayedDevCard(boolean value) set the playedDevCard flag
void	setPortFlag(int portType, boolean value) set a port flag
void	setPotentialAndLegalSettlements(java.util.Collection<java.lang.Integer> psList, boolean setLegalsToo, java.util.HashSet<java.lang.Integer>[] legalLandAreaNodes) Set which nodes are potential settlements.
void	setRestrictedLegalShips(int[] edgeList) Set the list of edges where the player can build ships, when the legal sea edges for ships are restricted by the game's scenario (_SC_PIRI).
void	setRobotFlag(boolean isRobot, boolean isBuiltIn) set the robot flags.
private void	setScenarioPlayerEvent(SOCScenarioPlayerEvent spe) Set a certain scenario player event flag.
void	setScenarioPlayerEvents(int events) At client, set the player's getScenarioPlayerEvents() based on a server message.
void	setScenarioSVPLandAreas(int las) At client, set the player's getScenarioPlayerEvents() based on a server message.
void	setSpecialBuilt(boolean set) In 6-player mode's Special Building Phase, set or clear the flag for this player already built this turn.
SOCSpecialItem	setSpecialItem(java.lang.String typeKey, int idx, SOCSpecialItem itm) Add or replace a special item in the player's list of items of that type.
void	setSpecialVP(int svp) Set the number of Special Victory Points (SVPs) awarded to this player.
void	setStartingLandAreasEncoded(int slas) At client, set the player's getStartingLandAreasEncoded() based on a server message.
java.lang.String	toString()
void	undoPutPiece(SOCPlayingPiece piece) undo the putting of a piece.
protected void	undoPutPieceAuxSettlement(int settlementNode) Auxiliary function for undoing settlement placement
(package private) void	updateAtOurTurn() Update game state as needed when this player begins their turn (before dice are rolled).
(package private) void	updateAtTurn() Update player's state as needed when any player begins their turn (before dice are rolled).
(package private) void	updateLegalShipsAddHex(int hexCoord) When a SOCBoardLarge.FOG_HEX is revealed to be water, or a land hex at the board's margin, update the set of edges used by isLegalShip(int).
(package private) void	updatePortFlagsAfterRemove(int portType, boolean removedPort) After removing a player's piece at a port, or removing the port, check to see if we still have a port of that type.
void	updatePotentials(SOCPlayingPiece piece) update the arrays that keep track of where this player can play further pieces, after a piece has just been played, or after another player's adjacent piece has been removed.

Methods inherited from class java.lang.Object

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

Field Detail

SHIP_COUNT

public static final int SHIP_COUNT

Number of ships a player can build (15) if SOCGame.hasSeaBoard.

Since:

2.0.00

See Also:

getNumPieces(int), Constant Field Values

name

private java.lang.String name

the name of the player

playerNumber

private int playerNumber

The integer id for this player (0 to n-1).

game

private SOCGame game

the game that this player is in

numPieces

private int[] numPieces

the number of pieces not in play. Indexes match SOCPlayingPiece constants: SOCPlayingPiece.ROAD, SOCPlayingPiece.SETTLEMENT, SOCPlayingPiece.CITY, SOCPlayingPiece.SHIP.

numWarships

private int numWarships

For scenario option _SC_PIRI, the number of SOCShips that are converted to warships. See getNumWarships() for details.

Since:

2.0.00

pieces

private java.util.Vector<SOCPlayingPiece> pieces

a list of this player's pieces in play (does not include any fortress).

roads

private java.util.Vector<SOCRoad> roads

a list of this player's roads and ships in play. Although roads and ships are kept together here, in numPieces[] they're counted separately.

See Also:

getRoadOrShip(int)

settlements

private java.util.Vector<SOCSettlement> settlements

a list of this player's settlements in play

cities

private java.util.Vector<SOCCity> cities

a list of this player's cities in play

fortress

private SOCFortress fortress

For scenario option _SC_PIRI, the "pirate fortress" that this player must defeat to win. The player's warships are used to defeat the fortress; see getNumWarships(). Null if fortress has been defeated and converted to a settlement. Null unless game has that scenario option.

There is no setFortress method; use putPiece. For details see getFortress().

Since:

2.0.00

spItems

private java.util.HashMap<java.lang.String,java.util.ArrayList<SOCSpecialItem>> spItems

Player's SOCSpecialItems, if any, by type. See getter/setter javadocs for details on type keys and rationale for lack of synchronization. ArrayList is used to guarantee we can store null items.

Since:

2.0.00

lastSettlementCoord

protected int lastSettlementCoord

The node coordinate of our most recent settlement. Useful during initial placement.

lastRoadCoord

protected int lastRoadCoord

The edge coordinate of our most recent road or ship. Useful during initial placement.

longestRoadLength

private int longestRoadLength

length of the longest road for this player

lrPaths

private java.util.Vector<SOCLRPathData> lrPaths

list of longest road / longest trade-route paths

resources

private SOCResourceSet resources

how many of each resource this player has

rolledResources

private SOCResourceSet rolledResources

Resources gained from dice roll of the current turn. Set in addRolledResources(SOCResourceSet), cleared in updateAtTurn().

Since:

2.0.00

lastActionBankTrade_give

SOCResourceSet lastActionBankTrade_give

For use at server by SOCGame, if the player's previous action this turn was a bank trade, the resources involved. Used to decide if they can undo the trade.

Ignore unless SOCGame.canUndoBankTrade(SOCResourceSet, SOCResourceSet) is true.

Since:

1.1.13

lastActionBankTrade_get

SOCResourceSet lastActionBankTrade_get

For use at server by SOCGame, if the player's previous action this turn was a bank trade, the resources involved. Used to decide if they can undo the trade.

Ignore unless SOCGame.canUndoBankTrade(SOCResourceSet, SOCResourceSet) is true.

Since:

1.1.13

resourceStats

private int[] resourceStats

server-only total count of how many of each known resource the player has received this game from dice rolls. The used indexes are SOCResourceConstants.CLAY - SOCResourceConstants.WOOD, and also (in v2.0.00+) SOCResourceConstants.GOLD_LOCAL. See getResourceRollStats() for details.

Since:

1.1.09

inventory

private SOCInventory inventory

The development cards this player holds, along with occasional scenario-specific items.

numKnights

private int numKnights

how many knights this player has in play

buildingVP

private int buildingVP

the number of victory points for settlements and cities

specialVP

private int specialVP

The number of Special Victory Points (SVPs), which are awarded in certain game scenarios on the large sea board. Does not include VPs from numCloth, cloth is part of getTotalVP().

When updating this value, if the SVP came from a piece, also set or check SOCPlayingPiece.specialVP and SOCPlayingPiece.specialVPEvent.

Since:

2.0.00

See Also:

svpInfo

svpInfo

private java.util.ArrayList<SOCPlayer.SpecialVPInfo> svpInfo

The details behind the total SVP count in specialVP, or null if none. This is filled at the server (because it has the text strings) when SOCGame.scenarioEventListener != null, and sent out to clients.

See Also:

addSpecialVPInfo(int, String)

finalTotalVP

private int finalTotalVP

the final total score (pushed from server at end of game), or 0 if no score has been forced.

See Also:

forceFinalVP(int)

numCloth

private int numCloth

For some game scenarios, how many cloth does this player have? Every 2 pieces of cloth is worth 1 VP.

Since:

2.0.00

See Also:

specialVP

needToDiscard

private boolean needToDiscard

this flag is true if the player needs to discard and must pick which resources to lose.

See Also:

needToPickGoldHexResources

needToPickGoldHexResources

private int needToPickGoldHexResources

If nonzero, waiting for player to pick this many gold-hex resources, after a dice roll or placing their final initial settlement.

When setting this field, also increment resourceStats [GOLD_LOCAL].

Game state SOCGame.WAITING_FOR_PICK_GOLD_RESOURCE or SOCGame.STARTS_WAITING_FOR_PICK_GOLD_RESOURCE.

Since:

2.0.00

See Also:

needToDiscard

roadNodes

private java.util.Vector<java.lang.Integer> roadNodes

all of the nodes that this player's roads and ships touch; this is used to calculate longest road / longest trade route.

roadNodeGraph

private java.util.Hashtable<java.lang.Integer,int[]> roadNodeGraph

A graph of what adjacent nodes are connected by this player's roads and ships. If roadNodeGraph[node1][node2], then a road or ship connects them; roadNodeGraph[node2][node1] will also be true.

Implementation:
Key = node1's coordinate Integer.
Value = int[] array of length 3, for the 3 adjacent nodes.
If an element of the array is 0, no connection. A non-zero element is node2's coordinate at the other end of the road connecting them.

See Also:

isConnectedByRoad(int, int)

legalRoads

private java.util.HashSet<java.lang.Integer> legalRoads

a list of edges where it is legal to place a road. an edge is legal if a road could eventually be placed there.

If not SOCGame.hasSeaBoard, initialized in constructor from SOCBoard.initPlayerLegalRoads().

If SOCGame.hasSeaBoard, empty until SOCBoard.makeNewBoard(Map) and SOCGame.startGame(), because the board layout and legal settlements vary from game to game.

legalSettlements

private java.util.HashSet<java.lang.Integer> legalSettlements

a set of nodes where it is legal to place a settlement. A node is legal if a settlement can ever be placed there. Placing a settlement will clear its node and adjacent nodes.

Key = node coordinate, as Integer. If legalSettlements.contains(new Integer(nodeCoord)), then nodeCoord is a legal settlement.

If not SOCGame.hasSeaBoard, initialized in constructor from SOCBoard.initPlayerLegalAndPotentialSettlements().

If SOCGame.hasSeaBoard: Empty at server until SOCBoardLarge.makeNewBoard(Map) and SOCGame.startGame(), because the board layout and legal settlements vary from game to game. Empty at client until setPotentialAndLegalSettlements(Collection, boolean, HashSet[]) is called.

See Also:

potentialSettlements, SOCBoard.nodesOnLand

addedLegalSettlement

private int addedLegalSettlement

The most recently added node from addLegalSettlement(int, boolean), or 0.

Since:

2.0.00

legalShips

private java.util.HashSet<java.lang.Integer> legalShips

a list of edges where it is legal to place a ship. an edge is legal if a ship could eventually be placed there.

If the game doesn't use the large sea board (! SOCGame.hasSeaBoard), this set is empty but non-null.

May be updated during game play by updateLegalShipsAddHex(int).

Since:

2.0.00

See Also:

legalShipsRestricted

legalShipsRestricted

private java.util.HashSet<java.lang.Integer> legalShipsRestricted

A list of edges if the legal sea edges for ships are restricted by the game's scenario (_SC_PIRI), or null if all sea edges are legal for ships. If the player has no legal ship edges, this list is empty (not null).

This list, separate from legalShips, is necessary because some methods change legalShips by removing or adding edges.

Since:

2.0.00

potentialRoads

private java.util.HashSet<java.lang.Integer> potentialRoads

a set of edges where a road could be placed on the next turn. At start of the game, this is clear/empty. Elements are set true when the player places adjacent settlements or roads, via updatePotentials(SOCPlayingPiece). Elements are set false when a road or ship is placed on their edge.

potentialSettlements

private java.util.HashSet<java.lang.Integer> potentialSettlements

a set of nodes where a settlement could be placed on the next turn. At start of the game, all legalSettlements are also potential. When the second settlement is placed, potentialSettlements is cleared, and then re-set via updatePotentials(SOCRoad). Placing a settlement will clear its node and adjacent nodes.

Key = node coordinate, as Integer. If potentialSettlements.contains(new Integer(nodeCoord)), then this is a potential settlement.

See Also:

legalSettlements, setPotentialAndLegalSettlements(Collection, boolean, HashSet[]), SOCBoard.nodesOnLand

potentialCities

private java.util.HashSet<java.lang.Integer> potentialCities

a set of nodes where a city could be placed on the next turn. At start of the game, this is clear/empty because the player has no settlements yet. Elements are set true when the player places settlements, via updatePotentials(SOCPlayingPiece). Elements are set false when cities are placed. Unlike other piece types, there is no "legalCities" set, because we use legalSettlements before placing a settlement, and settlements can always become cities.

potentialShips

private java.util.HashSet<java.lang.Integer> potentialShips

a set of edges where a ship could be placed on the next turn. At start of the game, this is clear/empty. Elements are set true when the player places adjacent settlements or ships, via updatePotentials(SOCPlayingPiece). Elements are set false when a road or ship is placed on their edge.

If the game doesn't use the large sea board (! SOCGame.hasSeaBoard), this set is empty but non-null.

Since:

2.0.00

ports

private boolean[] ports

a boolean array stating wheather this player is touching a particular kind of port. Index == port type, in range SOCBoard.MISC_PORT to SOCBoard.WOOD_PORT

currentOffer

private SOCTradeOffer currentOffer

this is the current trade offer that this player is making, or null if none

playedDevCard

private boolean playedDevCard

this is true if the player played a development card this turn

boardResetAskedThisTurn

private boolean boardResetAskedThisTurn

this is true if the player asked to reset the board this turn

askedSpecialBuild

private boolean askedSpecialBuild

In 6-player mode, is the player asking to build during the Special Building Phase?

Since:

1.1.08

See Also:

hasSpecialBuiltThisTurn

hasSpecialBuiltThisTurn

private boolean hasSpecialBuiltThisTurn

In 6-player mode, has the player already built during the Special Building Phase?

Since:

1.1.09

See Also:

askedSpecialBuild

scenario_playerEvents_bitmask

private int scenario_playerEvents_bitmask

Track one-time player events for scenarios on the large sea board. As events occur during a game, each one's SOCScenarioPlayerEvent.flagValue bit is set here.

Example events: SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA, SOCScenarioPlayerEvent.CLOTH_TRADE_ESTABLISHED_VILLAGE.

Bits are kept here, not in separate boolean fields, to keep them together and send over the network. Not all player events are here; some can't be represented in a single flag bit, such as scenario_svpFromEachLandArea_bitmask.

Since:

2.0.00

See Also:

getScenarioPlayerEvents()

scenario_svpFromEachLandArea_bitmask

private int scenario_svpFromEachLandArea_bitmask

For some scenarios on the large sea board, bitmask: true if the player has been given a Special Victory Point for placing a settlement in a given new land area. The bit value is (1 << (landAreaNumber - 1)).

Since:

2.0.00

See Also:

SOCScenarioPlayerEvent.SVP_SETTLED_EACH_NEW_LANDAREA, scenario_playerEvents_bitmask, getScenarioSVPLandAreas()

startingLandArea1

private int startingLandArea1

The land area(s) of the player's initial settlements, if SOCGame.hasSeaBoard and the board defines Land Areas (null != SOCBoardLarge.getLandAreasLegalNodes()). Used for Special Victory Points in some scenarios. 0 otherwise.

If both initial settlements are in the same land area, then startingLandArea2 is 0.

Also: If SOCBoardLarge.getStartingLandArea() != 0, the players must start in that land area. This is enforced at the server during makeNewBoard, by using that land area for the only initial potential/legal settlement locations.

Since:

2.0.00

startingLandArea2

private int startingLandArea2

The land area(s) of the player's initial settlements, if SOCGame.hasSeaBoard and the board defines Land Areas (null != SOCBoardLarge.getLandAreasLegalNodes()). Used for Special Victory Points in some scenarios. 0 otherwise.

If both initial settlements are in the same land area, then startingLandArea2 is 0.

Also: If SOCBoardLarge.getStartingLandArea() != 0, the players must start in that land area. This is enforced at the server during makeNewBoard, by using that land area for the only initial potential/legal settlement locations.

Since:

2.0.00

robotFlag

private boolean robotFlag

this is true if this player is a robot

builtInRobotFlag

private boolean builtInRobotFlag

Is this robot connection the built-in robot (not a 3rd-party), with the original AI?

Since:

1.1.09

See Also:

SOCImARobot

faceId

private int faceId

which face image this player is using

ourNumbers

private SOCPlayerNumbers ourNumbers

the numbers that our settlements are touching

isTradeRouteFarEndClosed_foundVillage

private SOCVillage isTradeRouteFarEndClosed_foundVillage

Set by isTradeRouteFarEndClosed(SOCShip, int, HashSet, List) if it finds a village at any far end. Not set unless SOCGame.hasSeaBoard and SOCGameOption.K_SC_CLVI are set.

Since:

2.0.00

Constructor Detail

SOCPlayer

public SOCPlayer(SOCPlayer player)
          throws java.lang.IllegalStateException

create a copy of the player

Parameters:

player - the player to copy

Throws:

java.lang.IllegalStateException - if player's dev cards can't be cloned (internal error); should not possibly occur

SOCPlayer

public SOCPlayer(int pn,
                 SOCGame ga)

Create a new player for a new empty board.

Unless SOCGame.hasSeaBoard, the player's possible placement locations will be set from SOCBoard.initPlayerLegalRoads() and SOCBoard.initPlayerLegalAndPotentialSettlements().

Once the game board is set up, be sure to call setPotentialAndLegalSettlements(Collection, boolean, HashSet[]) to update our data.

Parameters:

pn - the player number

ga - the game that the player is in

Method Detail

clearPotentialSettlements

public void clearPotentialSettlements()

At start of normal game play, set all nodes to not be potential settlements. Called by SOCGame.updateAtGameFirstTurn() in state SOCGame.START2A or SOCGame.START3A after final initial settlement placement.

Once they have placed another road, that road's putPiece(SOCPlayingPiece, boolean) call will call updatePotentials(SOCPlayingPiece), which will set potentialSettlements at the road's new end node.

updateAtTurn

void updateAtTurn()

Update player's state as needed when any player begins their turn (before dice are rolled). Called by server and client, as part of SOCGame.updateAtTurn().

Called for each player, just before calling the current player's updateAtOurTurn().

• Clear getRolledResources()

Since:

1.1.14

updateAtOurTurn

void updateAtOurTurn()

Update game state as needed when this player begins their turn (before dice are rolled). Called by server and client, as part of SOCGame.updateAtTurn(). Called just after calling each player's updateAtTurn().

May be called during initial placement. Is called at the end of initial placement, before the first player's first roll. On the 6-player board, is called at the start of the player's Special Building Phase.

• Mark our new dev cards as old
• Set getNeedToPickGoldHexResources() to 0
• Clear the "last-action bank trade" flag/list used by game.canUndoBankTrade

Since:

1.1.14

setName

public void setName(java.lang.String na)
             throws java.lang.IllegalArgumentException

set the name of the player

Parameters:

na - the player's new name, or null. For network message safety, must not contain control characters, SOCMessage.sep_char, or SOCMessage.sep2_char. This is enforced by calling SOCMessage.isSingleLineAndSafe(String).

Throws:

java.lang.IllegalArgumentException - if a non-null name fails SOCMessage.isSingleLineAndSafe(String). This exception was added in 1.1.07.

getName

public java.lang.String getName()

Returns:

the name of the player

getPlayerNumber

public int getPlayerNumber()

Get the player's seat number in the game.

Returns:

the player id

getGame

public SOCGame getGame()

Returns:

the game that this player is in

hasPlayedDevCard

public boolean hasPlayedDevCard()

Returns:

true if the player played a dev card this turn

setPlayedDevCard

public void setPlayedDevCard(boolean value)

set the playedDevCard flag

Parameters:

value - the value of the flag

hasAskedBoardReset

public boolean hasAskedBoardReset()

Returns:

true if the player asked to reset the board this turn

setAskedBoardReset

public void setAskedBoardReset(boolean value)

set the flag indicating if the player asked to reset the board this turn

Parameters:

value - true to set, false to clear

hasAskedSpecialBuild

public boolean hasAskedSpecialBuild()

In 6-player mode's Special Building Phase, this player has asked to build. To set or clear this flag, use setAskedSpecialBuild(boolean).

Returns:

if the player has asked to build

Since:

1.1.08

See Also:

hasSpecialBuilt()

setAskedSpecialBuild

public void setAskedSpecialBuild(boolean set)

In 6-player mode's Special Building Phase, set or clear the flag for this player asking to build. Does not validate that they are currently allowed to ask; use SOCGame.canAskSpecialBuild(int, boolean) for that. To read this flag, use hasAskedSpecialBuild().

Parameters:

set - if the player has asked to build

Since:

1.1.08

See Also:

SOCGame.askSpecialBuild(int, boolean)

hasSpecialBuilt

public boolean hasSpecialBuilt()

In 6-player mode's Special Building Phase, this player has already built this turn. To set or clear this flag, use setSpecialBuilt(boolean).

Returns:

if the player has built

Since:

1.1.09

See Also:

hasAskedSpecialBuild()

setSpecialBuilt

public void setSpecialBuilt(boolean set)

In 6-player mode's Special Building Phase, set or clear the flag for this player already built this turn. Does not validate against current game conditions. To read this flag, use hasSpecialBuilt().

Parameters:

set - if the player special-built this turn

Since:

1.1.09

setNeedToDiscard

public void setNeedToDiscard(boolean value)

set the "need to discard" flag

Parameters:

value - the value of the flag

getNeedToDiscard

public boolean getNeedToDiscard()

Returns:

true if this player needs to discard

See Also:

getNeedToPickGoldHexResources()

setNeedToPickGoldHexResources

public void setNeedToPickGoldHexResources(int numRes)

Set the number of gold-hex resources this player must now pick, after a dice roll or placing their 2nd initial settlement. 0 unless SOCGame.hasSeaBoard and player is adjacent to a SOCBoardLarge.GOLD_HEX. Game state SOCGame.WAITING_FOR_PICK_GOLD_RESOURCE. Once the player has picked their resources, returns to 0.

Parameters:

numRes - Number of resources to pick, or 0 for no pick

Since:

2.0.00

getNeedToPickGoldHexResources

public int getNeedToPickGoldHexResources()

Get the number of gold-hex resources this player must now pick, after a dice roll or placing their 2nd initial settlement. 0 unless SOCGame.hasSeaBoard and player is adjacent to a SOCBoardLarge.GOLD_HEX. Game state SOCGame.WAITING_FOR_PICK_GOLD_RESOURCE. Once the player has picked their resources, returns to 0.

Returns:

number of resources to pick

Since:

2.0.00

See Also:

getNeedToDiscard()

setRobotFlag

public void setRobotFlag(boolean isRobot,
                         boolean isBuiltIn)

set the robot flags.

Parameters:

isRobot - Is this player a robot?

isBuiltIn - Is this player the built-in robot type? Assume false if unknown, such as in SITDOWN message received at other clients.

isRobot

public boolean isRobot()

Is this player a robot AI (built-in or 3rd-party)?

Returns:

the value of the robot flag

See Also:

isBuiltInRobot()

isBuiltInRobot

public boolean isBuiltInRobot()

Is this robot player the built-in robot (not a 3rd-party), with the original AI? False if unknown.

Returns:

the value of the built-in-robot flag

Since:

1.1.09

See Also:

isRobot(), SOCImARobot

setFaceId

public void setFaceId(int id)

set the face image id

Parameters:

id - the image id. 1 is the first human face image; 0 is the robot.

getFaceId

public int getFaceId()

get the face image id.

Returns:

the face image id. 1 is the first human face image; 0 is the robot.

getNumbers

public SOCPlayerNumbers getNumbers()

Returns:

the numbers that this player's settlements are touching

getNumPieces

public int getNumPieces(int ptype)
                 throws java.lang.ArrayIndexOutOfBoundsException

Get the number of one piece type not in play and available to place. At the start of the game, for example, getNumPieces(SOCPlayingPiece.CITY) == 4. On the sea board, each player starts with SHIP_COUNT ships.

Parameters:

ptype - the type of piece; matches SOCPlayingPiece constants, such as SOCPlayingPiece.ROAD, SOCPlayingPiece.SETTLEMENT.

Returns:

the number of pieces not in play for a particular type of piece

Throws:

java.lang.ArrayIndexOutOfBoundsException - if piece type is invalid

See Also:

getPieces(), getNumWarships()

setNumPieces

public void setNumPieces(int ptype,
                         int amt)

set the amount of pieces not in play for a particular type of piece

Parameters:

ptype - the type of piece; matches SOCPlayingPiece constants, such as SOCPlayingPiece.ROAD, SOCPlayingPiece.SETTLEMENT.

amt - the amount

See Also:

setNumWarships(int)

getNumWarships

public int getNumWarships()

For scenario option _SC_PIRI, the number of SOCShips that have been converted to warships to defend against the pirate fleet and attack the SOCFortress.

SOCShip has no "isWarship" field; the player's first numWarships ships within getRoads() are the warships, because those are the ships heading out to sea starting at the player's settlement, placed chronologically. See SOCGame.isShipWarship(SOCShip) for details.

Since:

2.0.00

setNumWarships

public void setNumWarships(int count)

For scenario option _SC_PIRI, set the player's number of warships. See getNumWarships() for details.

Parameters:

count - New number of warships

Since:

2.0.00

getPieces

public java.util.Vector<SOCPlayingPiece> getPieces()

Get this player's pieces on the board. Does not include getFortress(), if any, because the player doesn't control that piece.

Returns:

the list of pieces in play

See Also:

getNumPieces(int)

getRoads

public java.util.Vector<SOCRoad> getRoads()

Get this player's roads and ships on the board. Chronological order. Note that if a ship is moved on the board, it may go to the end of this list.

Returns:

the list of roads/ships in play

See Also:

getRoadOrShip(int), getMostRecentShip()

getRoadOrShip

public SOCRoad getRoadOrShip(int edge)

Get this player's road or ship on an edge.

Parameters:

edge - Edge coordinate of the road or ship

Returns:

The player's road or ship in play at this edge, or null

Since:

2.0.00

See Also:

getMostRecentShip()

getMostRecentShip

public SOCShip getMostRecentShip()

Get this player's most recently placed ship, if any.

Returns:

Most recent ship from getRoads(), or null if that list contains no SOCShips

Since:

2.0.00

See Also:

getRoads()

getSettlements

public java.util.Vector<SOCSettlement> getSettlements()

Returns:

the list of settlements in play

getCities

public java.util.Vector<SOCCity> getCities()

Returns:

the list of cities in play

getSpecialItems

public java.util.ArrayList<SOCSpecialItem> getSpecialItems(java.lang.String typeKey)

Get a list of all special items of a given type held by the player. Only some scenarios and expansions use Special Items.

Locks: This getter is not synchronized: It's assumed that the structure of Special Item lists is set up at game creation time, and not often changed. If a specific item type or access pattern requires synchronization, do so outside this class and document the details.

Parameters:

typeKey - Special item type. Typically a SOCGameOption keyname; see the SOCSpecialItem class javadoc for details.

Returns:

List of all special items of that type, or null if none; will never return an empty list. Some list items may be null depending on the list structure created by the scenario or expansion.

Since:

2.0.00

See Also:

SOCGame.getSpecialItems(String), SOCGame.getSpecialItemTypes()

getSpecialItem

public SOCSpecialItem getSpecialItem(java.lang.String typeKey,
                                     int idx)

Get a special item of a given type, by index within the list of all items of that type held by the player. Only some scenarios and expansions use Special Items.

Locks: This getter is not synchronized: It's assumed that the structure of Special Item lists is set up at game creation time, and not often changed. If a specific item type or access pattern requires synchronization, do so outside this class and document the details.

Parameters:

typeKey - Special item type. Typically a SOCGameOption keyname; see the SOCSpecialItem class javadoc for details.

idx - Index within the list of special items of that type; must be within the list's current size

Returns:

The special item, or null if none of that type, or if that index is null within the list or is beyond the size of the list

Since:

2.0.00

See Also:

SOCGame.getSpecialItem(String, int), SOCGame.getSpecialItem(String, int, int, int), SOCSpecialItem.playerPickItem(String, SOCGame, SOCPlayer, int, int), SOCSpecialItem.playerSetItem(String, SOCGame, SOCPlayer, int, int, boolean)

setSpecialItem

public SOCSpecialItem setSpecialItem(java.lang.String typeKey,
                                     int idx,
                                     SOCSpecialItem itm)
                              throws java.lang.IndexOutOfBoundsException

Add or replace a special item in the player's list of items of that type. Only some scenarios and expansions use Special Items.

Parameters:

typeKey - Special item type. Typically a SOCGameOption keyname; see the SOCSpecialItem class javadoc for details. If no list with this key exists, it will be created here.

idx - Index within the list of special items of that type; if this is past the list's current size, null elements will be inserted as needed until idx is a valid index If idx is within the list, the current element at that index will be replaced.

itm - Item object to set within the list

Returns:

The item previously at this index, or null if none

Throws:

java.lang.IndexOutOfBoundsException - if idx < 0

See Also:

SOCGame.setSpecialItem(String, int, SOCSpecialItem)

getFortress

public SOCFortress getFortress()

For scenario option _SC_PIRI, the "pirate fortress" that this player must defeat to win. Null if fortress has already been defeated and converted to a settlement. Null unless game has that scenario option.

There is no setFortress method; instead call game.putPiece(SOCFortress) to set, or game.putPiece(SOCSettlement) to clear.

Since:

2.0.00

getCloth

public int getCloth()

For some game scenarios, get how many cloth this player currently has. Every 2 pieces of cloth is worth 1 VP.

Since:

2.0.00

setCloth

public void setCloth(int numCloth)

Set how many cloth this player currently has. More cloth gives the player more VPs, see getPublicVP(). For use at client based on messages from server.

Parameters:

numCloth - Number of cloth

Since:

2.0.00

canMoveShip

public boolean canMoveShip(SOCShip sh)

Can we move this ship, based on our trade routes and settlements/cities near its current location?

Only the ship at the newer end of an open trade route can be moved. So, to move a ship, one of its end nodes must be clear of this player's pieces: No settlement or city, and no other adjacent ship on the other side of the node. Other players' pieces are ignored. The ship must be part of an open trade route; sh.isClosed() must be false.

Does not check game state, only this player's pieces. Trade routes can branch, so it may be that more than one ship could be moved. The game limits players to one move per turn. That limit isn't checked here. After the player picks the ship's requested new location, SOCGame.canMoveShip(int, int, int) checks that limit, the other game conditions, and calls this method to check the player's piece conditions.

Once the player picks the ship's requested new location, that edge will be checked with isPotentialShipMoveTo(int, int).

Parameters:

sh - One of our ships

Since:

2.0.00

doesTradeRouteContinuePastEdge

private final boolean doesTradeRouteContinuePastEdge(int edge,
                                                     boolean wantShip)

For road/ship building, does this edge have a piece of ours adjacent to it (settlement, city, or same road/ship type as wantShip)?

Parameters:

edge - Check adjacents of this edge

wantShip - True to look for ships only, false for roads only

Returns:

True if we have an adjacent settlement or city, or our route continues on an adjacent edge

Since:

2.0.00

doesTradeRouteContinuePastNode

private final boolean doesTradeRouteContinuePastNode(SOCBoard board,
                                                     boolean wantShip,
                                                     int rsEdge,
                                                     int ignoreEdge,
                                                     int node)

Does this trade route (ships only, or roads only) continue past an unoccupied node?

Parameters:

board - game board

wantShip - True to look for ships only, false for roads only

rsEdge - Edge adjacent to node with a road/ship on the trade route

ignoreEdge - Edge to ignore our pieces on, or -9; used during the check before moving one of our ships to ignore the ship's current position (its fromEdge). Not necessarily adjacent to node or rsEdge.

In scenario _SC_PIRI, moving a ship must not create a new branch in the existing ship route. When not -9 in that scenario, this method checks that by counting our ships/roads adjacent to node besides rsEdge and ignoreEdge.

node - Node at one end of rsEdge, which does not have a settlement or city; check this node's other 2 edges for roads/ships continuing the trade route

Returns:

True if a road/ship continues the route past node along one or both of the node's 2 other edges

Since:

2.0.00

checkTradeRouteFarEndClosed

private java.util.Vector<SOCShip> checkTradeRouteFarEndClosed(SOCShip newShipEdge,
                                                              int edgeFarNode)
                                                       throws java.lang.IllegalStateException

Follow a trade route (a line of SOCShips) away from a newly closed end, to determine if the other end is closed or still open, and close this route if necessary.

We check the route in one direction towards edgeFarNode, because we assume that the other end of newShipEdge has a settlement, or that it branches from an already-closed trade route.

The route and its segments may end at a settlement/city/village, a branch where 3 ships meet at a node (and 2 of the 3 ships are closed), or may end "open" with no further pieces.

Settlements and cities owned by other players won't close the trade route. Villages are present only with scenario game option SOCGameOption.K_SC_CLVI. If this route becomes closed and is the player's first Cloth Trade route with a village, this method sets that player event flag and fires SOCScenarioPlayerEvent.CLOTH_TRADE_ESTABLISHED_VILLAGE.

Valid only when SOCGame.hasSeaBoard.

Parameters:

newShipEdge - A ship in a currently-open trade route, either newly placed or adjacent to a newly placed settlement. If the ship is newly placed, it should not yet be in roads. If the settlement is newly placed, it should not yet be in settlements.

edgeFarNode - The unvisited node at the far end of fromEdge. We'll examine this node and then continue to move along edges past it.

Returns:

null if open, otherwise all the newly-closed SOCShips

Throws:

java.lang.IllegalStateException - if not SOCGame.hasSeaBoard

Since:

2.0.00

isTradeRouteFarEndClosed

private java.util.Vector<SOCShip> isTradeRouteFarEndClosed(SOCShip edgeFirstShip,
                                                           int edgeFarNode,
                                                           java.util.HashSet<java.lang.Integer> alreadyVisited,
                                                           java.util.List<java.util.Vector<java.lang.Object>> encounteredSelf)
                                                    throws java.lang.ClassCastException,
                                                           java.lang.IllegalArgumentException

Recursive call for checkTradeRouteFarEndClosed(SOCShip, int). See that method for more information. This method checks one segment of the trade route going from a branch. The segment may end at a settlement/city/village, another branch, or end with no further pieces.

If recursion ends at a SOCVillage, isTradeRouteFarEndClosed_foundVillage will be set to it. If you're looking for villages, clear that field before calling this method.

Valid only when SOCGame.hasSeaBoard.

Parameters:

edgeFirstShip - First edge along the segment; an open ship required here. All edges, including this first edge, are checked against encounteredSelf.

edgeFarNode - The unvisited node at the far end of fromEdge. We'll examine this node and then continue to move along edges past it. If the "facing direction" we're moving in is called "moveDir", then edgeFarNode = board.getAdjacentNodeToEdge(edgeFirstShip.getCoordinates(), moveDir).

alreadyVisited - contains Integer edge coordinates as the segment is built; added to in this method

encounteredSelf - contains Vectors, each with a node coord Integer and SOCShips; might be added to in this method. Node is the "far end" of the segment from edgeFirstShip, just past the ship that was re-encountered. The SOCShips are ordered starting with edgeFirstShip and moving out to the node just past (farther than) the encounter ship. (That ship is not in the Vector.) The very first vector in the list is the one farthest from the original starting ship, and the following list entries will overall move closer to the start.

Returns:

a closed route of SOCShip or null, from fromEdge to far end; may also add to alreadyVisited and encounteredSelf

Throws:

java.lang.ClassCastException - if not SOCGame.hasSeaBoard.

java.lang.IllegalArgumentException - if edgeFirstShip.isClosed()

Since:

2.0.00

getLastSettlementCoord

public int getLastSettlementCoord()

Get the location of this player's most recent settlement. Useful during initial placement.

Returns:

the coordinates of the last settlement played by this player

getLastRoadCoord

public int getLastRoadCoord()

Get the location of this player's most recent road or ship. Useful during initial placement.

Returns:

the coordinates of the last road/ship played by this player

getLongestRoadLength

public int getLongestRoadLength()

Get the length of this player's longest road or trade route, as calculated by the most recent call to calcLongestRoad2().

Returns:

the longest road length / trade route length

getLRPaths

public java.util.Vector<SOCLRPathData> getLRPaths()

Get our longest road paths. Vector is empty if SOCGameOption.K_SC_0RVP is set.

Returns:

longest road paths

setLRPaths

public void setLRPaths(java.util.Vector<SOCLRPathData> vec)

set the longest paths vector

Parameters:

vec - the vector

setLongestRoadLength

public void setLongestRoadLength(int len)

set the longest road / longest trade route length

Parameters:

len - the length

getResources

public SOCResourceSet getResources()

Get the resources currently held in the player's hand.

Returns:

the resource set

getResourceRollStats

public int[] getResourceRollStats()

On server, get the current totals of resources received by dice rolls by this player. Each resource type's total includes resources picked from a rolled SOCBoardLarge.GOLD_HEX. For the Fog Scenario, includes resources picked when building a road or ship revealed gold from a SOCBoardLarge.FOG_HEX.

Please treat this as read-only.

Not currently tracked at client.

Returns:

array of resource counts from dice rolls; the used indexes are SOCResourceConstants.CLAY - SOCResourceConstants.WOOD. Index 0 is unused. In v2.0.00 and newer, index SOCResourceConstants.GOLD_LOCAL tracks how many resource picks the player has received from gold hexes.

Since:

1.1.09

addRolledResources

public void addRolledResources(SOCResourceSet rolled)

Add to this player's resources and resource-roll totals.

If SOCGame.hasSeaBoard, treat SOCResourceConstants.GOLD_LOCAL as the gold-hex resources they must pick, and set getNeedToPickGoldHexResources() to that amount. This method updates getResourceRollStats()[GOLD_LOCAL]. Once the resources from gold from a dice roll are picked, the game should update this player's getResourceRollStats().

Otherwise ignores rolled SOCResourceConstants.UNKNOWN resources.

Parameters:

rolled - The resources gained by this roll, as determined by SOCGame.rollDice()

Since:

1.1.09

getRolledResources

public SOCResourceSet getRolledResources()

Resources gained from dice roll of the current turn. Valid at server only, not at client. Please treat the returned set as read-only.

Returns:

the resources, if any, gained by this player from the current turn's SOCGame.rollDice().

Since:

2.0.00

getInventory

public SOCInventory getInventory()

Get the player's inventory of SOCDevCards and other occasional items.

Before v2.0.00, this method was getDevCards().

Returns:

the inventory (development card set)

hasUnplayedDevCards

public boolean hasUnplayedDevCards()

Returns:

whether this player has any unplayed dev cards

See Also:

getInventory()

getNumKnights

public int getNumKnights()

Returns:

the number of knights in play

setNumKnights

public void setNumKnights(int nk)

set the number of knights in play

Parameters:

nk - the number of knights

incrementNumKnights

public void incrementNumKnights()

increment the number of knights in play

hasLongestRoad

public boolean hasLongestRoad()

Returns:

true if this player has the longest road / longest trade route

hasLargestArmy

public boolean hasLargestArmy()

Returns:

true if this player has the largest army

getSpecialVP

public int getSpecialVP()

Get the number of Special Victory Points (SVPs) awarded to this player. SVPs are part of some game scenarios on the large sea board.

Returns:

the number of SVPs, or 0

Since:

2.0.00

See Also:

getSpecialVPInfo()

setSpecialVP

public void setSpecialVP(int svp)

Set the number of Special Victory Points (SVPs) awarded to this player. For use at client based on messages from server.

Parameters:

svp - the number of SVPs, or 0

Since:

2.0.00

See Also:

addSpecialVPInfo(int, String)

getPublicVP

public int getPublicVP()

This player's number of publicly known victory points. Public victory points exclude VP development cards, except at end of game, when they've been announced by server. Special Victory Points (SVPs) are included, if the game scenario awards them. Also includes any VP from cloth.

Returns:

the number of publicly known victory points

See Also:

getTotalVP(), getSpecialVP(), forceFinalVP(int)

getTotalVP

public int getTotalVP()

Returns:

the actual number of victory points (including VP cards/items)

See Also:

getPublicVP(), forceFinalVP(int)

forceFinalVP

public void forceFinalVP(int score)

If game is over, server can push the final score for each player to the client. During play, true scores aren't known, because of hidden victory-point cards. getTotalVP() and getPublicVP() will report this, if set.

Parameters:

score - Total score for the player, or 0 for no forced total.

addSpecialVPInfo

public void addSpecialVPInfo(int svp,
                             java.lang.String desc)

Add details on Special Victory Points (SVP) just awarded. This is called at the server (because it has the text strings) when SOCGame.scenarioEventListener != null, and sent out to clients. Clients call it from the network message handler.

Parameters:

svp - Number of SVP

desc - Description of player's action that led to the SVP. At the server this is an I18N string key, at the client it's localized text sent from the server.

Since:

2.0.00

See Also:

getSpecialVPInfo()

getSpecialVPInfo

public java.util.ArrayList<SOCPlayer.SpecialVPInfo> getSpecialVPInfo()

Get the details, if known, behind this player's getSpecialVP() total. In chronological order during game play.

Returns:

Info on the Special Victory Points (SVP) awarded, or null; please treat as read-only

Since:

2.0.00

getScenarioPlayerEvents

public int getScenarioPlayerEvents()

Gets one-time player events for scenarios on the large sea board. As events occur during a game, each one's SOCScenarioPlayerEvent.flagValue bit is set.

Example events: SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA, SOCScenarioPlayerEvent.CLOTH_TRADE_ESTABLISHED_VILLAGE. Not all player events are returned here; some can't be represented in a single flag bit.

Returns:

Player events which have occurred so far this game

Since:

2.0.00

See Also:

hasScenarioPlayerEvent(SOCScenarioPlayerEvent)

setScenarioPlayerEvents

public void setScenarioPlayerEvents(int events)

At client, set the player's getScenarioPlayerEvents() based on a server message.

Parameters:

events - Player event flags to set; all others will be cleared.

Since:

2.0.00

hasScenarioPlayerEvent

public final boolean hasScenarioPlayerEvent(SOCScenarioPlayerEvent spe)

Does this player have a certain scenario player event flag? Flag bits are set as per-player events occur during a game.

Parameters:

spe - Player event, such as SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA

Returns:

True if event flag is set for this player

Since:

2.0.00

See Also:

getScenarioPlayerEvents()

setScenarioPlayerEvent

private final void setScenarioPlayerEvent(SOCScenarioPlayerEvent spe)
                                   throws java.lang.IllegalStateException

Set a certain scenario player event flag. Can be set once per game.

Parameters:

spe - Player event, such as SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA

Throws:

java.lang.IllegalStateException - if this flag is already set. This is checked at server, not client, due to message timing: Game events happen at the server before they happen at the client.

Since:

2.0.00

See Also:

clearScenarioPlayerEvent(SOCScenarioPlayerEvent)

clearScenarioPlayerEvent

private final void clearScenarioPlayerEvent(SOCScenarioPlayerEvent spe)

Clear a certain scenario player event flag.

Parameters:

spe - Player event, such as SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA

Since:

2.0.00

See Also:

setScenarioPlayerEvent(SOCScenarioPlayerEvent)

getScenarioSVPLandAreas

public int getScenarioSVPLandAreas()

For scenarios on the large sea board, get this player's bitmask of land areas for tracking Special Victory Points (SVP). Used with scenario game option _SC_SEAC.

Returns:

land areas bitmask, or 0

Since:

2.0.00

setScenarioSVPLandAreas

public void setScenarioSVPLandAreas(int las)

At client, set the player's getScenarioPlayerEvents() based on a server message.

Parameters:

las - Land areas to set in player's bitmask; all others will be cleared.

Since:

2.0.00

getStartingLandAreasEncoded

public int getStartingLandAreasEncoded()

For scenarios on the large sea board, get this player's starting settlement land areas, encoded to send over the network from server to client. 0 otherwise.

Returns:

Encoded starting land area numbers 1 and 2

Since:

2.0.00

See Also:

SOCPlayerElement.STARTING_LANDAREAS

setStartingLandAreasEncoded

public void setStartingLandAreasEncoded(int slas)

At client, set the player's getStartingLandAreasEncoded() based on a server message.

Parameters:

slas - Starting land areas to set for player

Since:

2.0.00

getRoadNodes

public java.util.Vector<java.lang.Integer> getRoadNodes()

Returns:

the list of nodes that touch the roads/ships in play

getCurrentOffer

public SOCTradeOffer getCurrentOffer()

Returns:

this player's latest offer, or null if none

setCurrentOffer

public void setCurrentOffer(SOCTradeOffer of)

set the current offer for this player

Parameters:

of - the offer, or null to clear

isConnectedByRoad

public boolean isConnectedByRoad(int node1,
                                 int node2)

Are these two adjacent nodes connected by this player's road/ship?

Parameters:

node1 - coordinates of first node

node2 - coordinates of second node

Returns:

true if one of this player's roads or ships connects the two nodes.

putPiece

public void putPiece(SOCPlayingPiece piece,
                     boolean isTempPiece)
              throws java.lang.IllegalArgumentException

Put a piece into play. Update potential piece lists. For roads, update roadNodes and roadNodeGraph. Does not update longest road; instead, SOCGame.putPiece(SOCPlayingPiece) calls calcLongestRoad2().

Note: Placing a city automatically removes the settlement there via SOCGame.putPiece(SOCPlayingPiece) calling removePiece(SOCPlayingPiece, SOCPlayingPiece).

Call this before calling SOCBoard.putPiece(SOCPlayingPiece).

For some scenarios on the large sea board, placing a settlement in a new Land Area may award the player a Special Victory Point (SVP). This method will increment specialVP and set the SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA flag.

For scenario option _SC_PIRI, call with piece = SOCFortress to set the single "pirate fortress" that this player must defeat to win. When the fortress is defeated, it is converted to a settlement; call with piece = SOCSettlement at the fortress location. isTempPiece must be false to set or clear the fortress.

Parameters:

piece - The piece to be put into play; coordinates are not checked for validity.

isTempPiece - Is this a temporary piece? If so, do not call the game's SOCScenarioEventListener.

Throws:

java.lang.IllegalArgumentException - only if piece is a SOCFortress, and either isTempPiece, or player already has a fortress set.

putPiece_roadOrShip

private void putPiece_roadOrShip(SOCRoad piece,
                                 SOCBoard board,
                                 boolean isTempPiece)

For putPiece, update road/ship-related info, roadNodes, roadNodeGraph and lastRoadCoord. Call only when the piece is ours. Does not update potentialRoads/potentialShips; see updatePotentials(SOCPlayingPiece).

Parameters:

piece - The road or ship

board - The board

isTempPiece - Is this a temporary piece? If so, do not check special edges or "gift" ports.

Since:

2.0.00

putPiece_roadOrShip_checkNewShipTradeRouteAndSpecialEdges

private void putPiece_roadOrShip_checkNewShipTradeRouteAndSpecialEdges(SOCShip newShip,
                                                                       SOCBoardLarge board,
                                                                       boolean isTempPiece)

Check this new ship for adjacent settlements/cities/villages, to see if its trade route will be closed. Close it if so.

If the route becomes closed and is the player's first Cloth Trade route with a SOCVillage, this method sets that player flag and fires SOCScenarioPlayerEvent.CLOTH_TRADE_ESTABLISHED_VILLAGE.

If the board layout has Special Edges, check if the new ship has reached one, and if so reward the player and fire an event like SOCScenarioPlayerEvent.SVP_REACHED_SPECIAL_EDGE or SOCScenarioPlayerEvent.DEV_CARD_REACHED_SPECIAL_EDGE.

In scenario _SC_FTRI, checks for a "gift" trade port at new ship edge. If found, calls SOCGame.removePort(SOCPlayer, int) and fires SOCScenarioPlayerEvent.REMOVED_TRADE_PORT.

Parameters:

newShip - Our new ship being placed in putPiece(SOCPlayingPiece, boolean); should not yet be added to roads

board - game board

isTempPiece - Is this a temporary piece? If so, do not check special edges or "gift" ports.

Since:

2.0.00

putPiece_settlement_checkTradeRoutes

private void putPiece_settlement_checkTradeRoutes(SOCSettlement newSettle,
                                                  SOCBoard board)

Check this new settlement for adjacent open ships, to see their its trade route will be closed. Close it if so.

Parameters:

newSettle - Our new settlement being placed in putPiece(SOCPlayingPiece, boolean); should not yet be added to settlements

board - game board

Since:

2.0.00

putPiece_settlement_checkScenarioSVPs

private final void putPiece_settlement_checkScenarioSVPs(SOCSettlement newSettle,
                                                         int newSettleArea,
                                                         boolean isTempPiece)

Does the player get a Special Victory Point (SVP) for reaching a new land area? Call when a settlement has been placed in a land area different from startingLandArea1 and startingLandArea2. Used with game options _SC_SANY and _SC_SEAC.

Parameters:

newSettle - Newly placed settlement

newSettleArea - Land area number of new settlement's location

isTempPiece - Is this a temporary piece? If so, do not call the game's SOCScenarioEventListener.

Since:

2.0.00

undoPutPiece

public void undoPutPiece(SOCPlayingPiece piece)

undo the putting of a piece.

Among other actions, Updates the potential building lists for removing settlements or cities. Updates port flags, this player's dice resource numbers, etc.

Call this only after calling SOCBoard.removePiece(SOCPlayingPiece).

If the piece is ours, calls removePiece(piece, null).

For roads, does not update longest road; if you need to, call calcLongestRoad2() after this call.

For removing second initial settlement (state START2B), will zero the player's resource cards.

Parameters:

piece - the piece placement to be undone.

undoPutPieceAuxSettlement

protected void undoPutPieceAuxSettlement(int settlementNode)

Auxiliary function for undoing settlement placement

Parameters:

settlementNode - the node we want to consider

removePiece

public void removePiece(SOCPlayingPiece piece,
                        SOCPlayingPiece replacementPiece)

remove a player's piece from the board, and put it back in the player's hand.

Most callers will want to instead call undoPutPiece(SOCPlayingPiece) which calls removePiece and does more.

Don't call removePiece for a SOCFortress; see getFortress() javadoc.

Note: removePiece does NOT update the potential building lists for removing settlements or cities. It does update potential road lists. For roads, updates roadNodes and roadNodeGraph.

If a ship is removed in scenario _SC_PIRI, makes sure our getNumWarships() is never more than the number of ships on the board.

Parameters:

piece - Our player's piece, to be removed from the board

replacementPiece - Piece that's replacing this piece; usually null unless player is upgrading to a city. If not null, and same player as piece, the removed piece's SOCPlayingPiece.specialVP and SOCPlayingPiece.specialVPEvent are copied to replacementPiece instead of being subtracted from the player's getSpecialVP() count.

See Also:

undoPutPiece(SOCPlayingPiece)

removePieceUpdateSpecialVP

private final void removePieceUpdateSpecialVP(SOCPlayingPiece p)

As part of removePiece(SOCPlayingPiece, null), update player's specialVP and related fields. Not called if the removed piece is being replaced by another one (settlement upgrade to city).

Parameters:

p - Our piece being removed, which has SOCPlayingPiece.specialVP != 0

Since:

2.0.00

updatePortFlagsAfterRemove

void updatePortFlagsAfterRemove(int portType,
                                boolean removedPort)

After removing a player's piece at a port, or removing the port, check to see if we still have a port of that type.

Parameters:

portType - The type of port removed (in range MISC_PORT to WOOD_PORT)

removedPort - If true, the port was removed, not our piece there; affects port-counting logic

Since:

2.0.00

updateLegalShipsAddHex

void updateLegalShipsAddHex(int hexCoord)

When a SOCBoardLarge.FOG_HEX is revealed to be water, or a land hex at the board's margin, update the set of edges used by isLegalShip(int). The revealed hex's edges previously weren't part of the set, because we didn't know if the fog hid land or water.

Called by SOCGame.revealFogHiddenHex(int, int, int). If the hex type isn't SOCBoard.WATER_HEX and ! board.isHexAtBoardMargin(hexCoord), does nothing. Call only if SOCGame.hasSeaBoard.

Parameters:

hexCoord - Coordinate of hex to add if water

Since:

2.0.00

updatePotentials

public void updatePotentials(SOCPlayingPiece piece)

update the arrays that keep track of where this player can play further pieces, after a piece has just been played, or after another player's adjacent piece has been removed.

Special case: In game scenario _SC_PIRI, ship routes can't branch in different directions, only extend from their ends. So when a ship is placed to extend a sea route, this method will remove nearby potential ships which would now be side branches.

Parameters:

piece - a piece that has just been played or our piece adjacent to another player's removed piece

getPotentialSettlements

public java.util.HashSet<java.lang.Integer> getPotentialSettlements()

Get this player's current potential settlement nodes. At the start of the game (before/during initial placement), this is all legal nodes. Afterwards it's mostly empty, and follows from the player's road locations.

Please make no changes, treat the returned set as read-only.

Returns:

the player's set of Integer potential-settlement node coordinates

Since:

2.0.00

See Also:

getPotentialSettlements_arr()

getPotentialSettlements_arr

public int[] getPotentialSettlements_arr()

Get this player's current potential settlement nodes. At the start of the game (before/during initial placement), this is all legal nodes. Afterwards it's mostly empty, and follows from the player's road locations.

This variant returns them as an array, for ease of use when traversing all potential settlements.

Returns:

the player's set of potential-settlement node coordinates, or if none, null

Since:

2.0.00

See Also:

getPotentialSettlements()

setPotentialAndLegalSettlements

public void setPotentialAndLegalSettlements(java.util.Collection<java.lang.Integer> psList,
                                            boolean setLegalsToo,
                                            java.util.HashSet<java.lang.Integer>[] legalLandAreaNodes)

Set which nodes are potential settlements. Called at client when joining/creating a game when game's Potential Settlements message is received. At server, unless SOCGame.hasSeaBoard, the potentials list is instead copied at start of game from legalSettlements.

If our game uses the large sea board (SOCGame.hasSeaBoard), and setLegalsToo, and psList is not empty, then also update the player's legal settlements and legal road sets, since they aren't constant on that type of board; don't call this method before calling SOCBoardLarge.setLegalAndPotentialSettlements(Collection, int, HashSet[]), or the road sets won't be complete.

Call this method before, not after, calling setRestrictedLegalShips(int[]). However, if the player already has a restricted legal ship edge list, this method won't clear it.

This method is called at the server only when game.hasSeaBoard, just after makeNewBoard in SOCGame.startGame().

Before v2.0.00, this method was called setPotentialSettlements.

Parameters:

psList - the list of potential settlements, a Vector or HashSet of Integer node coordinates

setLegalsToo - If true, also update legal settlements/roads/ships if we're using the large board layout. [Parameter added in v2.0.00]

In scenario _SC_PIRI, for efficiency, the legal ships list will remain empty until setRestrictedLegalShips(int[]) is called.

legalLandAreaNodes - If non-null and setLegalsToo, all Land Areas' legal (but not currently potential) node coordinates. Index 0 is ignored; land area numbers start at 1.

See Also:

addLegalSettlement(int, boolean)

addLegalSettlement

public void addLegalSettlement(int node,
                               boolean checkAdjacents)

Add this node to the player's legal settlement coordinates, for future possible placement. Used in some scenarios when SOCGame.hasSeaBoard to add a location after calling setPotentialAndLegalSettlements(Collection, boolean, HashSet[]). This would be a lone location beyond the usual starting/legal LandAreas on the scenario's board.

Parameters:

node - A node coordinate to add, or 0 to do nothing

checkAdjacents - If true, check adjacent nodes before adding. If node is adjacent to a settlement, it won't be added and getAddedLegalSettlement() won't be updated to node.

Since:

2.0.00

See Also:

isLegalSettlement(int), getAddedLegalSettlement()

canPlaceSettlement

public boolean canPlaceSettlement(int node)

Can a settlement be placed at this node? Calls isPotentialSettlement(int). Does not check getNumPieces(SETTLEMENT). On the large board, checks against SOCBoardLarge.getPlayerExcludedLandAreas().

Parameters:

node - node coordinate

Returns:

True if can place, false otherwise

Since:

2.0.00

See Also:

SOCGame.couldBuildSettlement(int)

isPotentialSettlement

public boolean isPotentialSettlement(int node)

Is this node a potential settlement? True if the location is legal, currently not occupied, no settlement is currently on an adjacent node, and we have an adjacent road or ship. Does not check getNumPieces(SETTLEMENT).

Parameters:

node - the coordinates of a node on the board

Returns:

true if this node is a potential settlement

See Also:

canPlaceSettlement(int)

clearPotentialSettlement

public void clearPotentialSettlement(int node)

Set this node to not be a potential settlement. For use (by robots) when the server denies our request to build at a certain spot.

Parameters:

node - coordinates of a node on the board

Since:

1.1.09

See Also:

isPotentialSettlement(int)

isLegalSettlement

public boolean isLegalSettlement(int node)

Is this node to a legal settlement?

Parameters:

node - the coordinates of a node on the board

Returns:

true if this edge is a legal settlement

Since:

2.0.00

See Also:

getAddedLegalSettlement()

getAddedLegalSettlement

public int getAddedLegalSettlement()

Get the legal-settlement location, if any, added by addLegalSettlement(int, boolean).

That method could be called multiple times, but only the most recently added node is returned by this method.

Returns:

Legal settlement node added by most recent call to addLegalSettlement(int, boolean), or 0

Since:

2.0.00

isPotentialCity

public boolean isPotentialCity(int node)

Is this node a potential city? True if we currently have a settlement there. Does not check getNumPieces(CITY).

Parameters:

node - the coordinates of a node on the board

Returns:

true if this node is a potential city

clearPotentialCity

public void clearPotentialCity(int node)

Set this node to not be a potential city. For use (by robots) when the server denies our request to build at a certain spot.

Parameters:

node - coordinates of a node on the board

Since:

1.1.09

See Also:

isPotentialCity(int)

isPotentialRoad

public boolean isPotentialRoad(int edge)

Is this edge a potential road? True if the location is legal, currently not occupied, and we have an adjacent road, settlement, or city. Does not check getNumPieces(ROAD).

Parameters:

edge - the coordinates of an edge on the board. Accepts -1 for edge 0x00.

Returns:

true if this edge is a potential road

clearPotentialRoad

public void clearPotentialRoad(int edge)

Set this edge to not be a potential road. For use (by robots) when the server denies our request to build at a certain spot.

Parameters:

edge - coordinates of an edge on the board. Accepts -1 for edge 0x00.

Since:

1.1.09

See Also:

isPotentialRoad(int)

isLegalRoad

public boolean isLegalRoad(int edge)

Parameters:

edge - the coordinates of an edge on the board. Accepts -1 for edge 0x00; any other negative value returns false.

Returns:

true if this edge is a legal road

isPotentialShipMoveTo

public boolean isPotentialShipMoveTo(int toEdge,
                                     int fromEdge)

Is this edge coordinate a potential place to move a ship, even if another ship edge was not? Used by SOCGame.canMoveShip(int, int, int) to check the ship's requested new location.

First, toEdge must be a potential ship* now. Then, we check to see if even without the ship at fromEdge, toEdge is still potential: If either end node of toEdge has a settlement/city of ours, or has an adjacent edge with a ship of ours (except fromEdge), then toEdge is potential.

*In scenario _SC_PIRI, we check more carefully because after ship placement, nearby potential ships are removed to prevent any branching of the ship route. This would make it impossible to move the route's newest ship to its other potential direction from the previous node.

Parameters:

toEdge - the coordinates of an edge on the board; isPotentialShip(toEdge) must currently be true.

fromEdge - the ship's current edge coordinate, to ignore when determining if toEdge is still potential.

Returns:

true if this edge is still a potential ship

Since:

2.0.00

See Also:

isPotentialShip(int)

isPotentialShip

public boolean isPotentialShip(int edge)

Is this edge a potential ship? True if the location is legal, currently not occupied, we have an adjacent ship, settlement, or city, and SOCGame.hasSeaBoard, Does not check getNumPieces(SHIP).

Parameters:

edge - the coordinates of an edge on the board

Returns:

true if this edge is a potential ship; if not SOCGame.hasSeaBoard, always returns false because the player has no potential ship locations.

Since:

2.0.00

See Also:

isPotentialShipMoveTo(int, int), SOCGame.canPlaceShip(SOCPlayer, int)

clearPotentialShip

public void clearPotentialShip(int edge)

Set this edge to not be a potential ship. For use (by robots) when the server denies our request to build at a certain spot.

Parameters:

edge - coordinates of an edge on the board

Since:

2.0.00

See Also:

isPotentialRoad(int)

isLegalShip

public boolean isLegalShip(int edge)

Is this edge a legal ship placement?

Parameters:

edge - the coordinates of an edge on the board

Returns:

true if this edge is a legal ship

Since:

2.0.00

getRestrictedLegalShips

public java.util.HashSet<java.lang.Integer> getRestrictedLegalShips()

A list of edges where the player can build ships, if the legal sea edges for ships are restricted by the game's scenario (_SC_PIRI), or null if all sea edges are legal for ships. If the player has no legal ship edges, this list is empty (not null).

Please treat the returned HashSet as read-only.

Returns:

Legal sea edges if they're restricted, or null

Since:

2.0.00

setRestrictedLegalShips

public void setRestrictedLegalShips(int[] edgeList)

Set the list of edges where the player can build ships, when the legal sea edges for ships are restricted by the game's scenario (_SC_PIRI).

Parameters:

edgeList - List of edges, same format as one player's array from SOCBoardLargeAtServer.getLegalSeaEdges(SOCGame, int); or an empty array (length 0) for vacant players with no legal ship edges; or null for unrestricted ship placement.

If edgeList is null and the player previously had a restricted ship edge list, will call SOCBoardLarge.initPlayerLegalShips() to unrestrict the player's legal ship positions. If the game is already in progress, this naive call will include any no-longer-legal ships due to placed pieces.

Since:

2.0.00

hasPotentialRoad

public boolean hasPotentialRoad()

Returns:

true if there is at least one potential road

hasPotentialSettlement

public boolean hasPotentialSettlement()

Returns:

true if there is at least one potential settlement

hasPotentialCity

public boolean hasPotentialCity()

Returns:

true if there is at least one potential city

hasPotentialShip

public boolean hasPotentialShip()

Does this player have a potential edge to place a ship on, in a game using the large sea board?

Returns:

true if there is at least one potential ship

Since:

2.0.00

canBuildInitialPieceType

public boolean canBuildInitialPieceType(int pieceType)
                                 throws java.lang.IllegalStateException

Can this player build this piece type now, based on their pieces so far? Initial placement order is Settlement, Road/Ship, Settlement, Road/Ship. Once 2 settlements and 2 roads/ships have been placed, any piece type is valid.

Ignores the specific gameState (any initial state is OK). Ships are allowed only when SOCGame.hasSeaBoard.

Parameters:

pieceType - Piece type, such as SOCPlayingPiece.SETTLEMENT

Returns:

true if this piece type is the next to be placed

Throws:

java.lang.IllegalStateException - if gameState is past initial placement (> SOCGame.START3B)

Since:

1.1.12

calcLongestRoad2

public int calcLongestRoad2()

Calculates the longest road / longest trade route for this player

Returns:

the length of the longest road for this player

getPortMovePotentialLocations

public java.util.List<java.lang.Integer> getPortMovePotentialLocations(boolean all)

For scenario option _SC_FTRI, calculate if the player has any coastal settlement or city where they can place a moved "gift" port without it being adjacent to another port, and the edges where it could be placed next to such settlements or cities.

Parameters:

all - Return all such edges (for placement browsing), or just one (to see if they have any)?

Returns:

One or all potential coastal edge locations to place a moved port, or null if none

Since:

2.0.00

See Also:

SOCGame.canPlacePort(SOCPlayer, int)

setPortFlag

public void setPortFlag(int portType,
                        boolean value)

set a port flag

Parameters:

portType - the type of port; in range SOCBoard.MISC_PORT to SOCBoard.WOOD_PORT

value - true or false

getPortFlag

public boolean getPortFlag(int portType)

Parameters:

portType - the type of port; in range SOCBoard.MISC_PORT to SOCBoard.WOOD_PORT

Returns:

the port flag for a type of port

getPortFlags

public boolean[] getPortFlags()

Returns:

the ports array

numpieces

public java.lang.StringBuffer numpieces(java.lang.StringBuffer sb)

for debug prints; appends to sb or creates it, returns it

Since:

1.1.12

destroyPlayer

public void destroyPlayer()

set vars to null so gc can clean up

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object