Skip to content

Locations with Scripts

Jump to bottom
lilebonymace edited this page Jan 30, 2026 · 15 revisions

Locations with Scripts

It's possible to run a custom Papyrus script when your starting in your location, which allows you to perform any actions in addition to teleporting the player to the starting locations: adding items, enabling/disabling objects, completing/advancing/starting quests, adding the player to a faction, etc. If you don't need it, you don't need to do anything described on this page.

Examples

See the Orc Strongholds, Thalmor and Bruma addons.

Getting Started

  1. Create (in CK or xEdit) a new Quest that will host your script. You don't need to create an actual quest, just an empty invisible quest to attach your script to (this kind of quests are used in most mods that need to run Papyrus scripts that are not attached to specific ingame objects). Though, if your idea includes an actual quest, you can use the same quest (or you can start a different quest from this one).

  2. Attach a new script to the created quest. The script must extend SkyrimUnboundLocationAddonScript. For that you can replace "Quest" in the "Extends:" field with "SkyrimUnboundLocationAddonScript" when adding a new script in CK or in the first line of an already created script. The first line of your script must look like this (replace YourScriptName with your script name):

Scriptname YourScriptName extends SkyrimUnboundLocationAddonScript
  1. Add PrepareStart function to your script. SUR will call this function before teleporting the player to the starting location.
function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
endFunction

  1. Specify the created quest in your JSON in the fQuest property. You can set it either on a specific location or on a location type. A single quest can be used for multiple locations or/and location types (but you can use as many quests with their own scripts as you want). If for some location fQuest is set both on this location and its location type, only the quest on the location will be used.

  2. Now you can write any code you want in your script.

function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
    TeleportPlayer()
    Utility.Wait(0.1) ; the player is already teleported, but this will wait until the loading screen ends
    Debug.Messagebox("Hello, world!")
endFunction

Starting and stopping your quest

When creating a new quest in CK, the Start Game Enabled flag is checked by default. It's recommended to uncheck it if you don't need it - SUR will start your quest if it isn't started yet.

It's also recommended to stop your quest once everything is done if you don't need it to be running. To do this, call Stop() in the last line of the PrepareStart function. This way your quest and script will only work when they're needed.

function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
    ; do stuff
    Stop()
endFunction

SkyrimUnboundLocationAddonScript

Your location script must extend this script:

Scriptname YourScriptName extends SkyrimUnboundLocationAddonScript

SkyrimUnboundLocationAddonScript has two callback functions called by SUR, you need to implement one or both of them in your script:

  • PrepareStart
  • AfterTeleportationSync

SkyrimUnboundLocationAddonScript provides the following functions that you can use in your script:

  • TeleportPlayer

PrepareStart

function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
endFunction

A callback function called by SUR before teleporting the player to the selected strarting location. The player gets teleported after your PrepareStart function returns (finishes running). You can also call TeleportPlayer while PrepareStart is running so that all the code after TeleportPlayer is run after the player is teleported.

Parameters:

  • ObjectReference teleportMarker. This is the reference (the marker) that the player is being teleported to (the one you specified in fLocation on your location).
  • string locationTypeParam. A custom string parameter for location types. If sParam is specified on the location type in its JSON, SUR will pass that value in this parameter. If it's not specified, this parameter will be an empty string. If you use a location type from another addon, its location type sParam will be passed to your function.
  • string locationParam. A custom string parameter for specific locations. If sParam is specified on the specific location in its JSON, SUR will pass that value in this parameter. If it's not specified, this parameter will be an empty string.

If this script is used for multiple locations or/and location types, you can use the parameters of this function to identify which location was selected this time. You can either check teleportMarker (compare with specific markers or check if a location type formlist contains this marker) or use the custom parameters.

ObjectReference Property MyMarker1 Auto 
ObjectReference Property MyMarker2 Auto 
FormList Property MyLocTypeList1 Auto

function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
    if teleportMarker == MyMarker1
        ; do stuff needed for MyMarker1 
    elseif teleportMarker == MyMarker2
        ; do stuff needed for MyMarker2
    endif
    if MyLocTypeList1.HasForm(teleportMarker)
        ; do stuff needed for all locations in MyLocTypeList1
    endif
    ; do stuff needed for all locations that this script is used for
endFunction
function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
    if locationParam == "1" ; as set on the location 1 in the .json
        ; do stuff needed for location 1
    elseif locationParam == "2" ; as set on the location 2 in the .json
        ; do stuff needed for location 2
    endif
    if locationTypeParam == "MyType1" ; as set on the location type 1 in the .json
        ; do stuff needed for all locations of type 1
    endif
    ; do stuff needed for all locations that this script is used for
endFunction

TeleportPlayer

function TeleportPlayer(bool dontCompleteStartUntilPrepareStartReturns = false)

This function needs to be called while PrepareStart is running. It allows teleportation and waits until the player is teleported. You only need to call this function if you need to run some code after the player is teleported. I.e. there are two options:

function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
    ; code that runs before teleportation
endFunction
function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
    ; code that runs before teleportation
    TeleportPlayer()
    ; code that runs after teleportation
endFunction

Setting dontCompleteStartUntilPrepareStartReturns=true allows you to run some code after the player is already teleported to the starting location, but before SUR does anything that it does after the teleportation: enabling controls, advancing the stage of SkyrimUnbound quest and MQ101, sending SUR mod events, etc. With dontCompleteStartUntilPrepareStartReturns=true SUR will wait for this function to return before doing all of that. In most cases you don't need this and should keep this parameter on false (or better simply don't set it because false is the default value). One case in which you may want to use dontCompleteStartUntilPrepareStartReturns=true is if you want to show some messagebox or menu to the player after the start. If the player has other mods that add menus that pop up after the game start (like class selection), these menus will interfere with yours. By setting dontCompleteStartUntilPrepareStartReturns=true you show your menu before SUR enables controls, advances the stage of the Skyrim Unbound quest or MQ101, or sends mod events, therefore all menus from mods that wait for one of these things won't open until your menu is closed.

function PrepareStart(ObjectReference teleportMarker, string locationTypeParam, string locationParam)
    ; code that runs before teleportation
    TeleportPlayer(dontCompleteStartUntilPrepareStartReturns = true)
    ; code that runs after teleportation. SUR won't complete the start until the PrepareStart function returns.
endFunction

Scripting Tips

To manipulate or even simply retrieve a non-persistent ObjectReference or Actor, it must be loaded. If you need to do that, you can either edit the record by adding a Persistent flag to it or retrieve and manipulate it only when it's loaded. The latter can be done after the teleportation if the object is within the loaded area. For example this code retrieves and unlocks a non-persistent locked chest in the Bandit Camp > Ruins of Bthalft location (called after the teleportation when the player starts in Bthalft).

(Game.GetFormFromFile(0xFEADF, "Skyrim.esm") as ObjectReference).Lock(false, false)

Clone this wiki locally