<commit_before>== VASSAL Reference Manual
[#top]

[.small]#<<index.adoc#toc,Home>> > <<GameModule.adoc#top,Module>> > <<PieceWindow.adoc#top,Game Piece Palette>> > <<GamePiece.adoc#top,Game Piece>> > *Properties*#

'''''

=== Properties

[width="100%",cols="34%,33%,33%",]
|===
a|
A Property is like a variable in programming: it has a _value_ which can be referenced by including its _name_ in <<Expression.adoc#top,Expressions>>, <<MessageFormat.adoc#top,Message Formats>> and other similar fields.
Most types of Property have their values change through the course of the game.
Some Properties can have their values set by commands provided in Game Pieces themselves; others have their values set by the system and cannot be changed from within the module.

Each Game Piece has its own set of properties (each with a name and a value) that can be used for identification by various components.
You can add your own new properties to a Game Piece _explicitly_ by adding <<DynamicProperty.adoc#top,Dynamic Property>> traits to create values which can be changed during the course of the game and <<PropertyMarker.adoc#top,Marker>> traits for properties whose values will remain constant.
System-defined properties are also added _implicitly_ when other traits are added (see below). <<GlobalProperties.adoc#top,Global Properties>> can also be defined for a Zone, a Map or for the entire module.
If a referenced Property name is not defined in a Game Piece, the VASSAL looks for the value in the Zone containing the piece, then in the Map containing the piece, then in the module.

Properties can be matched using <<Expression.adoc#top,Expressions>> like _name == value_ for an exact match, _name != value_ for a non-match, or _name =~ value_ for a https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[regular expression] match.
For properties that return a numeric value (e.g.
the level in a <<Layer.adoc#Properties,Layer)>> you can use _<_, _<=_, _>_, and _>=._  You can combine expressions using && for logical AND and || for a logical OR.

*Components that use properties*

* Any <<MessageFormat.adoc#top,Message Format>> defined in a Game Piece will substitute values for the properties defined on that Game Piece.

* The <<Map.adoc#GlobalKeyCommand,Global Key Command>> component uses properties to determine which pieces will respond to the command.
* The <<Map.adoc#GamePieceLayers,Game Piece Layers>> component uses properties to determine relative ordering when drawing pieces on the map.
* The <<TriggerAction.adoc#top,Trigger Action>> trait uses properties to determine when to fire a Key Command or <<NamedKeyCommand.adoc#top,Named Key Command>> .
* The <<Label.adoc#top,Text Label>> trait substitutes properties when setting the text of the label.
* A <<ZonedGrid.adoc#Zone,Zone>> uses properties to specify a <<ZonedGrid.adoc#ZoneHighlighter,Zone Highlighter>>.

*Properties defined by Game Pieces*

* The <<BasicPiece.adoc#top,Basic Piece>> defines properties related to a piece's name, location, side, and whether it's selected.

* The <<Layer.adoc#Properties,Layer>> trait defines properties related to the state of that Layer.
* The <<Rotate.adoc#top,Rotate>> trait defines properties related to the current facing of the piece.

* The <<Label.adoc#top,Text Label>> trait returns the value of the label as a property.
* The <<PropertyMarker.adoc#top,Marker>> trait allows you to define your own static properties.
* The <<DynamicProperty.adoc#top,Dynamic Property>> trait allows you to define your own changeable properties.

* The <<MarkMoved.adoc#top,Mark When Moved>> trait sets a property when a piece has moved.
* The <<Mask.adoc#Properties,Mask>> trait sets a property when the piece is masked.
* The <<Hideable.adoc#top,Invisible>> trait sets a property when the piece is invisible.

* The <<PropertySheet.adoc#top,Property Sheet>> trait exposes a set of user-editable properties.

*Properties defined by other components*

* The <<GlobalProperties.adoc#top,Global Property>> component defines properties for a <<ZonedGrid.adoc#Zone,Zone>>, <<Map.adoc#top,Map>> or the <<GameModule.adoc#top,module>>.
* The <<GlobalOptions.adoc#top,Global Options>> component allows you to tie property values to preferences settings.
* The results of a roll by a <<GameModule.adoc#DiceButton,Dice Button>> is exposed as a property
* A <<Deck.adoc#top,Deck>> component exposes the number of cards remaining as a Map-level property.
|===

==== Handy Combined List of VASSAL-defined Properties for Game Pieces

|===
|Property |Trait |Description
|*BasicName* |<<BasicPiece.adoc#top,Basic Piece>> |The basic name of the piece.
|*ClickedX* |Basic Piece |Map X-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
|*ClickedY* |Basic Piece |Map Y-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
|*CurrentBoard* |Basic Piece |Current Board name or "" if not on a map.
|*CurrentMap* |Basic Piece |Current Map name or "" if not on a map.
|*CurrentX* |Basic Piece |Current X-coordinate of the piece.
|*CurrentY* |Basic Piece |Current Y-coordinate of the piece.
|*CurrentZone* |Basic Piece |Current Zone name if the current map has a <<ZonedGrid.adoc#top,multi-zoned grid>>, or "" if the piece is not in any zone, or not on a map.
|*DeckName* |Basic Piece |Current Deck name if stacked in a <<Deck.adoc#top,Deck>>, or "" if not in a Deck.
|*IgnoreGrid* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece ignores the map grid when moving.
|*Immobile* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece cannot be moved by drag and drop.
|*Invisible* |<<Hideable.adoc#top,Invisible>> |"true" if this piece is invisible to the current player.
|*InvisibleToOthers* |<<Hideable.adoc#top,Invisible>> |"true" if this piece is invisible to other players.
|*LocationName* |Basic Piece |Name of the piece's current location, as determined by the map's <<ZonedGrid.adoc#Zone,Zone>> (if any) and grid settings.
|*Moved* |<<MarkMoved.adoc#top,Mark When Moved>> |"true" if this piece has moved since the last time its movement history was cleared.
|*NoStack* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece cannot stack with other pieces.
|*Obscured* |<<Mask.adoc#top,Mask>> |"true" if this piece is masked from the current player.
|*ObscuredToOthers* |<<Mask.adoc#top,Mask>> |"true" if this piece is masked from other players.
|*OldBoard* |Basic Piece |Board name prior to most recent movement.
|*OldLocationName* |Basic Piece |Location name prior to most recent movement.
|*OldMap* |Basic Piece |Map name prior to most recent movement.<commit_msg>Fixed Properties reference docs.<commit_after>== VASSAL Reference Manual
[#top]

[.small]#<<index.adoc#toc,Home>> > <<GameModule.adoc#top,Module>> > <<PieceWindow.adoc#top,Game Piece Palette>> > <<GamePiece.adoc#top,Game Piece>> > *Properties*#

'''''

=== Properties

A Property is like a variable in programming: it has a _value_ which can be referenced by including its _name_ in <<Expression.adoc#top,Expressions>>, <<MessageFormat.adoc#top,Message Formats>> and other similar fields.
Most types of Property have their values change through the course of the game.
Some Properties can have their values set by commands provided in Game Pieces themselves; others have their values set by the system and cannot be changed from within the module.

Each Game Piece has its own set of properties (each with a name and a value) that can be used for identification by various components.
You can add your own new properties to a Game Piece _explicitly_ by adding <<DynamicProperty.adoc#top,Dynamic Property>> traits to create values which can be changed during the course of the game and <<PropertyMarker.adoc#top,Marker>> traits for properties whose values will remain constant.
System-defined properties are also added _implicitly_ when other traits are added (see below). <<GlobalProperties.adoc#top,Global Properties>> can also be defined for a Zone, a Map or for the entire module.
If a referenced Property name is not defined in a Game Piece, the VASSAL looks for the value in the Zone containing the piece, then in the Map containing the piece, then in the module.

Properties can be matched using <<Expression.adoc#top,Expressions>> like _name == value_ for an exact match, _name != value_ for a non-match, or _name =~ value_ for a https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[regular expression] match.
For properties that return a numeric value (e.g.
the level in a <<Layer.adoc#Properties,Layer)>> you can use _<_, _<=_, _>_, and _>=._  You can combine expressions using && for logical AND and || for a logical OR.

*Components that use properties*

* Any <<MessageFormat.adoc#top,Message Format>> defined in a Game Piece will substitute values for the properties defined on that Game Piece.

* The <<Map.adoc#GlobalKeyCommand,Global Key Command>> component uses properties to determine which pieces will respond to the command.
* The <<Map.adoc#GamePieceLayers,Game Piece Layers>> component uses properties to determine relative ordering when drawing pieces on the map.
* The <<TriggerAction.adoc#top,Trigger Action>> trait uses properties to determine when to fire a Key Command or <<NamedKeyCommand.adoc#top,Named Key Command>> .
* The <<Label.adoc#top,Text Label>> trait substitutes properties when setting the text of the label.
* A <<ZonedGrid.adoc#Zone,Zone>> uses properties to specify a <<ZonedGrid.adoc#ZoneHighlighter,Zone Highlighter>>.

*Properties defined by Game Pieces*

* The <<BasicPiece.adoc#top,Basic Piece>> defines properties related to a piece's name, location, side, and whether it's selected.

* The <<Layer.adoc#Properties,Layer>> trait defines properties related to the state of that Layer.
* The <<Rotate.adoc#top,Rotate>> trait defines properties related to the current facing of the piece.

* The <<Label.adoc#top,Text Label>> trait returns the value of the label as a property.
* The <<PropertyMarker.adoc#top,Marker>> trait allows you to define your own static properties.
* The <<DynamicProperty.adoc#top,Dynamic Property>> trait allows you to define your own changeable properties.

* The <<MarkMoved.adoc#top,Mark When Moved>> trait sets a property when a piece has moved.
* The <<Mask.adoc#Properties,Mask>> trait sets a property when the piece is masked.
* The <<Hideable.adoc#top,Invisible>> trait sets a property when the piece is invisible.

* The <<PropertySheet.adoc#top,Property Sheet>> trait exposes a set of user-editable properties.

*Properties defined by other components*

* The <<GlobalProperties.adoc#top,Global Property>> component defines properties for a <<ZonedGrid.adoc#Zone,Zone>>, <<Map.adoc#top,Map>> or the <<GameModule.adoc#top,module>>.
* The <<GlobalOptions.adoc#top,Global Options>> component allows you to tie property values to preferences settings.
* The results of a roll by a <<GameModule.adoc#DiceButton,Dice Button>> is exposed as a property
* A <<Deck.adoc#top,Deck>> component exposes the number of cards remaining as a Map-level property.

==== Handy Combined List of VASSAL-defined Properties for Game Pieces

|===
|Property |Trait |Description
|*BasicName* |<<BasicPiece.adoc#top,Basic Piece>> |The basic name of the piece.
|*ClickedX* |Basic Piece |Map X-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
|*ClickedY* |Basic Piece |Map Y-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
|*CurrentBoard* |Basic Piece |Current Board name or "" if not on a map.
|*CurrentMap* |Basic Piece |Current Map name or "" if not on a map.
|*CurrentX* |Basic Piece |Current X-coordinate of the piece.
|*CurrentY* |Basic Piece |Current Y-coordinate of the piece.
|*CurrentZone* |Basic Piece |Current Zone name if the current map has a <<ZonedGrid.adoc#top,multi-zoned grid>>, or "" if the piece is not in any zone, or not on a map.
|*DeckName* |Basic Piece |Current Deck name if stacked in a <<Deck.adoc#top,Deck>>, or "" if not in a Deck.
|*IgnoreGrid* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece ignores the map grid when moving.
|*Immobile* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece cannot be moved by drag and drop.
|*Invisible* |<<Hideable.adoc#top,Invisible>> |"true" if this piece is invisible to the current player.
|*InvisibleToOthers* |<<Hideable.adoc#top,Invisible>> |"true" if this piece is invisible to other players.
|*LocationName* |Basic Piece |Name of the piece's current location, as determined by the map's <<ZonedGrid.adoc#Zone,Zone>> (if any) and grid settings.
|*Moved* |<<MarkMoved.adoc#top,Mark When Moved>> |"true" if this piece has moved since the last time its movement history was cleared.
|*NoStack* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece cannot stack with other pieces.
|*Obscured* |<<Mask.adoc#top,Mask>> |"true" if this piece is masked from the current player.
|*ObscuredToOthers* |<<Mask.adoc#top,Mask>> |"true" if this piece is masked from other players.
|*OldBoard* |Basic Piece |Board name prior to most recent movement.
|*OldLocationName* |Basic Piece |Location name prior to most recent movement.
|*OldMap* |Basic Piece |Map name prior to most recent movement.
{'fraction_non_alphanumeric': 0.1013285296104481, 'fraction_numerical': 0.001125872551227201, 'mean_word_length': 5.359904534606205, 'pattern_counts': {'":': 0, '<': 199, '<?xml version=': 0, '>': 207, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3438693', 'n_tokens_mistral': 3841, 'n_tokens_neox': 3672, 'n_words': 1720}