Difference between revisions of "Papyrus Introduction"
m
Added missing space character and normalised apostrophe characters
imported>Yggie13 |
imported>Cipscis m (Added missing space character and normalised apostrophe characters) |
||
| Line 7: | Line 7: | ||
A papyrus script is essentially a plain text source document ('''.psc''' file) that you can use any text editor to write and [[Papyrus_Compiler_Reference|compile]] it into a form the game can understand ('''.pex''' file). To make changes after it is compiled, the raw .psc must be updated or replaced, re-compiled, replacing the outdated .pex. | A papyrus script is essentially a plain text source document ('''.psc''' file) that you can use any text editor to write and [[Papyrus_Compiler_Reference|compile]] it into a form the game can understand ('''.pex''' file). To make changes after it is compiled, the raw .psc must be updated or replaced, re-compiled, replacing the outdated .pex. | ||
= | =What's in a Papyrus script?= | ||
The language of papyrus can be broken down into a handful of concepts: '''[[:Category:Script_Objects|Objects]], [[Function Reference|Functions]], [[Events]], [[Variables and Properties]].''' The'''[[Script_File_Structure|Script File Structure]]''' page provides information and examples of these concepts. | The language of papyrus can be broken down into a handful of concepts: '''[[:Category:Script_Objects|Objects]], [[Function Reference|Functions]], [[Events]], [[Variables and Properties]].''' The '''[[Script_File_Structure|Script File Structure]]''' page provides information and examples of these concepts. | ||
Each script is defined to be a type of '''[[:Category:Script_Objects|Object]]''', such as a “[[Quest]]”, a “[[Reference]],” an “[[Actor]],” or a “[[Book]].” For the most part, these script objects correlate exactly to the objects found in the editor's masterfile. | Each script is defined to be a type of '''[[:Category:Script_Objects|Object]]''', such as a “[[Quest]]”, a “[[Reference]],” an “[[Actor]],” or a “[[Book]].” For the most part, these script objects correlate exactly to the objects found in the editor's masterfile. | ||
These objects have '''[[Function Reference|Functions]]''' that can be used to get at the data they have in them from the masterfile or that is saved in them at run time. For example, you can use the function [[GetActorValue_-_Actor|GetActorValue(“Health”)]] to get the current health value of an actor, and [[ModActorValue_-_Actor|ModActorValue(“Health”, 50)]] to add 50 points to an | These objects have '''[[Function Reference|Functions]]''' that can be used to get at the data they have in them from the masterfile or that is saved in them at run time. For example, you can use the function [[GetActorValue_-_Actor|GetActorValue(“Health”)]] to get the current health value of an actor, and [[ModActorValue_-_Actor|ModActorValue(“Health”, 50)]] to add 50 points to an actor's health value. You could also use the function [[Kill - Actor|Kill()]] to kill an actor. Each of these functions is part of the [[Actor Script]] object. If you tried to call Kill() on a [[Book Script]], because the Book script has no Kill() function defined for it (''since the game code has no notion of killing books''), the compiler will complain and refuse to compile the script, giving you an error message that Kill() is not a function on the Book script. | ||
Scripts also have '''[[Events]],''' which are like function calls that the game itself calls on the object. For example, there is an [[OnDeath - Actor|OnDeath()]] event, that the game sends to [[Actor Script]]s attached to an actor when the actor dies. This allows you to respond to game events, for example, completing a quest after the player kills a particular enemy. Therefore, [[Function Reference|Functions]] as described in the previous paragraph are typically called ''within'' an event. | Scripts also have '''[[Events]],''' which are like function calls that the game itself calls on the object. For example, there is an [[OnDeath - Actor|OnDeath()]] event, that the game sends to [[Actor Script]]s attached to an actor when the actor dies. This allows you to respond to game events, for example, completing a quest after the player kills a particular enemy. Therefore, [[Function Reference|Functions]] as described in the previous paragraph are typically called ''within'' an event. | ||
| Line 18: | Line 18: | ||
A script can also have '''[[Variables and Properties|Variables]]'''. A variable is a value that can be modified and reference by the game and scripts. For example, you might want to store the number you get from a [[GetActorValue_-_Actor|GetActorValue()]]. With variables you can store this information, and use it later. | A script can also have '''[[Variables and Properties|Variables]]'''. A variable is a value that can be modified and reference by the game and scripts. For example, you might want to store the number you get from a [[GetActorValue_-_Actor|GetActorValue()]]. With variables you can store this information, and use it later. | ||
A script can also have '''[[Variables and Properties|Properties]]''', which function almost identically to variables, except that ''other'' scripts can ask about and set them. Properties can also be modified in the editor. (''Note: In reality properties are more a bit complex than simply a “variable that you can get/set externally,” but for practical purposes, | A script can also have '''[[Variables and Properties|Properties]]''', which function almost identically to variables, except that ''other'' scripts can ask about and set them. Properties can also be modified in the editor. (''Note: In reality properties are more a bit complex than simply a “variable that you can get/set externally,” but for practical purposes, that's a fine way to think of them''). | ||
[[Variables and Properties]] can be defined to be simple structures like a [[Literals_Reference#Boolean_Literals|Boolean, an Integer, a Float, etc.]] But their real power lies in that they can be defined as and hold '''any''' [[:Category:Script_Objects|Object Type]]. A Quest script, for instance, can have a property that holds a pointer to an Actor. Once you have a pointer to an object in a script property, that script can run functions on that property and thus on the object in it. For example, a quest script holding a property pointing to an Actor, can call Kill() on that property and it will kill that actor. Properties can be set by the script at run time, or can be set by pointing to objects in the editor. | [[Variables and Properties]] can be defined to be simple structures like a [[Literals_Reference#Boolean_Literals|Boolean, an Integer, a Float, etc.]] But their real power lies in that they can be defined as and hold '''any''' [[:Category:Script_Objects|Object Type]]. A Quest script, for instance, can have a property that holds a pointer to an Actor. Once you have a pointer to an object in a script property, that script can run functions on that property and thus on the object in it. For example, a quest script holding a property pointing to an Actor, can call Kill() on that property and it will kill that actor. Properties can be set by the script at run time, or can be set by pointing to objects in the editor. | ||
| Line 35: | Line 35: | ||
You will use a text editor to write the script (favorites include [[Notepad%2B%2B_Setup|Notepad++]] and [[Sublime_Text_Setup|Sublime Text]]). Once you have written the script, you will need to [[Papyrus_Compiler_Reference|compile]] it before it will work in game. | You will use a text editor to write the script (favorites include [[Notepad%2B%2B_Setup|Notepad++]] and [[Sublime_Text_Setup|Sublime Text]]). Once you have written the script, you will need to [[Papyrus_Compiler_Reference|compile]] it before it will work in game. | ||
Before you sit down to write a script, you need to think about what type of script | Before you sit down to write a script, you need to think about what type of script it's going to be. Or in other words, what type of object it's going to be running on. Once you decide that, you create a new script by declaring it at the top of a .psc file, and EXTEND the Object Script that it's based on. For example, if you are going to be creating a triggerbox that sets a variable, you will create a script that extends [[ObjectReference Script|ObjectReference]]. | ||
=Extending scripts= | =Extending scripts= | ||
| Line 45: | Line 45: | ||
=Example Script (extending ObjectReference)= | =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 | 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 the 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. | ||
<source lang="papyrus"> | <source lang="papyrus"> | ||
| Line 61: | Line 61: | ||
</source> | </source> | ||
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 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. | ||