Property Reference

From Creation Kit
Jump to: navigation, search

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.

Flags

  • Hidden
  • Conditional
  • Auto
  • AutoReadOnly

Note: Full properties will only compile with the Hidden flag.


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)

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 in-game. Unlike other property variables, AutoReadOnly Properties do not bake into your savegame. For obvious reasons, it must be initialized with a value when declared. (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 to)

Examples

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


Conditional Property

 <conditional property> ::= <type> 'Property' <identifier> '=' <constant> ['Auto' | 'AutoReadOnly'] 'Conditional'

A conditional property can be read using the GetVMQuestVariable and GetVMScriptVariable conditional functions. The script containing conditional properties must also be defined as conditional. Only one conditional script may be attached to a game object at a time.

See Also