SOCBoard

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

soc.game
Class SOCBoard

java.lang.Object
  soc.game.SOCBoard

All Implemented Interfaces:: java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:: SOCBoardLarge

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

This is a representation of the board in Settlers of Catan. Board initialization is done in makeNewBoard(Map); that method has some internal comments on structures, coordinates, layout and values.

Because some game variants may need different board layouts or features, you may need a subclass of SOCBoard: Use SOCBoard.BoardFactory.createBoard(Map, boolean, int) whenever you need to construct a new SOCBoard.

A SOCGame uses this board; the board is not given a reference to the game, to enforce layering and keep the board logic simple. Game rules should be enforced at the game, not the board. Calling board methods won't change the game state.

To identify nearby nodes, edges, hexes, etc, use the methods with names such as getAdjacentHexesToNode(int).

Other methods to examine the board: SOCGame.getPlayersOnHex(int), SOCGame.putPiece(SOCPlayingPiece), etc.

Geometry/Navigation methods:

	Adjacent to a:
Get the:	Hex	Edge	Node
Hex	`getAdjacentHexesToHex(int, boolean)`	`getAdjacentHexToEdge(int, int)`	`getAdjacentHexesToNode(int)`
Edge	-	`getAdjacentEdgesToEdge(int)`	`getAdjacentEdgeToNode(int, int)` `getAdjacentEdgeToNode2Away(int, int)` `getAdjacentEdgesToNode(int)` `getAdjacentEdgesToNode_arr(int)` `getEdgeBetweenAdjacentNodes(int, int)` `isEdgeAdjacentToNode(int, int)`
Node	`getAdjacentNodeToHex(int, int)` `getAdjacentNodesToHex(int)`	`getAdjacentNodesToEdge(int)` `getAdjacentNodesToEdge_arr(int)` `getAdjacentNodeFarEndOfEdge(int, int)`	`getAdjacentNodeToNode(int, int)` `getAdjacentNodeToNode2Away(int, int)` `getAdjacentNodesToNode(int)` `getAdjacentNodesToNode_arr(int)` `isNodeAdjacentToNode(int, int)` `isNode2AwayFromNode(int, int)`
Other methods:	Hex	Edge	Node
	`isHexOnLand(int)` `isHexOnWater(int)` `getNumberOnHexFromCoord(int)` `getNumberOnHexFromNumber(int)` `getHexTypeFromCoord(int)` `getHexTypeFromNumber(int)` `getHexNumFromCoord(int)` `getRobberHex()` `getPreviousRobberHex()` `getHexLayout()` `getLandHexCoords()`	`roadAtEdge(int)` `getPortsEdges()`	`isNodeOnLand(int)` `settlementAtNode(int)` `getPortTypeFromNodeCoord(int)`

See also SOCBoardLarge which has more geometry methods.

Coordinate system, as seen in appendix A of Robert S Thomas' dissertation:

Hexes (represented as coordinate of their centers), nodes (corners of hexes; where settlements/cities are placed), and edges (between nodes; where roads are placed), share the same grid of coordinates. Each hex is 2 units wide, in a 2-D coordinate system.

Current coordinate encodings: v1 (BOARD_ENCODING_ORIGINAL), v2 (BOARD_ENCODING_6PLAYER), v3 (BOARD_ENCODING_LARGE).

On the 4-player board: See src/docs/hexcoord.gif
Coordinates start with hex (1,1) on the far west, and go to (D,D) on the east. The ring of water hexes surrounding land, is within these coordinates. (Land hexes in that row are (3,3) to (B,B). The first axis runs northwest to southeast; the second runs southwest to northeast. Having six sides, hexes run in a straight line west to east, separated by vertical edges; both coordinates increase along a west-to-east line.

All coordinates are encoded as two-digit hex integers, one digit per axis (thus 00 to FF). The center hex is encoded as 77; see the dissertation PDF's appendix for diagrams. Unfortunately this format means the board can't be expanded without changing its encoding, which is used across the network.

On the 6-player board: See src/docs/hexcoord-6player.gif
The 6-player board is rotated 90 degrees clockwise from the 4-player board, so coordinates start with hex (1,1) as the northernmost land hex, and hex (B,B) is the southernmost land hex. The ring of water hexes are outside this coordinate grid.

For the large sea board (encoding v3: BOARD_ENCODING_LARGE), see subclass SOCBoardLarge. Remember that ship pieces extend the SOCRoad class. Most methods of SOCBoard, SOCGame and SOCPlayer differentiate them (SOCPlayer.hasPotentialRoad() vs SOCPlayer.hasPotentialShip()), but a few methods group them together:

On the large sea board, there can optionally be multiple "land areas" (groups of islands), if SOCBoardLarge.getLandAreasLegalNodes() != null.

Author:: Robert S Thomas
See Also:: SOCBoardLarge, Serialized Form

Nested Class Summary
`static interface`	`SOCBoard.BoardFactory` Board Factory for creating new boards for games at the client or server.
`static class`	`SOCBoard.DefaultBoardFactory` Default implementation of `SOCBoard.BoardFactory`, used at client.

Field Summary
`static int`	`BOARD_ENCODING_6PLAYER` 6-player format (v2) for `getBoardEncodingFormat()`: Land hexes are same encoding as `BOARD_ENCODING_ORIGINAL`.
`static int`	`BOARD_ENCODING_LARGE` Sea board format (v3) for `getBoardEncodingFormat()`: Allows up to 127 x 127 board with an arbitrary mix of land and water tiles.
`static int`	`BOARD_ENCODING_ORIGINAL` Original format (v1) for `getBoardEncodingFormat()`: Hexadecimal 0x00 to 0xFF along 2 diagonal axes.
`protected int`	`boardEncodingFormat` The encoding format of board coordinates, or `BOARD_ENCODING_ORIGINAL` (default, original).
`protected int`	`boardHeight` Maximum valid coordinate value; size of board in coordinates (not in number of hexes across).
`protected int`	`boardWidth` Maximum valid coordinate value; size of board in coordinates (not in number of hexes across).
`protected java.util.Vector<SOCCity>`	`cities` cities on the board; Vector of SOCPlayingPiece
`static int`	`CLAY_HEX` Clay; lowest-numbered hex type.
`static int`	`CLAY_PORT` Clay port type.
`static int`	`CLAY_PORT_HEX`
`static int`	`DESERT_HEX` Desert; highest-numbered hex type.
`static int`	`FACING_E` Facing is the direction (1-6) to the hex touching a hex or edge, or from a node to another node 2 nodes away.
`static int`	`FACING_NE` Facing is the direction (1-6) to the hex touching a hex or edge, or from a node to another node 2 nodes away.
`static int`	`FACING_NW` Facing is the direction (1-6) to the hex touching a hex or edge, or from a node to another node 2 nodes away.
`static int`	`FACING_SE` Facing is the direction (1-6) to the hex touching a hex or edge, or from a node to another node 2 nodes away.
`static int`	`FACING_SW` Facing is the direction (1-6) to the hex touching a hex or edge, or from a node to another node 2 nodes away.
`static int`	`FACING_W` Facing is the direction (1-6) to the hex touching a hex or edge, or from a node to another node 2 nodes away.
`static int[]`	`HEXCOORDS_LAND_V1` Land-hex coordinates in standard board (`BOARD_ENCODING_ORIGINAL`).
`static int[]`	`HEXCOORDS_LAND_V2` Land-hex coordinates in 6-player board (`BOARD_ENCODING_6PLAYER`).
`private int[]`	`hexIDtoNum` translate hex ID (hex coordinate) to an array index within `hexLayout`, which is sometimes called its "hex number".
`private int[]`	`hexLayout` Hex data array, one element per water or land (or port, which is special water) hex.
`private static int[]`	`HEXNODES` Offset to add to hex coordinate to get all adjacent node coords, starting at index 0 at the top (northern corner of hex) and going clockwise (RST dissertation figure A.5).
`protected static int[]`	`makeNewBoard_diceNums_v1` Dice numbers in the original 4-player board layout, in order along `numPath` (`makeNewBoard_numPaths_v1`).
`protected static int[]`	`makeNewBoard_diceNums_v2` Dice numbers in the 6-player board layout, in order along `numPath` (`makeNewBoard_numPaths_v2`).
`protected static int[]`	`makeNewBoard_landHexTypes_v1` Land hex types on the original 4-player board layout (v1).
`protected static int[]`	`makeNewBoard_landHexTypes_v2` Land hex types on the 6-player board layout (v2).
`private static int[][]`	`makeNewBoard_numPaths_v1` Possible number paths for 4-player original board.
`private static int[][]`	`makeNewBoard_numPaths_v2` Possible number paths for 6-player board.
`static int`	`MAX_BOARD_ENCODING` Largest value of `getBoardEncodingFormat()` supported in this version.
`private static int`	`MAX_LAND_HEX` Highest-numbered land hex type (`DESERT_HEX`).
`int`	`max_robber_hextype` Maximum hex type value for the robber; can be used for array sizing.
`private int`	`maxEdge` Minimum and maximum edge and node coordinates in this board's encoding.
`protected static int`	`MAXEDGE_V1` largest coordinate value for an edge, in the v1 encoding.
`protected static int`	`MAXEDGE_V2` largest coordinate value for an edge, in the v2 encoding
`protected static int`	`MAXHEX` largest coordinate value for a hex, in the current encoding.
`private static int`	`MAXNODE` largest coordinate value for a node on land, in the v1 and v2 encodings
`private int`	`minEdge` Minimum and maximum edge and node coordinates in this board's encoding.
`protected static int`	`MINEDGE_V1` smallest coordinate value for an edge, in the v1 encoding.
`protected static int`	`MINEDGE_V2` smallest coordinate value for an edge, in the v2 encoding
`protected static int`	`MINHEX` smallest coordinate value for a hex, in the current encoding.
`private int`	`minNode` Minimum and maximum edge and node coordinates in this board's encoding.
`protected static int`	`MINNODE_V1` smallest coordinate value for a node on land, in the v1 encoding.
`protected static int`	`MINNODE_V2` smallest coordinate value for a node on land, in the v2 encoding
`static int`	`MISC_PORT` Misc (3-for-1) port; lowest-numbered port-type integer.
`static int`	`MISC_PORT_HEX` Misc (3-for-1) port type; lowest-numbered port-hextype integer
`private static int[]`	`NODE_2_AWAY` Offsets from a node to another node 2 away, indexed by the facing directions: `FACING_NE` is 1, `FACING_E` is 2, etc; `FACING_NW` is 6.
`protected java.util.HashMap<java.lang.Integer,java.lang.Integer>`	`nodeIDtoPortType` translate node ID (node coordinate) to a port's type (`MISC_PORT` to `WOOD_PORT`).
`protected java.util.HashSet<java.lang.Integer>`	`nodesOnLand` a list of nodes on the land of the board; key is node's Integer coordinate, value is Boolean.
`private int[]`	`numberLayout` Dice number from hex numbers.
`private int[]`	`numToHexID` Hex coordinates ("IDs") of each hex number ("hex number" means index within `hexLayout`).
`static int`	`ORE_HEX`
`static int`	`ORE_PORT` Ore port type.
`static int`	`ORE_PORT_HEX`
`private static java.lang.String[][]`	`PORT_DESC_FOR_TYPE` String keys without/with articles for each port type, for `getPortDescForType(int, boolean)`.
`protected java.util.Vector<java.lang.Integer>[]`	`ports` where the ports of each type are; coordinates per port type.
`private static int[]`	`PORTS_EDGE_V1` Each port's 2 node coordinates on standard board.
`private static int[]`	`PORTS_EDGE_V2` Each port's edge coordinate on the 6-player board.
`private static int[]`	`PORTS_FACING_V1` Each port's facing towards land, on the standard board.
`private static int[]`	`PORTS_FACING_V2` Each port's facing, on 6-player board.
`private static int[]`	`PORTS_HEXNUM_V1` Each port's hex number within `hexLayout` on standard board.
`protected static int[]`	`PORTS_TYPE_V1` Each port's type, such as `SHEEP_PORT`, on standard board.
`protected static int[]`	`PORTS_TYPE_V2` Each port's type, such as `SHEEP_PORT`, on 6-player board.
`protected int[]`	`portsLayout` Port information; varies by board layout encoding format.
`private int`	`prevRobberHex` the previous hex coordinate that the robber is in; -1 unless `setRobberHex(rh, true)` was called.
`protected java.util.Random`	`rand` random number generator
`protected java.util.Vector<SOCRoad>`	`roads` roads on the board; Vector of SOCPlayingPiece.
`private int`	`robberHex` the hex coordinate that the robber is in, or -1; placed on desert in `makeNewBoard(Map)`.
`private static long`	`serialVersionUID`
`protected java.util.Vector<SOCSettlement>`	`settlements` settlements on the board; Vector of SOCPlayingPiece
`static int`	`SHEEP_HEX`
`static int`	`SHEEP_PORT` Sheep port type.
`static int`	`SHEEP_PORT_HEX`
`static int`	`WATER_HEX` Water hex; lower-numbered than all land hex types.
`static int`	`WHEAT_HEX`
`static int`	`WHEAT_PORT` Wheat port type.
`static int`	`WHEAT_PORT_HEX`
`static int`	`WOOD_HEX` Wood.
`static int`	`WOOD_PORT` Wood port type; highest-numbered port-type integer.
`static int`	`WOOD_PORT_HEX` Wood port type; highest-numbered port-hextype integer

Constructor Summary
`protected`	`SOCBoard(int boardEncodingFmt, int maxRobberHextype)` Minimal super constructor for subclasses.
`protected`	`SOCBoard(java.util.Map<java.lang.String,SOCGameOption> gameOpts, int maxPlayers)` Create a new Settlers of Catan Board, with the v1 or v2 encoding.

Method Summary
`java.lang.String`	`edgeCoordToString(int edge)` Get the dice roll numbers for hexes on either side of this edge.
`java.util.Vector<java.lang.Integer>`	`getAdjacentEdgesToEdge(int coord)` Get the edge coordinates of the 2 to 4 edges adjacent to this edge.
`int[]`	`getAdjacentEdgesToNode_arr(int coord)` Get the valid edge coordinates adjacent to this node.
`java.util.Vector<java.lang.Integer>`	`getAdjacentEdgesToNode(int coord)` Get the valid edge coordinates adjacent to this node.
`int`	`getAdjacentEdgeToNode(int nodeCoord, int nodeDir)` Given a node, get the valid adjacent edge in a given direction, if any.
`int`	`getAdjacentEdgeToNode2Away(int node, int node2away)` Given an initial node, and a second node 2 nodes away, calculate the edge coordinate (adjacent to the initial node) going towards the second node.
`private void`	`getAdjacentHexes_AddIfOK(java.util.Vector<java.lang.Integer> addTo, boolean includeWater, int hexCoord, int d1, int d2)` Check one possible coordinate for getAdjacentHexesToHex.
`java.util.Vector<java.lang.Integer>`	`getAdjacentHexesToHex(int hexCoord, boolean includeWater)` Make a list of all valid hex coordinates (or, only land) adjacent to this hex.
`java.util.Vector<java.lang.Integer>`	`getAdjacentHexesToNode(int coord)` Get the coordinates of the valid hexes adjacent to this node.
`int`	`getAdjacentHexToEdge(int edgeCoord, int facing)` The hex touching an edge in a given direction, either along its length or at one end node.
`int`	`getAdjacentNodeFarEndOfEdge(int edgeCoord, int nodeCoord)` Get an edge's other adjacent node (its other end).
`int[]`	`getAdjacentNodesToEdge_arr(int coord)` Adjacent node coordinates to an edge.
`java.util.Vector<java.lang.Integer>`	`getAdjacentNodesToEdge(int coord)` Adjacent node coordinates to an edge, within valid range to be on the board.
`int[]`	`getAdjacentNodesToHex(int hexCoord)` The node coordinates adjacent to this hex in all 6 directions.
`int[]`	`getAdjacentNodesToNode_arr(int coord)` Get the valid node coordinates adjacent to this node.
`java.util.Vector<java.lang.Integer>`	`getAdjacentNodesToNode(int coord)` Get the valid node coordinates adjacent to this node.
`int`	`getAdjacentNodeToHex(int hexCoord, int dir)` The node coordinate adjacent to this hex in a given direction.
`int`	`getAdjacentNodeToNode(int nodeCoord, int nodeDir)` Given a node, get the valid adjacent node in a given direction, if any.
`int`	`getAdjacentNodeToNode2Away(int nodeCoord, int facing)` Get the coordinate of another node 2 away, based on a starting node.
`int`	`getBoardEncodingFormat()` Get the encoding format of this board (for coordinates, etc).
`int`	`getBoardHeight()` Height of this board in coordinates (not in number of hexes across.) The maximum row coordinate.
`int`	`getBoardWidth()` Width of this board in coordinates (not in number of hexes across.) The maximum column coordinate.
`java.util.Vector<SOCCity>`	`getCities()` get the list of cities
`int`	`getEdgeBetweenAdjacentNodes(int nodeA, int nodeB)` Given a pair of adjacent node coordinates, get the edge coordinate that connects them.
`int[]`	`getHexLayout()`
`int`	`getHexNumFromCoord(int hexCoord)` Given a hex coordinate, return the hex number (index).
`int`	`getHexTypeFromCoord(int hex)` Given a hex coordinate, return the type of hex
`int`	`getHexTypeFromNumber(int hex)` Given a hex number, return the type of hex
`int[]`	`getLandHexCoords()` The hex coordinates of all land hexes.
`int[]`	`getNumberLayout()` The dice-number layout of dice rolls at each hex number.
`int`	`getNumberOnHexFromCoord(int hex)` Given a hex coordinate, return the dice-roll number on that hex
`int`	`getNumberOnHexFromNumber(int hex)` Given a hex number (index), return the (dice-roll) number on that hex
`java.util.Vector<java.lang.Integer>`	`getPortCoordinates(int portType)`
`static java.lang.String`	`getPortDescForType(int portType, boolean withArticle)` Descriptive text key for a given port type, for i18n `SOCStringManager.get(key)`.
`int`	`getPortsCount()` Get the number of ports on this board.
`int[]`	`getPortsEdges()` Each port's edge coordinate.
`int[]`	`getPortsFacing()` Each port's facing, such as `FACING_NW`.
`int[]`	`getPortsLayout()` On the 6-player (v2 layout) board, each port's type, such as `SHEEP_PORT`.
`private int`	`getPortTypeFromHexType(int hexType)` Given a hex type, return the port type.
`int`	`getPortTypeFromNodeCoord(int nodeCoord)` What type of port is at this node?
`int`	`getPreviousRobberHex()` If the robber has been moved by calling `setRobberHex(int, boolean)` where `rememberPrevious == true`, get the previous coordinate of the robber.
`java.util.Vector<SOCRoad>`	`getRoads()` get the list of roads and ships
`int`	`getRobberHex()`
`java.util.Vector<SOCSettlement>`	`getSettlements()` get the list of settlements
`private void`	`initHexIDtoNumAux(int begin, int end, int num)` Auxiliary method for initializing part of the hexIDtoNum array.
`private void`	`initNodesOnLand()` As part of the constructor, check the `boardEncodingFormat` and initialize `nodesOnLand` accordingly.
`(package private) java.util.HashSet<java.lang.Integer>`	`initPlayerLegalAndPotentialSettlements()` Create and initialize a `SOCPlayer`'s set of legal settlements.
`(package private) java.util.HashSet<java.lang.Integer>`	`initPlayerLegalRoads()` Create and initialize a `SOCPlayer`'s legalRoads set.
`boolean`	`isEdgeAdjacentToNode(int nodeCoord, int edgeCoord)` Determine if this node and edge are adjacent.
`boolean`	`isHexOnLand(int hexCoord)` Is this the coordinate of a land hex (not water)?
`boolean`	`isHexOnWater(int hexCoord)` Is this the coordinate of a water hex (not land)?
`boolean`	`isNode2AwayFromNode(int n1, int n2)` Determine if these 2 nodes are 2 nodes apart on the board, by the node coordinate arithmetic.
`boolean`	`isNodeAdjacentToNode(int nodeA, int nodeB)` Are these nodes adjacent to each other?
`boolean`	`isNodeOnLand(int node)`
`protected boolean`	`makeNewBoard_checkLandHexResourceClumps(java.util.Vector<java.lang.Integer> unvisited, int clumpSize)` Depth-first search to check land hexes for resource clumps.
`private void`	`makeNewBoard_placeHexes(int[] landHex, int[] numPath, int[] number, SOCGameOption optBC)` For `makeNewBoard(Map)`, place the land hexes, number, and robber, after shuffling landHex[].
`protected void`	`makeNewBoard_shufflePorts(int[] portHex, SOCGameOption opt_breakClumps)` For makeNewBoard, shuffle portHex[].
`void`	`makeNewBoard(java.util.Map<java.lang.String,SOCGameOption> opts)` Shuffle the hex tiles and layout a board.
`java.lang.String`	`nodeCoordToString(int node)` Get the dice roll numbers for hexes adjacent to this node.
`protected void`	`placePort(int ptype, int hex, int face, int node1, int node2)` Auxiliary method for placing the port hexes, changing an element of `hexLayout` and setting 2 elements of `nodeIDtoPortType`.
`void`	`putPiece(SOCPlayingPiece pp)` Put a piece on the board.
`void`	`removePiece(SOCPlayingPiece piece)` remove a piece from the board.
`SOCRoad`	`roadAtEdge(int edgeCoord)` If there's a road or ship placed at this edge, find it.
`protected void`	`setBoardBounds(int boardH, int boardW)` For subclass constructor usage, set the board height and width.
`void`	`setBoardEncodingFormat(int fmt)` set the board encoding format.
`void`	`setHexLayout(int[] hl)` set the hexLayout.
`void`	`setNumberLayout(int[] nl)` Set the number layout.
`void`	`setPortsLayout(int[] portTypes)` On the 6-player (v2 layout) board, each port's type, such as `SHEEP_PORT`.
`void`	`setRobberHex(int rh, boolean rememberPrevious)` set where the robber is
`SOCPlayingPiece`	`settlementAtNode(int nodeCoord)` If there's a settlement or city at this node, find it.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

serialVersionUID

private static final long serialVersionUID

See Also:: Constant Field Values

WATER_HEX

public static final int WATER_HEX

Water hex; lower-numbered than all land hex types. Before v2.0.00, value was 6 instead of 0.

See Also:: isHexOnLand(int), isHexOnWater(int), CLAY_HEX, MAX_LAND_HEX, Constant Field Values

CLAY_HEX

public static final int CLAY_HEX

Clay; lowest-numbered hex type. Same numeric value as SOCResourceConstants.CLAY.

See Also:: WATER_HEX, Constant Field Values

ORE_HEX

public static final int ORE_HEX

See Also:: Constant Field Values

SHEEP_HEX

public static final int SHEEP_HEX

See Also:: Constant Field Values

WHEAT_HEX

public static final int WHEAT_HEX

See Also:: Constant Field Values

WOOD_HEX

public static final int WOOD_HEX

Wood. As with all land resource hex types, same numeric value as its resource constant SOCResourceConstants.WOOD.

See Also:: Constant Field Values

DESERT_HEX

public static final int DESERT_HEX

Desert; highest-numbered hex type. Also MAX_LAND_HEX for the v1 and v2 board encodings. Before v2.0.00, value was 0 instead of 6.

See Also:: Constant Field Values

MAX_LAND_HEX

private static final int MAX_LAND_HEX

Highest-numbered land hex type (DESERT_HEX).

The v3 encoding has a higher SOCBoardLarge.GOLD_HEX and SOCBoardLarge.FOG_HEX, but they aren't encodable in this class (v1 or v2 encoding) because of MISC_PORT_HEX.

Since:: 1.1.07
See Also:: isHexOnLand(int), isHexOnWater(int), WATER_HEX, Constant Field Values

MISC_PORT_HEX

public static final int MISC_PORT_HEX

Misc (3-for-1) port type; lowest-numbered port-hextype integer

See Also:: Constant Field Values

CLAY_PORT_HEX

public static final int CLAY_PORT_HEX

See Also:: Constant Field Values

ORE_PORT_HEX

public static final int ORE_PORT_HEX

See Also:: Constant Field Values

SHEEP_PORT_HEX

public static final int SHEEP_PORT_HEX

See Also:: Constant Field Values

WHEAT_PORT_HEX

public static final int WHEAT_PORT_HEX

See Also:: Constant Field Values

WOOD_PORT_HEX

public static final int WOOD_PORT_HEX

Wood port type; highest-numbered port-hextype integer

See Also:: Constant Field Values

MISC_PORT

public static final int MISC_PORT

Misc (3-for-1) port; lowest-numbered port-type integer.

Other code such as SOCBoardPanel.drawHex relies on the fact that MISC_PORT == 0 == WATER_HEX, and that the range CLAY_PORT - WOOD_PORT are 1 - 5, and CLAY_HEX == CLAY_PORT.

See Also:: Constant Field Values

CLAY_PORT

public static final int CLAY_PORT

Clay port type. CLAY_PORT == CLAY_HEX.

See Also:: Constant Field Values

ORE_PORT

public static final int ORE_PORT

Ore port type. ORE_PORT == ORE_HEX.

See Also:: Constant Field Values

SHEEP_PORT

public static final int SHEEP_PORT

Sheep port type. SHEEP_PORT == SHEEP_HEX.

See Also:: Constant Field Values

WHEAT_PORT

public static final int WHEAT_PORT

Wheat port type. WHEAT_PORT == WHEAT_HEX.

See Also:: Constant Field Values

WOOD_PORT

public static final int WOOD_PORT

Wood port type; highest-numbered port-type integer. WOOD_PORT == WOOD_HEX.

See Also:: Constant Field Values

FACING_NE

public static final int FACING_NE

Facing is the direction (1-6) to the hex touching a hex or edge, or from a node to another node 2 nodes away. Facing 1 is NE, 2 is E, 3 is SE, 4 is SW, etc; used in hexLayout for ports, and elsewhere.

      6 <--.    .--> 1
            \/\/
            /  \
       5<--|    |--> 2
           |    |
            \  /
            /\/\
      4 <--.    .--> 3

Since:: 1.1.08
See Also:: Constant Field Values

FACING_E

public static final int FACING_E

      6 <--.    .--> 1
            \/\/
            /  \
       5<--|    |--> 2
           |    |
            \  /
            /\/\
      4 <--.    .--> 3

Since:: 1.1.08
See Also:: Constant Field Values

FACING_SE

public static final int FACING_SE

      6 <--.    .--> 1
            \/\/
            /  \
       5<--|    |--> 2
           |    |
            \  /
            /\/\
      4 <--.    .--> 3

Since:: 1.1.08
See Also:: Constant Field Values

FACING_SW

public static final int FACING_SW

      6 <--.    .--> 1
            \/\/
            /  \
       5<--|    |--> 2
           |    |
            \  /
            /\/\
      4 <--.    .--> 3

Since:: 1.1.08
See Also:: Constant Field Values

FACING_W

public static final int FACING_W

      6 <--.    .--> 1
            \/\/
            /  \
       5<--|    |--> 2
           |    |
            \  /
            /\/\
      4 <--.    .--> 3

Since:: 1.1.08
See Also:: Constant Field Values

FACING_NW

public static final int FACING_NW

      6 <--.    .--> 1
            \/\/
            /  \
       5<--|    |--> 2
           |    |
            \  /
            /\/\
      4 <--.    .--> 3

Since:: 1.1.08
See Also:: Constant Field Values

PORTS_TYPE_V1

protected static final int[] PORTS_TYPE_V1

Each port's type, such as SHEEP_PORT, on standard board. Same order as PORTS_FACING_V1. MISC_PORT is 0.

Since:: 1.1.08

PORTS_HEXNUM_V1

private static final int[] PORTS_HEXNUM_V1

Each port's hex number within hexLayout on standard board. Same order as PORTS_FACING_V1: Clockwise from upper-left (hex coordinate 0x17).

Since:: 1.1.08

PORTS_FACING_V1

private static final int[] PORTS_FACING_V1

Each port's facing towards land, on the standard board. Ordered clockwise from upper-left (hex coordinate 0x17). Port Facing is the direction from the port hex/edge, to the land hex touching it which will have 2 nodes where a port settlement/city can be built. Facing 2 is east (FACING_E), 3 is SE, 4 is SW, etc; see hexLayout.

Since:: 1.1.08

PORTS_EDGE_V1

private static final int[] PORTS_EDGE_V1

Each port's 2 node coordinates on standard board. Same order as PORTS_FACING_V1: Clockwise from upper-left (hex coordinate 0x17).

Since:: 1.1.08

PORTS_TYPE_V2

protected static final int[] PORTS_TYPE_V2

Each port's type, such as SHEEP_PORT, on 6-player board. Same order as PORTS_FACING_V2. MISC_PORT is 0.

Since:: 1.1.08

PORTS_FACING_V2

private static final int[] PORTS_FACING_V2

Each port's facing, on 6-player board. Ordered clockwise from upper-left (hex coordinate 0x17, which is land in the V2 layout). Port Facing is the direction from the port hex/edge, to the land hex touching it which will have 2 nodes where a port settlement/city can be built. Within the board orientation (not the rotated visual orientation), facing 2 is east (FACING_E), 3 is SE, 4 is SW, etc.

Since:: 1.1.08

PORTS_EDGE_V2

private static final int[] PORTS_EDGE_V2

Each port's edge coordinate on the 6-player board. This is the edge whose 2 end nodes can be used to build port settlements/cities. Same order as PORTS_FACING_V2: Clockwise from upper-left (hex coordinate 0x17, which is land in the V2 layout).

Since:: 1.1.08

BOARD_ENCODING_ORIGINAL

public static final int BOARD_ENCODING_ORIGINAL

Original format (v1) for getBoardEncodingFormat(): Hexadecimal 0x00 to 0xFF along 2 diagonal axes. Coordinate range on each axis is 0 to 15 decimal. In hex:

   Hexes: 11 to DD
   Nodes: 01 or 10, to FE or EF
   Edges: 00 to EE

See the Dissertation PDF for details.

Since:: 1.1.06
See Also:: Constant Field Values

BOARD_ENCODING_6PLAYER

public static final int BOARD_ENCODING_6PLAYER

6-player format (v2) for getBoardEncodingFormat(): Land hexes are same encoding as BOARD_ENCODING_ORIGINAL. Land starts 1 extra hex west of standard board, and has an extra row of land at north and south end.

Ports are not part of hexLayout because their coordinates wouldn't fit within 2 hex digits. Instead, see getPortTypeFromNodeCoord(int), getPortsEdges(), getPortsFacing(), getPortCoordinates(int) or getPortsLayout().

Since:: 1.1.08
See Also:: Constant Field Values

BOARD_ENCODING_LARGE

public static final int BOARD_ENCODING_LARGE

Sea board format (v3) for getBoardEncodingFormat(): Allows up to 127 x 127 board with an arbitrary mix of land and water tiles. Land, water, and port locations/facings are no longer hardcoded. Use getPortsCount() to get the number of ports. For other port information, use the same methods as in BOARD_ENCODING_6PLAYER.

Activated with SOCGameOption "SBL".

Since:: 2.0.00
See Also:: SOCBoardLarge, Constant Field Values

MAX_BOARD_ENCODING

public static final int MAX_BOARD_ENCODING

Largest value of getBoardEncodingFormat() supported in this version.

Since:: 1.1.08
See Also:: Constant Field Values

boardWidth

protected int boardWidth

Maximum valid coordinate value; size of board in coordinates (not in number of hexes across). Default size per BOARD_ENCODING_ORIGINAL is:

   Hexes: 11 to DD
   Nodes: 01 or 10, to FE or EF
   Edges: 00 to EE

Although this field is protected (not private), please treat it as read-only.

Since:: 1.1.06

boardHeight

protected int boardHeight

Maximum valid coordinate value; size of board in coordinates (not in number of hexes across). Default size per BOARD_ENCODING_ORIGINAL is:

   Hexes: 11 to DD
   Nodes: 01 or 10, to FE or EF
   Edges: 00 to EE

Although this field is protected (not private), please treat it as read-only.

Since:: 1.1.06

minNode

private int minNode

Minimum and maximum edge and node coordinates in this board's encoding. (MAXNODE is the same in the v1 and v2 current encodings.) Not used in v3 (BOARD_ENCODING_LARGE).

Since:: 1.1.08

minEdge

private int minEdge

Minimum and maximum edge and node coordinates in this board's encoding. (MAXNODE is the same in the v1 and v2 current encodings.) Not used in v3 (BOARD_ENCODING_LARGE).

Since:: 1.1.08

maxEdge

private int maxEdge

Minimum and maximum edge and node coordinates in this board's encoding. (MAXNODE is the same in the v1 and v2 current encodings.) Not used in v3 (BOARD_ENCODING_LARGE).

Since:: 1.1.08

boardEncodingFormat

protected int boardEncodingFormat

The encoding format of board coordinates, or BOARD_ENCODING_ORIGINAL (default, original). The board size determines the required encoding format.

1 - Original format: hexadecimal 0x00 to 0xFF. Coordinate range is 0 to 15 (in decimal). Port types and facings encoded within hexLayout.
2 - 6-player board, variant of original format: hexadecimal 0x00 to 0xFF. Coordinate range is 0 to 15 (in decimal). Port types stored in portsLayout. Added in 1.1.08.
3 - Large board (BOARD_ENCODING_LARGE). Coordinate range for rows,columns is each 0 to 255 decimal, or altogether 0x0000 to 0xFFFF hex. Arbitrary mix of land and water tiles. Added in 2.0.00, implemented in SOCBoardLarge. Activated with SOCGameOption "SBL".

Although this field is protected (not private), please treat it as read-only.

Since:: 1.1.06

MAXHEX

protected static final int MAXHEX

largest coordinate value for a hex, in the current encoding.

See Also:: Constant Field Values

MINHEX

protected static final int MINHEX

smallest coordinate value for a hex, in the current encoding.

See Also:: Constant Field Values

MAXEDGE_V1

protected static final int MAXEDGE_V1

largest coordinate value for an edge, in the v1 encoding. Named MAXEDGE before v1.1.11 ; the name change is a reminder that MAXEDGE_V2 represents a different encoding.

Since:: 1.1.11
See Also:: Constant Field Values

MAXEDGE_V2

protected static final int MAXEDGE_V2

largest coordinate value for an edge, in the v2 encoding

Since:: 1.1.08
See Also:: Constant Field Values

MINEDGE_V1

protected static final int MINEDGE_V1

smallest coordinate value for an edge, in the v1 encoding. Named MINEDGE before v1.1.11 ; the name change is a reminder that MINEDGE_V2 has a different value.

Since:: 1.1.11
See Also:: Constant Field Values

MINEDGE_V2

protected static final int MINEDGE_V2

smallest coordinate value for an edge, in the v2 encoding

Since:: 1.1.08
See Also:: Constant Field Values

MAXNODE

private static final int MAXNODE

largest coordinate value for a node on land, in the v1 and v2 encodings

See Also:: Constant Field Values

MINNODE_V1

protected static final int MINNODE_V1

smallest coordinate value for a node on land, in the v1 encoding. Named MINNODE before v1.1.11 ; the name change is a reminder that MINNODE_V2 has a different value.

Since:: 1.1.11
See Also:: Constant Field Values

MINNODE_V2

protected static final int MINNODE_V2

smallest coordinate value for a node on land, in the v2 encoding

Since:: 1.1.08
See Also:: Constant Field Values

HEXCOORDS_LAND_V1

public static final int[] HEXCOORDS_LAND_V1

Land-hex coordinates in standard board (BOARD_ENCODING_ORIGINAL).

Since:: 1.1.08

HEXCOORDS_LAND_V2

public static final int[] HEXCOORDS_LAND_V2

Land-hex coordinates in 6-player board (BOARD_ENCODING_6PLAYER).

Since:: 1.1.08.

hexLayout

private int[] hexLayout

Hex data array, one element per water or land (or port, which is special water) hex. Each element's coordinates on the board ("hex ID") is numToHexID[i]. Each element's value encodes hex type and, if a port, its facing (FACING_NE to FACING_NW).

For land hexes, the dice number on hexLayout[i] is numberLayout[i].

Key to the hexLayout[] values:
Note that hexLayout contains ports only for the v1 encoding (BOARD_ENCODING_ORIGINAL); v2 and v3 use portsLayout instead, and hexLayout contains only water and the land hex types. The v3 encoding (BOARD_ENCODING_LARGE) doesn't use hexLayout at all, instead it has a 2-dimensional hexLayoutLg structure.

       0 : water   WATER_HEX (was 6 before v2.0.00)
       1 : clay    CLAY_HEX
       2 : ore     ORE_HEX
       3 : sheep   SHEEP_HEX
       4 : wheat   WHEAT_HEX
       5 : wood    WOOD_HEX
       6 : desert  DESERT_HEX (was 0 before v2.0.00)  also: MAX_LAND_HEX
       7 : misc port ("3:1") facing land in direction 1 (NorthEast)
                             (this port type is MISC_PORT in getPortTypeFromNodeCoord(int))
       8 : misc port facing 2 (FACING_E)
       9 : misc port facing 3 (FACING_SE)
       10 : misc port facing 4 (FACING_SW)
       11 : misc port facing 5 (FACING_W)
       12 : misc port facing 6 (NorthWest)
       16+: non-misc ("2:1") encoded port

Non-misc ports are encoded here in binary like this:

      (port facing, 1-6)        (kind of port)
              \--> [0 0 0][0 0 0 0] <--/

Kind of port:

        1 : clay  (port type CLAY_PORT in getPortTypeFromNodeCoord(int))
        2 : ore    ORE_PORT
        3 : sheep  SHEEP_PORT
        4 : wheat  WHEAT_PORT
        5 : wood   WOOD_PORT

Port facing is the edge of the port's hex touching land, which contains 2 nodes where player can build a port settlement/city; facing is a number 1-6 (FACING_NE-FACING_NW).

      6 <--.    .--> 1
            \/\/
            /  \
       5<--|    |--> 2
           |    |
            \  /
            /\/\
      4 <--.    .--> 3

For board encoding formats BOARD_ENCODING_ORIGINAL and BOARD_ENCODING_6PLAYER, hexLayout indexes are arranged this way per numToHexID:

       0   1   2   3

     4   5   6   7   8

   9  10  11  12  13  14

15  16  17  18  19  20  21

  22  23  24  25  26  27

    28  29  30  31  32

      33  34  35  36

The 6-player board is visually rotated clockwise 90 degrees; the client's visual "North" (index 15, hex coordinate 0x11) on that board is West internally in the board layout.

See Also:: getHexTypeFromNumber(int), getAdjacentNodeToHex(int, int)

portsLayout

protected int[] portsLayout

Port information; varies by board layout encoding format. Initialized in makeNewBoard(Map) if not null.

v1: Not used in the original board, these are part of hexLayout instead, and this field is null.
v2: On the 6-player (v2 layout) board, each port's type. Same value range as in hexLayout. 1 element per port. Same ordering as PORTS_FACING_V2.
v3: BOARD_ENCODING_LARGE stores more information within the port layout array. n = getPortsCount(). The port types are stored at the beginning, from index 0 to n - 1. The next n indexes store each port's edge coordinate. The next n store each port's facing (towards land).
One scenario there has movable ports; a port's edge might temporarily be -1. Ignore this port if so, it's not currently placed on the board.

Since:: 1.1.08
See Also:: ports

numberLayout

private int[] numberLayout

Dice number from hex numbers. For coord mapping, see numToHexID

numberLayout[i] is the dice number for the land hex stored in hexLayout[i]. The robber hex is 0. Water hexes are -1.

Used in the v1 and v2 encodings (ORIGINAL, 6PLAYER). The v3 encoding (BOARD_ENCODING_LARGE) doesn't use this array, instead it uses SOCBoardLarge.numberLayoutLg.

numToHexID

private int[] numToHexID

Hex coordinates ("IDs") of each hex number ("hex number" means index within hexLayout).

BOARD_ENCODING_ORIGINAL: The hexes in here are the board's land hexes and also the surrounding ring of water/port hexes.
BOARD_ENCODING_6PLAYER: The hexes in here are the board's land hexes and also the unused hexes (rightmost column: 7D - DD - D7).
BOARD_ENCODING_LARGE: Does not use numToHexID or hexLayout; hex coordinate == hex number.

See Also:: hexIDtoNum, nodesOnLand, HEXCOORDS_LAND_V1, HEXCOORDS_LAND_V2, getLandHexCoords()

hexIDtoNum

private int[] hexIDtoNum

translate hex ID (hex coordinate) to an array index within hexLayout, which is sometimes called its "hex number". The numbers in here are the board's land hexes and also the surrounding ring of water/port hexes. Initialized in constructor. Length is >= MAXHEX. A value of -1 means the ID isn't a valid hex number on the board.

See Also:: numToHexID, nodeIDtoPortType

nodeIDtoPortType

protected java.util.HashMap<java.lang.Integer,java.lang.Integer> nodeIDtoPortType

translate node ID (node coordinate) to a port's type (MISC_PORT to WOOD_PORT). Initialized in makeNewBoard(Map). Key = node coordinate as Integer; value = port type as Integer. If the node ID isn't present, that coordinate isn't a valid port on the board.

Since:: 1.1.08
See Also:: ports, portsLayout, hexIDtoNum

HEXNODES

private static final int[] HEXNODES

Offset to add to hex coordinate to get all adjacent node coords, starting at index 0 at the top (northern corner of hex) and going clockwise (RST dissertation figure A.5). Because we're looking at nodes and not edges (corners, not sides, of the hex), these are offset from the set of "facing" directions by 30 degrees. -- see getAdjacent* methods instead

NODE_2_AWAY

private static final int[] NODE_2_AWAY

Offsets from a node to another node 2 away, indexed by the facing directions: FACING_NE is 1, FACING_E is 2, etc; FACING_NW is 6. Used by getAdjacentNodeToNode2Away(int, int). See RST dissertation figure A.2.

Since:: 1.1.12

robberHex

private int robberHex

the hex coordinate that the robber is in, or -1; placed on desert in makeNewBoard(Map). Once the robber is placed on the board, it cannot be removed (cannot become -1 again).

prevRobberHex

private int prevRobberHex

the previous hex coordinate that the robber is in; -1 unless setRobberHex(rh, true) was called.

Since:: 1.1.11

max_robber_hextype

public final int max_robber_hextype

Maximum hex type value for the robber; can be used for array sizing. Same value range as getHexTypeFromCoord(int) for the current board encoding.

Since:: 2.0.00
See Also:: SOCGame.canMoveRobber(int, int)

ports

protected java.util.Vector<java.lang.Integer>[] ports

where the ports of each type are; coordinates per port type. Indexes are port types, MISC_PORT to WOOD_PORT. Values are Vectors of Integer node coordinates; each port will have 2 Integers because it touches 2 nodes. So, the number of ports of a type is ports[type].size() / 2.

See Also:: portsLayout, getPortsEdges()

roads

protected java.util.Vector<SOCRoad> roads

roads on the board; Vector of SOCPlayingPiece. On the large sea board (SOCBoardLarge), also contains all ships on the board.

settlements

protected java.util.Vector<SOCSettlement> settlements

settlements on the board; Vector of SOCPlayingPiece

cities

protected java.util.Vector<SOCCity> cities

cities on the board; Vector of SOCPlayingPiece

rand

protected java.util.Random rand

random number generator

nodesOnLand

protected java.util.HashSet<java.lang.Integer> nodesOnLand

a list of nodes on the land of the board; key is node's Integer coordinate, value is Boolean. nodes on outer edges of surrounding water/ports are not on the board.

See dissertation figure A.2. See also initPlayerLegalAndPotentialSettlements() and getLandHexCoords().

On the large sea board, there can optionally be multiple "land areas" (groups of islands), if SOCBoardLarge.getLandAreasLegalNodes() != null. In that case, nodesOnLand contains all nodes of all land areas.

makeNewBoard_numPaths_v1

private static final int[][] makeNewBoard_numPaths_v1

Possible number paths for 4-player original board. makeNewBoard(Map) randomly chooses one path (one 1-dimensional array) to be used as numPath[] in makeNewBoard_placeHexes(int[], int[], int[], SOCGameOption).

makeNewBoard_numPaths_v2

private static final int[][] makeNewBoard_numPaths_v2

Possible number paths for 6-player board. makeNewBoard(Map) randomly chooses one path (one 1-dimensional array) to be used as numPath[] in makeNewBoard_placeHexes(int[], int[], int[], SOCGameOption).

makeNewBoard_landHexTypes_v1

protected static final int[] makeNewBoard_landHexTypes_v1

Land hex types on the original 4-player board layout (v1). For more information see makeNewBoard_placeHexes(int[], int[], int[], SOCGameOption).

Since:: 2.0.00

makeNewBoard_diceNums_v1

protected static final int[] makeNewBoard_diceNums_v1

Dice numbers in the original 4-player board layout, in order along numPath (makeNewBoard_numPaths_v1). For more information see makeNewBoard_placeHexes(int[], int[], int[], SOCGameOption).

Since:: 2.0.00

makeNewBoard_landHexTypes_v2

protected static final int[] makeNewBoard_landHexTypes_v2

Land hex types on the 6-player board layout (v2). For more information see makeNewBoard_placeHexes(int[], int[], int[], SOCGameOption).

Since:: 2.0.00

makeNewBoard_diceNums_v2

protected static final int[] makeNewBoard_diceNums_v2

Dice numbers in the 6-player board layout, in order along numPath (makeNewBoard_numPaths_v2). For more information see makeNewBoard_placeHexes(int[], int[], int[], SOCGameOption).

Since:: 2.0.00

PORT_DESC_FOR_TYPE

private static final java.lang.String[][] PORT_DESC_FOR_TYPE

String keys without/with articles for each port type, for getPortDescForType(int, boolean). Index 0 == MISC_PORT, 1 == CLAY_PORT, etc.

Since:: 2.0.00

Constructor Detail

SOCBoard

protected SOCBoard(int boardEncodingFmt,
                   int maxRobberHextype)
            throws java.lang.IllegalArgumentException

Minimal super constructor for subclasses. Sets boardEncodingFormat, robberHex, prevRobberHex. Creates empty Vectors for roads, settlements, cities and ports, but not portsLayout. Creates an empty HashSet for nodesOnLand.

Most likely you should also call setBoardBounds(int, int).

Parameters:: boardEncodingFmt - A format constant in the currently valid range: Must be >= BOARD_ENCODING_ORIGINAL and <= MAX_BOARD_ENCODING.; maxRobberHextype - Maximum land hextype value, or maximum hex type the robber can be placed at. Same value range as max_robber_hextype and as your subclass's getHexTypeFromCoord(int) method.
Throws:: java.lang.IllegalArgumentException - if boardEncodingFmt is out of range
Since:: 2.0.00

SOCBoard

protected SOCBoard(java.util.Map<java.lang.String,SOCGameOption> gameOpts,
                   int maxPlayers)
            throws java.lang.IllegalArgumentException

Create a new Settlers of Catan Board, with the v1 or v2 encoding. (For the v3 encoding, instead use a SOCBoardLarge constructor.)

Parameters:: gameOpts - if game has options, map of SOCGameOption; otherwise null.; maxPlayers - Maximum players; must be 4 or 6. (Added in 1.1.08)
Throws:: java.lang.IllegalArgumentException - if maxPlayers is not 4 or 6
See Also:: SOCBoard.BoardFactory.createBoard(Map, boolean, int)

Method Detail

initNodesOnLand

private void initNodesOnLand()

As part of the constructor, check the boardEncodingFormat and initialize nodesOnLand accordingly.

Since:: 2.0.00
See Also:: initPlayerLegalAndPotentialSettlements()

initHexIDtoNumAux

private final void initHexIDtoNumAux(int begin,
                                     int end,
                                     int num)

Auxiliary method for initializing part of the hexIDtoNum array. Between begin and end, increment coord by 0x22, which moves 1 hex to the east. See dissertation figure A.1.

Parameters:: begin - Beginning of coordinate range; end - Ending coordinate - same horizontal row as begin; num - Number to assign to first hexIDtoNum[] within this coordinate range; corresponds to hex's index ("hex number") within hexLayout.

makeNewBoard

public void makeNewBoard(java.util.Map<java.lang.String,SOCGameOption> opts)

Shuffle the hex tiles and layout a board. This is called at server, but not at client; client instead calls methods such as setHexLayout(int[]) or SOCBoardLarge.setLandHexLayout(int[]).

Parameters:: opts - Game options, which may affect tile placement on board, or null. opts must be the same as passed to constructor, and thus give the same size and layout (same getBoardEncodingFormat()).

makeNewBoard_placeHexes

private final void makeNewBoard_placeHexes(int[] landHex,
                                           int[] numPath,
                                           int[] number,
                                           SOCGameOption optBC)
                                    throws java.lang.IllegalArgumentException

For makeNewBoard(Map), place the land hexes, number, and robber, after shuffling landHex[]. Sets robberHex, contents of hexLayout[] and numberLayout[]. Also checks vs game option BC: Break up clumps of # or more same-type hexes/ports (for land hex resource types). Called from makeNewBoard(Map) at server only; client has its board layout sent from the server.

This method does not clear out hexLayout or numberLayout before it starts placement. Since hexLayout's land hex coordinates are hardcoded within numToHexID, it can only be called once per board layout.

Parameters:: landHex - Resource type to place into hexLayout for each land hex; will be shuffled. Values are CLAY_HEX, DESERT_HEX, etc.; numPath - Indexes within hexLayout (also within numberLayout) for each land hex; same array length as landHex[]; number - Numbers to place into numberLayout for each land hex; array length is landHex[].length minus 1 for each desert in landHex[]; optBC - Game option "BC" from the options for this board, or null.
Throws:: java.lang.IllegalArgumentException - if makeNewBoard_checkLandHexResourceClumps(Vector, int) finds an invalid or uninitialized hex coordinate (hex type -1)

makeNewBoard_checkLandHexResourceClumps

protected boolean makeNewBoard_checkLandHexResourceClumps(java.util.Vector<java.lang.Integer> unvisited,
                                                          int clumpSize)
                                                   throws java.lang.IllegalArgumentException

Depth-first search to check land hexes for resource clumps.

Start with the set of all land hexes, and consider them 'unvisited'. Look at each hex in the set, marking them as visited and moving them into new subsets ("clumps") composed of adjacent hexes of the same resource type. Build clumps by immediately visiting those adjacent hexes, and their unvisited same-type adjacents, etc. Once we've visited each hex, check if any clump subset's size is larger than the allowed size.

For the Fog Island (scenario option _SC_FOG on SOCBoardLarge), one land area contains some water. So, unvisited may contain a few water hexes. For performance, in general you should omit water hex locations from unvisited.

Called from makeNewBoard_placeHexes(int[], int[], int[], SOCGameOption). Before v2.0.00, this was part of makeNewBoard_placeHexes.

Parameters:: unvisited - Contains each land hex's coordinate as an Integer; Note: This vector will be modified by the method.
See note above about occasional water hex coordinates in univisited.; clumpSize - Clumps of this size or more are too large. Minimum value is 3, smaller values will always return false.
Returns:: true if large clumps found, false if okay
Throws:: java.lang.IllegalArgumentException - if a hex type is -1 (uninitialized or not a valid hex coordinate)
Since:: 2.0.00

makeNewBoard_shufflePorts

protected void makeNewBoard_shufflePorts(int[] portHex,
                                         SOCGameOption opt_breakClumps)
                                  throws java.lang.IllegalStateException

For makeNewBoard, shuffle portHex[]. Sets no fields, only rearranges the contents of that array. Also checks vs game option BC: Break up clumps of # or more same-type hexes/ports (for ports, the types here are: 3-for-1, or 2-for-1). If the clumps couldn't be broken after 100 tries, give up trying. (Maybe the set doesn't have enough 3-for-1, or is too small overall.)

Parameters:: portHex - Contains port types, 1 per port, as they will appear in clockwise order around the edge of the board. Must not all be the same type. MISC_PORT is the 3-for-1 port type value.; opt_breakClumps - Game option "BC", or null
Throws:: java.lang.IllegalStateException - if opt_breakClumps is set, and all portHex[] elements have the same value

placePort

protected final void placePort(int ptype,
                               int hex,
                               int face,
                               int node1,
                               int node2)

Auxiliary method for placing the port hexes, changing an element of hexLayout and setting 2 elements of nodeIDtoPortType. Adds the 2 nodes to ports[ptype].

Parameters:: ptype - Port type; in range MISC_PORT to WOOD_PORT.; hex - Hex number (index) within hexLayout, or -1 if BOARD_ENCODING_6PLAYER or if you don't want to change hexLayout[hex]'s value.; face - Facing of port towards land; 1 to 6 (FACING_NE to FACING_NW). Ignored if hex == -1.; node1 - Node coordinate 1 of port; node2 - Node coordinate 2 of port

initPlayerLegalRoads

java.util.HashSet<java.lang.Integer> initPlayerLegalRoads()

Create and initialize a SOCPlayer's legalRoads set.

Previously part of SOCPlayer, but moved here in version 1.1.12 to better encapsulate the board coordinate encoding.

Note: If your board is board layout v3 (SOCBoardLarge): Because the v3 board layout varies: At the server, call this after makeNewBoard(Map). At the client, call this after SOCBoardLarge.setLegalAndPotentialSettlements(java.util.Collection, int, HashSet[]).

Returns:: the set of legal edge coordinates for roads, as a new Set of Integers
Since:: 1.1.12

initPlayerLegalAndPotentialSettlements

java.util.HashSet<java.lang.Integer> initPlayerLegalAndPotentialSettlements()

Create and initialize a SOCPlayer's set of legal settlements.

For v1 and v2, you can clone the returned legalSettlements to potentialSettlements.

For v3 (SOCBoardLarge), the potentials may be only a subset of legalSettlements; after makeNewBoard(Map), call SOCBoardLarge.getLegalAndPotentialSettlements() instead of this method.

Previously part of SOCPlayer, but moved here in version 1.1.12 to better encapsulate the board coordinate encoding. In encoding v1 and v2, this is always the same coordinates as nodesOnLand.

Since:: 1.1.12
See Also:: nodesOnLand

getHexLayout

public int[] getHexLayout()
                   throws java.lang.UnsupportedOperationException

Returns:: the hex layout; meaning of values same as hexLayout. Please treat the returned array as read-only.
Throws:: java.lang.UnsupportedOperationException - if the board encoding doesn't support this method; the v1 and v2 encodings do, but v3 (BOARD_ENCODING_LARGE) does not.
See Also:: getLandHexCoords()

getLandHexCoords

public int[] getLandHexCoords()

The hex coordinates of all land hexes.

Before v2.0.00, this was getHexLandCoords().

Returns:: land hex coordinates, in no particular order, or null if none (all water).
Since:: 1.1.08

isHexOnLand

public boolean isHexOnLand(int hexCoord)

Is this the coordinate of a land hex (not water)?

Parameters:: hexCoord - Hex coordinate, between 0 and MAXHEX
Returns:: True if land, false if water or not a valid hex coordinate
Since:: 2.0.00
See Also:: isHexOnWater(int)

isHexOnWater

public boolean isHexOnWater(int hexCoord)

Is this the coordinate of a water hex (not land)?

Parameters:: hexCoord - Hex coordinate, between 0 and MAXHEX
Returns:: True if water, false if land or not a valid hex coordinate
Since:: 2.0.00
See Also:: isHexOnLand(int)

getNumberLayout

public int[] getNumberLayout()
                      throws java.lang.UnsupportedOperationException

The dice-number layout of dice rolls at each hex number. Valid for the v1 and v2 encodings, not v3 (BOARD_ENCODING_LARGE). For v3, call getLandHexCoords() and getNumberOnHexFromCoord(int) instead.

Returns:: the number layout; each element is valued 2-12. The robber hex is 0. Water hexes are -1.
Throws:: java.lang.UnsupportedOperationException - if the board encoding doesn't support this method; the v1 and v2 encodings do, but v3 (BOARD_ENCODING_LARGE) does not.

getPortsLayout

public int[] getPortsLayout()

On the 6-player (v2 layout) board, each port's type, such as SHEEP_PORT. Same value range as in hexLayout. (In the standard board (v1), these are part of hexLayout instead.) Same order as getPortsFacing(): Clockwise from upper-left. The number of ports is getPortsCount().

Note: The v3 layout (BOARD_ENCODING_LARGE) stores more information within the port layout array. The port types are stored at the beginning, from index 0 to getPortsCount()-1. If you call setPortsLayout(int[]), be sure to give it the entire array returned from here.

Returns:: the ports layout, or null if not used in this board encoding format
Since:: 1.1.08
See Also:: getPortTypeFromNodeCoord(int), getPortCoordinates(int)

getPortsFacing

public int[] getPortsFacing()

Each port's facing, such as FACING_NW. Port Facing is the direction from the port hex, to the land hex touching it which will have 2 nodes where a port settlement/city can be built. Same order as getPortsLayout(): Clockwise from upper-left. The length of this array is always getPortsCount().

This method should not be called frequently.

Returns:: the ports' facing
Since:: 1.1.08
See Also:: getPortsEdges()

getPortsEdges

public int[] getPortsEdges()

Each port's edge coordinate. This is the edge whose 2 end nodes can be used to build port settlements/cities. Same order as getPortsLayout(): Clockwise from upper-left. The length of this array is always getPortsCount().

This method should not be called frequently.

A scenario of SOCBoardLarge has movable ports; a port's edge there might temporarily be -1. Ignore this port if so, it's not currently placed on the board. This happens only with SOCBoardLarge (layout encoding v3), not the original or 6-player (v1 or v2) SOCBoard layouts.

Returns:: the ports' edges
Since:: 1.1.08
See Also:: getPortsFacing(), getPortCoordinates(int)

getRobberHex

public int getRobberHex()

Returns:: coordinate where the robber is, or -1 if not on the board
See Also:: getPreviousRobberHex(), SOCBoardLarge.getPirateHex()

getPreviousRobberHex

public int getPreviousRobberHex()

If the robber has been moved by calling setRobberHex(int, boolean) where rememberPrevious == true, get the previous coordinate of the robber.

Returns:: hex coordinate where the robber was, or -1
Since:: 1.1.11
See Also:: getRobberHex()

setBoardEncodingFormat

public void setBoardEncodingFormat(int fmt)
                            throws java.lang.IllegalArgumentException

set the board encoding format. Intended for client-side use.

Parameters:: fmt - Board encoding format number
Throws:: java.lang.IllegalArgumentException - if fmt < 1 or > MAX_BOARD_ENCODING

setHexLayout

public void setHexLayout(int[] hl)
                  throws java.lang.UnsupportedOperationException

set the hexLayout. Please call setBoardEncodingFormat(int) first, unless the format is BOARD_ENCODING_ORIGINAL.

Parameters:: hl - the hex layout. For BOARD_ENCODING_ORIGINAL: if hl[0] is WATER_HEX, the board is assumed empty and ports arrays won't be filled.
Throws:: java.lang.UnsupportedOperationException - if the board encoding doesn't support this method; the v1 and v2 encodings do, but v3 (BOARD_ENCODING_LARGE) does not.

setPortsLayout

public void setPortsLayout(int[] portTypes)

On the 6-player (v2 layout) board, each port's type, such as SHEEP_PORT. (In the standard board (v1), these are part of hexLayout instead.) Same order as PORTS_FACING_V2: Clockwise from upper-left.

Note: The v3 layout (BOARD_ENCODING_LARGE) stores more information within the port layout array. If you call setPortsLayout(int[]), be sure you are giving all information returned by getPortsLayout(), not just the port types.

Since:: 1.1.08
See Also:: getPortsLayout()

getPortTypeFromHexType

private final int getPortTypeFromHexType(int hexType)

Given a hex type, return the port type. Used in BOARD_ENCODING_ORIGINAL to set up port info in setHexLayout(int[]).

Parameters:: hexType - the hex type, as in hexLayout
Returns:: the type of port given a hex type; in range MISC_PORT to WOOD_PORT. If called on a non-port hex, returns 0 (which is MISC_PORT).
See Also:: getHexTypeFromCoord(int), getPortTypeFromNodeCoord(int)

setNumberLayout

public void setNumberLayout(int[] nl)
                     throws java.lang.UnsupportedOperationException

Set the number layout. Valid for the v1 and v2 encodings, not v3 (BOARD_ENCODING_LARGE). For v3, call SOCBoardLarge.setLandHexLayout(int[]) instead.

Parameters:: nl - the number layout, from getNumberLayout()
Throws:: java.lang.UnsupportedOperationException - if the board encoding doesn't support this method; the v1 and v2 encodings do, but v3 (BOARD_ENCODING_LARGE) does not.

setRobberHex

public void setRobberHex(int rh,
                         boolean rememberPrevious)
                  throws java.lang.IllegalArgumentException

set where the robber is

Parameters:: rh - the new robber hex coordinate; must be > 0, not validated beyond that; rememberPrevious - Should we remember the old robber hex? (added in 1.1.11)
Throws:: java.lang.IllegalArgumentException - if rh <= 0
See Also:: getRobberHex(), getPreviousRobberHex(), SOCBoardLarge.setPirateHex(int, boolean)

getPortsCount

public int getPortsCount()

Get the number of ports on this board. The original and 6-player board layouts each have a constant number of ports. The v3 layout (BOARD_ENCODING_LARGE) has a varying amount of ports, set during makeNewBoard(Map).

Returns:: the number of ports on this board; might be 0 if makeNewBoard(Map) hasn't been called yet.
Since:: 2.0.00

getPortCoordinates

public java.util.Vector<java.lang.Integer> getPortCoordinates(int portType)

Parameters:: portType - the type of port; in range MISC_PORT to WOOD_PORT.
Returns:: the list of node coordinates for a type of port; each element is an Integer
See Also:: getPortTypeFromNodeCoord(int), getPortsLayout(), getPortsEdges()

getPortTypeFromNodeCoord

public int getPortTypeFromNodeCoord(int nodeCoord)

What type of port is at this node?

Parameters:: nodeCoord - the coordinates for a node
Returns:: the type of port (in range MISC_PORT to WOOD_PORT), or -1 if no port at this node
Since:: 1.1.08
See Also:: getPortDescForType(int, boolean)

getPortDescForType

public static java.lang.String getPortDescForType(int portType,
                                                  boolean withArticle)

Descriptive text key for a given port type, for i18n SOCStringManager.get(key).

From v1.1.08 through all v1.1.xx, this method was in SOCBoardPanel.

Parameters:: portType - Port type, as from getPortTypeFromNodeCoord(int). Should be in range MISC_PORT to WOOD_PORT, or -1.; withArticle - If true, string key's value format is "a 2:1 clay port", if false "2:1 Clay port"
Returns:: Key for port text description, or null for -1 (no port at node). Text format is "3:1 Port" or "2:1 Wood port". Defaults to generic type if portType value is unknown.
Since:: 2.0.00

getNumberOnHexFromCoord

public int getNumberOnHexFromCoord(int hex)

Given a hex coordinate, return the dice-roll number on that hex

Parameters:: hex - the coordinates ("ID") for a hex
Returns:: the dice-roll number on that hex, or 0 if not a hex coordinate
See Also:: getNumberOnHexFromNumber(int)

getNumberOnHexFromNumber

public int getNumberOnHexFromNumber(int hex)

Given a hex number (index), return the (dice-roll) number on that hex

Parameters:: hex - the number of a hex, or -1 if invalid
Returns:: the dice-roll number on that hex, or 0
See Also:: getNumberOnHexFromCoord(int)

getHexNumFromCoord

public int getHexNumFromCoord(int hexCoord)
                       throws java.lang.UnsupportedOperationException

Given a hex coordinate, return the hex number (index). Valid only for the v1 and v2 board encoding, not v3.

Parameters:: hexCoord - the coordinates ("ID") for a hex
Returns:: the hex number (index in numberLayout), or -1 if hexCoord isn't a hex coordinate on the board
Throws:: java.lang.UnsupportedOperationException - if the board encoding doesn't support this method; the v1 and v2 encodings do, but v3 (BOARD_ENCODING_LARGE) does not.
Since:: 1.1.08
See Also:: getHexTypeFromCoord(int)

getHexTypeFromCoord

public int getHexTypeFromCoord(int hex)

Given a hex coordinate, return the type of hex

Parameters:: hex - the coordinates ("ID") for a hex
Returns:: the type of hex: Land in range CLAY_HEX to WOOD_HEX, or DESERT_HEX, or MISC_PORT_HEX or another port type (CLAY_PORT_HEX, etc), or WATER_HEX or -1 for invalid hex coordinate
See Also:: getHexNumFromCoord(int), getLandHexCoords()

getHexTypeFromNumber

public int getHexTypeFromNumber(int hex)

Given a hex number, return the type of hex

Parameters:: hex - the number of a hex (its index in hexLayout, not its coordinate), or -1 for invalid
Returns:: the type of hex: Land in range CLAY_HEX to WOOD_HEX, DESERT_HEX, or WATER_HEX, or MISC_PORT_HEX or another port type (CLAY_PORT_HEX, etc). Invalid hex numbers return -1.
See Also:: getHexTypeFromCoord(int)

putPiece

public void putPiece(SOCPlayingPiece pp)

Put a piece on the board.

Call this only after calling pl.putPiece(pp, isTempPiece) for each player.

Parameters:: pp - Piece to place on the board; coordinates are not checked for validity
See Also:: removePiece(SOCPlayingPiece)

removePiece

public void removePiece(SOCPlayingPiece piece)

remove a piece from the board.

If you're calling SOCPlayer.undoPutPiece(SOCPlayingPiece), call this method first.

Parameters:: piece - Piece to be removed from the board (identified by its piece type, coordinate, and player number)
See Also:: putPiece(SOCPlayingPiece)

getRoads

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

get the list of roads and ships

getSettlements

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

get the list of settlements

getCities

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

get the list of cities

getBoardWidth

public int getBoardWidth()

Width of this board in coordinates (not in number of hexes across.) The maximum column coordinate. For the default size, see BOARD_ENCODING_ORIGINAL.

Since:: 1.1.06

getBoardHeight

public int getBoardHeight()

Height of this board in coordinates (not in number of hexes across.) The maximum row coordinate. For the default size, see BOARD_ENCODING_ORIGINAL.

Since:: 1.1.06

setBoardBounds

protected void setBoardBounds(int boardH,
                              int boardW)

For subclass constructor usage, set the board height and width. Does not set node or edge ranges (minNode, maxEdge, etc) because these limits aren't used in all encodings.

Parameters:: boardH - New maximum row coordinate, for getBoardHeight(); boardW - New maximum column coordinate, for getBoardWidth()
Since:: 2.0.00

getBoardEncodingFormat

public int getBoardEncodingFormat()

Get the encoding format of this board (for coordinates, etc). See the encoding constants' javadocs for more documentation.

Returns:: board coordinate-encoding format, such as BOARD_ENCODING_ORIGINAL
Since:: 1.1.06

getAdjacentNodesToEdge

public java.util.Vector<java.lang.Integer> getAdjacentNodesToEdge(int coord)

Adjacent node coordinates to an edge, within valid range to be on the board.

For v1 and v2 encoding, this range is MINNODE_V1 to MAXNODE, or MINNODE_V2 to MAXNODE. For v3 encoding, nodes are around all valid land or water hexes, and the board size is getBoardHeight() x getBoardHeight().

Returns:: the nodes that touch this edge, as a Vector of Integer coordinates
See Also:: getAdjacentNodesToEdge_arr(int)

getAdjacentNodesToEdge_arr

public int[] getAdjacentNodesToEdge_arr(int coord)

Adjacent node coordinates to an edge. Does not check against range MINNODE_V1 to MAXNODE, so nodes in the water (off the land board) may be returned.

Parameters:: coord - Edge coordinate; not checked for validity
Returns:: the nodes that touch this edge, as an array of 2 integer coordinates
Since:: 1.1.08
See Also:: getAdjacentNodesToEdge(int), getAdjacentNodeFarEndOfEdge(int, int)

getAdjacentNodeFarEndOfEdge

public int getAdjacentNodeFarEndOfEdge(int edgeCoord,
                                       int nodeCoord)

Get an edge's other adjacent node (its other end). Calls getAdjacentNodesToEdge_arr(int) and returns the node that isn't nodeCoord.

Parameters:: edgeCoord - Edge coordinate; not checked for validity; nodeCoord - Node at one end of edgeCoord; the opposite end node will be returned.
Returns:: the edge's other end node, opposite nodeCoord
Since:: 2.0.00

getAdjacentEdgesToEdge

public java.util.Vector<java.lang.Integer> getAdjacentEdgesToEdge(int coord)

Get the edge coordinates of the 2 to 4 edges adjacent to this edge.

Parameters:: coord - Edge coordinate; for the 6-player encoding, use 0, not -1, for edge 0x00. Not checked for validity.
Returns:: the valid adjacent edges to this edge, as a Vector of 2 to 4 Integer coordinates

getAdjacentHexesToNode

public java.util.Vector<java.lang.Integer> getAdjacentHexesToNode(int coord)

Get the coordinates of the valid hexes adjacent to this node. These hexes may contain land or water.

Parameters:: coord - Node coordinate. Is not checked for validity.
Returns:: the coordinates (Integers) of the 1 to 3 hexes touching this node

getAdjacentEdgesToNode

public java.util.Vector<java.lang.Integer> getAdjacentEdgesToNode(int coord)

Get the valid edge coordinates adjacent to this node. Calls getAdjacentEdgeToNode(int, int).

Returns:: the edges touching this node, as a Vector of Integer coordinates
See Also:: getAdjacentEdgeToNode(int, int)

getAdjacentEdgesToNode_arr

public final int[] getAdjacentEdgesToNode_arr(int coord)

Get the valid edge coordinates adjacent to this node. In the 6-player layout, valid land nodes/edges are found on the outer ring of the board coordinate system, but some of their adjacent nodes/edges may be "off the board" and thus invalid. Calls getAdjacentEdgeToNode(int, int).

Parameters:: coord - Node coordinate. Is not checked for validity.
Returns:: the edges touching this node, as an array of 3 coordinates. Unused elements of the array are set to -9.
Since:: 1.1.08

getAdjacentEdgeToNode

public int getAdjacentEdgeToNode(int nodeCoord,
                                 int nodeDir)
                          throws java.lang.IllegalArgumentException

Given a node, get the valid adjacent edge in a given direction, if any.

In the 6-player layout, valid land nodes/edges are found on the outer ring of the board coordinate system, but some of their adjacent nodes/edges may be "off the board" and thus invalid.

Parameters:: nodeCoord - Node coordinate to go from; not checked for validity.; nodeDir - 0 for northwest or southwest; 1 for northeast or southeast; 2 for north or south
Returns:: The adjacent edge in that direction, or -9 if none (if off the board)
Throws:: java.lang.IllegalArgumentException - if nodeDir is less than 0 or greater than 2
Since:: 1.1.12
See Also:: getAdjacentEdgesToNode(int), getEdgeBetweenAdjacentNodes(int, int), getAdjacentNodeToNode(int, int)

getEdgeBetweenAdjacentNodes

public int getEdgeBetweenAdjacentNodes(int nodeA,
                                       int nodeB)

Given a pair of adjacent node coordinates, get the edge coordinate that connects them.

Does not check actual roads or other pieces on the board, only uses the calculations in Robert S Thomas' dissertation figures A.7 - A.10.

Parameters:: nodeA - Node coordinate adjacent to nodeB; not checked for validity; nodeB - Node coordinate adjacent to nodeA; not checked for validity
Returns:: edge coordinate, or -9 if nodeA and nodeB aren't adjacent
Since:: 1.1.12
See Also:: getAdjacentEdgesToNode(int), getAdjacentEdgeToNode(int, int)

isEdgeAdjacentToNode

public boolean isEdgeAdjacentToNode(int nodeCoord,
                                    int edgeCoord)

Determine if this node and edge are adjacent. Checking is not as strict as in getAdjacentEdgesToNode(int), so there may be a false positive, but not a false negative.

Parameters:: nodeCoord - Node coordinate; not bounds-checked; edgeCoord - Edge coordinate; checked against minEdge, maxEdge. For the 6-player encoding, use 0, not -1, to indicate edge 0x00.
Returns:: is the edge in-bounds and adjacent?
Since:: 1.1.11
See Also:: getEdgeBetweenAdjacentNodes(int, int)

getAdjacentNodesToNode

public java.util.Vector<java.lang.Integer> getAdjacentNodesToNode(int coord)

Get the valid node coordinates adjacent to this node. Calls getAdjacentNodeToNode(int, int).

Returns:: the nodes adjacent to this node, as a Vector of Integer coordinates
See Also:: isNodeAdjacentToNode(int, int)

getAdjacentNodesToNode_arr

public final int[] getAdjacentNodesToNode_arr(int coord)

Get the valid node coordinates adjacent to this node. In the 6-player layout, valid land nodes/edges are found on the outer ring of the board coordinate system, but some of their adjacent nodes/edges may be "off the board" and thus invalid.

Calls getAdjacentNodeToNode(int, int).

Parameters:: coord - Node coordinate. Is not checked for validity.
Returns:: the nodes touching this node, as an array of 3 coordinates. Unused elements of the array are set to -9.
Since:: 1.1.08
See Also:: isNodeAdjacentToNode(int, int)

isNodeAdjacentToNode

public final boolean isNodeAdjacentToNode(int nodeA,
                                          int nodeB)

Are these nodes adjacent to each other?

Parameters:: nodeA - One node coordinate; not validated; nodeB - Other node coordinate; not validated
Returns:: True if getAdjacentNodesToNode(nodeA) contains nodeB
Since:: 2.0.00
See Also:: getAdjacentNodesToNode(int)

getAdjacentNodeToNode

public int getAdjacentNodeToNode(int nodeCoord,
                                 int nodeDir)
                          throws java.lang.IllegalArgumentException

Given a node, get the valid adjacent node in a given direction, if any.

In the 6-player layout, valid land nodes/edges are found on the outer ring of the board coordinate system, but some of their adjacent nodes/edges may be "off the board" and thus invalid.

Parameters:: nodeCoord - Node coordinate to go from; not checked for validity.; nodeDir - 0 for northwest or southwest; 1 for northeast or southeast; 2 for north or south
Returns:: The adjacent node in that direction, or -9 if none (if off the board)
Throws:: java.lang.IllegalArgumentException - if nodeDir is less than 0 or greater than 2
Since:: 1.1.12
See Also:: getAdjacentNodesToNode(int), getAdjacentNodeToNode2Away(int, int), getAdjacentEdgeToNode(int, int), isNodeAdjacentToNode(int, int)

getAdjacentNodeToNode2Away

public int getAdjacentNodeToNode2Away(int nodeCoord,
                                      int facing)
                               throws java.lang.IllegalArgumentException

Get the coordinate of another node 2 away, based on a starting node. Facing is indexed by the facing directions: FACING_NE is 1, FACING_E is 2, etc; FACING_NW is 6.

Parameters:: nodeCoord - Starting node's coordinate; facing - Facing from node; 1 to 6. This will be one of the 6 directions from a node to another node 2 away. Facing 2 is FACING_E, 3 is FACING_SE, 4 is SW, etc.
Returns:: the node coordinate, or -9 if that node is not on the board.
Throws:: java.lang.IllegalArgumentException - if facing < 1 or facing > 6
Since:: 1.1.12
See Also:: getAdjacentNodeToNode(int, int), getAdjacentEdgeToNode2Away(int, int), isNode2AwayFromNode(int, int)

isNode2AwayFromNode

public boolean isNode2AwayFromNode(int n1,
                                   int n2)

Determine if these 2 nodes are 2 nodes apart on the board, by the node coordinate arithmetic.

Parameters:: n1 - Node coordinate; not validated; n2 - Node coordinate; not validated
Returns:: are these nodes 2 away from each other?
Since:: 1.1.12
See Also:: getAdjacentNodeToNode2Away(int, int)

getAdjacentEdgeToNode2Away

public int getAdjacentEdgeToNode2Away(int node,
                                      int node2away)

Given an initial node, and a second node 2 nodes away, calculate the edge coordinate (adjacent to the initial node) going towards the second node.

Parameters:: node - Initial node coordinate; not validated; node2away - Second node coordinate; should be 2 away, but this is not validated
Returns:: An edge coordinate, adjacent to initial node, in the direction of the second node.
Since:: 1.1.12
See Also:: getAdjacentNodeToNode2Away(int, int)

getAdjacentHexesToHex

public java.util.Vector<java.lang.Integer> getAdjacentHexesToHex(int hexCoord,
                                                                 boolean includeWater)

Make a list of all valid hex coordinates (or, only land) adjacent to this hex. Valid coordinates are those within the board data structures, within MINHEX to MAXHEX, and valid according to getHexNumFromCoord(int).

Coordinate offsets, from Dissertation figure A.4 - adjacent hexes to hex:

    (-2,0)   (0,+2)

 (-2,-2)   x    (+2,+2)

    (0,-2)   (+2,0)

Parameters:: hexCoord - Coordinate ("ID") of this hex; not checked for validity; includeWater - Should water hexes be returned (not only land ones)? Port hexes are water hexes.
Returns:: the hexes that touch this hex, as a Vector of Integer coordinates, or null if none are adjacent (will not return a 0-length vector)
Since:: 1.1.07

getAdjacentHexes_AddIfOK

private final void getAdjacentHexes_AddIfOK(java.util.Vector<java.lang.Integer> addTo,
                                            boolean includeWater,
                                            int hexCoord,
                                            int d1,
                                            int d2)

Check one possible coordinate for getAdjacentHexesToHex.

Parameters:: addTo - the list we're building of hexes that touch this hex, as a Vector of Integer coordinates.; includeWater - Should water hexes be returned (not only land ones)? Port hexes are water hexes.; hexCoord - Coordinate ("ID") of this hex; d1 - Delta along axis 1; d2 - Delta along axis 2
Since:: 1.1.07

getAdjacentNodeToHex

public int getAdjacentNodeToHex(int hexCoord,
                                int dir)
                         throws java.lang.IllegalArgumentException

The node coordinate adjacent to this hex in a given direction. Since all hexes have 6 nodes, all node coordinates are valid if the hex coordinate is valid.

Parameters:: hexCoord - Coordinate ("ID") of this hex; dir - Direction, clockwise from top (northern point of hex): 0 is north, 1 is northeast, etc, 5 is northwest.
Returns:: Node coordinate in that direction
Throws:: java.lang.IllegalArgumentException - if dir < 0 or dir > 5
Since:: 1.1.08

getAdjacentNodesToHex

public int[] getAdjacentNodesToHex(int hexCoord)

The node coordinates adjacent to this hex in all 6 directions. Since all hexes have 6 nodes, all node coordinates are valid if the hex coordinate is valid.

Parameters:: hexCoord - Coordinate of this hex
Returns:: Node coordinate in all 6 directions, clockwise from top (northern point of hex): 0 is north, 1 is northeast, etc, 5 is northwest.
Since:: 2.0.00
See Also:: getAdjacentNodeToHex(int, int)

getAdjacentHexToEdge

public int getAdjacentHexToEdge(int edgeCoord,
                                int facing)
                         throws java.lang.IllegalArgumentException

The hex touching an edge in a given direction, either along its length or at one end node. Each edge touches up to 4 valid hexes.

Parameters:: edgeCoord - The edge's coordinate. maxEdge is 0xCC in v1 and v2 encoding.; facing - Facing from edge; 1 to 6. This will be either a direction perpendicular to the edge, or towards one end. Each end has two facing directions angled towards it; both will return the same hex. Facing 2 is FACING_E, 3 is FACING_SE, 4 is SW, etc.
Returns:: hex coordinate of hex in the facing direction, or 0 if a hex digit would be below 0 after subtraction or above F after addition.
Throws:: java.lang.IllegalArgumentException - if facing < 1 or facing > 6
Since:: 1.1.08

settlementAtNode

public SOCPlayingPiece settlementAtNode(int nodeCoord)

If there's a settlement or city at this node, find it.

Parameters:: nodeCoord - Location coordinate (as returned by SOCBoardPanel.findNode)
Returns:: Settlement or city at nodeCoord, or null

roadAtEdge

public SOCRoad roadAtEdge(int edgeCoord)

If there's a road or ship placed at this edge, find it.

Parameters:: edgeCoord - Location coordinate (as returned by SOCBoardPanel.findEdge)
Returns:: road or ship, or null. Use SOCPlayingPiece.getType() or SOCRoad.isRoadNotShip() to determine the returned piece type. At most one road or ship can be placed at any one edge.

isNodeOnLand

public boolean isNodeOnLand(int node)

Parameters:: node - Node coordinate
Returns:: true if the node is on the land of the board (not water)

nodeCoordToString

public java.lang.String nodeCoordToString(int node)

Get the dice roll numbers for hexes adjacent to this node.

Returns:: a string representation of a node coordinate's adjacent hex dice roll numbers, such as "5/3/6", or if no hexes adjacent, "(node 0x___)"
See Also:: getAdjacentHexesToNode(int)

edgeCoordToString

public java.lang.String edgeCoordToString(int edge)

Get the dice roll numbers for hexes on either side of this edge.

Returns:: a string representation of an edge coordinate's dice numbers, such as "5/3"; if a hex isn't a land hex, its number will be 0.
See Also:: getNumberOnHexFromCoord(int)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

soc.game Class SOCBoard

Geometry/Navigation methods:

serialVersionUID

WATER_HEX

CLAY_HEX

ORE_HEX

SHEEP_HEX

WHEAT_HEX

WOOD_HEX

DESERT_HEX

MAX_LAND_HEX

MISC_PORT_HEX

CLAY_PORT_HEX

ORE_PORT_HEX

SHEEP_PORT_HEX

WHEAT_PORT_HEX

WOOD_PORT_HEX

MISC_PORT

CLAY_PORT

ORE_PORT

SHEEP_PORT

WHEAT_PORT

WOOD_PORT

FACING_NE

FACING_E

FACING_SE

FACING_SW

FACING_W

FACING_NW

PORTS_TYPE_V1

PORTS_HEXNUM_V1

PORTS_FACING_V1

PORTS_EDGE_V1

PORTS_TYPE_V2

PORTS_FACING_V2

PORTS_EDGE_V2

BOARD_ENCODING_ORIGINAL

BOARD_ENCODING_6PLAYER

BOARD_ENCODING_LARGE

MAX_BOARD_ENCODING

boardWidth

boardHeight

minNode

minEdge

maxEdge

boardEncodingFormat

MAXHEX

MINHEX

MAXEDGE_V1

MAXEDGE_V2

MINEDGE_V1

MINEDGE_V2

MAXNODE

MINNODE_V1

MINNODE_V2

HEXCOORDS_LAND_V1

HEXCOORDS_LAND_V2

hexLayout

portsLayout

numberLayout

numToHexID

hexIDtoNum

nodeIDtoPortType

HEXNODES

NODE_2_AWAY

robberHex

prevRobberHex

max_robber_hextype

ports

roads

settlements

cities

rand

nodesOnLand

makeNewBoard_numPaths_v1

makeNewBoard_numPaths_v2

makeNewBoard_landHexTypes_v1

makeNewBoard_diceNums_v1

makeNewBoard_landHexTypes_v2

makeNewBoard_diceNums_v2

soc.game
Class SOCBoard