Difference between revisions of "Variables and Properties"
→Notes
imported>Kivan m (Typo: "it's" -> its") |
imported>Marth (→Notes) |
||
| (57 intermediate revisions by 14 users not shown) | |||
| Line 1: | Line 1: | ||
=Description= | ==Description== | ||
Variables and Properties are similar things, they both "hold" values and objects. A variable is "private" meaning that only that script is aware of them, can set their contents, and get their contents. A Property is essentially a variable that other scripts can access, their contents can be set and get by a other scripts. | Variables and Properties are similar things, they both "hold" values and objects. A variable is "private" meaning that only that script is aware of them, can set their contents, and get their contents. A Property is essentially a variable that other scripts can access, their contents can be set and get by a other scripts. If a variable or property holds a numeric value, like an integer, get/set returns its value. If a variable or property holds an object, you can access that object's properties and functions. (This is analogous to a reference variable from the old scripting system.) | ||
=Declaring Variables= | ==Declaring Variables== | ||
<source lang="papyrus"> | <source lang="papyrus"> | ||
float myFloat | float myFloat | ||
| Line 11: | Line 10: | ||
</source> | </source> | ||
MyFloat starts at 0, myOtherFloat starts at 13.5 and can be set by scripting in | MyFloat starts at 0, myOtherFloat starts at 13.5 and can be set by scripting in its own script, but nothing else. | ||
=Declaring Properties= | ==Declaring Properties== | ||
==Full Property== | ===Full Property=== | ||
To define a property, you first write the type, then "property", then the name of the property. You then define two functions, a get which returns the property's value, and a set which takes a new value for the property. And then you cap it off with "EndProperty" | To define a property, you first write the type, then "property", then the name of the property. You then define two functions, a get which returns the property's value, and a set which takes a new value for the property. And then you cap it off with "EndProperty" | ||
| Line 76: | Line 75: | ||
The above property is write-only. Scripts outside of this one cannot read the value. It also uses an if to make sure the value is never below 0. | The above property is write-only. Scripts outside of this one cannot read the value. It also uses an if to make sure the value is never below 0. | ||
==Auto Properties== | If a full property has its value set in the Creation Kit, its ''set'' function will be called when the object is initialized, just before its [[OnInit]] event is called. | ||
===Auto Properties=== | |||
An auto property is one that writes the above get and set functions for you, behind the scenes. There are also some minor optimizations in the VM that speed up auto properties slightly. To make an auto property, simply omit the functions and endProperty and add "auto" to the end of the property definition. You can set the property's initial value using the "= <value>" syntax. | An auto property is one that writes the above get and set functions for you, behind the scenes. There are also some minor optimizations in the VM that speed up auto properties slightly. To make an auto property, simply omit the functions and endProperty and add "auto" to the end of the property definition. You can set the property's initial value using the "= <value>" syntax. | ||
| Line 84: | Line 85: | ||
</source> | </source> | ||
==Auto Read-only Properties== | |||
===Auto Read-only Properties=== | |||
An auto read-only property is an auto property that can never have its value changed. This can be convenient if certain numbers mean different things in your script and you want to use a name instead of a number to represent it. You specify these by using "AutoReadOnly" instead of "Auto". These properties ''must'' have their initial value set using "= <value>" syntax. | An auto read-only property is an auto property that can never have its value changed. This can be convenient if certain numbers mean different things in your script and you want to use a name instead of a number to represent it. You specify these by using "AutoReadOnly" instead of "Auto". These properties ''must'' have their initial value set using "= <value>" syntax. | ||
| Line 92: | Line 94: | ||
</source> | </source> | ||
==Conditional Properties== | |||
===Conditional Properties=== | |||
Properties cannot be declared as conditional. Auto properties can be defined as conditional because what they actually do is define the hidden variable they create as conditional. This is why you see mangled auto property names when you select a Papyrus variable in the condition system - you're selecting from a list of hidden variables. | Properties cannot be declared as conditional. Auto properties can be defined as conditional because what they actually do is define the hidden variable they create as conditional. This is why you see mangled auto property names when you select a Papyrus variable in the condition system - you're selecting from a list of hidden variables. | ||
| Line 100: | Line 103: | ||
</source> | </source> | ||
=Getting Properties of a | More information on the conditional keyword can be found in the [[Papyrus_Introduction#Writing_Custom_Functions|Papyrus Introduction]] and in the [[Flag_Reference|Flag reference]] | ||
==From | |||
==Getting Properties of a Quest Script== | |||
===From Result Script Owned by the Same Quest=== | |||
Often you will need to get a property of a quest script, and use it in a result script somewhere else. This is one of the more tricky things, but once you understand what's happening, it makes sense. First look at the example, then we'll describe what's happening. | Often you will need to get a property of a quest script, and use it in a result script somewhere else. This is one of the more tricky things, but once you understand what's happening, it makes sense. First look at the example, then we'll describe what's happening. | ||
| Line 123: | Line 129: | ||
In the result script, we create a variable that represents the quest script that has the property we want (in this case MQ01Script's "DeadCount" property). Note our variable myQuest is declare as MQ01Script. This is because when we made our quest script "scriptName MQ01Script extends Quest" we've essentially created a new type of object... a MQ01Script object. GetOwningQuest returns a quest object (before we extended it). So we also need to ''cast'' the quest returned by GetOwningQuest AS that new object "myQuest = GetOwningQuest() as MQ01Script" so we have access to it's extended properties. If we didn't cast it as a MQ01Script it would only have the functions and properties of a Quest object, which wouldn't contain our deadCount property. | In the result script, we create a variable that represents the quest script that has the property we want (in this case MQ01Script's "DeadCount" property). Note our variable myQuest is declare as MQ01Script. This is because when we made our quest script "scriptName MQ01Script extends Quest" we've essentially created a new type of object... a MQ01Script object. GetOwningQuest returns a quest object (before we extended it). So we also need to ''cast'' the quest returned by GetOwningQuest AS that new object "myQuest = GetOwningQuest() as MQ01Script" so we have access to it's extended properties. If we didn't cast it as a MQ01Script it would only have the functions and properties of a Quest object, which wouldn't contain our deadCount property. | ||
In | In other words, when we created MQ01Script which extended the Quest script, unless we cast the object returned by GetOwningQuest AS our new script, it won't have our new properties declared in our new script. | ||
===With kmyQuest=== | ====With kmyQuest==== | ||
If the fragment you are using has a "kmyquest" drop down, you can select a script attached to the quest owning that fragment, and then use the kmyQuest "magic variable" to refer to quest script without casting it. | If the fragment you are using has a "kmyquest" drop down, you can select a script attached to the quest owning that fragment, and then use the kmyQuest "magic variable" to refer to quest script without casting it. | ||
| Line 132: | Line 138: | ||
float myDeadCount | float myDeadCount | ||
myDeadCount = kmyQuest.deadCount ;getting property | myDeadCount = kmyQuest.deadCount ;getting property | ||
kmyQuest.deadCount = | kmyQuest.deadCount = 10 ;setting property | ||
</source> | |||
===From Within a Magic Effect Script=== | |||
Let's look at an example where a scripted spell accesses a quest's properties: | |||
<source lang="papyrus"> | |||
Scriptname myQuestNameScript extends Quest | |||
Int Property PublicInt Auto ; This value is defined as a property and can be accessed from outside this script | |||
Int PrivateInt = 30 ; This value is private to the script and cannot be accessed from outside this script | |||
Function DamageTargBasedOnPublic(Actor akTarget) | |||
;This code will damage the akTarget for PublicInt damage | |||
akTarget.DamageAV("Health", PublicInt) | |||
EndFunction | |||
Function DamageTargBasedOnPrivate(Actor akTarget) | |||
;This code will damage the akTarget for PrivateInt damage | |||
akTarget.DamageAV("Health", PrivateInt) | |||
EndFunction | |||
</source> | |||
Now that we have defined our quest script and created an accessible property, we can control it from the outside. | |||
<source lang="papyrus"> | |||
Scriptname mySpellEffectScript extends activemagiceffect | |||
myQuestNameScript Property myQuestRef auto | |||
Event OnEffectStart(Actor akTarget, Actor akCaster) | |||
myQuestRef.PublicInt = 20 ; This will change the damage for the DamageTargBasedonPublic Function | |||
myQuestRef.DamageTargBasedOnPublic(akTarget) ; You can manipulate this damage by changing PublicDamage Prior to calling it | |||
myQuestRef.DamageTargBasedOnPrivate(akTarget) ; This will always do 30 damage unless the quest changes the private variable | |||
EndEvent | |||
</source> | |||
After this point, you will need to go to the properties window for whatever your script is attached to (in this case, the script properties windows of the script for mySpellEffectScript) and then set the property for myQuestRef to the Quest associated with the quest script. | |||
==Getting Properties From Any Other Script== | |||
You can access the properties of any script attached to any object not just those attached to quests. But you will be accessing a specific script attached to a specific object. | |||
'''Example:''' | |||
<source lang="papyrus"> | |||
ScriptName ScriptA extends ObjectReference | |||
int Property count Auto | |||
float Property weight Auto | |||
</source> | |||
If both scripts are attached to the same game object (Quest, Perk, ObjectReference, etc.) accessing the variables from the other script is simply a matter of casting self to the correct type. | |||
'''Example:''' | |||
<source lang="papyrus"> | |||
ScriptName ScriptB extends ObjectReference | |||
Event OnInit() | |||
ScriptA me = self as ScriptA | |||
me.count = 1 | |||
me.weight = 12.9 | |||
(self as ScriptA).count += 7 ; this in-line method works too | |||
EndEvent | |||
</source> | |||
If the other script is attached to some other object then you'll need a way to access that object. The most common way is a property but you might also get access through some Event argument instead. | |||
'''Example:''' | |||
<source lang="papyrus"> | |||
ScriptName ScriptB extends ObjectReference | |||
ScriptA Property remoteObject Auto | |||
Event OnInit() | |||
remoteObject.count = 1 | |||
remoteObject.weight = 12.9 | |||
EndEvent | |||
Event OnActivate(ObjectReference akActionRef) | |||
if (akActionRef as ScriptA) | |||
(akActionRef as ScriptA).count += 7 | |||
endif | |||
EndEvent | |||
</source> | </source> | ||
=Warnings= | For a list of objects you can use as a type that are already within the game, visit the [[Script Objects]] page. | ||
Be careful with variables and auto properties on scripts | |||
'''See Also: [[Function_Reference#Accessing_Functions_From_Other_Scripts|Accessing Functions From Other Scripts]]''' | |||
==Warnings== | |||
Be careful with variables and auto properties on "base" scripts, which are extended by multiple other scripts. This is because it would be possible to have multiple scripts containing the same variable or auto property attached to the same object, and the game may not reliably select the appropriate instance of the variable or property. | |||
For example, consider the following 3 short scripts:<source lang="papyrus">ScriptName Base extends ObjectReference | |||
Int Property MyValue Auto</source> | |||
<source lang="papyrus">ScriptName Derived1 extends Base</source> | |||
<source lang="papyrus">ScriptName Derived2 extends Base</source> | |||
Because both Derived1 and Derived2 extend Base, they each inherit its MyValue property. | |||
Now, imagine that an object is created and the scripts Derived1 and Derived2 are both attached to it. Trying to access the value of MyValue by casting this object to Base will not reliably return the same value:<source lang="papyrus">(MyObjectReference as Base).MyValue</source> | |||
This is doubly-true of variables and auto properties declared in [[:Category:Script_Objects|native script objects]], such as the [[Actor Script]]. This is because the game can attach these to in-game objects at any time if it needs to, thereby creating another copy of the variable or auto property. | |||
In order to avoid these problems, avoid editing native script objects, and in the case where a single object has multiple scripts attached to it that inherit the same property, make sure you cast it to its most derived form before attempting to access that property. In the above example, that would mean using syntax like this:<source lang="papyrus">(MyObjectReference as Derived1).MyValue</source> | |||
==Notes== | |||
*The list of properties in properties dialog is only updated after adding a new property or after compiling the script with the build-in editor. | |||
*You should avoid adding or removing Properties to a base item's script if one or more of its child ObjectReference's is already baked into a current save game. | |||
=See Also= | ==See Also== | ||
*[[Variable Reference]] | |||
*[[Property Reference]] | *[[Property Reference]] | ||
*[[Default Value Reference]] | |||
*[[Cast Reference]] | |||
[[Category: Papyrus]] | [[Category: Papyrus]] | ||
[[Category: Papyrus Tutorials]] | [[Category: Papyrus Tutorials]] | ||
{{Languages}} | |||