Editing Papyrus Introduction (section)

==Example Script (extending ObjectReference)==
For example, let's say you want to set a quest stage when the player hits a particular triggerbox. You would create a script called “MyTriggerBoxScript” that '''[[Extending_Scripts_(Papyrus)|extends]]''' “ObjectReference” and attach that to the triggerbox's [[reference]] in the [[Render Window]]. You then create a Property called MyQuest, and point it to your quest in the editor. Then you write your version of the OnTriggerEnter event, that calls set stage on the quest in the myQuest property.

<syntaxhighlight lang="papyrus">
 Scriptname MyTriggerBoxScript extends ObjectReference
 
 Quest Property MyQuest Auto
 Int Property StageToSet Auto
 
 Event OnTriggerEnter(ObjectReference akActionRef)
 	If akActionRef == Game.GetPlayer()
 		MyQuest.SetStage(StageToSet)
 	EndIf
 
 EndEvent
</syntaxhighlight>

There's a lot going on in the above example, let's break it down and further illustrate some points, and raise new ones.

The first line of any script starts ([[Script_File_Structure#Header_Line|the "header line"]]) with “Scriptname” that is us telling the compiler that this script is going to have following name (in this case the name is “MyTriggerBoxScript). This name MUST match the name of the text file you are writing the script in (in this case “MyTriggerBoxScript.psc”). The word “[[Extending_Scripts_(Papyrus)|extends]]” means this script is going to be based on another script (in this case the “[[ObjectReference Script|ObjectReference]]” script). That means your script will have access to all the functions and events defined in “ObjectReference.psc” and you can change them, or add new ones to your script.

The next line is [[Variables_and_Properties#Auto_Properties|declaring an "auto" property]]. “Property” is saying that we are about to declare a new property to use in our script. Quest is the Type of the property (in other words, only Quest objects can be put into this property). MyQuest is the name of the property. So all together this line is telling the compiler “I want you to know about a property called MyQuest, and it will only be able to have a Quest object in it, nothing else.” (For now we will ignore the “auto” keyword. Just know that you almost always write “auto” at the end of every property you declare. For the full discussion see: [[Variables_and_Properties#Declaring_Properties|Declaring Properties.]])

Similarly the next line is defining an [[Literals_Reference#Integer_Literals|integer]] property.
	
Next we see some lines that start with [[Events_Reference|Event]] and end with [[Events_Reference|EndEvent]]. You can think of these like book ends for this particular event. Everything in between is how this script will respond to the “[[OnTriggerEnter_-_ObjectReference|OnTriggerEnter]]” event. You might have a script that responds to multiple events. Using Event/EndEvent you isolate everything you want to happen for this event from another one elsewhere in the script.

The OnTriggerEnter is the name of the event your script is implementing. The ( ) [[Events_Reference#Parameters|define what parameters]] the game is going to send to your script's OnTriggerEnter event. "akActionRef" is the name of the parameter, and "ObjectReference" defines what type that parameter is – and, if you have been paying attention, you also know that "ObjectReference" is itself a papyrus script ([[ObjectReference Script]]).

The next line starts with “if” and a line below it “EndIf.” This is a conditional [[Statement_Reference|statement]]. You will be writing a lot of “[[Statement_Reference#If_Statement|if-then-else statements]]” in your script. Here we are testing if the ObjectReference “akActionRef” that the game passed into our OnTriggerEnter when an actor walked into it is the player or not.

Game.GetPlayer() is a function [[GetPlayer - Game|GetPlayer()]] on the [[Game Script]] that returns the [[Actor Script|Actor]] that represents the player. The == is a test (a "[[Operator_Reference#Comparison_Operators|Comparison Operator]]") which means “is this thing exactly this other thing?” So we are asking is the [[reference]] that the game sent to our script when an actor entered our trigger box, is that the same as the actor [[reference]] returned by Game.GetPlayer()? In other worlds “did the player enter the trigger?” If so, then call the SetStage() function on the quest that is in the MyQuest property, and tell it the stage we want to set is whatever we have stored in the StageToSet property.

If you have been following along carefully, you may wonder at how we can compare an [[ObjectReference Script|ObjectReference]] "akActionRef" to an [[Actor Script|Actor]] (the return value of Game.GetPlayer()). The reason we can do this is because the compiler knows that all Actors are also ObjectReferences because the [[Actor Script]] '''[[Extending_Scripts_(Papyrus)|extends]]''' the [[ObjectReference Script]]. So here you see that extension isn't used only for your own scripts, but the base scripts also extend each other as well! The wiki writeup for each [[:Category:Script Objects|Script Object]] contains at the top of its page, which script it is extending from.


So now we know how to set up a script that checks and does things with properties, but we may be wondering, where do we tell the script what objects and what values to assign into your properties? (In the above example, which quest, and which quest stage are we talking about here?)