Properties

I’ve been sporadically updating the Vassal reference doc. (Thank Brian for pointing me in the right direction.) I was going to update the Properties doc, but I realized I didn’t know the answers to important questions, which aren’t documented. I could test and use the results, but then I would be documenting behavior and not intent. So here is a list of questions. If you are not a developer, consider it a quiz, and see how well you do.

  1. Are property name case sensitive?

  2. What special characters should not be used in property names?

  3. What happens if I define a property more than once? Say I create a marker “country = Italy”, and farther down in the trait list I create “country = Spain.” Which takes precedence?

  4. Related to 3. What happens if a duplicate definition is calculated, dynamic, or global (within scope)?

4a. Not related to properties but similar in thought. What happens if I use the same key command in two different places? Say I use ^R to return to deck and ^R to clone a piece.

  1. What happens if I redefine a Vassal property? Say I create a marker “CurrentX = 10”?

  2. If a property contains the name of another property, how do I reference the contents of the second property?

  3. I am issuing a global key command that tests for {country == “Germany”}. What happens if a piece does not define “country”? What does a piece see when it’s supposed to reference a property it doesn’t know about?

  4. How do I set up a property check to test if a property is undefined (as in #7)?

  5. Related to 7 and 8, a property is numeric. Suppose I have coin pieces, and each piece has a marker “value,” which defines its worth (e.g. 1, 5, 10). Suppose I issue a GKC to have each piece adds it value to a global property. What happens if a piece tries to add an undefined property value to the global property?

  6. How does Vassal (or Beanshell) handle floating point numbers? Does it even understand them?

  7. In a Beanshell expression, can I use the bit operators | and &? How about ++ and --?

  8. In a Beanshell property expression, what’s different if a property is to the left or right? For example, {country == “Italy”} or {“Italy” == country}?

Thank you for what promises to be a useful update to the documentation! My exam paper will need to be marked by someone with deeper knowledge, but this is what I think I know from my recent foray into Vassal module editing…

1. Are property name case sensitive?
Yes

2. What special characters should not be used in property names?
I don’t know the full answer but it is not as many as you might think. You can use GetProperty() and the escape character () to force evaluation of some otherwise invalid names as a property. A common example is the Space character, as Legacy mode allows this in property name fields, whereas for beanshell the space characters must be delimited if they are used in a property name. So for example, the expression {MyProp + 2} will work but {My Prop +2} will not - use {GetProperty(“My Prop”) + 2} instead.

3. What happens if I define a property more than once? Say I create a marker “country = Italy”, and farther down in the trait list I create “country = Spain.” Which takes precedence?
I think Marker at the bottom is set last. This can be a handy way to over-ride the “default” set in a Prototype

4. Related to 3. What happens if a duplicate definition is calculated, dynamic, or global (within scope)?
CP - One will override the other but then the other will serve no function. Self-referencing the CP will cause an endless loop.
DP, GP - definitions will each be calculated according to trait order (bottom up except if controlled by a Trigger, the Trigger executing after non-trigger and in top-down order).

4a. Not related to properties but similar in thought. What happens if I use the same key command in two different places? Say I use ^R to return to deck and ^R to clone a piece.
Barring any Restrictions or Trigger conditions that tailor the effects, both Ctrl+R functions will operate - assuming that the traits are defined on the same piece.

5. What happens if I redefine a Vassal property? Say I create a marker “CurrentX = 10”?
I expect that this will override the system generated CurrentX. I’d find another way to achieve my goal.

6. If a property contains the name of another property, how do I reference the contents of the second property?
Assume MyProp1=“MyProp2” and MyProp2=“Hello, World” ; GetProperty(“MyProp1”) will return “MyProp2”; GetProperty(MyProp1) will return “Hello, World”. The same effect can be achieved in legacy (non-beanshell) using "$"s to surround the property name.

7. I am issuing a global key command that tests for {country == “Germany”}. What happens if a piece does not define “country”? What does a piece see when it’s supposed to reference a property it doesn’t know about?
An undefined property has a value of null. You could test for that in your example using {country == “”}. DP/GPs can be assigned a default value also.
As an aside to this topic; the default of null can be an issue for Boolean values as null equates to neither false nor true and so use of the undefined property as a boolean causes an exception. The safe way around this is to be explicit in the condition e.g. MyBooleanProp!=true or MyBooleanProp!=false depending on which way you want to default to go.

8. How do I set up a property check to test if a property is undefined (as in #7)?
Test for null; for example, take a property MyProp that is an integer value for which you wish to apply a default of 1; this expression will assign a value of “1” to MyProp if it is undefined, or otherwise leave MyProp unchanged:
{ MyProp == “” ? 1 : MyProp}

9. Related to 7 and 8, a property is numeric. Suppose I have coin pieces, and each piece has a marker “value,” which defines its worth (e.g. 1, 5, 10). Suppose I issue a GKC to have each piece adds it value to a global property. What happens if a piece tries to add an undefined property value to the global property?
The value zero will be added.

10. How does Vassal (or Beanshell) handle floating point numbers? Does it even understand them?
I haven’t needed floating point numbers so I can’t offer an answer. In my experience, interim values are not integers but the result rounds to the nearest integer.

11. In a Beanshell expression, can I use the bit operators | and &? How about ++ and --?
No. Or if you can (e.g. ++), they don’t work.

12. In a Beanshell property expression, what’s different if a property is to the left or right? For example, {country == “Italy”} or {“Italy” == country}?
[/quote]
In the example, there is no difference but left to right does affect whether parts of the expression are evaluated as a number or not. It rarely seems to be an issue but I did raise a thread somewhile back where I had an issue and was helped to fix it by forcing the expression to be evaluated as a number in this way.