Package VASSAL.build

Class GameModule

java.lang.Object

VASSAL.search.AbstractImageFinder

VASSAL.build.AbstractBuildable

VASSAL.build.AbstractConfigurable

VASSAL.build.GameModule

All Implemented Interfaces:

AutoConfigurable, Buildable, Configurable, GpIdSupport, MutablePropertiesContainer, PropertyNameSource, PropertySource, TranslatableStringContainer, CommandEncoder, ValidityChecker, Translatable, Auditable, ImageSearchTarget, SearchTarget, ToolBarComponent

Direct Known Subclasses:

BasicModule

public class GameModule
extends AbstractConfigurable
implements CommandEncoder, ToolBarComponent, PropertySource, MutablePropertiesContainer, TranslatableStringContainer, GpIdSupport

The GameModule class is the base class for a VASSAL module. It is the root of the Buildable containment hierarchy, and thus also the root of the Editor's ConfigureTree. GameModule's implementation of CommandEncoder is slightly different, serving as a central dispatch point for all other CommandEncoders, which register themselves with GameModule. Components which are intended to be added directly to the GameModule are contained in the VASSAL.build.module package.

GameModule is a singleton, and contains access points for many other classes, such as DataArchive, ServerConnection, Logger, Chatter, and Prefs.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	GameModule.GameFileMode	Last type of game save/load for our current game

Nested classes/interfaces inherited from interface VASSAL.build.AutoConfigurable

AutoConfigurable.Util

Nested classes/interfaces inherited from interface VASSAL.build.module.properties.MutablePropertiesContainer

MutablePropertiesContainer.Impl

Nested classes/interfaces inherited from interface VASSAL.build.module.properties.TranslatableStringContainer

TranslatableStringContainer.Impl

Field Summary

Fields

Modifier and Type	Field	Description
static final String	BUILDFILE
static final String	BUILDFILE_OLD
static final String	DESCRIPTION
static final String	DRAWING_MOUSEOVER_INDEX_PROPERTY
static final String	DRAWING_MOUSEOVER_PROPERTY
static final String	IS_VISIBLE
static final String	MODULE_CURRENT_LOCALE
static final String	MODULE_CURRENT_LOCALE_NAME
static final String	MODULE_DESCRIPTION_PROPERTY
static final String	MODULE_NAME
static final String	MODULE_NAME_PROPERTY
static final String	MODULE_OTHER1_PROPERTY
static final String	MODULE_OTHER2_PROPERTY
static final String	MODULE_VASSAL_VERSION_CREATED_PROPERTY
static final String	MODULE_VASSAL_VERSION_RUNNING_PROPERTY
static final String	MODULE_VERSION
static final String	MODULE_VERSION_PROPERTY
static final String	NEXT_PIECESLOT_ID
static final String	PERSONAL_INFO	The Prefs key for the user's personal info
static final String	REAL_NAME	The Prefs key for the user's real name
static final String	RECENT_GAMES
static final String	SECRET_NAME	The Prefs key for the user's secret name
static final String	UI_PIECE_COUNT
static final String	UI_PIECE_INDEX
static final String	VASSAL_VERSION_CREATED
static final String	VASSAL_VERSION_RUNNING	The System property of this name will return a version identifier for the version of VASSAL being run

Fields inherited from class VASSAL.build.AbstractConfigurable

changeSupport, config, localizedName, myI18nData, name

Fields inherited from class VASSAL.build.AbstractBuildable

buildComponents, validator

Fields inherited from interface VASSAL.build.Configurable

NAME_PROPERTY

Constructor Summary

Constructors

Constructor	Description
GameModule(DataArchive archive)	Constructor for a GameModule.

Method Summary

Modifier and Type	Method	Description
void	addCommandEncoder(CommandEncoder ce)	GameModule holds the master list of CommandEncoders, and invokes them as appropriate when commands are sent and received.
void	addIdChangeListener(PropertyChangeListener l)	Currently used to listen for changes to player names
void	addKeyStrokeListener(KeyStrokeListener l)	The GameModule acts as the mediator for hotkey events.
void	addKeyStrokeSource(KeyStrokeSource src)	The GameModule acts as the mediator for hotkey events.
void	addMutableProperty(String key, MutableProperty p)	Adds a new mutable (changeable) "Global Property" to the Module.
void	addSideChangeListenerToPlayerRoster(PlayerRoster.SideChangeListener l)	Adds listener for players changing sides
void	addTo(Buildable b)	Game Module is normally at the root of the hierarchy, so it doesn't expect to get added to anything.
void	addTranslatableString(String key, TranslatableString p)	Add a property under the given key
void	appendToTitle(String s)	Deprecated, for removal: This API element is subject to removal in a future version. use updateTitleBar()
void	build(Element e)	Builds the module's component hierarchy from a given XML element, or a null one is given initializes a brand new default "new module" hierarchy.
void	clearPausedCommands()	Clear outstanding Commands Use where the calling level handles the sending of outstanding commands
static void	clearTempUserId()
GamePiece	createPiece(String type)	Central location to create any type of GamePiece from within VASSAL
GamePiece	createPiece(String type, GamePiece inner)	Central location to create any type of GamePiece Trait (Decorator) from within VASSAL
Command	decode(String command)	Decodes our inbound Command traffic -- incoming player commands ready to be executed.
String	encode(Command c)	Encodes our outbound Command traffic -- outgoing player commands to be sent to other players' clients via either online (server) or logfile (PBEM).
final void	finalizeUiPieceProcessing()	Record the end of a multi-piece UI gesture
void	fireKeyStroke(NamedKeyStroke stroke)	Invokes a NamedKeyStroke to all of our listeners.
String	generateGpId()	Allocates the next available GamePiece ID and returns it.
static String	getActiveUserId()
Class<?>[]	getAllowableConfigureComponents()	List of subcomponents which can be added to a GameModule.
ArchiveWriter	getArchiveWriter()	VASSAL modules are stored in ".vmod" files, which are actually simple ".zip" files with a unique extension.
String[]	getAttributeDescriptions()	Return an array of Strings describing the attributes of this object.
String[]	getAttributeNames()	Lists all the buildFile (XML) attribute names for this component.
Class<?>[]	getAttributeTypes()	Return the Class for the attributes of this object.
String	getAttributeValueString(String name)	Called by the Buildable.getBuildElement(org.w3c.dom.Document) method to write the attributes into an XML element
BasicLogger	getBasicLogger()
Chatter	getChatter()
long	getCombinedCrc()
long	getCombinedCrc(boolean forceRegenerate)
static String	getConfigureTypeName()	Gets the generic name for this type of class across all instances of it.
Console	getConsole()
JComponent	getControlPanel()
long	getCrc()
long	getCrc(boolean forceRegenerate)
DataArchive	getDataArchive()	VASSAL modules are stored in ".vmod" files, which are actually simple ".zip" files with a unique extension.
DebugControls	getDebugControls()
DeckManager	getDeckManager()
FileChooser	getEditorImageChooser()
FileChooser	getEditorSoundChooser()
List<String>	getExpressionList()	SearchTarget
FileChooser	getFileChooser()
JFrame	getFrame()	Deprecated. use getPlayerWindow()
String	getGameFile()
GameModule.GameFileMode	getGameFileMode()
static GameModule	getGameModule()
String	getGameName()
GameState	getGameState()	Return the object responsible for tracking the state of a game.
String	getGameVersion()
GpIdSupport	getGpIdSupport()
HelpFile	getHelpFile()
ComponentI18nData	getI18nData()
String	getI18nPrefix()
ImageTileSource	getImageTileSource()
IndexManager	getIndexManager()
String	getLocalizedGameName()
Object	getLocalizedProperty(Object key)	Returns a localized translation of the specified property value, if available.
KeyCommand	getLocationKeyCommand()
Logger	getLogger()
String	getModuleOther1()
String	getModuleOther2()
String	getMutablePropertiesContainerId()	Return a unique Id for the container
MutableProperty	getMutableProperty(String name)	Gets the value of a mutable (changeable) "Global Property".
int	getNextGpId()	Accessors to check and update the next GpId if necessary.
ToggleablePasswordConfigurer	getPasswordConfigurer()
PieceWindow	getPieceWindow()
PlayerRoster	getPlayerRoster()
PlayerWindow	getPlayerWindow()	"Player" in this context meaning the VASSAL Player, i.e.
Prefs	getPrefs()
Object	getProperty(Object key)	Gets the value of a module level global property -- this includes identification information for the local player as well as the contents of any Global Property objects defined at module level in the Module.
List<String>	getPropertyNames()	Override this method to provide a list of properties to be exposed for use by expressions in the module.
ResourcePathFinder	getResourcePathFinder()
Random	getRNG()
ServerConnection	getServer()
ChatServerControls	getServerControls()
static String	getTempUserId()
String	getTitleString()	Returns an appropriate Title Bar string for the main module window, based on the module name, the last read/written game file, and the manner of interaction with it.
JToolBar	getToolBar()	Provides access to the Game Module's toolbar.
TranslatableString	getTranslatableString(String name)	Find an object with the given name
String	getTranslatableStringContainerId()	Return a unique Id for the container
int	getUiPieceCount()	Return number of pieces to be processed by the current multi-piece UI gesture
int	getUiPieceIndex()	Return the index of the current piece being processed by the current multi-piece UI gesture
static String	getUserId()
String	getWindowTitleString(String key, String name)
String	getWindowTitleString(String key, String name, boolean moduleVersion)	Returns an appropriate Title Bar string for a window, based on the module name, the last read/written game file, and the manner of interaction with it.
WizardSupport	getWizardSupport()
static void	init(GameModule module)	Loads a module object into the player window.
void	initFrameTitle()	Sets the proper name for module window's title bar
final void	initializeUiPieceProcessing(int pieceCount)	A multi-piece UI gesture is starting.
boolean	isEditorOpen()	Is an editor window currently open
static boolean	isErrorLogToChat()
boolean	isLoadingContinuationSemaphore()
boolean	isLoadOverSemaphore()
boolean	isLocalizationEnabled()	Is the module being translated into the user's Locale? Localization is disabled when editing a module
boolean	isMatSupport()
boolean	isMultiPlayer()
boolean	isMultiplayerConnected()
boolean	isMutableButtonLabelSupport()
boolean	isNonBlankPassword()	Returns true if user has supplied a real password for current GameModule.
boolean	isRealName()	Returns true if user has supplied a real name Test's whether GameModule.REAL_NAME is non-empty and not "newbie"
boolean	isRefreshingSemaphore()
boolean	isReplayingOrLogging()
boolean	isSuppressAutoCenterUpdate()
boolean	isSuppressSounds()
boolean	isTranslatableSupport()
boolean	isTrueMovedSupport()
boolean	pauseLogging()	Pause logging and return true if successful.
final void	processNextUiPiece()	The next piece in a multi-piece UI gesture is about to be processed.
void	quit()	Exit the application, prompting user to save if necessary
void	refreshKeyStrokeListeners()	If our keyboard mapping paradigm changes (example: Mac Legacy preference checked/unchecked), we need to reregister all of our KeyStrokeListeners
final void	refreshVisibleMaps()	Refresh the visible portions of all currently showing maps.
void	removeCommandEncoder(CommandEncoder ce)	This method removes a CommandEncoder from the list of objects that will attempt to decode/encode a command
void	removeFrom(Buildable parent)	Since we aren't expecting to be addTo(VASSAL.build.Buildable)'ed to a parent, we likewise don't need to do much about being "removeFrom'ed" one.
void	removeIdChangeListener(PropertyChangeListener l)	Currently used to listen for changes to player names
void	removeKeyStrokeListener(KeyStrokeListener l)
MutableProperty	removeMutableProperty(String key)	Removes a mutable property from the Global Properties list.
void	removeSideChangeListenerFromPlayerRoster(PlayerRoster.SideChangeListener l)	Removes listener for players changing sides
TranslatableString	removeTranslatableString(String key)	Remove the property with the given key
void	resetSourcesAndListeners()
Command	resumeLogging()	Restart logging and return any outstanding commands
void	save()	If the module is being edited, write the module data to the current filename
void	saveAs()	If the module is being edited, write the module data after prompting for a new filename.
void	sendAndLog(Command c)	When the local player has taken any action that would change the game state (or otherwise needs to be sent to any other players' clients), the action should be encapsulated into a Command and sent here.
void	setAttribute(String name, Object value)	Sets a buildFile (XML) attribute value for this component.
void	setChatter(Chatter c)	Allows the Chat Log window to register itself to the Module.
void	setDirty(boolean touchThis)
static void	setErrorLogToChat(boolean errorLogToChat)
void	setGameFile(String gameFile, GameModule.GameFileMode mode)	Sets the most recent .VSAV / .VLOG file saved, loaded, or logged to, along with the type of action taken with that file.
void	setGameFileMode(GameModule.GameFileMode mode)	Sets the type of interaction we most recently had with saving/loading/replaying/logging, for managing title bars of windows.
void	setGpIdSupport(GpIdSupport s)	Registers a GamePiece ID support object for us to manage a namespace for unique GamePiece objects.
void	setLoadingContinuationSemaphore(boolean state)
void	setLoadOverSemaphore(boolean state)
void	setLocationKeyCommand(KeyCommand kc)
void	setMatSupport(boolean matSupport)
void	setMutableButtonSupport(boolean support)
void	setNextGpId(int id)	Sets the next available GamePiece ID
void	setPieceWindow(PieceWindow pieceWindow)	Allows a PieceWindow that wants to be our docked PieceWindow to register itself.
void	setPrefs(Prefs p)
void	setRefreshingSemaphore(boolean state)
void	setSuppressAutoCenterUpdate(boolean suppressAutoCenterUpdate)
void	setSuppressSounds(boolean suppressSounds)
static void	setTempUserId(String id)
void	setTrueMovedSupport(boolean trueMovedSupport)
static void	setUserId(String newId)	Set the identifier for the user
boolean	shutDown()	Prompt user to save open game and modules/extensions being edited
String	toString()
void	updateLastSave()	Save the current buildString for comparison when we try and quit.
void	updateMutableButtonLabels()	A property has changed somewhere, so we need to redraw all the toolbar buttons that use properties
void	updateTitleBar()	Updates the title bar of the main module window, and all map windows
void	warn(String s)	Display the given text in the control window's status line.

Methods inherited from class VASSAL.build.AbstractConfigurable

add, addPropertyChangeListener, getAttributeVisibility, getConfigureComponents, getConfigureName, getConfigurer, getFormattedStringList, getLocalizedConfigureName, getMenuTextList, getNamedKeyStrokeList, getPropertyList, getTypeName, remove, removePropertyChangeListener, setAllAttributesUntranslatable, setAttributeTranslatable, setConfigureName

Methods inherited from class VASSAL.build.AbstractBuildable

addImageNamesRecursively, buildString, getAllDescendantComponentsOf, getAncestor, getBuildables, getBuildComponents, getBuildElement, getComponents, getComponentsOf, getNonFolderAncestor, setAncestor, validate

Methods inherited from class VASSAL.search.AbstractImageFinder

addLocalImageNames, getAllImageNames, getLocalImageNames

Methods inherited from class java.lang.Object

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

Methods inherited from interface VASSAL.script.expression.Auditable

getComponentName, getComponentTypeName

Methods inherited from interface VASSAL.build.Buildable

getBuildElement, isMandatory, isMovable, isUnique

Methods inherited from interface VASSAL.tools.ToolBarComponent

updateToolbarButtons

Field Details

MODULE_NAME

public static final String MODULE_NAME

See Also:

• Constant Field Values

MODULE_VERSION

public static final String MODULE_VERSION

See Also:

• Constant Field Values

DESCRIPTION

public static final String DESCRIPTION

See Also:

• Constant Field Values

VASSAL_VERSION_CREATED

public static final String VASSAL_VERSION_CREATED

See Also:

• Constant Field Values

VASSAL_VERSION_RUNNING

public static final String VASSAL_VERSION_RUNNING

The System property of this name will return a version identifier for the version of VASSAL being run

See Also:

• Constant Field Values

NEXT_PIECESLOT_ID

public static final String NEXT_PIECESLOT_ID

See Also:

• Constant Field Values

BUILDFILE

public static final String BUILDFILE

See Also:

• Constant Field Values

BUILDFILE_OLD

public static final String BUILDFILE_OLD

See Also:

• Constant Field Values

REAL_NAME

public static final String REAL_NAME

The Prefs key for the user's real name

See Also:

• Constant Field Values

SECRET_NAME

public static final String SECRET_NAME

The Prefs key for the user's secret name

See Also:

• Constant Field Values

PERSONAL_INFO

public static final String PERSONAL_INFO

The Prefs key for the user's personal info

See Also:

• Constant Field Values

MODULE_NAME_PROPERTY

public static final String MODULE_NAME_PROPERTY

See Also:

• Constant Field Values

MODULE_VERSION_PROPERTY

public static final String MODULE_VERSION_PROPERTY

See Also:

• Constant Field Values

MODULE_DESCRIPTION_PROPERTY

public static final String MODULE_DESCRIPTION_PROPERTY

See Also:

• Constant Field Values

MODULE_OTHER1_PROPERTY

public static final String MODULE_OTHER1_PROPERTY

See Also:

• Constant Field Values

MODULE_OTHER2_PROPERTY

public static final String MODULE_OTHER2_PROPERTY

See Also:

• Constant Field Values

MODULE_VASSAL_VERSION_CREATED_PROPERTY

public static final String MODULE_VASSAL_VERSION_CREATED_PROPERTY

See Also:

• Constant Field Values

MODULE_VASSAL_VERSION_RUNNING_PROPERTY

public static final String MODULE_VASSAL_VERSION_RUNNING_PROPERTY

See Also:

• Constant Field Values

MODULE_CURRENT_LOCALE

public static final String MODULE_CURRENT_LOCALE

See Also:

• Constant Field Values

MODULE_CURRENT_LOCALE_NAME

public static final String MODULE_CURRENT_LOCALE_NAME

See Also:

• Constant Field Values

DRAWING_MOUSEOVER_PROPERTY

public static final String DRAWING_MOUSEOVER_PROPERTY

See Also:

• Constant Field Values

DRAWING_MOUSEOVER_INDEX_PROPERTY

public static final String DRAWING_MOUSEOVER_INDEX_PROPERTY

See Also:

• Constant Field Values

IS_VISIBLE

public static final String IS_VISIBLE

See Also:

• Constant Field Values

UI_PIECE_COUNT

public static final String UI_PIECE_COUNT

See Also:

• Constant Field Values

UI_PIECE_INDEX

public static final String UI_PIECE_INDEX

See Also:

• Constant Field Values

RECENT_GAMES

public static final String RECENT_GAMES

See Also:

• Constant Field Values

Constructor Details

GameModule

public GameModule(DataArchive archive)

Constructor for a GameModule.

Parameters:

archive - The .vmod (or .tmp) archive to associate

Method Details

getDeckManager

public DeckManager getDeckManager()

getPasswordConfigurer

public ToggleablePasswordConfigurer getPasswordConfigurer()

isMatSupport

public boolean isMatSupport()

Returns:

True if there are any Mat or MatCargo objects in the module

setMatSupport

public void setMatSupport(boolean matSupport)

Parameters:

matSupport - true if a Mat or MatCargo trait has been added to the module (thus meaning we'll want to do those calculations during moves/selects)

isTrueMovedSupport

public boolean isTrueMovedSupport()

Returns:

True if there are any ignore-small-moves traits in the module

setTrueMovedSupport

public void setTrueMovedSupport(boolean trueMovedSupport)

Parameters:

trueMovedSupport - true if a ignore-small-moves trait exists in the module

setMutableButtonSupport

public void setMutableButtonSupport(boolean support)

Parameters:

support - true if any toolbar buttons use $...$ or { } expressions

isMutableButtonLabelSupport

public boolean isMutableButtonLabelSupport()

Returns:

True if there are toolbar buttons using $...$ or { } expressions in the module

isSuppressSounds

public boolean isSuppressSounds()

Returns:

True if currently suppressing sounds (eg during a Global Key Command)

setSuppressSounds

public void setSuppressSounds(boolean suppressSounds)

Parameters:

suppressSounds - true if sounds should be suppressed during command processing

setSuppressAutoCenterUpdate

public void setSuppressAutoCenterUpdate(boolean suppressAutoCenterUpdate)

isSuppressAutoCenterUpdate

public boolean isSuppressAutoCenterUpdate()

getLocationKeyCommand

public KeyCommand getLocationKeyCommand()

setLocationKeyCommand

public void setLocationKeyCommand(KeyCommand kc)

getIndexManager

public IndexManager getIndexManager()

setLoadOverSemaphore

public void setLoadOverSemaphore(boolean state)

Parameters:

state - - true if we're loading-over-top of an existing game (so don't disturb UI elements if possible, will receive a setup(true) soon enough)

isLoadOverSemaphore

public boolean isLoadOverSemaphore()

Returns:

true if we're loading-over-top of an existing game (so don't disturb UI elements if possible, will receive a setup(true) soon enough)

setRefreshingSemaphore

public void setRefreshingSemaphore(boolean state)

Parameters:

state - - true if refreshing (suppresses GameState.setup method)

isRefreshingSemaphore

public boolean isRefreshingSemaphore()

Returns:

true if refreshing (suppresses GameState.setup method)

setLoadingContinuationSemaphore

public void setLoadingContinuationSemaphore(boolean state)

Parameters:

state - - true if loading game as continuation (don't thrash listeners)

isLoadingContinuationSemaphore

public boolean isLoadingContinuationSemaphore()

Returns:

true if loading game as continuation (don't thrash listeners)

getFrame

@Deprecated(since="2020-08-06",
            forRemoval=false)
public JFrame getFrame()

Deprecated.

use getPlayerWindow()

Returns:

the top-level frame of the controls window

toString

public String toString()

Overrides:

toString in class Object

Returns:

String identifier for module

getPlayerWindow

public PlayerWindow getPlayerWindow()

"Player" in this context meaning the VASSAL Player, i.e. the main module window, as opposed to any individual player meaning participant-in-a-boardgame.

Returns:

The main window for the module

initFrameTitle

public void initFrameTitle()

Sets the proper name for module window's title bar

getWizardSupport

public WizardSupport getWizardSupport()

Returns:

Our wizard

getServerControls

public ChatServerControls getServerControls()

Returns:

our ChatServerControls.

getDebugControls

public DebugControls getDebugControls()

Returns:

our DebugControls

getConsole

public Console getConsole()

Returns:

our Console

isErrorLogToChat

public static boolean isErrorLogToChat()

Returns:

True if errorLog should also be sent to chat log.

setErrorLogToChat

public static void setErrorLogToChat(boolean errorLogToChat)

Parameters:

errorLogToChat - true if errorLog should also be sent to chat log

getI18nPrefix

public String getI18nPrefix()

Overrides:

getI18nPrefix in class AbstractConfigurable

Returns:

Generate a standard prefix for i18n keys for attributes of this component - Classname.attributeName

setDirty

public void setDirty(boolean touchThis)

build

public void build(Element e)

Builds the module's component hierarchy from a given XML element, or a null one is given initializes a brand new default "new module" hierarchy.

Specified by:

build in interface Buildable

Overrides:

build in class AbstractBuildable

Parameters:

e - XML element to build from, or null to build the default hierarchy

setAttribute

public void setAttribute(String name,
 Object value)

Sets a buildFile (XML) attribute value for this component.

Specified by:

setAttribute in interface AutoConfigurable

Specified by:

setAttribute in interface Translatable

Specified by:

setAttribute in class AbstractBuildable

Parameters:

name - the name of the attribute. Will be one of those listed in getAttributeNames()

value - If the value parameter is a String, it will be the value returned by getAttributeValueString(java.lang.String) for the same key. If the implementing class extends AbstractConfigurable, then value can also be an instance of

getAttributeValueString

public String getAttributeValueString(String name)

Description copied from interface: AutoConfigurable

Called by the Buildable.getBuildElement(org.w3c.dom.Document) method to write the attributes into an XML element

Specified by:

getAttributeValueString in interface AutoConfigurable

Specified by:

getAttributeValueString in interface Translatable

Specified by:

getAttributeValueString in class AbstractBuildable

Parameters:

name - the name of the attribute. Will be one of those listed in getAttributeNames()

Returns:

a String representation of the attribute with the given name. When initializing a module, this String value will be passed to setAttribute(java.lang.String, java.lang.Object)

addTo

public void addTo(Buildable b)

Game Module is normally at the root of the hierarchy, so it doesn't expect to get added to anything.

Specified by:

addTo in interface Buildable

Parameters:

b - Notional "parent" of this GameModule

getConfigureTypeName

public static String getConfigureTypeName()

Gets the generic name for this type of class across all instances of it. Appears in the Editor window in [..] as e.g. [Map], [Prototype], etc.

Returns:

The generic name for this kind of component, i.e. the part appearing [In Brackets] in the Editor's ConfigureTree.

removeFrom

public void removeFrom(Buildable parent)

Since we aren't expecting to be addTo(VASSAL.build.Buildable)'ed to a parent, we likewise don't need to do much about being "removeFrom'ed" one.

Specified by:

removeFrom in interface Configurable

Parameters:

parent - Notional "parent" of this GameModule

getHelpFile

public HelpFile getHelpFile()

Specified by:

getHelpFile in interface Configurable

Returns:

a HelpFile describing how to use and configure this component

getAttributeNames

public String[] getAttributeNames()

Lists all the buildFile (XML) attribute names for this component. If this component is ALSO an AbstractConfigurable, then this list of attributes determines the appropriate attribute order for AbstractConfigurable.getAttributeDescriptions() and AbstractConfigurable.getAttributeTypes().

Specified by:

getAttributeNames in interface AutoConfigurable

Specified by:

getAttributeNames in class AbstractBuildable

Returns:

a list of all buildFile (XML) attribute names for this component

See Also:

• AbstractBuildable

getAttributeDescriptions

public String[] getAttributeDescriptions()

Description copied from interface: AutoConfigurable

Return an array of Strings describing the attributes of this object. These strings are used as prompts in the Properties window for this object.

Specified by:

getAttributeDescriptions in interface AutoConfigurable

Specified by:

getAttributeDescriptions in class AbstractConfigurable

Returns:

an array of Strings describing the buildFile (XML) attributes of this component. These strings are used as prompts in the Properties window for this object, when the component is configured in the Editor. The order of descriptions should be the same as the order of names in AbstractBuildable.getAttributeNames()

See Also:

• AbstractConfigurable

getAttributeTypes

public Class<?>[] getAttributeTypes()

Description copied from interface: AutoConfigurable

Return the Class for the attributes of this object. Valid classes are: String, Integer, Double, Boolean, Image, File, Color, and KeyStroke

Specified by:

getAttributeTypes in interface AutoConfigurable

Specified by:

getAttributeTypes in class AbstractConfigurable

Returns:

the Class for the buildFile (XML) attributes of this component. Valid classes include: String, Integer, Double, Boolean, Image, Color, and KeyStroke, along with any class for which a Configurer exists in VASSAL.configure. The class determines, among other things, which type of AutoConfigurer will be used to configure the attribute when the object is configured in the Editor. The order of classes should be the same as the order of names in AbstractBuildable.getAttributeNames()

See Also:

• AbstractConfigurable

getAllowableConfigureComponents

public Class<?>[] getAllowableConfigureComponents()

List of subcomponents which can be added to a GameModule.

Specified by:

getAllowableConfigureComponents in interface Configurable

Returns:

a list of valid sub-component Classes. If a Class appears in this list, then instances of that class may be added to this component from the Editor's ConfigureTree window by right-clicking on the component and selecting the appropriate "Add" option.

See Also:

• Configurable

addKeyStrokeSource

public void addKeyStrokeSource(KeyStrokeSource src)

The GameModule acts as the mediator for hotkey events. Components that wish to fire hotkey events when they have the focus should register themselves using this method. These events will be forwarded to all listeners that have registered themselves with addKeyStrokeListener(VASSAL.tools.KeyStrokeListener)

Parameters:

src - KeyStrokeSource Component that wants to register as a source for hotkey events

removeKeyStrokeListener

public void removeKeyStrokeListener(KeyStrokeListener l)

addKeyStrokeListener

public void addKeyStrokeListener(KeyStrokeListener l)

The GameModule acts as the mediator for hotkey events. Objects that react to hotkey events should register themselves using this method. Any component that has been registered with addKeyStrokeSource(VASSAL.tools.KeyStrokeSource) will forward hotkey events to listeners registered with this method.

Parameters:

l - KeystrokeListener to add

resetSourcesAndListeners

public void resetSourcesAndListeners()

refreshKeyStrokeListeners

public void refreshKeyStrokeListeners()

If our keyboard mapping paradigm changes (example: Mac Legacy preference checked/unchecked), we need to reregister all of our KeyStrokeListeners

fireKeyStroke

public void fireKeyStroke(NamedKeyStroke stroke)

Invokes a NamedKeyStroke to all of our listeners.

Parameters:

stroke - NamedKeyStroke to invoke

getGameName

public String getGameName()

Returns:

the name of the game for this module

getLocalizedGameName

public String getLocalizedGameName()

Returns:

the localized/translated game name for this module

getGameVersion

public String getGameVersion()

Returns:

the version number for this module

getModuleOther1

public String getModuleOther1()

Returns:

extra information 1 for module

getModuleOther2

public String getModuleOther2()

Returns:

extra information 2 for module

addIdChangeListener

public void addIdChangeListener(PropertyChangeListener l)

Currently used to listen for changes to player names

Parameters:

l - propertyChangeListener to add

removeIdChangeListener

public void removeIdChangeListener(PropertyChangeListener l)

Currently used to listen for changes to player names

Parameters:

l - propertyChangeListener to remove

getPrefs

public Prefs getPrefs()

Returns:

the preferences for this module

isTranslatableSupport

public boolean isTranslatableSupport()

addCommandEncoder

public void addCommandEncoder(CommandEncoder ce)

GameModule holds the master list of CommandEncoders, and invokes them as appropriate when commands are sent and received. This method adds a CommandEncoder to the list of objects that will attempt to decode/encode a command.

See Also:

• decode(java.lang.String)
• encode(VASSAL.command.Command)

removeCommandEncoder

public void removeCommandEncoder(CommandEncoder ce)

This method removes a CommandEncoder from the list of objects that will attempt to decode/encode a command

See Also:

• addCommandEncoder(VASSAL.command.CommandEncoder)
• decode(java.lang.String)
• encode(VASSAL.command.Command)

createPiece

public GamePiece createPiece(String type)

Central location to create any type of GamePiece from within VASSAL

Parameters:

type - String definition of the piece

Returns:

Created Piece

createPiece

public GamePiece createPiece(String type,
 GamePiece inner)

Central location to create any type of GamePiece Trait (Decorator) from within VASSAL

Parameters:

type - String definition of the Trait (Decorator)

Returns:

Created Piece

warn

public void warn(String s)

Display the given text in the control window's status line. Save the messages for later if the Chatter has not been initialised yet

Parameters:

s - message to display in Chat Log

getRNG

public Random getRNG()

Returns:

a single Random number generator that all objects may share

getLogger

public Logger getLogger()

Returns:

the object responsible for logging commands to a .vlog logfile to support PBEM play

getBasicLogger

public BasicLogger getBasicLogger()

Returns:

BasicLogger, if we have one

setChatter

public void setChatter(Chatter c)

Allows the Chat Log window to register itself to the Module. When a Chat Log is first registered, display any warning messages deferred during earlier initialisation

Parameters:

c - The Chat Log window we want to use

getControlPanel

public JComponent getControlPanel()

getChatter

public Chatter getChatter()

Returns:

the registered Chat Log for the Module Window (window that displays chat text)

getPieceWindow

public PieceWindow getPieceWindow()

Returns:

the registered docked PieceWindow (game piece palette) for the module

setPieceWindow

public void setPieceWindow(PieceWindow pieceWindow)

Allows a PieceWindow that wants to be our docked PieceWindow to register itself.

Parameters:

pieceWindow - PieceWindow to be our docked one

setPrefs

public void setPrefs(Prefs p)

decode

public Command decode(String command)

Decodes our inbound Command traffic -- incoming player commands ready to be executed. Unlike everybody else's decode method, the GameModule's method first pulls apart strings of multiple commands into singles. It then invokes each of its registered CommandEncoders in turn until one of them is able to deserialize the command from a String into a Command object ready to be executed.

Specified by:

decode in interface CommandEncoder

encode

public String encode(Command c)

Encodes our outbound Command traffic -- outgoing player commands to be sent to other players' clients via either online (server) or logfile (PBEM). Unlike everybody else's encode method, the GameModule's method accepts Command trees containing multiple appended commands. It goes through them in order and for each command invokes each of its registered CommandEncoders in turn until one of them is able to serialize the Command object into an ascii-compatible String ready to be sent to other players' clients. It does this for each of the subcommands in the list, and the results for all are returned as a single String.

Specified by:

encode in interface CommandEncoder

getFileChooser

public FileChooser getFileChooser()

Returns:

a common FileChooser so that recent file locations can be remembered

getEditorImageChooser

public FileChooser getEditorImageChooser()

Returns:

a common FileChooser so that recent file locations can be remembered

getEditorSoundChooser

public FileChooser getEditorSoundChooser()

Returns:

a common FileChooser so that recent file locations can be remembered

getToolBar

public JToolBar getToolBar()

Provides access to the Game Module's toolbar.

Specified by:

getToolBar in interface ToolBarComponent

Returns:

the JToolBar of the command window

getWindowTitleString

public String getWindowTitleString(String key,
 String name,
 boolean moduleVersion)

Returns an appropriate Title Bar string for a window, based on the module name, the last read/written game file, and the manner of interaction with it.

Parameters:

key - Localization key to be used to generate string

name - Name of the object whose title bar is to be generated

moduleVersion - if true, include the module version number

Returns:

appropriate title bar string for a window.

getWindowTitleString

public String getWindowTitleString(String key,
 String name)

getTitleString

public String getTitleString()

Returns an appropriate Title Bar string for the main module window, based on the module name, the last read/written game file, and the manner of interaction with it.

Returns:

appropriate title bar string for main module window.

updateTitleBar

public void updateTitleBar()

Updates the title bar of the main module window, and all map windows

appendToTitle

@Deprecated(since="2020-09-16",
            forRemoval=true)
public void appendToTitle(String s)

Deprecated, for removal: This API element is subject to removal in a future version.

use updateTitleBar()

Parameters:

s - String to append to title

setGameFile

public void setGameFile(String gameFile,
 GameModule.GameFileMode mode)

Sets the most recent .VSAV / .VLOG file saved, loaded, or logged to, along with the type of action taken with that file.

Parameters:

gameFile - Most recent VSAV/VLOG if any

mode - mode of access

getGameFile

public String getGameFile()

Returns:

Most recent .VSAV/.VLOG that we've read or written.

setGameFileMode

public void setGameFileMode(GameModule.GameFileMode mode)

Sets the type of interaction we most recently had with saving/loading/replaying/logging, for managing title bars of windows.

Parameters:

mode - mode of access

getGameFileMode

public GameModule.GameFileMode getGameFileMode()

Returns:

Returns the most recent type of interaction we've had for saving/loading/replaying/logging the game, for managing title bars of windows.

isReplayingOrLogging

public boolean isReplayingOrLogging()

Returns:

true if we are currently logging or replaying a game.

quit

public void quit()

Exit the application, prompting user to save if necessary

shutDown

public boolean shutDown()

Prompt user to save open game and modules/extensions being edited

Returns:

true if shutDown should proceed, i.e. user did not cancel

sendAndLog

public void sendAndLog(Command c)

When the local player has taken any action that would change the game state (or otherwise needs to be sent to any other players' clients), the action should be encapsulated into a Command and sent here. This method encodes the Command, sends it to the server (if we're online) and write it to a .vlog PBEM logfile (if any is open). It thus drives both formats of multiplayer game through a common interface.

Parameters:

c - The Command to be sent and logged.

See Also:

• encode(VASSAL.command.Command)

pauseLogging

public boolean pauseLogging()

Pause logging and return true if successful. Return false if logging already paused While Paused, commands are accumulated into pausedCommands so that they can all be logged at the same time, and generate a single UNDO command.

Returns:

Current logging pause status, false if logging currently paused

resumeLogging

public Command resumeLogging()

Restart logging and return any outstanding commands

Returns:

any outstanding Command (can contain multiple chained commands)

clearPausedCommands

public void clearPausedCommands()

Clear outstanding Commands Use where the calling level handles the sending of outstanding commands

getActiveUserId

public static String getActiveUserId()

Returns:

the userId/password we're currently using, in case we're using one of our alternate defaults. Or if none explicitly picked, the actual contents of our password field.

getTempUserId

public static String getTempUserId()

setTempUserId

public static void setTempUserId(String id)

clearTempUserId

public static void clearTempUserId()

getUserId

public static String getUserId()

Returns:

a String that uniquely identifies the user

setUserId

public static void setUserId(String newId)

Set the identifier for the user

getServer

public ServerConnection getServer()

Returns:

the object responsible for sending messages to the server

isMultiPlayer

public boolean isMultiPlayer()

Returns:

true if the game is online or has ever had more than one player.

isMultiplayerConnected

public boolean isMultiplayerConnected()

Returns:

true if the game is currently online

init

public static void init(GameModule module)
                 throws IOException

Loads a module object into the player window. Registers a singleton GameModule and invokes Buildable.build(org.w3c.dom.Element) on it to build it from the XML buildFile. This will have the effect of invoking Buildable.build(org.w3c.dom.Element) on all of the module's subcomponents as well, effectively building our whole component hierarchy from the XML.

Throws:

IOException

updateLastSave

public void updateLastSave()

Save the current buildString for comparison when we try and quit.

generateGpId

public String generateGpId()

Allocates the next available GamePiece ID and returns it.

Specified by:

generateGpId in interface GpIdSupport

Returns:

an available GpID

See Also:

• GpIdSupport

getNextGpId

public int getNextGpId()

Description copied from interface: GpIdSupport

Accessors to check and update the next GpId if necessary.

Specified by:

getNextGpId in interface GpIdSupport

Returns:

the next available GpId (GamePiece ID) (but doesn't allocate it -- for that see generateGpId())

See Also:

• GpIdSupport

setNextGpId

public void setNextGpId(int id)

Sets the next available GamePiece ID

Specified by:

setNextGpId in interface GpIdSupport

Parameters:

id - new value for nextGpId.

See Also:

• GpIdSupport

setGpIdSupport

public void setGpIdSupport(GpIdSupport s)

Registers a GamePiece ID support object for us to manage a namespace for unique GamePiece objects.

Parameters:

s - GamePiece ID object

getGpIdSupport

public GpIdSupport getGpIdSupport()

Returns:

Our registered Game Piece ID namespace service provider.

getDataArchive

public DataArchive getDataArchive()

VASSAL modules are stored in ".vmod" files, which are actually simple ".zip" files with a unique extension.

Returns:

the object which stores data for the module -- our .vmod Zip file.

getResourcePathFinder

public ResourcePathFinder getResourcePathFinder()

getArchiveWriter

public ArchiveWriter getArchiveWriter()

VASSAL modules are stored in ".vmod" files, which are actually simple ".zip" files with a unique extension. If the module is being edited, return the writeable archive for the module

Returns:

the writer for our .vmod Zip file

getImageTileSource

public ImageTileSource getImageTileSource()

Returns:

the object that provides tiling and caching services for tiling large map images.

isLocalizationEnabled

public boolean isLocalizationEnabled()

Is the module being translated into the user's Locale? Localization is disabled when editing a module

Returns:

true if the module/extension has been localized

isEditorOpen

public boolean isEditorOpen()

Is an editor window currently open

Returns:

true if we're running with an editor window

getGameModule

public static GameModule getGameModule()

Returns:

the singleton instance of GameModule

getGameState

public GameState getGameState()

Return the object responsible for tracking the state of a game. Only one game in progress is allowed;

saveAs

public void saveAs()

If the module is being edited, write the module data after prompting for a new filename.

save

public void save()

If the module is being edited, write the module data to the current filename

isRealName

public boolean isRealName()

Returns true if user has supplied a real name Test's whether GameModule.REAL_NAME is non-empty and not "newbie"

Returns:

true if user supplied a real name

isNonBlankPassword

public boolean isNonBlankPassword()

Returns true if user has supplied a real password for current GameModule. Test's whether GameModule.SECRET_NAME is non-empty

Returns:

true if user supplied a real password

getProperty

public Object getProperty(Object key)

Gets the value of a module level global property -- this includes identification information for the local player as well as the contents of any Global Property objects defined at module level in the Module.

Specified by:

getProperty in interface PropertySource

Parameters:

key - identifies the global property to be returned

Returns:

value of designated global property

refreshVisibleMaps

public final void refreshVisibleMaps()

Refresh the visible portions of all currently showing maps. This is called in when the following are completed: - Any right-click menu option on a piece - Any Toolbar button action - Any Toolbar Menu item selection - Each Step replay from a log file - Each Undo - Each time a counter or stack is drag'n'dropped - Each message received during on-line play - Any click on an Action Button These eight actions can cause changes that result in text displaying Calculated properties and Beanshell expressions to change in places unrelated to where the action occurred, leaving these counters out of sync until a later click in their general area.

getUiPieceCount

public int getUiPieceCount()

Return number of pieces to be processed by the current multi-piece UI gesture

getUiPieceIndex

public int getUiPieceIndex()

Return the index of the current piece being processed by the current multi-piece UI gesture

initializeUiPieceProcessing

public final void initializeUiPieceProcessing(int pieceCount)

A multi-piece UI gesture is starting. Record the number of pieces to be processed and reset the counter.

Parameters:

pieceCount - Number of pieces to be processed

processNextUiPiece

public final void processNextUiPiece()

The next piece in a multi-piece UI gesture is about to be processed.

finalizeUiPieceProcessing

public final void finalizeUiPieceProcessing()

Record the end of a multi-piece UI gesture

getPropertyNames

public List<String> getPropertyNames()

Description copied from class: AbstractBuildable

Override this method to provide a list of properties to be exposed for use by expressions in the module.

Specified by:

getPropertyNames in interface PropertyNameSource

Overrides:

getPropertyNames in class AbstractBuildable

Returns:

Default implementation of PropertyNameSource - No properties exposed

updateMutableButtonLabels

public void updateMutableButtonLabels()

A property has changed somewhere, so we need to redraw all the toolbar buttons that use properties

getMutableProperty

public MutableProperty getMutableProperty(String name)

Gets the value of a mutable (changeable) "Global Property". Module level Global Properties serve as the "global variables" of a VASSAL Module, as they are accessible by any component at any time.

Specified by:

getMutableProperty in interface MutablePropertiesContainer

Parameters:

name - identifies the Global Property whose value should be returned

Returns:

value of designated global property

getTranslatableString

public TranslatableString getTranslatableString(String name)

Description copied from interface: TranslatableStringContainer

Find an object with the given name

Specified by:

getTranslatableString in interface TranslatableStringContainer

addMutableProperty

public void addMutableProperty(String key,
 MutableProperty p)

Adds a new mutable (changeable) "Global Property" to the Module. Module level Global Properties serve as the "global variables" of a VASSAL Module, as they are accessible by any component at any time.

Specified by:

addMutableProperty in interface MutablePropertiesContainer

Parameters:

key - Name for the new Global Property

p - Starting property value

addTranslatableString

public void addTranslatableString(String key,
 TranslatableString p)

Description copied from interface: TranslatableStringContainer

Add a property under the given key

Specified by:

addTranslatableString in interface TranslatableStringContainer

Parameters:

key - key

p - property

removeMutableProperty

public MutableProperty removeMutableProperty(String key)

Removes a mutable property from the Global Properties list.

Specified by:

removeMutableProperty in interface MutablePropertiesContainer

Parameters:

key - Name of the Global Property

Returns:

the removed property, for some reason.

removeTranslatableString

public TranslatableString removeTranslatableString(String key)

Description copied from interface: TranslatableStringContainer

Remove the property with the given key

Specified by:

removeTranslatableString in interface TranslatableStringContainer

Parameters:

key - key

getMutablePropertiesContainerId

public String getMutablePropertiesContainerId()

Description copied from interface: MutablePropertiesContainer

Return a unique Id for the container

Specified by:

getMutablePropertiesContainerId in interface MutablePropertiesContainer

Returns:

Identifies the ID/level for mutable properties stored here in the Module.

getTranslatableStringContainerId

public String getTranslatableStringContainerId()

Description copied from interface: TranslatableStringContainer

Return a unique Id for the container

Specified by:

getTranslatableStringContainerId in interface TranslatableStringContainer

getLocalizedProperty

public Object getLocalizedProperty(Object key)

Description copied from interface: PropertySource

Returns a localized translation of the specified property value, if available. Otherwise returns the non-localized version.

Specified by:

getLocalizedProperty in interface PropertySource

Parameters:

key - Name of the property to get the value of

Returns:

Localized/translated name of the named property, if one is available, otherwise returns the non-localized name

getCrc

public long getCrc()

Returns:

a cumulative CRC from all of our files

getCrc

public long getCrc(boolean forceRegenerate)

getCombinedCrc

public long getCombinedCrc()

getCombinedCrc

public long getCombinedCrc(boolean forceRegenerate)

getI18nData

public ComponentI18nData getI18nData()

Specified by:

getI18nData in interface Translatable

Overrides:

getI18nData in class AbstractConfigurable

Returns:

the object containing the internationalization/localization information for this component

getPlayerRoster

public PlayerRoster getPlayerRoster()

Returns:

the PlayerRoster instance, or null if no PlayerRoster exists within this GameModule

addSideChangeListenerToPlayerRoster

public void addSideChangeListenerToPlayerRoster(PlayerRoster.SideChangeListener l)

Adds listener for players changing sides

Parameters:

l - new SideChangeListener

removeSideChangeListenerFromPlayerRoster

public void removeSideChangeListenerFromPlayerRoster(PlayerRoster.SideChangeListener l)

Removes listener for players changing sides

Parameters:

l - old SideChangeListener

getExpressionList

public List<String> getExpressionList()

Description copied from class: AbstractConfigurable

SearchTarget

Specified by:

getExpressionList in interface SearchTarget

Overrides:

getExpressionList in class AbstractConfigurable

Returns:

a list of the Configurables string/expression fields if any (for search)