Home > Papyrus Scripting

Papyrus Scripting for Fallout 4

Learn to create custom scripts for Fallout 4 using the Papyrus scripting language.

Table of Contents

What is Papyrus?

Papyrus is Bethesda's scripting language used in Fallout 4 and Skyrim. It allows you to create custom behaviors, events, and interactions for your mods.

Getting Started

Before diving into Papyrus scripting, make sure you have the necessary prerequisites and understand the basics.

Prerequisites

  • Basic programming knowledge (helpful but not required)
  • Creation Kit installed
  • Understanding of Fallout 4's object system

Your First Script

Let's create a simple script that makes an object glow when activated:

Scriptname MyFirstScript extends ObjectReference

Event OnActivate(ObjectReference akActionRef)
    ; Make the object glow
    SetLight(true, 100)
    ; Wait 5 seconds
    Utility.Wait(5.0)
    ; Turn off the glow
    SetLight(false, 0)
EndEvent

Script Structure

Understanding the basic components and structure of Papyrus scripts is essential for effective scripting.

Basic Components

  • Scriptname: Unique identifier for your script
  • extends: What type of object this script is attached to
  • Properties: Variables that can be set in the Creation Kit
  • Events: Functions that respond to game events
  • Functions: Custom code you can call

Common Object Types

  • ObjectReference: Any object in the world
  • Actor: NPCs and the player
  • Quest: Quest scripts
  • Form: Base objects and items

Variables and Properties

Understanding how to work with variables and properties in Papyrus.

Variable Types

  • Int: Whole numbers (1, 2, 3)
  • Float: Decimal numbers (1.5, 2.7)
  • String: Text ("Hello World")
  • Bool: True or false values
  • ObjectReference: References to game objects

Creating Properties

Scriptname MyScript extends ObjectReference

; Properties that can be set in Creation Kit
Int Property MyNumber = 10 Auto
String Property MyText = "Hello" Auto
ObjectReference Property MyObject Auto
Bool Property IsActive = True Auto

Events

Understanding how events work in Papyrus scripting.

Common Events

  • OnActivate: When object is activated
  • OnLoad: When object loads into the world
  • OnUnload: When object unloads
  • OnHit: When object is hit
  • OnDeath: When actor dies

Event Example

Scriptname DoorScript extends ObjectReference

Event OnActivate(ObjectReference akActionRef)
    ; Check if player is activating
    if akActionRef == Game.GetPlayer()
        ; Open the door
        SetOpen(True)
        ; Play a sound
        PlaySound(OpenSound)
    endif
EndEvent

Functions

Creating custom functions in Papyrus for reusable code.

Creating Custom Functions

Scriptname UtilityScript extends ObjectReference

; Custom function to heal the player
Function HealPlayer(float amount)
    Actor player = Game.GetPlayer()
    player.RestoreActorValue("Health", amount)
    Debug.Notification("Healed for " + amount + " points")
EndFunction

; Function that can be called from other scripts
Function DoSomething()
    ; Your custom code here
    Debug.Trace("Something happened!")
EndFunction

Conditional Statements

Using if/else statements and loops in Papyrus.

If/Else Statements

Event OnActivate(ObjectReference akActionRef)
    if akActionRef == Game.GetPlayer()
        ; Player activated
        Debug.Notification("Player activated this object")
    elseif akActionRef as Actor
        ; NPC activated
        Debug.Notification("NPC activated this object")
    else
        ; Something else activated
        Debug.Notification("Unknown activation")
    endif
EndEvent

Loops

; While loop
int counter = 0
while counter < 10
    Debug.Trace("Counter: " + counter)
    counter += 1
endwhile

; For loop (using while)
int i = 0
while i < 5
    Debug.Trace("Iteration: " + i)
    i += 1
endwhile

Working with Game Objects

How to interact with game objects and actors in Papyrus.

Getting References

; Get the player
Actor player = Game.GetPlayer()

; Get a specific actor by ID
Actor npc = Game.GetFormFromFile(0x123456, "MyMod.esp") as Actor

; Get all actors in a cell
ObjectReference[] actors = GetActorsInCell()

Modifying Objects

; Move an object
MyObject.MoveTo(NewLocation)

; Add item to player
Game.GetPlayer().AddItem(MyItem, 1)

; Change actor's health
MyActor.SetActorValue("Health", 100)

; Play animation
MyActor.PlayAnimation("IdleStanding")

Debugging

Debug Commands

  • Debug.Trace: Write to log file
  • Debug.Notification: Show message on screen
  • Debug.MessageBox: Show popup dialog

Example Debugging

Event OnActivate(ObjectReference akActionRef)
    Debug.Trace("Object activated by: " + akActionRef)
    Debug.Notification("Object activated!")
    
    ; Check if it's the player
    if akActionRef == Game.GetPlayer()
        Debug.MessageBox("Player activated this object!")
    endif
EndEvent

Best Practices

Scripting Tips

  • Always use descriptive variable names
  • Comment your code for clarity
  • Test scripts thoroughly
  • Use properties for values that might change
  • Handle errors gracefully

Performance Considerations

  • Avoid heavy operations in frequently called events
  • Use timers instead of while loops with waits
  • Clean up references when done
  • Minimize script overhead

Advanced Topics

Custom Events

; Define custom event
CustomEvent OnMyCustomEvent

; Send custom event
SendCustomEvent("OnMyCustomEvent")

; Listen for custom event
Event OnMyCustomEvent()
    Debug.Notification("Custom event received!")
EndEvent

State Machines

Use states to create complex behaviors:

Scriptname StateScript extends ObjectReference

; Default state
Event OnActivate(ObjectReference akActionRef)
    GoToState("Activated")
EndEvent

; Activated state
State Activated
    Event OnActivate(ObjectReference akActionRef)
        GoToState("Deactivated")
    EndEvent
EndState

Learning Resources

Essential resources for learning Papyrus scripting and improving your skills.

Text Guides

  • Hello World - A Papyrus Primer For Programmers - Read Guide - Excellent starting point for programmers
  • Fallout 4 Creation Kit Wiki: Papyrus Category - Browse Wiki - Official comprehensive documentation

Video Tutorials

  • Bethesda Mod School: Scripting 101 - Deployable Turrets Mod - Watch Video - Project-based learning experience

Video Tutorials

Step-by-step video guides for learning Papyrus scripting through practical examples.

Scripting 101 - Deployable Turrets

Learn Papyrus scripting by building a functional mod from the ground up.

Watch Tutorial

Next Steps

Continue your modding journey with these related topics:

NifSkope

Learn to work with 3D models and meshes

Learn More
Creation Kit

Master the official modding tool

Learn More
xEdit

Learn to clean mods and create patches

Learn More

Ready to Script!

You now have the foundation to start creating custom scripts for your Fallout 4 mods. Practice with simple scripts and gradually work your way up to more complex projects.