Arcane University: Scripting Best Practices

< Arcane University:Implementation

This is a guide of best practices to follow when writing Papyrus scripts.

Papyrus Scripting Best Practices

1. COMMENT YOUR CODE! Use ; for general comments, ;/ ... /; for comment blocks, and { ... } for docstrings.
2. To get started with Papyrus scripting, read through the concepts and tutorials here: https://www.creationkit.com/index.php?title=Category:Papyrus
3. If you expect to do extensive scripting, an external editor & compiler is highly recommended (see above link for instructions for different editors).
4. Keep these pages bookmarked; you will use them often:
   • https://www.creationkit.com/index.php?title=List_of_Papyrus_Functions
   • https://www.creationkit.com/index.php?title=Category:Events
   • https://www.creationkit.com/index.php?title=Default_Scripts_List
   • https://www.creationkit.com/index.php?title=Condition_Functions
5. Enable and check your Papyrus logs. Make liberal use if debug.trace(...) when first writing and testing your code.
6. Avoid using Game.GetPlayer() when possible. It is almost always better to use and autofill an Actor property PlayerREF instead.
7. If you want to remove a property from a script, be sure to clear that property from anywhere that script is used in the Creation Kit first. Otherwise, the property will still exist on the CK object (but you won't be able to see it) and the game will still try to load the property. If you forget to do this, you can remove the zombie property in xEdit.
8. Before making a new script, see if there's an existing default script you can use, e.g. defaultSetStageOnDeath or defaultPlayerEnableDisableLinkedRef.
9. Don’t start properties, variables, functions, or any type of Papyrus identifier with a number --- the compiler will fail (i.e. 123function() fails).
10. Avoid constant polling with short intervals whenever possible. There are almost always more efficient ways of doing something, such as events that detect what you are trying to poll. If you use a while loop or OnUpdate, make sure there is some failsafe to exit the loop/stop the updates.
11. Avoid long Wait() functions (this can cause issues with stack dumping: https://www.creationkit.com/index.php?title=User:DavidJCobb/Stack_dumping). Instead, use RegisterForSingleUpdate/OnUpdate or RegisterForSingleUpdateGameTime/OnUpdateGameTime.
12. If you make an ObjectReference or an Actor a property, that ref will become persistent (always loaded). Avoid this when possible and use linkedrefs or referencealiases.
13. If you must use an Actor or ObjectReference property, try to use a reference alias instead, as these clear automatically when the quest is done. Example: ReferenceAlias Property Hentus_alias Auto, then later (Hentus_alias.GetReference() as actor).AddItem(). (See Skyrim quests for examples.)
14. More information on levels of persistence can be found here: https://www.afkmods.com/index.php?/topic/4250-skyrim-levels-of-persistence/ and more information on how to avoid persistence can be found here: https://www.creationkit.com/index.php?title=Persistence_(Papyrus)
15. When testing a script, if you choose to COC into the cell, COC into a cell NEAR the one where your script will be triggered, not in it, or it might bug out – better yet, just travel to the trigger area in the same way a real player would.
16. If you’re making a do-once script, use states and make sure to send the script to an empty state when it is done running.
17. If you’ve got an empty state, make sure it remains empty; otherwise the event in it will still be processed, which takes away a big benefit to empty states (not having events even be processed).
18. Avoid piling too much onto your script at once, especially if it has to be run often – too much activity can be hard on Papyrus. States can be useful for limiting what is running at a given point in time.
19. Avoid convenience functions – use GetReference() as Actor instead of GetActorRef(), GetActorValue() instead of GetAV(), etc...
20. Sometimes there are Condition Functions that do not have Papyrus equivalents (e.g. IsPlayerInRegion). If you need to access these conditions in a script, two possibilities are:
    1. Use a spell: Make a constant effect magic effect that sets a global to 1 on effect start and 0 on effect end. Then, make an ability that has this effect, and condition the effect using the condition function you want to use in your Papyrus script. Add the ability to the player (or to a player quest alias). Then, add this global variable as a script property. You can check if it is equal to 1 or 0 to see if your condition is met.
    2. Use a quest: Make a quest with reusable stages, then make a stage with multiple log entries. Condition the different entries using the condition function you need to check, and use quest fragments for the different entries for how you want your script to respond to the different conditions. Then, when you need to check the condition, use the SetStage command on your new quest. The quest will evaluate the conditions, and response with the appropriate fragment.
21. Condition functions generally process faster than their Papyrus equivalents. For a large script, using the steps in (20) can also be a good way to lighten the load of your script.
22. More generally: Don't use Papyrus for something that can be done without papyrus.
23. COMMENT 👏 YOUR 👏 CODE 👏
24. Performance: Profile your scripts and functions to understand the time delay by your scripts and functions. https://www.reddit.com/r/skyrimmods/comments/i57siz/profiling_your_papyrus_scripts/