Property Reference

A property is a pair of functions (or, sometimes, only one function) that looks and behaves kind of like a variable. You can read a value from it, or assign a new one, just like a variable, assuming that it's allowed. There are three kinds of property, the full property, the auto property, and the auto read-only property. All three of them appear the same to an external script. You can kind of think of them as public variables, but where the owning script can control how they are used.

Full Property

<property> ::= <type> 'Property' <identifier> <flags>*
                 <function>
                 [<function>]
               'endProperty'

The full property gives you full control over exactly what the property does and what it does or does not allow. The functions inside the property definition are normal functions, with the exception that they must be either a "Get" function (which returns the same type as the property and takes no parameters), or a "Set" function (which returns nothing and takes a single parameter of the same type as the property). You may omit either one of them, but at least one must exist.

When someone assigns a value to the property, it will call the set function, passing in the desired value. When someone tries to get the value a property holds, it will call the get function and take the result. If the set function does not exist, then no one can write to the property. If the get function does not exist, then no one can read from it.

If you want the property to show up in the editor, it should at least have a set function, and not have the hidden flag.

Examples

int myValue = 0 ; Private, like all variables
int Property ValueProperty ; Publicly accessible, but won't let you set a value less then 0
  Function Set(int newValue)
    if newValue >= 0
      myValue = newValue
    endIf
  EndFunction
  int Function Get()
    return myValue
  EndFunction
EndProperty

int myValue = 0 ; Private
int Property ReadOnlyValue ; Publicly accessible, but this one won't let anyone set it
  int Function Get()
    return myValue
  EndFunction
EndProperty

Auto Property

<auto property> ::= <type> 'Property' <identifier> ['=' <constant>] 'Auto' <flags>*

An auto property is, for all intents and purposes, a public variable. It will create a hidden variable and hidden get and set functions that manipulate it, so you don't have to. It may optionally be initialized with a value using the same syntax as an object variable. (There are also some internal optimizations that make this kind of property more efficient to use then the full type if you don't need limitations)

Auto properties may not be defined in native scripts

An auto property may be defined as 'const' by adding "Const" to the end of the definition line. Const properties can only have their value set in the editor and any value given them in a save game will be ignored, allowing changes to the master file to override the save game.

Examples

; Make an auto property that exposes a float value, and initialize it with 1.0
float Property MyProperty = 1.0 Auto

Auto Read-Only Property

<auto read-only property> ::= <type> 'Property' <identifier> '=' <constant> 'AutoReadOnly' <flags>*

An auto read-only property is simply a publicly accessible value that cannot be changed. For obvious reasons, it must be assigned a value when declared. (There are also internal optimizations that make these properties more efficient than other properties.)

Examples

; Make an auto read-only property that exposes a string and cannot be changed
string Property Hello = "Hello world!" AutoReadOnly