soc.game
Class SOCInventoryItem

java.lang.Object
  soc.game.SOCInventoryItem

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

SOCDevCard

public class SOCInventoryItem
extends java.lang.Object
implements java.lang.Cloneable

An inventory item, such as a SOCDevCard or a scenario-specific item, held in a player's hand to be played later or kept until scoring at the end of the game.

To see if a player can currently play an inventory item, use SOCGame.canPlayInventoryItem(int, int).

Inventory items must be Cloneable for use in set copy constructors, see clone() for details.

This class provides the methods needed for game logic. For user-visible item names, you must provide i18n keys and possibly override getItemName(SOCGame, boolean, SOCStringManager); see that method for details.

When adding a new kind of inventory item:

• Decide how and when the new kind of item will be played
• Decide which scenario SOCGameOption will use the new kind of item; all code and javadoc updates will check for or mention the option
• Update getItemName(SOCGame, boolean, SOCStringManager)
• Update SOCGame.canPlayInventoryItem(int, int)
• Update SOCGame.playInventoryItem(int)
• Decide if the server will communicate item-related actions using SOCSimpleRequest, SOCSimpleAction or SOCInventoryItemAction messages, or more specific message types. Update those message handlers at clients and at server's SOCGameHandler; search where-used for the message classes that will be used.
• Not all items are placed on the board, and not all of those allow placement to be canceled: check and update isPlayForPlacement(SOCGame, int), SOCGame.cancelPlaceInventoryItem(boolean), SOCGame's javadocs for gameState, oldGameState, and PLACING_INV_ITEM. For cancelable items, set the canCancelPlay flag when calling the constructor.
• If the item is playable, update SOCGame.forceEndTurn() and SOCGameHandler.forceEndGameTurn(SOCGame, String) to return it to the player's inventory if their turn must be ended; search where-used for SOCForceEndTurnResult.getReturnedInvItem().
• If there's already a similar kind of item, search where-used for its SOCGameOption or related constants, and decide if your new kind should be checked at the same places in the code.

Since:

2.0.00

Author:

Jeremy D Monin <jeremy@nand.net>

Field Summary

protected java.lang.String	aStrKey i18n string key for an item of this type, to be resolved by SOCStringManager to something like "a Market (+1VP)"
boolean	canCancelPlay While this item is being played or placed on the board, can placement be canceled? (Not all items can be played or placed.) The canceled item is returned to the player's inventory to be played later.
int	itype This inventory item's identifying type code or Dev Card type, which may be used at client and server and sent over the network to specify this particular kind of item in a game.
private boolean	kept Is this item to be kept in hand until end of game (never state NEW)?
private boolean	playable Is this item playable this turn (state PLAYABLE), not newly given (NEW)?
protected java.lang.String	strKey i18n string key for this type of item, to be resolved by SOCStringManager to something like "Market (1VP)"
private boolean	vpItem Is this item worth Victory Points when kept in inventory?

Constructor Summary

SOCInventoryItem(int type, boolean isPlayable, boolean isKept, boolean isVP, boolean canCancel, java.lang.String strKey, java.lang.String aStrKey)
Create a new generic inventory item.

Method Summary

SOCInventoryItem	clone() For use in set copy constructors, create and return a clone of this SOCInventoryItem.
static SOCInventoryItem	createForScenario(SOCGame ga, int type, boolean isPlayable, boolean isKept, boolean isVP, boolean canCancel) Factory method to create a specific scenario's special items, including item name i18n string keys appropriate for type among the scenario's item types.
java.lang.String	getItemName(SOCGame game, boolean withArticle, SOCStringManager strings) Get the item's name.
boolean	isKept() Is this item to be kept in hand until end of game (never state NEW)?
boolean	isNew() Is this item newly given to a player (state NEW), not isPlayable() or isKept()?
boolean	isPlayable() Is this item playable this turn (state PLAYABLE), not newly given (NEW)?
static boolean	isPlayForPlacement(SOCGame ga, int type) Does this type of item require placement on the board (state SOCGame.PLACING_INV_ITEM) when played? If so, when the item is played, caller should call SOCGame.setPlacingItem(SOCInventoryItem).
boolean	isVPItem() Is this item worth Victory Points when kept in inventory?
void	newToOld() At the start of the holding player's turn, change state from NEW to PLAYABLE.

Methods inherited from class java.lang.Object

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

Field Detail

itype

public final int itype

This inventory item's identifying type code or Dev Card type, which may be used at client and server and sent over the network to specify this particular kind of item in a game.

For dev cards, it would be SOCDevCardConstants.KNIGHT, SOCDevCardConstants.DISC, etc. The type code for items which aren't dev cards should be unique within the game scenario being played, not just unique within its java class, and not overlap with the dev card constants. For a port being moved in scenario _SC_FTRI, it would be negative: -SOCBoard.MISC_PORT, -SOCBoard.SHEEP_PORT, etc.

playable

private boolean playable

Is this item playable this turn (state PLAYABLE), not newly given (NEW)?

kept

private final boolean kept

Is this item to be kept in hand until end of game (never state NEW)?

Items with this flag can either be isPlayable() before keeping, or not. When the item is added to inventory, isPlayable() is checked before isKept() to determine the item's initial state.

See Also:

isVPItem()

vpItem

private final boolean vpItem

Is this item worth Victory Points when kept in inventory?

canCancelPlay

public final boolean canCancelPlay

While this item is being played or placed on the board, can placement be canceled? (Not all items can be played or placed.) The canceled item is returned to the player's inventory to be played later.

strKey

protected final java.lang.String strKey

i18n string key for this type of item, to be resolved by SOCStringManager to something like "Market (1VP)"

aStrKey

protected final java.lang.String aStrKey

i18n string key for an item of this type, to be resolved by SOCStringManager to something like "a Market (+1VP)"

Constructor Detail

SOCInventoryItem

public SOCInventoryItem(int type,
                        boolean isPlayable,
                        boolean isKept,
                        boolean isVP,
                        boolean canCancel,
                        java.lang.String strKey,
                        java.lang.String aStrKey)

Create a new generic inventory item.

See also the factory method for specific scenarios' items: createForScenario(SOCGame, int, boolean, boolean, boolean, boolean)

Parameters:

type - Item or card type code, to be stored in itype

isPlayable - Is this item playable this turn (state PLAYABLE), not newly given (NEW)?

isKept - Is this item to be kept in hand until end of game? See isKept().

isVP - Is this item worth Victory Points when kept in inventory?

canCancel - Can this item's play or placement be canceled? See canCancelPlay.

strKey - i18n string key for this type of item, to be resolved by SOCStringManager to something like "Market (1VP)"

aStrKey - i18m string key for an item of this type, to be resolved by SOCStringManager to something like "a Market (+1VP)"

Method Detail

createForScenario

public static final SOCInventoryItem createForScenario(SOCGame ga,
                                                       int type,
                                                       boolean isPlayable,
                                                       boolean isKept,
                                                       boolean isVP,
                                                       boolean canCancel)

Factory method to create a specific scenario's special items, including item name i18n string keys appropriate for type among the scenario's item types.

Currently recognizes and calls:

• _SC_FTRI: Trade port: SOCBoard.getPortDescForType(-type, withArticle)

Callable at server and client. If client version is older than the scenario, this method will fall back to generic "unknown item" string keys.

Parameters:

ga - Game, to check scenario options and determine kind of item being created

type - Item or card type code, to be stored in itype

isPlayable - Is the item playable this turn?

isKept - Is this item to be kept in hand until end of game? See isKept().

isVP - Is this item worth Victory Points when kept in inventory?

canCancel - Can this item's play or placement be canceled? See canCancelPlay.

Returns:

An inventory item named from this scenario's item types, or with generic name keys if ga doesn't have a scenario option recognized here

isPlayForPlacement

public static final boolean isPlayForPlacement(SOCGame ga,
                                               int type)

Does this type of item require placement on the board (state SOCGame.PLACING_INV_ITEM) when played? If so, when the item is played, caller should call SOCGame.setPlacingItem(SOCInventoryItem).

Parameters:

ga - Game, to check scenario options and determine kind of item being played

type - Item or card type code, from itype

Returns:

True if this item must be placed when played; false if not, or if no known scenario game option is active.

isNew

public boolean isNew()

Is this item newly given to a player (state NEW), not isPlayable() or isKept()?

isPlayable

public boolean isPlayable()

Is this item playable this turn (state PLAYABLE), not newly given (NEW)?

See Also:

isNew(), isKept()

isKept

public boolean isKept()

Is this item to be kept in hand until end of game (never state NEW)?

Items with this flag can either be isPlayable() before keeping, or not. When the item is added to a SOCInventory, isPlayable() is checked before isKept() to determine the item's initial state.

This flag's value never changes during the item's lifetime.

See Also:

isVPItem()

isVPItem

public boolean isVPItem()

Is this item worth Victory Points when kept in inventory?

This flag's value never changes during the item's lifetime.

Returns:

True for VP items, false otherwise

See Also:

isKept()

newToOld

public void newToOld()

At the start of the holding player's turn, change state from NEW to PLAYABLE.

getItemName

public java.lang.String getItemName(SOCGame game,
                                    boolean withArticle,
                                    SOCStringManager strings)

Get the item's name.

Called at server and at client, so any i18n name keys used must be in properties files at server and client.

SOCInventoryItem's implementation just calls strings.get(key) with the string keys passed to the constructor. If you need something more dynamic, override this in your subclass.

Parameters:

game - Game data, or null; some game options might change an item name. For example, _SC_PIRI renames "Knight" to "Warship".

withArticle - If true, format is: "a Market (+1VP)"; if false, is "Market (1VP)"

strings - StringManager to get i18n localized text

Returns:

The localized item name, formatted per withArticle

clone

public SOCInventoryItem clone()
                       throws java.lang.CloneNotSupportedException

For use in set copy constructors, create and return a clone of this SOCInventoryItem. The SOCInventoryItem implementation just calls super.clone().

Overrides:

clone in class java.lang.Object

Returns:

super.clone(), with any object fields deep-copied

Throws:

java.lang.CloneNotSupportedException - Declared from super.clone(), should not occur since SOCInventoryItem implements Cloneable.