SOCGameOption

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 SOCGameOption

java.lang.Object
  soc.game.SOCVersionedItem
      soc.game.SOCGameOption

All Implemented Interfaces:: java.lang.Cloneable, java.lang.Comparable<java.lang.Object>

public class SOCGameOption
extends SOCVersionedItem
implements java.lang.Cloneable, java.lang.Comparable<java.lang.Object>
extends SOCVersionedItem
implements java.lang.Cloneable, java.lang.Comparable<java.lang.Object>

Game-specific options, configurable at game creation. This class has two purposes:

Per-game values of options
Static dictionary of known options; see initAllOptions() for the current list.

To get the list of known options, use getAllKnownOptions().

For information about adding or changing game options in a later version of JSettlers, please see initAllOptions().

All in-game code uses the 2-letter or 3-letter key strings to query and change game option settings; only a very few places use SOCGameOption objects. To search the code for uses of a game option, search for its capitalized key string. You will see calls to SOCGame.isGameOptionDefined(String), SOCGame.getGameOptionIntValue(Map, String, int, boolean), etc. Also search SOCScenario for the option as part of a string, such as "SBL=t,VP=12".

Most option name keys are 2 or 3 characters; before 2.0.00, the maximum length was 3. The maximum key length is now 8, but older clients will reject keys longer than 3.

Option name keys must start with a letter and contain only ASCII uppercase letters ('A' through 'Z') and digits ('0' through '9'), in order to normalize handling and network message formats. This is enforced in constructors via SOCVersionedItem.isAlphanumericUpcaseAscii(String). Version 2.0.00 and newer allow '_'; please check SOCVersionedItem.minVersion, name keys with '_' can't be sent to older clients. Options starting with '_' are meant to be set by the server during game creation, not requested by the client. They're set during adjustOptionsToKnown(opts, null, true).

For the same reason, option string values (and enum choices) must not contain certain characters or span more than 1 line; this is checked by calling SOCMessage.isSingleLineAndSafe(String) within constructors and setters.

The "known options" are initialized via initAllOptions(). See that method's description for more details on adding an option. If a new option changes previously expected behavior of the game, it should default to the old behavior; its default value on your server can be changed at runtime.

Since 1.1.13, when the user changes options while creating a new game, related options can be changed on-screen for consistency; see SOCGameOption.ChangeListener for details. If you create a ChangeListener, consider adding equivalent code to adjustOptionsToKnown(Map, Map, boolean) for the server side.

Sea Board Scenarios:
Game scenarios were introduced with the large sea board in 2.0.00. Game options are used to indicate which scenario events and rules are possible in the current game. These all start with "_SC_" and have a static key string; an example is K_SC_SANY for scenario game option "_SC_SANY".

Version negotiation:
Game options were introduced in 1.1.07; check server, client versions against SOCNewGameWithOptions.VERSION_FOR_NEWGAMEWITHOPTIONS. Each option has version information, because options can be added or changed with new versions of JSettlers. Since games run on the server, the server is authoritative about game options: If the client is newer, it must defer to the server's older set of known options. At client connect, the client compares its JSettlers version number to the server's, and asks for any changes to options if their versions differ.

I18N:
Game option descriptions are also stored as gameopt.* in server/strings/toClient_*.properties to be sent to clients if needed during version negotiation. An option's text can be localized with SOCVersionedItem.setDesc(String).

Since:: 1.1.07
Author:: Jeremy D. Monin <jeremy@nand.net>

Nested Class Summary
`static interface`	`SOCGameOption.ChangeListener` Listener for option value changes at the client during game creation.

Field Summary
`private static java.util.Map<java.lang.String,SOCGameOption>`	`allOptions` Set of "known options".
`private boolean`	`boolValue`
`boolean`	`defaultBoolValue` Default value for boolean part of this option, if any
`int`	`defaultIntValue` Default value for integer part of this option, if any
`java.lang.String[]`	`enumVals` For type `OTYPE_ENUM` and `OTYPE_ENUMBOOL`, descriptive text for each possible value; null for other types.
`static int`	`FLAG_DROP_IF_UNUSED` `optFlags` bitfield constant to indicate option should be dropped if unset/default.
`static int`	`FLAG_INTERNAL_GAME_PROPERTY` `optFlags` bitfield constant to indicate option is an internal property.
`private int`	`intValue`
`static java.lang.String`	`K_SC_0RVP` Scenario key `_SC_0RVP`: No "longest trade route" VP / Longest Road.
`static java.lang.String`	`K_SC_3IP` Scenario key `_SC_3IP`: Third initial placement of settlement and road or ship.
`static java.lang.String`	`K_SC_CLVI` Scenario key `_SC_CLVI` for `SOCScenarioPlayerEvent.CLOTH_TRADE_ESTABLISHED_VILLAGE`: Cloth Trade with neutral `villages`.
`static java.lang.String`	`K_SC_FOG` Scenario key `_SC_FOG` for `SOCScenarioGameEvent.SGE_FOG_HEX_REVEALED`.
`static java.lang.String`	`K_SC_FTRI` Scenario key `_SC_FTRI` for the Forgotten Tribe.
`static java.lang.String`	`K_SC_PIRI` Scenario key `_SC_PIRI` for Pirate Islands and `fortresses`.
`static java.lang.String`	`K_SC_SANY` Scenario key `_SC_SANY` for `SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA`.
`static java.lang.String`	`K_SC_SEAC` Scenario key `_SC_SEAC` for `SOCScenarioPlayerEvent.SVP_SETTLED_EACH_NEW_LANDAREA`.
`static java.lang.String`	`K_SC_WOND` Scenario key `_SC_WOND` for Wonders.
`int`	`maxIntValue` Minumum and maximum permitted values for integer part of this option, if any, or maximum length of a string value.
`int`	`minIntValue` Minumum and maximum permitted values for integer part of this option, if any, or maximum length of a string value.
`private SOCGameOption.ChangeListener`	`optCL` The option's ChangeListener, or null.
`int`	`optFlags` Sum of all of option's flags, if any, such as `FLAG_DROP_IF_UNUSED`.
`int`	`optType` Option type.
`static int`	`OTYPE_BOOL` Option type: boolean
`static int`	`OTYPE_ENUM` Option type: enumeration (1 of several possible choices, described with text strings, stored here as intVal).
`static int`	`OTYPE_ENUMBOOL` Option type: enumeration + boolean; see `OTYPE_ENUM`.
`static int`	`OTYPE_INT` Option type: integer.
`static int`	`OTYPE_INTBOOL` Option type: integer + boolean.
`static int`	`OTYPE_MAX` Highest OTYPE value known at this version
`static int`	`OTYPE_MIN` Lowest OTYPE_ (`optType`) value known at this version
`static int`	`OTYPE_STR` Option type: text string (max string length is `maxIntValue`, default value is "")
`static int`	`OTYPE_STRHIDE` Option type: text string (like `OTYPE_STR`) but hidden from view; is NOT encrypted, but contents show up as "*" when typed into a text field.
`static int`	`OTYPE_UNKNOWN` Option type: unknown (probably due to version mismatch).
`private static java.util.List<SOCGameOption>`	`refreshList` List of options to refresh on-screen after a change during game creation; filled by `refreshDisplay()`.
`private java.lang.String`	`strValue`
`boolean`	`userChanged` Has the user selected a value? False if unchanged, or if changed only by a `SOCGameOption.ChangeListener` or other automatic means.
`static int`	`VERSION_FOR_LONGER_OPTNAMES` Version 2.0.00 introduced longer option keynames (8 characters, earlier max was 3) and underscores '_' in option names.

Fields inherited from class soc.game.SOCVersionedItem
`desc, isKnown, key, lastModVersion, minVersion`

Constructor Summary
`protected`	`SOCGameOption(int otype, java.lang.String key, int minVers, int lastModVers, boolean defaultBoolValue, int defaultIntValue, int minValue, int maxValue, java.lang.String[] enumVals, int flags, java.lang.String desc)` Create a new game option - common constructor.
`protected`	`SOCGameOption(SOCGameOption intOpt, int maxIntValue)` Copy constructor for int-valued types (`OTYPE_INT`, `OTYPE_INTBOOL`), for restricting (trimming) max value for a certain client version.
	`SOCGameOption(SOCGameOption opt, java.lang.String newDesc)` Copy constructor for i18n localization of `getDesc()`.
`protected`	`SOCGameOption(SOCGameOption enumOpt, java.lang.String[] keptEnumVals)` Copy constructor for enum-valued types (`OTYPE_ENUM`, `OTYPE_ENUMBOOL`), for restricting (trimming) values for a certain client version.
	`SOCGameOption(java.lang.String key)` Create a new game option of unknown type (`OTYPE_UNKNOWN`).
	`SOCGameOption(java.lang.String key, int minVers, int lastModVers, boolean defaultBoolValue, int defaultIntValue, int minValue, int maxValue, int flags, java.lang.String desc)` Create a new int+boolean game option (`OTYPE_INTBOOL`).
	`SOCGameOption(java.lang.String key, int minVers, int lastModVers, boolean defaultValue, int flags, java.lang.String desc)` Create a new boolean game option (`OTYPE_BOOL`).
	`SOCGameOption(java.lang.String key, int minVers, int lastModVers, boolean defaultBoolValue, int defaultIntValue, java.lang.String[] enumVals, int flags, java.lang.String desc)` Create a new enumerated + boolean game option (`OTYPE_ENUMBOOL`).
	`SOCGameOption(java.lang.String key, int minVers, int lastModVers, int maxLength, boolean hideTyping, int flags, java.lang.String desc)` Create a new text game option (`OTYPE_STR` or `OTYPE_STRHIDE`).
	`SOCGameOption(java.lang.String key, int minVers, int lastModVers, int defaultValue, int minValue, int maxValue, int flags, java.lang.String desc)` Create a new integer game option (`OTYPE_INT`).
	`SOCGameOption(java.lang.String key, int minVers, int lastModVers, int defaultValue, java.lang.String[] enumVals, int flags, java.lang.String desc)` Create a new enumerated game option (`OTYPE_ENUM`).

Method Summary
`void`	`addChangeListener(SOCGameOption.ChangeListener cl)` Add or remove this option's change listener.
`static boolean`	`addKnownOption(SOCGameOption onew)` Add a new known option (presumably received from a server of newer or older version), or update the option's information.
`static java.lang.StringBuilder`	`adjustOptionsToKnown(java.util.Map<java.lang.String,SOCGameOption> newOpts, java.util.Map<java.lang.String,SOCGameOption> knownOpts, boolean doServerPreadjust)` Compare a set of options with known-good values.
`static java.util.Map<java.lang.String,SOCGameOption>`	`cloneOptions(java.util.Map<java.lang.String,SOCGameOption> opts)` Make a deep copy of a group of options.
`int`	`compareTo(java.lang.Object other)` Compare two options, for display purposes.
`static java.util.Map<java.lang.String,SOCGameOption>`	`getAllKnownOptions()`
`static java.util.List<SOCGameOption>`	`getAndClearRefreshList()` Get the list of `SOCGameOption`s whose `refreshDisplay()` methods have been called, and clear the internal static copy.
`boolean`	`getBoolValue()` Is this option set, if this option's type has a boolean component?
`SOCGameOption.ChangeListener`	`getChangeListener()` Get this option's `SOCGameOption.ChangeListener`, if any
`int`	`getIntValue()` This option's integer value, if this option's type has an integer component.
`static int`	`getMaxEnumValueForVersion(java.lang.String optKey, int vers)` For use at server, for enum options where some values require a newer client version.
`static int`	`getMaxIntValueForVersion(java.lang.String optKey, int vers)` For use at server, for int options where some values require a newer client version.
`int`	`getMinVersion(java.util.Map<?,? extends SOCVersionedItem> opts)` Minimum game version supporting this option, given `SOCVersionedItem.minVersion` and the option's current value.
`static SOCGameOption`	`getOption(java.lang.String key, boolean clone)` Get information about a known option.
`java.lang.StringBuilder`	`getPackedValue()` Form a StringBuilder containing the current value.
`java.lang.String`	`getStringValue()`
`boolean`	`hasChangeListener()` Does this option have a non-null `SOCGameOption.ChangeListener`?
`boolean`	`hasFlag(int flagMask)` Does this game option have these specified flag(s)?
`private static java.util.List<SOCGameOption>`	`implOptionsVersionCheck(int vers, boolean getAllForVersion, boolean checkValues, boolean trimEnums, java.util.Map<java.lang.String,SOCGameOption> opts)` Get all options added or changed since version `vers`, or all options valid at `vers`, to implement `optionsNewerThanVersion(int, boolean, boolean, Map)` and `optionsForVersion(int, Map)`.
`static java.util.Map<java.lang.String,SOCGameOption>`	`initAllOptions()` Create a set of the known options.
`static java.util.List<SOCGameOption>`	`optionsForVersion(int vers, java.util.Map<java.lang.String,SOCGameOption> opts)` Get all options valid at version `vers`.
`static java.util.List<SOCGameOption>`	`optionsNewerThanVersion(int vers, boolean checkValues, boolean trimEnums, java.util.Map<java.lang.String,SOCGameOption> opts)` Compare a set of options against the specified version.
`static java.lang.String`	`optionTypeName(int optType)` For user output, the string name of the option type's constant.
`static java.lang.String`	`packKnownOptionsToString(boolean hideEmptyStringOpts, boolean hideLongNameOpts)` Utility - build a string of option name-value pairs from the `known options`' current values.
`static java.lang.String`	`packOptionsToString(java.util.Map<java.lang.String,SOCGameOption> omap, boolean hideEmptyStringOpts)` Utility - build a string of option name-value pairs.
`static java.lang.String`	`packOptionsToString(java.util.Map<java.lang.String,SOCGameOption> omap, boolean hideEmptyStringOpts, int cliVers)` Utility - build a string of option name-value pairs, adjusting for old clients if necessary.
`void`	`packValue(java.lang.StringBuilder sb)` Pack current value of this option into a string.
`static SOCGameOption`	`parseOptionNameValue(java.lang.String nvpair, boolean forceNameUpcase)` Utility - parse a single name-value pair produced by packOptionsToString.
`static SOCGameOption`	`parseOptionNameValue(java.lang.String optkey, java.lang.String optval, boolean forceNameUpcase)` Utility - parse an option name-value pair produced by `packValue(StringBuilder)` or `packOptionsToString(Map, boolean)`.
`static java.util.Map<java.lang.String,SOCGameOption>`	`parseOptionsToMap(java.lang.String ostr)` Utility - build a map of keys to SOCGameOptions by parsing a list of option name-value pairs.
`void`	`refreshDisplay()` If this game option is displayed on-screen, refresh it; call this after changing the value.
`static void`	`setBoolOption(java.util.Map<java.lang.String,SOCGameOption> newOpts, java.lang.String boKey)` Within a set of options, include a boolean option and make it true.
`void`	`setBoolValue(boolean v)`
`static void`	`setIntOption(java.util.Map<java.lang.String,SOCGameOption> newOpts, java.lang.String ioKey, int ivalue, boolean bvalue)` Within a set of options, include an int or intbool option and set its value.
`void`	`setIntValue(int v)` Set this option's integer value to new value v, or clip to min/max allowed values.
`static void`	`setKnownOptionCurrentValue(SOCGameOption ocurr)` Set the current value(s) of a known option, based on the current value(s) of another object `ocurr` with the same `key`.
`void`	`setStringValue(java.lang.String v)` Set this option's string value to new value v
`java.lang.String`	`toString()` Form a string with the key and current value, useful for debugging purposes.
`static SOCGameOption`	`trimEnumForVersion(SOCGameOption opt, int vers)` Copy this option and restrict its enumerated values (type `OTYPE_ENUM` or similar) by trimming `enumVals` shorter.

Methods inherited from class soc.game.SOCVersionedItem
`findUnknowns, getDesc, implItemsVersionCheck, isAlphanumericUpcaseAscii, itemsForVersion, itemsMinimumVersion, itemsMinimumVersion, itemsNewerThanVersion, setDesc`

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

Field Detail

FLAG_DROP_IF_UNUSED

public static final int FLAG_DROP_IF_UNUSED

optFlags bitfield constant to indicate option should be dropped if unset/default. If this option's value is the default, then server should not add it to game options or send over the network (to reduce overhead). Only recommended if game behavior without the option is well-established (for example, trading is allowed unless option NT is present).

Details:
Should the server drop this option from game options, and not send over the network, if the value is false or blank? (Meaning false (not set) for OTYPE_BOOL, OTYPE_ENUMBOOL or OTYPE_INTBOOL; blank for OTYPE_STR or OTYPE_STRHIDE; defaultIntValue for OTYPE_INT or OTYPE_ENUM)

Only recommended for seldom-used options. The removal is done in adjustOptionsToKnown(Map, Map, boolean). Once this flag is set for an option, it should not be un-set if the option is changed in a later version.

For OTYPE_INTBOOL and OTYPE_ENUMBOOL, both the integer and boolean values are checked against defaults.

This flag is ignored at the client when asking to create a new game: NewGameOptionsFrame sends all options it has displayed, even those which would be dropped because they're unused and they have this flag.

Recognized in v1.1.07 and newer. This is the only flag recognized by clients older than v2.0.00. Clients older than v2.0.00 also ignore this flag for OTYPE_INT, OTYPE_ENUM.

See Also:: Constant Field Values

FLAG_INTERNAL_GAME_PROPERTY

public static final int FLAG_INTERNAL_GAME_PROPERTY

optFlags bitfield constant to indicate option is an internal property. Set if the purpose of this option is to hold information about the option's game or its board. The user shouldn't be able to set this option when creating a game, and it should be hidden not shown in the Game Options window during play (NewGameOptionsFrame).

Options with this flag should have a key starting with '_', although not all options which start with '_' are hidden for internal use. (Options starting with '_' are meant to be set by the server during game creation, not requested by the client.)

Since:: 2.0.00
See Also:: Constant Field Values

OTYPE_MIN

public static final int OTYPE_MIN

Lowest OTYPE_ (optType) value known at this version

See Also:: Constant Field Values

OTYPE_UNKNOWN

public static final int OTYPE_UNKNOWN

Option type: unknown (probably due to version mismatch). Options of this type will also set their isKnown flag false.

See Also:: Constant Field Values

OTYPE_BOOL

public static final int OTYPE_BOOL

Option type: boolean

See Also:: Constant Field Values

OTYPE_INT

public static final int OTYPE_INT

Option type: integer.

In v1.1.20 and newer, while reading values in the NewGameOptionsFrame dialog, a blank textfield is treated as 0. If 0 is out of range, the user will have to enter a valid number.

See Also:: Constant Field Values

OTYPE_INTBOOL

public static final int OTYPE_INTBOOL

Option type: integer + boolean. Both boolValue and intValue fields are used.

In v1.1.20 and newer, while reading values in the NewGameOptionsFrame dialog, a blank int value textfield is treated as 0. If 0 is out of range, the user will have to enter a valid number. If the option's boolean value checkbox isn't set, the int value isn't set or changed.

See Also:: Constant Field Values

OTYPE_ENUM

public static final int OTYPE_ENUM

Option type: enumeration (1 of several possible choices, described with text strings, stored here as intVal). Choices' strings are stored in enumVals.

See Also:: Constant Field Values

OTYPE_ENUMBOOL

public static final int OTYPE_ENUMBOOL

Option type: enumeration + boolean; see OTYPE_ENUM. Like OTYPE_INTBOOL, both boolValue and intValue fields are used.

See Also:: Constant Field Values

OTYPE_STR

public static final int OTYPE_STR

Option type: text string (max string length is maxIntValue, default value is "")

See Also:: Constant Field Values

OTYPE_STRHIDE

public static final int OTYPE_STRHIDE

Option type: text string (like OTYPE_STR) but hidden from view; is NOT encrypted, but contents show up as "*" when typed into a text field.

See Also:: Constant Field Values

OTYPE_MAX

public static final int OTYPE_MAX

Highest OTYPE value known at this version

See Also:: Constant Field Values

K_SC_SANY

public static final java.lang.String K_SC_SANY

Scenario key _SC_SANY for SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA.

Since:: 2.0.00
See Also:: Constant Field Values

K_SC_SEAC

public static final java.lang.String K_SC_SEAC

Scenario key _SC_SEAC for SOCScenarioPlayerEvent.SVP_SETTLED_EACH_NEW_LANDAREA.

Since:: 2.0.00
See Also:: Constant Field Values

K_SC_FOG

public static final java.lang.String K_SC_FOG

Scenario key _SC_FOG for SOCScenarioGameEvent.SGE_FOG_HEX_REVEALED.

Since:: 2.0.00
See Also:: SOCScenario.K_SC_FOG, Constant Field Values

K_SC_0RVP

public static final java.lang.String K_SC_0RVP

Scenario key _SC_0RVP: No "longest trade route" VP / Longest Road.

Since:: 2.0.00
See Also:: Constant Field Values

K_SC_3IP

public static final java.lang.String K_SC_3IP

Scenario key _SC_3IP: Third initial placement of settlement and road or ship. Initial resources are given for this one, not the second settlement.

Since:: 2.0.00
See Also:: Constant Field Values

K_SC_CLVI

public static final java.lang.String K_SC_CLVI

Scenario key _SC_CLVI for SOCScenarioPlayerEvent.CLOTH_TRADE_ESTABLISHED_VILLAGE: Cloth Trade with neutral villages. Villages and cloth are in a game only if this option is set.

Since:: 2.0.00
See Also:: SOCScenario.K_SC_CLVI, Constant Field Values

K_SC_PIRI

public static final java.lang.String K_SC_PIRI

Scenario key _SC_PIRI for Pirate Islands and fortresses. Fortresses and player warships are in a game only if this option is set. For more details and special rules see SOCScenario.K_SC_PIRI.

Since:: 2.0.00
See Also:: Constant Field Values

K_SC_FTRI

public static final java.lang.String K_SC_FTRI

Scenario key _SC_FTRI for the Forgotten Tribe. Special edges with SVP, dev cards, and "gift" ports placed via SOCInventoryItem. For more details and special rules see SOCScenario.K_SC_FTRI.

Since:: 2.0.00
See Also:: Constant Field Values

K_SC_WOND

public static final java.lang.String K_SC_WOND

Scenario key _SC_WOND for Wonders. Special unique "wonders" claimed by players and built up to several levels. No pirate ship. For more details, special rules, and Special Items, see SOCScenario.K_SC_WOND.

Since:: 2.0.00
See Also:: Constant Field Values

VERSION_FOR_LONGER_OPTNAMES

public static final int VERSION_FOR_LONGER_OPTNAMES

Version 2.0.00 introduced longer option keynames (8 characters, earlier max was 3) and underscores '_' in option names. Game option names sent to 1.1.xx servers must be 3 characters or less, alphanumeric, no underscores ('_').

Since:: 2.0.00
See Also:: Constant Field Values

allOptions

private static java.util.Map<java.lang.String,SOCGameOption> allOptions

Set of "known options". allOptions must never be null, because other places assume it is filled.

refreshList

private static java.util.List<SOCGameOption> refreshList

List of options to refresh on-screen after a change during game creation; filled by refreshDisplay(). Not thread-safe.

Since:: 1.1.13
See Also:: SOCGameOption.ChangeListener

optType

public final int optType

Option type.

OTYPE_BOOL Boolean
OTYPE_INT Integer, with min/max value
OTYPE_INTBOOL Int plus bool (Ex. [x] no robber rolls in first _5_ turns)
OTYPE_ENUM Enumerated-choice (Ex. Standard vs Seafarers): Stored like integer OTYPE_INT in range 1-n, described to user with text strings.
OTYPE_ENUMBOOL Enum plus bool; stored like OTYPE_INTBOOL.
OTYPE_STR short text string: max string length is maxIntValue; default value is the empty string.
OTYPE_STRHIDE text string (like OTYPE_STR) but hidden from view; is NOT encrypted.

optFlags

public final int optFlags

Sum of all of option's flags, if any, such as FLAG_DROP_IF_UNUSED.

Since:: 2.0.00
See Also:: hasFlag(int)

defaultBoolValue

public final boolean defaultBoolValue

Default value for boolean part of this option, if any

defaultIntValue

public final int defaultIntValue

Default value for integer part of this option, if any

minIntValue

public final int minIntValue

Minumum and maximum permitted values for integer part of this option, if any, or maximum length of a string value. (There is no minimum length)

maxIntValue

public final int maxIntValue

Minumum and maximum permitted values for integer part of this option, if any, or maximum length of a string value. (There is no minimum length)

enumVals

public final java.lang.String[] enumVals

For type OTYPE_ENUM and OTYPE_ENUMBOOL, descriptive text for each possible value; null for other types. If a value is added or changed in a later version, the option's SOCVersionedItem.lastModVersion field must be updated, so server/client will know to ask for the proper version with all available options. Although the option's intVals are in the range 1 to n, this array is indexed 0 to n-1.

boolValue

private boolean boolValue

intValue

private int intValue

strValue

private java.lang.String strValue

optCL

private transient SOCGameOption.ChangeListener optCL

The option's ChangeListener, or null.

Since:: 1.1.13

userChanged

public transient boolean userChanged

Has the user selected a value? False if unchanged, or if changed only by a SOCGameOption.ChangeListener or other automatic means.

If a SOCGameOption.ChangeListener later changes the option's value, consider clearing userChanged because the user hasn't set that.

Client use only; not sent over the network. Set in NewGameOptionsFrame.

Since:: 2.0.00

Constructor Detail

SOCGameOption

public SOCGameOption(java.lang.String key)
              throws java.lang.IllegalArgumentException

Create a new game option of unknown type (OTYPE_UNKNOWN). Minimum version will be Integer.MAX_VALUE. Value will be false/0. desc will be an empty string.

Parameters:: key - Alphanumeric 2-character code for this option; see SOCVersionedItem.isAlphanumericUpcaseAscii(String) for format.
Throws:: java.lang.IllegalArgumentException - if key length is > 3 or not alphanumeric

SOCGameOption

public SOCGameOption(java.lang.String key,
                     int minVers,
                     int lastModVers,
                     boolean defaultValue,
                     int flags,
                     java.lang.String desc)
              throws java.lang.IllegalArgumentException

Create a new boolean game option (OTYPE_BOOL).

Parameters:: key - Alphanumeric 2-character code for this option; see SOCVersionedItem.isAlphanumericUpcaseAscii(String) for format.; minVers - Minimum client version if this option is set (is true), or -1; lastModVers - Last-modified version for this option, or version which added it; defaultValue - Default value (true if set, false if not set); flags - Option flags such as FLAG_DROP_IF_UNUSED, or 0; Remember that older clients won't recognize some gameoption flags.; desc - Descriptive brief text, to appear in the options dialog
Throws:: java.lang.IllegalArgumentException - if key length is > 3 or not alphanumeric, or if desc contains SOCMessage.sep_char or SOCMessage.sep2_char, or if minVers or lastModVers is under 1000 but not -1

SOCGameOption

public SOCGameOption(java.lang.String key,
                     int minVers,
                     int lastModVers,
                     int defaultValue,
                     int minValue,
                     int maxValue,
                     int flags,
                     java.lang.String desc)
              throws java.lang.IllegalArgumentException

Create a new integer game option (OTYPE_INT).

If FLAG_DROP_IF_UNUSED is set, the option will be dropped if == defaultIntValue.
Before v2.0.00, there was no dropIfUnused flag for integer options.

Parameters:: key - Alphanumeric 2-character code for this option; see SOCVersionedItem.isAlphanumericUpcaseAscii(String) for format.; minVers - Minimum client version if this option is set (boolean is true), or -1; lastModVers - Last-modified version for this option, or version which added it; defaultValue - Default int value; minValue - Minimum permissible value; maxValue - Maximum permissible value; the width of the options-dialog value field is based on the number of digits in maxValue.; flags - Option flags such as FLAG_DROP_IF_UNUSED, or 0; Remember that older clients won't recognize some gameoption flags.; desc - Descriptive brief text, to appear in the options dialog; may contain a placeholder character '#' where the int value goes. If no placeholder is found, the value text field appears at left, like boolean options.
Throws:: java.lang.IllegalArgumentException - if defaultValue < minValue or is > maxValue, or if key length is > 3 or not alphanumeric, or if desc contains SOCMessage.sep_char or SOCMessage.sep2_char, or if minVers or lastModVers is under 1000 but not -1

SOCGameOption

public SOCGameOption(java.lang.String key,
                     int minVers,
                     int lastModVers,
                     boolean defaultBoolValue,
                     int defaultIntValue,
                     int minValue,
                     int maxValue,
                     int flags,
                     java.lang.String desc)
              throws java.lang.IllegalArgumentException

Create a new int+boolean game option (OTYPE_INTBOOL).

Parameters:: key - Alphanumeric 2-character code for this option; see SOCVersionedItem.isAlphanumericUpcaseAscii(String) for format.; minVers - Minimum client version if this option is set (boolean is true), or -1; lastModVers - Last-modified version for this option, or version which added it; defaultBoolValue - Default value (true if set, false if not set); defaultIntValue - Default int value, to use if option is set; minValue - Minimum permissible value; maxValue - Maximum permissible value; the width of the options-dialog value field is based on the number of digits in maxValue.; flags - Option flags such as FLAG_DROP_IF_UNUSED, or 0; Remember that older clients won't recognize some gameoption flags.; desc - Descriptive brief text, to appear in the options dialog; should contain a placeholder character '#' where the int value goes.
Throws:: java.lang.IllegalArgumentException - if defaultIntValue < minValue or is > maxValue, or if key length is > 3 or not alphanumeric, or if desc contains SOCMessage.sep_char or SOCMessage.sep2_char, or if minVers or lastModVers is under 1000 but not -1

SOCGameOption

public SOCGameOption(java.lang.String key,
                     int minVers,
                     int lastModVers,
                     int defaultValue,
                     java.lang.String[] enumVals,
                     int flags,
                     java.lang.String desc)
              throws java.lang.IllegalArgumentException

Create a new enumerated game option (OTYPE_ENUM). The minIntValue will be 1, maxIntValue will be enumVals.length.

If FLAG_DROP_IF_UNUSED is set, the option will be dropped if == defaultIntValue.
Before v2.0.00, there was no dropIfUnused flag for enum options.

Parameters:: key - Alphanumeric 2-character code for this option; see SOCVersionedItem.isAlphanumericUpcaseAscii(String) for format.; minVers - Minimum client version if this option is set (boolean is true), or -1; lastModVers - Last-modified version for this option, or version which added it; defaultValue - Default int value, in range 1 - n (n == number of possible values); flags - Option flags such as FLAG_DROP_IF_UNUSED, or 0; Remember that older clients won't recognize some gameoption flags.; enumVals - text to display for each possible choice of this option. Please see the explanation at initAllOptions() about changing or adding to enumVals in later versions.; desc - Descriptive brief text, to appear in the options dialog; may contain a placeholder character '#' where the enum's popup-menu goes. If no placeholder is found, the value field appears at left, like boolean options.
Throws:: java.lang.IllegalArgumentException - if defaultValue < minValue or is > maxValue, or if key length is > 3 or not alphanumeric, or if desc contains SOCMessage.sep_char or SOCMessage.sep2_char, or if minVers or lastModVers is under 1000 but not -1

SOCGameOption

public SOCGameOption(java.lang.String key,
                     int minVers,
                     int lastModVers,
                     boolean defaultBoolValue,
                     int defaultIntValue,
                     java.lang.String[] enumVals,
                     int flags,
                     java.lang.String desc)
              throws java.lang.IllegalArgumentException

Create a new enumerated + boolean game option (OTYPE_ENUMBOOL). The minIntValue will be 1, maxIntValue will be enumVals.length.

Parameters:: key - Alphanumeric 2-character code for this option; see SOCVersionedItem.isAlphanumericUpcaseAscii(String) for format.; minVers - Minimum client version if this option is set (boolean is true), or -1; lastModVers - Last-modified version for this option, or version which added it; defaultBoolValue - Default value (true if set, false if not set); defaultIntValue - Default int value, in range 1 - n (n == number of possible values); enumVals - text to display for each possible choice of this option; flags - Option flags such as FLAG_DROP_IF_UNUSED, or 0; Remember that older clients won't recognize some gameoption flags.; desc - Descriptive brief text, to appear in the options dialog; may contain a placeholder character '#' where the enum's popup-menu goes. If no placeholder is found, the value field appears at left, like boolean options.
Throws:: java.lang.IllegalArgumentException - if defaultValue < minValue or is > maxValue, or if key length is > 3 or not alphanumeric, or if desc contains SOCMessage.sep_char or SOCMessage.sep2_char, or if minVers or lastModVers is under 1000 but not -1

SOCGameOption

public SOCGameOption(java.lang.String key,
                     int minVers,
                     int lastModVers,
                     int maxLength,
                     boolean hideTyping,
                     int flags,
                     java.lang.String desc)
              throws java.lang.IllegalArgumentException

Create a new text game option (OTYPE_STR or OTYPE_STRHIDE). The maxIntValue will be maxLength.

Parameters:: key - Alphanumeric 2-character code for this option; see SOCVersionedItem.isAlphanumericUpcaseAscii(String) for format.; minVers - Minimum client version if this option is set (boolean is true), or -1; lastModVers - Last-modified version for this option, or version which added it; maxLength - Maximum length, between 1 and 255 (for network bandwidth conservation); hideTyping - Should type be OTYPE_STRHIDE instead of OTYPE_STR?; flags - Option flags such as FLAG_DROP_IF_UNUSED, or 0; Remember that older clients won't recognize some gameoption flags.; desc - Descriptive brief text, to appear in the options dialog; may contain a placeholder character '#' where the text value goes. If no placeholder is found, the value text field appears at left, like boolean options.
Throws:: java.lang.IllegalArgumentException - if maxLength > 255, or if key length is > 3 or not alphanumeric, or if desc contains SOCMessage.sep_char or SOCMessage.sep2_char, or if minVers or lastModVers is under 1000 but not -1

SOCGameOption

protected SOCGameOption(int otype,
                        java.lang.String key,
                        int minVers,
                        int lastModVers,
                        boolean defaultBoolValue,
                        int defaultIntValue,
                        int minValue,
                        int maxValue,
                        java.lang.String[] enumVals,
                        int flags,
                        java.lang.String desc)
                 throws java.lang.IllegalArgumentException

Create a new game option - common constructor.

Parameters:: otype - Option type; use caution, as this is unvalidated against OTYPE_MIN or OTYPE_MAX.; key - Alphanumeric uppercase code for this option; see SOCVersionedItem.isAlphanumericUpcaseAscii(String) for format. Most option keys are 2 or 3 characters; before 2.0.00, the maximum length was 3. The maximum key length is now 8, but older clients will reject keys longer than 3.; minVers - Minimum client version for games where this option is set (its boolean field is true), or -1. If key is longer than 3 characters, minVers must be at least 2000 (VERSION_FOR_LONGER_OPTNAMES).; lastModVers - Last-modified version for this option, or version which added it; defaultBoolValue - Default value (true if set, false if not set); defaultIntValue - Default int value, to use if option is set; minValue - Minimum permissible value; maxValue - Maximum permissible value; the width of the options-dialog value field is based on the number of digits in maxValue.; enumVals - Possible choice texts for OTYPE_ENUM or OTYPE_ENUMBOOL, or null; value(s) must pass same checks as desc.; flags - Option flags such as FLAG_DROP_IF_UNUSED, or 0; Remember that older clients won't recognize some gameoption flags.; desc - Descriptive brief text, to appear in the options dialog; should contain a placeholder character '#' where the int value goes. Desc must not contain SOCMessage.sep_char or SOCMessage.sep2_char, and must evaluate true from SOCMessage.isSingleLineAndSafe(String).
Throws:: java.lang.IllegalArgumentException - if defaultIntValue < minValue or is > maxValue, or if key is not alphanumeric or length is > 8, or if key length > 3 and minVers < 2000, or if desc contains SOCMessage.sep_char or SOCMessage.sep2_char, or if minVers or lastModVers is under 1000 but not -1

SOCGameOption

public SOCGameOption(SOCGameOption opt,
                     java.lang.String newDesc)

Copy constructor for i18n localization of getDesc().

Parameters:: opt - Option to copy; newDesc - Localized option description, or null to use getDesc()
Since:: 2.0.00

SOCGameOption

protected SOCGameOption(SOCGameOption enumOpt,
                        java.lang.String[] keptEnumVals)
                 throws java.lang.NullPointerException

Copy constructor for enum-valued types (OTYPE_ENUM, OTYPE_ENUMBOOL), for restricting (trimming) values for a certain client version.

Parameters:: enumOpt - Option object to copy. If its defaultIntValue is greater than keptEnumVals.length, the default will be reduced to that.; keptEnumVals - Enum values to keep; should be a subset of enumOpt.enumVals containing the first n values of that list.
Throws:: java.lang.NullPointerException - if keptEnumVals is null
See Also:: getMaxEnumValueForVersion(String, int), optionsNewerThanVersion(int, boolean, boolean, Map)

SOCGameOption

protected SOCGameOption(SOCGameOption intOpt,
                        int maxIntValue)

Copy constructor for int-valued types (OTYPE_INT, OTYPE_INTBOOL), for restricting (trimming) max value for a certain client version.

Parameters:: intOpt - Option object to copy. If its defaultIntValue is greater than maxIntValue, the default will be reduced to that.; maxIntValue - Maximum value to keep, in the copy
Since:: 1.1.08
See Also:: getMaxIntValueForVersion(String, int), optionsNewerThanVersion(int, boolean, boolean, Map)

Method Detail

initAllOptions

public static java.util.Map<java.lang.String,SOCGameOption> initAllOptions()

Create a set of the known options. This method creates and returns a new map, but does not set the static allOptions field.

Current known options:

PL Maximum # players (2-6)
PLB Use 6-player board*
SBL Use sea board layout (has a large, varying max size)
RD Robber can't return to the desert
N7 Roll no 7s during first # rounds
N7C Roll no 7s until a city is built
BC Break up clumps of # or more same-type ports/hexes
NT No trading allowed
VP Victory points (10-15)
SC Game Scenario (optional groups of rules; see SOCScenario)
_BHW Board height and width, if not default, for SOCBoardLarge: 0xRRCC

* Grouping: PLB is 3 characters, not 2, and its first 2 characters match an existing option. So in NewGameOptionsFrame, it appears on the line following the PL option in client version 1.1.13 and above.

Current Game Scenario options:

_SC_SANY SVP to settle in any new land area: SOCScenarioPlayerEvent.SVP_SETTLED_ANY_NEW_LANDAREA
_SC_SEAC 2 SVP each time settle in another new land area: SOCScenarioPlayerEvent.SVP_SETTLED_EACH_NEW_LANDAREA
_SC_FOG A hex has been revealed from behind fog: SOCScenarioGameEvent.SGE_FOG_HEX_REVEALED: See SOCScenario.K_SC_FOG
_SC_0RVP No VP for longest road / longest trade route
_SC_3IP Third initial settlement and road/ship placement
_SC_CLVI Cloth trade with neutral villages: See SOCScenario.K_SC_CLVI
_SC_FTRI The Forgotten Tribe: See SOCScenario.K_SC_FTRI
_SC_PIRI Pirate Islands and fortresses: See SOCScenario.K_SC_PIRI
_SC_WOND Wonders: See SOCScenario.K_SC_WOND

If you want to add a game option:

Choose an unused 2-character key name: for example, "PL" for "max players". All in-game code uses these key strings to query and change game option settings; only a very few places use SOCGameOption objects, and you won't need to adjust those places. The list of already-used key names is here within initAllOptions.
If your option supports a SOCScenario, its name should start with "_SC_" and it should have a constant name field here (like K_SC_3IP) with a short descriptive javadoc. Link in javadoc to the SOCScenario field and add it to the list above.
Decide which option type your option will be (boolean, enumerated, int+bool, etc.), and its default value. Typically the default will let the game behave as it did before the option existed (for example, the "max players" default is 4). Its default value on your own server can be changed at runtime.
Decide if all client versions can use your option. Typically, if the option requires server changes but not any client changes, all clients can use it. (For example, "N7" for "roll no 7s early in the game" works with any client because dice rolls are done at the server.)
Create the option by calling opt.put here in initAllOptions. Use the current version for the "last modified" field.
Add the new option's description to the gameopt.* section of server/strings/toClient_*.properties to be sent to clients if needed.
If only some values of the option will require client changes, also update getMinVersion(Map). (For example, if "PL"'s value is 5 or 6, a new client would be needed to display that many players at once, but 2 - 4 can use any client version.)
If this is the case and your option type is OTYPE_ENUM or OTYPE_ENUMBOOL, also update getMaxEnumValueForVersion(String, int). Otherwise, update getMaxIntValueForVersion(String, int).
If the new option can be used by old clients by changing the values of other related options when game options are sent to those versions, add code to getMinVersion(Map).
For example, the boolean "PLB" can force use of the 6-player board in versions 1.1.08 - 1.1.12 by changing "PL"'s value to 5 or 6.
Within SOCGame, don't add any object fields due to the new option; instead call SOCGame.isGameOptionDefined(String), SOCGame.getGameOptionIntValue(String), etc. Look for game methods where game behavior changes with the new option, and adjust those.
Check the server and clients for places which must check for the new option. Typically these will be the places which call the game methods affected.
- SOCServer is the server class, see its "handle" methods for network messages
- SOCPlayerClient is the graphical client
- SOCRobotClient and SOCRobotBrain.run() together handle the robot client messages
- SOCDisplaylessPlayerClient is the foundation for the robot client, and handles some of its messages
Some options don't need any code at the robot; for example, the robot doesn't care about the maximum number of players in a game, because the server tells the robot when to join a game.
Some options need code only in the SOCGame constructor.
To find other places which may possibly need an update from your new option, search the entire source tree for this marker: // NEW_OPTION
This would include places like SOCRobotParameters.copyIfOptionChanged(Map) which ignore most, but not all, game options.

If you want to change a game option (in a later version):

Typical changes to a game option would be:

Add new values to an enumerated option; they must be added to the end of the list
Change the maximum or minimum permitted values for an integer option
Change the default value, although this can also be done at runtime on the command line
Change the value at the server based on other options' values

Things you can't change about an option, because inconsistencies would occur:

name key
optType
SOCVersionedItem.minVersion
optFlags such as FLAG_DROP_IF_UNUSED -- newly defined flags could maybe be added, if old versions can safely ignore them, but a flag can't be removed from an option in a later version.
For OTYPE_ENUM and OTYPE_ENUMBOOL, you can't remove options or change the meaning of current ones, because this would mean that the option's intValue (sent over the network) would mean different things to different-versioned clients in the game.

To make the change:

Change the option here in initAllOptions; change the "last modified" field to the current game version. Otherwise the server can't tell the client what has changed about the option.
If new values require a newer minimum client version, add code to getMinVersion(Map).
If adding a new enum value for OTYPE_ENUM and OTYPE_ENUMBOOL, add code to getMaxEnumValueForVersion(String, int).
If increasing the maximum value of an int-valued parameter, and the new maximum requires a certain version, add code to getMaxIntValueForVersion(String, int). For example, versions below 1.1.08 limit "max players" to 4.
Search the entire source tree for its key name, to find places which may need an update.
Consider if any other places listed above (for add) need adjustment.

If you want to remove or obsolete a game option (in a later version):

Please think twice beforehand; breaking compatibility with older clients shouldn't be done without a very good reason. That said, the server is authoritative on options. If an option isn't in its known list (initAllOptions()), the client won't be allowed to ask for it. Any obsolete options should be kept around as commented-out code.

Returns:: a fresh copy of the "known" options, with their hardcoded default values

getBoolValue

public boolean getBoolValue()

Is this option set, if this option's type has a boolean component?

Returns:: current boolean value of this option
See Also:: SOCGame.isGameOptionSet(Map, String)

setBoolValue

public void setBoolValue(boolean v)

getIntValue

public int getIntValue()

This option's integer value, if this option's type has an integer component.

Returns:: current integer value of this option
See Also:: SOCGame.getGameOptionIntValue(Map, String), SOCGame.getGameOptionIntValue(Map, String, int, boolean)

setIntValue

public void setIntValue(int v)

Set this option's integer value to new value v, or clip to min/max allowed values.

Parameters:: v - set to this value, if it's within min/max for this option

getStringValue

public java.lang.String getStringValue()

Returns:: current string value of this option, or "" (empty string) if not set. Will not contain newlines or otherwise fail SOCMessage.isSingleLineAndSafe(String).
See Also:: SOCGame.getGameOptionStringValue(Map, String)

setStringValue

public void setStringValue(java.lang.String v)
                    throws java.lang.IllegalArgumentException

Set this option's string value to new value v

Parameters:: v - set to this value, or "" (empty string) if null; should be a simple string (no newlines or control characters). if v.length > maxIntValue, length will be truncated. Must not contain SOCMessage.sep_char or SOCMessage.sep2_char ('|' or ',').
Throws:: java.lang.IllegalArgumentException - if v contains characters reserved for message handling: SOCMessage.sep or SOCMessage.sep2 ('|' or ','), or is multi-line or otherwise fails SOCMessage.isSingleLineAndSafe(String).

getMinVersion

public int getMinVersion(java.util.Map<?,? extends SOCVersionedItem> opts)

Minimum game version supporting this option, given SOCVersionedItem.minVersion and the option's current value. The current value of an option can change its minimum version. For example, option "PL"'s minVersion is -1 for 2- to 4-player games with any client version, but a 5- or 6-player game will need client 1.1.08 or newer. For boolean-valued option types (OTYPE_BOOL, OTYPE_ENUMBOOL and OTYPE_INTBOOL), the minimum value is -1 unless getBoolValue() is true (that is, unless the option is set).

Occasionally, an older client version supports a new option, but only by changing the value of some other options it recognizes. This method will calculate the minimum client version at which options are unchanged, if opts != null.

Because this calculation is hardcoded here, the version returned may be too low when called at an older-version client. The server will let the client know if it's too old to join or create a game due to options.

Overrides:: getMinVersion in class SOCVersionedItem

Parameters:: opts - If null, return the minimum version supporting this option. Otherwise, the minimum version at which this option's value isn't changed (for compatibility) by the presence of other options.
Returns:: minimum version, or -1; same format as Version.versionNumber(). If opts != null, the returned version will either be -1 or >= 1107 (the first version with game options).
See Also:: SOCVersionedItem.itemsMinimumVersion(Map), getMaxEnumValueForVersion(String, int), getMaxIntValueForVersion(String, int)

getMaxEnumValueForVersion

public static final int getMaxEnumValueForVersion(java.lang.String optKey,
                                                  int vers)

For use at server, for enum options where some values require a newer client version. Given the option's keyname and a version, what is the maximum permitted enum value? The server, when giving option info to a connecting client, can remove the too-new values, and send only the permitted values to an older client.

Parameters:: optKey - Option's keyname; vers - Version of client, same format as SOCVersion.getVersionNumber() and Version.versionNumber()
Returns:: Maximum permitted value for this version, or Integer.MAX_VALUE if this option has no restriction. Enum values range from 1 to n, not from 0 to n-1.

getMaxIntValueForVersion

public static final int getMaxIntValueForVersion(java.lang.String optKey,
                                                 int vers)

For use at server, for int options where some values require a newer client version. For example, versions below 1.1.08 limit "max players" to 4. Given the option's keyname and a version, what is the maximum permitted int value? The server, when giving option info to a connecting client, can remove the too-new values.

Parameters:: optKey - Option's keyname; vers - Version of client, same format as SOCVersion.getVersionNumber() and Version.versionNumber()
Returns:: Maximum permitted value for this version, or Integer.MAX_VALUE if this option has no restriction.
Since:: 1.1.08

getAllKnownOptions

public static java.util.Map<java.lang.String,SOCGameOption> getAllKnownOptions()

Returns:: a deep copy of all known option objects
See Also:: addKnownOption(SOCGameOption)

addKnownOption

public static boolean addKnownOption(SOCGameOption onew)

Add a new known option (presumably received from a server of newer or older version), or update the option's information.

Parameters:: onew - New option, or a changed version of an option we already know. If onew.optType == OTYPE_UNKNOWN, will remove from the known table. If this option is already known and the old copy has a getChangeListener(), that listener is copied to onew.
Returns:: true if it's new, false if we already had that key and it was updated
See Also:: getAllKnownOptions()

setKnownOptionCurrentValue

public static void setKnownOptionCurrentValue(SOCGameOption ocurr)
                                       throws java.lang.IllegalArgumentException

Set the current value(s) of a known option, based on the current value(s) of another object ocurr with the same key. If there is no known option with oCurr.key, it is ignored and nothing is set.

Parameters:: ocurr - Option with the requested current value. ocurr's value field contents are copied to the known option's values, the ocurr reference won't be added to the known option set.
Throws:: java.lang.IllegalArgumentException - if string value is not permitted; note that int values outside of range are silently clipped, and will not throw this exception.
See Also:: getOption(String, boolean)

cloneOptions

public static java.util.Map<java.lang.String,SOCGameOption> cloneOptions(java.util.Map<java.lang.String,SOCGameOption> opts)

Make a deep copy of a group of options.

Parameters:: opts - a map of SOCGameOptions, or null; method synchronizes on opts
Returns:: a deep copy of all option objects within opts, or null if opts is null

getOption

public static SOCGameOption getOption(java.lang.String key,
                                      boolean clone)
                               throws java.lang.IllegalStateException

Get information about a known option.

Parameters:: key - Option key; clone - True if a copy of the option is needed; set this true unless you're sure you won't be changing any fields of its original object, which is a shared copy in a static namekey->object map.
Returns:: information about a known option, or null if none with that key
Throws:: java.lang.IllegalStateException - if clone but the object couldn't be cloned; this isn't expected to ever happen
See Also:: getAllKnownOptions()

packKnownOptionsToString

public static java.lang.String packKnownOptionsToString(boolean hideEmptyStringOpts,
                                                        boolean hideLongNameOpts)

Utility - build a string of option name-value pairs from the known options' current values.

Parameters:: hideEmptyStringOpts - omit string-valued options which are empty? Suitable only for sending defaults.; hideLongNameOpts - omit options with long key names or underscores? Set true if client's version < VERSION_FOR_LONGER_OPTNAMES.
Returns:: string of name-value pairs, same format as packOptionsToString(Map, boolean); any gameoptions of OTYPE_UNKNOWN will not be part of the string.
See Also:: parseOptionsToMap(String)

packOptionsToString

public static java.lang.String packOptionsToString(java.util.Map<java.lang.String,SOCGameOption> omap,
                                                   boolean hideEmptyStringOpts)
                                            throws java.lang.ClassCastException

Utility - build a string of option name-value pairs. This can be unpacked with parseOptionsToMap(String).

Parameters:

omap - Map of SOCGameOptions, or null

hideEmptyStringOpts - omit string-valued options which are empty? Suitable only for sending defaults.

Returns:

string of name-value pairs, or "-" for an empty or null omap; any gameoptions of OTYPE_UNKNOWN will not be part of the string. Format: k1=t,k2=f,k3=10,k4=t7,k5=f7. The format for each value depends on its type:

OTYPE_BOOL: t or f
OTYPE_ENUM: int in range 1-n
OTYPE_INTBOOL: t or f followed immediately by int value, as in: t7 or f9
All other optTypes: int value or string value, as appropriate

Throws:

java.lang.ClassCastException - if omap contains anything other than SOCGameOptions

packOptionsToString

public static java.lang.String packOptionsToString(java.util.Map<java.lang.String,SOCGameOption> omap,
                                                   boolean hideEmptyStringOpts,
                                                   int cliVers)
                                            throws java.lang.ClassCastException

Utility - build a string of option name-value pairs, adjusting for old clients if necessary. This can be unpacked with parseOptionsToMap(String). See packOptionsToString(Map, boolean) javadoc for details.

Parameters:: omap - Map of SOCGameOptions, or null; hideEmptyStringOpts - omit string-valued options which are empty? Suitable only for sending defaults.; cliVers - Client version; assumed >= SOCNewGameWithOptions.VERSION_FOR_NEWGAMEWITHOPTIONS. If any game's options need adjustment for an older client, cliVers triggers that. Use -2 if the client version doesn't matter, or if adjustment should not be done. Use -3 to omit options with long names, and do no other adjustment; for use with clients older than VERSION_FOR_LONGER_OPTNAMES.
Returns:: string of name-value pairs, or "-" for an empty or null omap; see packOptionsToString(Map, boolean) javadoc for details.
Throws:: java.lang.ClassCastException - if omap contains anything other than SOCGameOptions
See Also:: packValue(StringBuilder)

packValue

public void packValue(java.lang.StringBuilder sb)

Pack current value of this option into a string. This is used in packOptionsToString(Map, boolean) and read in parseOptionNameValue(String, boolean) and parseOptionsToMap(String). See packOptionsToString(Map, boolean) for the string's format.

Parameters:: sb - Pack into (append to) this buffer
See Also:: toString()

parseOptionsToMap

public static java.util.Map<java.lang.String,SOCGameOption> parseOptionsToMap(java.lang.String ostr)

Utility - build a map of keys to SOCGameOptions by parsing a list of option name-value pairs.

Before v2.0.00, this was parseOptionsToHash.

Parameters:: ostr - string of name-value pairs, as created by packOptionsToString(Map, boolean). A leading comma is OK (possible artifact of StringTokenizer coming from over the network). If ostr=="-", returned map will be null.
Returns:: map of SOCGameOptions, or null if ostr==null or empty ("-") or if ostr is malformed. Any unrecognized options will be in the map as type OTYPE_UNKNOWN. The returned known SGOs are clones from the set of all known options.
See Also:: parseOptionNameValue(String, boolean), parseOptionNameValue(String, String, boolean)

parseOptionNameValue

public static SOCGameOption parseOptionNameValue(java.lang.String nvpair,
                                                 boolean forceNameUpcase)
                                          throws java.lang.IllegalArgumentException

Utility - parse a single name-value pair produced by packOptionsToString. Expected format of nvpair: "optname=optvalue". Expected format of optvalue depends on its type. See packOptionsToString(Map, boolean) for the format.

Parameters:: nvpair - Name-value pair string, as created by packOptionsToString(Map, boolean).
'T', 't', 'Y', 'y' are always allowed for bool true values, regardless of forceNameUpcase. 'F', 'f', 'N', 'n' are the valid bool false values.; forceNameUpcase - Call String.toUpperCase() on keyname within nvpair? For friendlier parsing of manually entered (command-line) nvpair strings.
Returns:: Parsed option, or null if parse error; if known, the returned object is a clone of the SGO from the set of all known options. if nvpair's option keyname is not a known option, returned optType will be OTYPE_UNKNOWN.
Throws:: java.lang.IllegalArgumentException - if optkey is unknown and not a valid alphanumeric keyname by the rules listed at SOCGameOption(String)
See Also:: parseOptionNameValue(String, String, boolean), parseOptionsToMap(String), packValue(StringBuilder)

parseOptionNameValue

public static SOCGameOption parseOptionNameValue(java.lang.String optkey,
                                                 java.lang.String optval,
                                                 boolean forceNameUpcase)
                                          throws java.lang.IllegalArgumentException

Utility - parse an option name-value pair produced by packValue(StringBuilder) or packOptionsToString(Map, boolean). Expected format of optval depends on its type. See packOptionsToString(..) for the format.

Parameters:: optkey - Game option's alphanumeric keyname, known or unknown. Optkey must be a valid key by the rules listed at SOCGameOption(String).; optval - Game option's value, as created by packOptionsToString(Map, boolean).
'T', 't', 'Y', 'y' are always allowed for bool true values, regardless of forceNameUpcase. 'F', 'f', 'N', 'n' are the valid bool false values.; forceNameUpcase - Call String.toUpperCase() on optkey? For friendlier parsing of manually entered (command-line) name=value pairs.
Returns:: Parsed option, or null if parse error; if known, the returned object is a clone of the SGO from the set of all known options. if optkey is not a known option, returned optType will be OTYPE_UNKNOWN.
Throws:: java.lang.IllegalArgumentException - if optkey is unknown and not a valid alphanumeric keyname by the rules listed at SOCGameOption(String)
Since:: 2.0.00
See Also:: parseOptionNameValue(String, boolean), parseOptionsToMap(String), packValue(StringBuilder)

optionsNewerThanVersion

public static java.util.List<SOCGameOption> optionsNewerThanVersion(int vers,
                                                                    boolean checkValues,
                                                                    boolean trimEnums,
                                                                    java.util.Map<java.lang.String,SOCGameOption> opts)

Compare a set of options against the specified version. Make a list of all which are new or changed since that version.

This method has 2 modes, because it's called for 2 different purposes:

sync client-server known-option info, in general: checkValues == false
check if client can create game with a specific set of option values: checkValues == true

See checkValues for method's behavior in each mode.

Game option names:
When running this at the client (vers is the older remote server's version), some of the returned too-new options have long names that can't be sent to a 1.1.xx server (vers < VERSION_FOR_LONGER_OPTNAMES). You must check for this and remove them before sending them to the remote server. Game option names sent to 1.1.xx servers must be 3 characters or less, alphanumeric, no underscores ('_').

When running at the server, we will never send an option whose name is invalid to 1.1.xx clients, because the SOCGameOption constructors enforce minVers >= 2000 when the name is longer than 3 characters or contains '_'.

Parameters:: vers - Version to compare known options against; checkValues - Which mode: Check options' current values and SOCVersionedItem.minVersion, not their SOCVersionedItem.lastModVersion? An option's minimum version can increase based on its value; see getMinVersion(Map).; trimEnums - For enum-type options where minVersion changes based on current value, should we remove too-new values from the returned option info? This lets us send only the permitted values to an older client.; opts - Set of SOCGameOptions to check versions and current values; if null, use the "known option" set
Returns:: List of the newer (added or changed) SOCGameOptions, or null if all are known and unchanged since vers.
Note: May include options with SOCVersionedItem.minVersion > vers; the client may want to know about those.
See Also:: optionsForVersion(int, Map)

optionsForVersion

public static java.util.List<SOCGameOption> optionsForVersion(int vers,
                                                              java.util.Map<java.lang.String,SOCGameOption> opts)

Get all options valid at version vers. If necessary, trim enum value ranges or int value ranges if range was smaller at vers, like optionsNewerThanVersion(int, boolean, boolean, Map) does.

If vers from a client is newer than this version of SOCGameOption, will return all options known at this version, which may not include all of the newer version's options. Client game-option negotiation handles this by having the newer client send all its new (added or changed) option keynames to the older server to allow, adjust, or reject.

Parameters:: vers - Version to compare options against; opts - Set of SOCGameOptions to check versions, or null to use the "known option" set
Returns:: List of all SOCGameOptions valid at version vers, or null if none.
Since:: 2.0.00

implOptionsVersionCheck

private static java.util.List<SOCGameOption> implOptionsVersionCheck(int vers,
                                                                     boolean getAllForVersion,
                                                                     boolean checkValues,
                                                                     boolean trimEnums,
                                                                     java.util.Map<java.lang.String,SOCGameOption> opts)
                                                              throws java.lang.IllegalArgumentException

Get all options added or changed since version vers, or all options valid at vers, to implement optionsNewerThanVersion(int, boolean, boolean, Map) and optionsForVersion(int, Map).

Parameters:: vers - Version to compare options against; getAllForVersion - True to get all valid options (optionsForVersion mode), false for newer added or changed options only (optionsNewerThanVersion modes). If true and vers is newer than this version of SOCGameOption, will return all options known at this version.; checkValues - If not getAllForVersion, which mode to run in: Check options' current values and SOCVersionedItem.minVersion, not their SOCVersionedItem.lastModVersion? An option's minimum version can increase based on its value; see getMinVersion(Map).; trimEnums - For enum-type options where minVersion changes based on current value, should we remove too-new values from the returned option info? This lets us send only the permitted values to an older client.; opts - Set of SOCGameOptions to check versions and current values; if null, use the "known option" set
Returns:: List of the requested SOCGameOptions, or null if none match the conditions, at vers; see optionsNewerThanVersion and optionsForVersion for return details.
Note: If not getAllForVersion, may include options with SOCVersionedItem.minVersion > vers; the client may want to know about those.
Throws:: java.lang.IllegalArgumentException - if getAllForVersion && checkValues: Cannot combine these modes
Since:: 2.0.00

trimEnumForVersion

public static SOCGameOption trimEnumForVersion(SOCGameOption opt,
                                               int vers)

Copy this option and restrict its enumerated values (type OTYPE_ENUM or similar) by trimming enumVals shorter. Assumes getMaxEnumValueForVersion(String, int) indicates this is needed.

Parameters:: opt - Option to restrict; vers - Version to restrict to
Returns:: A copy of the option, containing only the enum values permitted at vers. If no restriction is needed, return opt.

adjustOptionsToKnown

public static java.lang.StringBuilder adjustOptionsToKnown(java.util.Map<java.lang.String,SOCGameOption> newOpts,
                                                           java.util.Map<java.lang.String,SOCGameOption> knownOpts,
                                                           boolean doServerPreadjust)
                                                    throws java.lang.IllegalArgumentException

Compare a set of options with known-good values. If any are above/below maximum/minimum, clip to the max/min value in knownOpts. If any are unknown, return a description. Will still check (and clip) the known ones. If any options are default, and unset/blank, and their FLAG_DROP_IF_UNUSED flag is set, remove them from newOpts. For OTYPE_INTBOOL and OTYPE_ENUMBOOL, both the integer and boolean values are checked against defaults.

If doServerPreadjust is true, then the server might also change some option values before creating the game, for overall consistency of the set of options. This is a server-side equivalent to the client-side SOCGameOption.ChangeListeners. For example, if "PL" (number of players) > 4, but "PLB" (use 6-player board) is not set, doServerPreadjust wil set the "PLB" option. doServerPreadjust will also remove any game-internal options the client has sent.

Before any other adjustments when doServerPreadjust, will check for the game scenario option "SC". If that option is set, call SOCScenario.getScenario(String); the scenario name must be known. Then, add that scenario's .scOpts into newOpts. Scenario option values always overwrite those in newOpts, except for "VP" where newOpts value (if any) is kept.

Client-side gameopt code also assumes all scenarios use the sea board, and sets game option "SBL" when a scenario is chosen by the user.

Parameters:

newOpts - Set of SOCGameOptions to check against knownOpts; an option's current value will be changed if it's outside of the min/max for that option in knownOpts. Must not be null.

knownOpts - Set of known SOCGameOptions to check against, or null to use the server's static copy

doServerPreadjust - If true, we're calling from the server before creating a game; pre-adjust any values for consistency. This is a server-side equivalent to the client-side SOCGameOption.ChangeListeners. (Added in 1.1.13)

Returns:

null if all are known; or, a human-readable problem description if:

any of newOpts are unknown
or an opt's type differs from that in knownOpts
or an opt's SOCVersionedItem.lastModVersion differs from in knownOpts

Throws:

java.lang.IllegalArgumentException - if newOpts contains a non-SOCGameOption

setBoolOption

public static void setBoolOption(java.util.Map<java.lang.String,SOCGameOption> newOpts,
                                 java.lang.String boKey)
                          throws java.lang.NullPointerException

Within a set of options, include a boolean option and make it true. If the option object doesn't exist in newOpts, it will be cloned from the set of known options.

Parameters:: newOpts - Options to set boKey within; boKey - Key name for boolean option to set
Throws:: java.lang.NullPointerException - if boKey isn't in newOpts and doesn't exist in the set of known options
Since:: 1.1.17
See Also:: setIntOption(Map, String, int, boolean)

setIntOption

public static void setIntOption(java.util.Map<java.lang.String,SOCGameOption> newOpts,
                                java.lang.String ioKey,
                                int ivalue,
                                boolean bvalue)
                         throws java.lang.NullPointerException

Within a set of options, include an int or intbool option and set its value. If the option object doesn't exist in newOpts, it will be cloned from the set of known options.

Parameters:: newOpts - Options to set ioKey within; ioKey - Key name for int option to set; ivalue - Set option to this int value; bvalue - Set option to this boolean value (ignored if option type not intbool)
Throws:: java.lang.NullPointerException - if ioKey isn't in newOpts and doesn't exist in the set of known options
Since:: 1.1.17
See Also:: setBoolOption(Map, String)

optionTypeName

public static java.lang.String optionTypeName(int optType)

For user output, the string name of the option type's constant. The prefix "OTYPE_" is omitted.

Parameters:: optType - An option's optType value
Returns:: String for this otype constant, such as "INTBOOL" or "UNKNOWN", or null if optType is outside the known type value range.

getAndClearRefreshList

public static final java.util.List<SOCGameOption> getAndClearRefreshList()

Get the list of SOCGameOptions whose refreshDisplay() methods have been called, and clear the internal static copy. Not thread-safe, assumes only 1 GUI thread or 1 NewGameOptionsFrame at a time.

Returns:: the list, or null if refreshDisplay wasn't called on any option
Since:: 1.1.13

refreshDisplay

public void refreshDisplay()

If this game option is displayed on-screen, refresh it; call this after changing the value.

Since:: 1.1.13

hasFlag

public final boolean hasFlag(int flagMask)

Does this game option have these specified flag(s)?

Parameters:: flagMask - Option flag such as FLAG_DROP_IF_UNUSED, or multiple flags added together
Returns:: True if optFlags contains all flags in flagMask
Since:: 2.0.00

addChangeListener

public void addChangeListener(SOCGameOption.ChangeListener cl)

Add or remove this option's change listener. Does not support multiple listeners, so if it's already set, it will be changed to the new value.

Parameters:: cl - Change listener to add, or null to remove.
Since:: 1.1.13
See Also:: hasChangeListener()

hasChangeListener

public boolean hasChangeListener()

Does this option have a non-null SOCGameOption.ChangeListener?

Since:: 1.1.13
See Also:: getChangeListener()

getChangeListener

public SOCGameOption.ChangeListener getChangeListener()

Get this option's SOCGameOption.ChangeListener, if any

Returns:: the changelistener, or null if none
Since:: 1.1.13
See Also:: hasChangeListener(), addChangeListener(ChangeListener)

toString

public java.lang.String toString()

Form a string with the key and current value, useful for debugging purposes.

Overrides:: toString in class java.lang.Object

Returns:: string such as "PL=4" or "BC=t3", with the same format as packKnownOptionsToString(boolean, boolean).
See Also:: packValue(StringBuilder), getPackedValue(), optionTypeName(int)

getPackedValue

public final java.lang.StringBuilder getPackedValue()

Form a StringBuilder containing the current value. This is a convenience method.

Returns:: stringbuffer such as "4" or "t3", with the same value format as #packKnownOptionsToString(boolean).
Since:: 1.1.20
See Also:: packValue(StringBuilder), toString()

compareTo

public int compareTo(java.lang.Object other)

Compare two options, for display purposes. (Comparable interface) Two gameoptions are considered equal if they have the same key. Greater/lesser is determined by desc.compareTo().

Specified by:: compareTo in interface java.lang.Comparable<java.lang.Object>

Parameters:: other - A SOCGameOption to compare, or another object; if other isn't a gameoption, the Object.hashCode()s are compared.

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 SOCGameOption

FLAG_DROP_IF_UNUSED

FLAG_INTERNAL_GAME_PROPERTY

OTYPE_MIN

OTYPE_UNKNOWN

OTYPE_BOOL

OTYPE_INT

OTYPE_INTBOOL

OTYPE_ENUM

OTYPE_ENUMBOOL

OTYPE_STR

OTYPE_STRHIDE

OTYPE_MAX

K_SC_SANY

K_SC_SEAC

K_SC_FOG

K_SC_0RVP

K_SC_3IP

K_SC_CLVI

K_SC_PIRI

K_SC_FTRI

K_SC_WOND

VERSION_FOR_LONGER_OPTNAMES

allOptions

refreshList

optType

optFlags

defaultBoolValue

defaultIntValue

minIntValue

maxIntValue

enumVals

boolValue

intValue

strValue

optCL

userChanged

SOCGameOption

SOCGameOption

SOCGameOption

SOCGameOption

SOCGameOption

SOCGameOption

SOCGameOption

SOCGameOption

SOCGameOption

SOCGameOption

SOCGameOption

initAllOptions

Current known options:

Current Game Scenario options:

If you want to add a game option:

If you want to change a game option (in a later version):

If you want to remove or obsolete a game option (in a later version):

getBoolValue

setBoolValue

getIntValue

setIntValue

getStringValue

setStringValue

getMinVersion

getMaxEnumValueForVersion

getMaxIntValueForVersion

getAllKnownOptions

addKnownOption

setKnownOptionCurrentValue

cloneOptions

getOption

packKnownOptionsToString

packOptionsToString

packOptionsToString

packValue

parseOptionsToMap

parseOptionNameValue

parseOptionNameValue

optionsNewerThanVersion

optionsForVersion

implOptionsVersionCheck

trimEnumForVersion

adjustOptionsToKnown

soc.game
Class SOCGameOption