Skip to content
Back to search

sf-papyrus-ref

An offline Papyrus reference for Starfield that looks up official function names and flags, checks .psc and .pex scripts for DebugOnly, BetaOnly and Latent calls, and runs as an MCP server for AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/taosecurity--sf-papyrus-ref/badge.svg)](/listings/taosecurity--sf-papyrus-ref)

HTML

<a href="/listings/taosecurity--sf-papyrus-ref"><img src="/api/listings/taosecurity--sf-papyrus-ref/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

sf-papyrus-ref needs Python 3.9 or newer, on Windows or Linux. There's nothing else to install, because it uses Python's standard library only.

1. Install Python 3.11 or newer from [python.org](https://www.python.org/downloads/). On the first screen of the installer, tick **Add python.exe to PATH**. To check that it worked, open a new Command Prompt and type `python --version`. It should print a version number. 2. Download `sf-papyrus-ref-0.1.0.zip` and its `.sha256` file from the [releases page](https://github.com/taosecurity/sf-papyrus-ref/releases). 3. Check the zip. On Windows, run `certutil -hashfile sf-papyrus-ref-0.1.0.zip SHA256` and compare the result with the `.sha256` file. On Linux, run `sha256sum -c sf-papyrus-ref-0.1.0.zip.sha256`. 4. Unzip it anywhere, for example `C:\Tools\sf-papyrus-ref`. Keep its files together. 5. Open the unzipped folder in File Explorer, click the address bar at the top, type `cmd` and press Enter. A Command Prompt window opens in that folder, ready for the commands below. 6. Try it:

   sf-papyrus-ref lookup Utility.Wait

On Linux, use `./sf-papyrus-ref lookup Utility.Wait`. The launchers simply run `python -I sf_papyrus_ref.py` with your arguments, so `python -I sf_papyrus_ref.py lookup Utility.Wait` works too.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 249 lines
  1. # sf-papyrus-ref
  2. sf-papyrus-ref answers "does this Papyrus function exist in Starfield, on which script, and is it safe on Xbox?" offline, from the command line, in about a tenth of a second. It also checks your mod's scripts for calls that never work on consoles or should never ship.
  3. Download the latest zip from the [releases page](https://github.com/taosecurity/sf-papyrus-ref/releases), unzip it, open a Command Prompt in the folder and look a name up:
  4. ```
  5. sf-papyrus-ref lookup Debug.Notification
  6. ```
  7. For AI assistants: step-by-step instructions are in [AGENTS.md](AGENTS.md). They include the MCP server setup for Claude Code.
  8. ## Example
  9. Look up a function. This run is on a fresh install, before `build-local`, so it shows the official flags and wiki page but no signature yet:
  10. ```
  11. > sf-papyrus-ref lookup Debug.Notification
  12. sf-papyrus-ref 0.1.0 by Richard Bejtlich - MIT - https://github.com/taosecurity/sf-papyrus-ref
  13. Debug.Notification (function)
  14. Flags: DebugOnly
  15. Official page: https://starfield.creationkit.bethesda.net/w/index.php?title=Notification_-_Debug
  16. Run 'sf-papyrus-ref build-local' once to see signatures from your own Creation Kit sources.
  17. ```
  18. Check a script. The release zip holds a small made-up test script in `tests\fixtures`, as source (`.psc`) and compiled (`.pex`):
  19. ```
  20. > sf-papyrus-ref check tests\fixtures\SfprFixture.psc --allow Debug.Trace
  21. sf-papyrus-ref 0.1.0 by Richard Bejtlich - MIT - https://github.com/taosecurity/sf-papyrus-ref
  22. tests\fixtures\SfprFixture.psc:8: warning: Debug.Notification is DebugOnly: it does nothing in release builds on Xbox and PlayStation
  23. tests\fixtures\SfprFixture.psc:11: warning: Utility.Wait is Latent and is called inside a loop: each pass waits for it to finish
  24. tests\fixtures\SfprFixture.psc:15: error: Game.Warning is BetaOnly: it is meant for beta builds and should never ship
  25. tests\fixtures\SfprFixture.psc:31: warning: Debug.MessageBox is DebugOnly: it does nothing in release builds on Xbox and PlayStation
  26. Checked 1 files: 1 errors, 3 warnings.
  27. ```
  28. ## What it does for you
  29. - **It looks up a name.** `lookup` tells you which script has a function, event or struct, gives its official flags and links to its page on the official Creation Kit wiki. A name that isn't on the official list is reported as not found, with near matches. The tool never guesses.
  30. - **It lists a script.** `script Actor` shows every function and event on Actor.
  31. - **It filters by flag.** `list --flag latent` shows every Latent function.
  32. - **It checks your scripts.** `check` reads your `.psc` sources or compiled `.pex` files, and reports:
  33. - **BetaOnly** calls, as errors. They are meant for Bethesda's beta builds and should never ship.
  34. - **DebugOnly** calls, as warnings, or as errors with `--creations`. These calls do nothing in release builds on Xbox and PlayStation, so a `Debug.Notification` or `Debug.MessageBox` that the player should see is invisible on a console.
  35. - **Latent** calls inside a `While` loop, as warnings. The script waits for each one to finish on every pass.
  36. - **It helps AI agents.** `mcp` runs a small read-only server that Claude Code and other agents can query, so they look a name up instead of inventing one.
  37. The five flags come from the official wiki: Latent, Non-delayed, DebugOnly, BetaOnly and Inventory-safe. The wiki's [Latent Functions](https://starfield.creationkit.bethesda.net/w/index.php?title=Category:Latent_Functions) and [Non-Delayed Native Functions](https://starfield.creationkit.bethesda.net/w/index.php?title=Category:Non-Delayed_Native_Functions) pages explain the two timing flags.
  38. ## Install
  39. sf-papyrus-ref needs Python 3.9 or newer, on Windows or Linux. There's nothing else to install, because it uses Python's standard library only.
  40. 1. Install Python 3.11 or newer from [python.org](https://www.python.org/downloads/). On the first screen of the installer, tick **Add python.exe to PATH**. To check that it worked, open a new Command Prompt and type `python --version`. It should print a version number.
  41. 2. Download `sf-papyrus-ref-0.1.0.zip` and its `.sha256` file from the [releases page](https://github.com/taosecurity/sf-papyrus-ref/releases).
  42. 3. Check the zip. On Windows, run `certutil -hashfile sf-papyrus-ref-0.1.0.zip SHA256` and compare the result with the `.sha256` file. On Linux, run `sha256sum -c sf-papyrus-ref-0.1.0.zip.sha256`.
  43. 4. Unzip it anywhere, for example `C:\Tools\sf-papyrus-ref`. Keep its files together.
  44. 5. Open the unzipped folder in File Explorer, click the address bar at the top, type `cmd` and press Enter. A Command Prompt window opens in that folder, ready for the commands below.
  45. 6. Try it:
  46. ```
  47. sf-papyrus-ref lookup Utility.Wait
  48. ```
  49. On Linux, use `./sf-papyrus-ref lookup Utility.Wait`. The launchers simply run `python -I sf_papyrus_ref.py` with your arguments, so `python -I sf_papyrus_ref.py lookup Utility.Wait` works too.
  50. ## Words used here
  51. - **Papyrus:** Starfield's scripting language. Scripts are written as `.psc` source files and compiled into `.pex` files that the game runs. A mod's scripts are what make things happen in the game, such as starting a quest or giving an item.
  52. - **Function, event and struct:** a function is something a script can call (`Debug.Notification`), an event is something the game calls on a script when a thing happens (`OnActivate`), and a struct is a small group of named values.
  53. - **Creation Kit (CK):** Bethesda's official editor for making Starfield mods. Its download includes the source of the game's own scripts, in `Tools\ContentResources.zip`.
  54. - **Latent:** a function that makes the script wait until it finishes, such as `Utility.Wait`.
  55. - **DebugOnly and BetaOnly:** functions that work only in debug or beta builds of the game. On Xbox and PlayStation they do nothing.
  56. - **SFSE:** the Starfield Script Extender, which adds features the game lacks, on PC only. Its functions aren't on the official list.
  57. - **MCP (Model Context Protocol):** a standard way for AI assistants to call a tool.
  58. ## lookup: where a name lives
  59. Give it a name, or a script and a name. The Example above shows a name that exists. A misspelled name is reported as not found, with near matches, and exits with code 1:
  60. ```
  61. > sf-papyrus-ref lookup Notifcation
  62. sf-papyrus-ref 0.1.0 by Richard Bejtlich - MIT - https://github.com/taosecurity/sf-papyrus-ref
  63. Notifcation: Not in the official list. It may be a script extender (SFSE) function, a function from another mod's script, or a made-up name. The Papyrus compiler is the final judge.
  64. Did you mean: Notification, OnStoryInfection, GetClassification, IsInFaction, GetLocation
  65. ```
  66. ## script: everything on one script
  67. `script` lists a script's functions, events and structs, with each one's flags:
  68. ```
  69. > sf-papyrus-ref script Utility
  70. sf-papyrus-ref 0.1.0 by Richard Bejtlich - MIT - https://github.com/taosecurity/sf-papyrus-ref
  71. Utility - Functions (25)
  72. CallGlobalFunction [Latent, Non-delayed]
  73. CallGlobalFunctionNoWait [Non-delayed]
  74. ExpiryDay
  75. GameTimeToString
  76. ...
  77. Wait [Latent]
  78. ...
  79. ```
  80. ## list: everything with one flag
  81. `list --flag` takes latent, nondelayed, debugonly, betaonly or invsafe. Add `--script` to look at one script only:
  82. ```
  83. > sf-papyrus-ref list --flag latent --script Utility
  84. sf-papyrus-ref 0.1.0 by Richard Bejtlich - MIT - https://github.com/taosecurity/sf-papyrus-ref
  85. Utility.CallGlobalFunction (function)
  86. Utility.Wait (function)
  87. Utility.WaitGameTime (function)
  88. Utility.WaitMenuPause (function)
  89. 4 entries flagged Latent on Utility.
  90. ```
  91. ## data: where the list comes from
  92. ```
  93. > sf-papyrus-ref data
  94. sf-papyrus-ref 0.1.0 by Richard Bejtlich - MIT - https://github.com/taosecurity/sf-papyrus-ref
  95. Data file: ...\sf-papyrus-ref\data\official-names.json
  96. Official wiki revision 8392, list built 2026-11-20.
  97. 103 scripts, 1390 functions, 260 events, 3 structs.
  98. Flags: Latent 63, Non-delayed 194, DebugOnly 56, BetaOnly 2, Inventory-safe 37
  99. Names and flag categories from the official Starfield Creation Kit wiki (starfield.creationkit.bethesda.net). Names, flags and links only: no wiki text, no signatures and no game script sources.
  100. ```
  101. ## build-local: read signatures from your own Creation Kit (recommended)
  102. The shipped list holds names and flags only. Run this once to add signatures and parent scripts from your own Creation Kit:
  103. ```
  104. > sf-papyrus-ref build-local
  105. sf-papyrus-ref 0.1.0 by Richard Bejtlich - MIT - https://github.com/taosecurity/sf-papyrus-ref
  106. Read 1702 scripts (8381 functions, events and structs) from C:\Program Files (x86)\Steam\steamapps\common\Starfield\Tools\ContentResources.zip.
  107. 102 of the 103 scripts on the official list are among them.
  108. Saved the local cache to C:\Users\<you>\AppData\Local\sf-papyrus-ref\local.json (it stays on this machine; never share it).
  109. ```
  110. (The user name in the cache path is replaced with `<you>`.)
  111. It finds `Tools\ContentResources.zip` in your Steam Starfield folder (in any Steam library) and reads the script sources inside it without extracting them. That takes about a second. It saves a cache to `%LOCALAPPDATA%\sf-papyrus-ref\local.json` on Windows, or `~/.cache/sf-papyrus-ref/local.json` on Linux. The cache is made from Bethesda's files, so keep it on your machine.
  112. - **Steam:** found on its own. The Creation Kit is a free Steam tool ("Starfield Creation Kit").
  113. - **Game Pass:** the Creation Kit ships only on Steam. If you have the sources somewhere else, pass their location with `--sources`.
  114. - **Extracted sources, MO2 or Vortex:** if you unpacked the sources into a folder (for example `Data\Scripts\Source`, or an MO2 mod folder), pass it with `--sources <folder>`. Use the folder that holds `Debug.psc`.
  115. Once the cache exists, these commands improve:
  116. - `lookup` and `script` show each signature, and `lookup` also finds functions on the game's other scripts, such as quest scripts. After `build-local`, the Example lookup gains the line `Signature (your sources): Function Notification(string asNotificationText) native global`.
  117. - `check` follows parent scripts. For example, a call to `MoveTo` on an Actor is matched to `ObjectReference.MoveTo`.
  118. - `diff` compares the official list with your sources (see below).
  119. ## diff: the official list against your sources
  120. `diff` shows names and flags present in only one of the two lists. The sources mark more functions DebugOnly than the wiki does, and `check` uses both.
  121. ```
  122. > sf-papyrus-ref diff --quiet
  123. Official list (wiki revision 8392) against your sources (C:\Program Files (x86)\Steam\steamapps\common\Starfield\Tools\ContentResources.zip).
  124. Scripts on the official list but not in your sources: 1: Array
  125. Names on the wiki but not in your sources: 2
  126. Game.EnableFastTravel
  127. ObjectReference.OnDeath
  128. Names in your sources but not on the wiki: 497
  129. ActiveMagicEffect.OnActivate
  130. ...
  131. ```
  132. ## check: check your scripts
  133. ```
  134. sf-papyrus-ref check "C:\MyMod\Scripts\Source" --allow Debug.Trace
  135. ```
  136. The Example above shows its output on the bundled test script.
  137. - Give it files or folders (folders are searched below them), holding `.psc` sources or compiled `.pex` scripts.
  138. - `--allow Script.Name` never reports that call. `--allow Debug.Trace` suits mods that log on purpose, because a Trace that vanishes on a console does no harm. Repeat the option, or separate names with commas.
  139. - `--creations` makes DebugOnly an error. Use it before you publish to Bethesda Creations, where console players will run your mod.
  140. - `--json` writes the findings for a script or a build step.
  141. - A finding marked `[name only]` was matched by its name alone, because the tool could not tell the object's type. Run `build-local` for exact matches. `--strict` also reports names that only some scripts flag.
  142. - It is a light reader, not a compiler. The Papyrus compiler stays the final judge of whether a script is correct.
  143. ## Use it from Claude Code (MCP)
  144. Add it once (use the folder where you unzipped it):
  145. ```
  146. claude mcp add sf-papyrus-ref -- python -I C:\Tools\sf-papyrus-ref\sf_papyrus_ref.py mcp --quiet
  147. ```
  148. The agent then has four read-only tools: `papyrus_lookup`, `papyrus_script`, `papyrus_list_flag` and `papyrus_check`. A good line for your project's `CLAUDE.md` is "Look up every Papyrus function with papyrus_lookup before using it, and run papyrus_check on scripts you change." Other MCP clients start the same command.
  149. ## Commands and exit codes
  150. | Command | What it does | Exit code |
  151. |---|---|---|
  152. | `lookup <Name or Script.Name>` | Where a name lives, its flags, its page, its signature | 0 found, 1 not found |
  153. | `script <Script>` | Every function, event and struct on a script | 0 found, 1 not found |
  154. | `list --flag <flag> [--script X]` | Every entry with a flag (latent, nondelayed, debugonly, betaonly, invsafe) | 0 some, 1 none |
  155. | `data` | Which wiki revision the shipped list comes from | 0 |
  156. | `build-local [--sources <path>]` | Builds the local cache from your Creation Kit sources | 0 done |
  157. | `diff [--all]` | The official list against your sources | 0 done |
  158. | `check <paths> [--allow X] [--creations] [--strict]` | BetaOnly, DebugOnly and Latent-in-loop calls | 0 clean, 1 findings |
  159. | `mcp` | Read-only MCP server on stdin and stdout | 0 when the client closes it |
  160. Exit code 2 always means a problem with the input: a bad option, a file that could not be read, or no sources found.
  161. Every command takes `--json`, `--quiet` (no byline), `--verbose`, `--log <file>`, `--cache <file>`, `--no-local` and `--data <file>`. `--version` shows the version and credits.
  162. ## Logs
  163. If something goes wrong, run the same command with `--verbose` to see on screen what it read and decided, or with `--log sf-papyrus-ref.log` to save that to a file. The log names every file read and every call it matched by name only. It can show your user folder and Steam library paths, so read it before you post it.
  164. ## What is in the data, and what isn't
  165. `data/official-names.json` lists, for each official Papyrus function, event and struct: its name, its script, its kind, its flags and a link to its official wiki page. The flags are the official wiki's category pages, and the list was built with `tools/build_names.py` from wiki revision 8392.
  166. The tool ships **no** text from the wiki, **no** signatures and **no** script sources. Signatures appear only after you run `build-local`, and they come from the copy of the Creation Kit on your own machine.
  167. ## Similar tools
  168. - [Papyrus Index](https://papyrus.bellcube.dev/) by BellCube is a searchable site for Papyrus in several games. Its Starfield data is from game version 1.15.216.
  169. - [papyrus-tools](https://github.com/Kiyozz/papyrus-tools) by Kiyozz is a Papyrus linter, formatter and language server.
  170. - Bethesda's VS Code extension (in the Creation Kit's `Tools\VSCodePapyrusAddon`) and [Papyrus Language Tools](https://github.com/joelday/papyrus-lang) give completion and hover help while you edit.
  171. - The [official Creation Kit wiki](https://starfield.creationkit.bethesda.net/) has the full description of every function.
  172. ## Updates
  173. When Bethesda updates the wiki, a new release of the name list follows. `sf-papyrus-ref data` shows which revision you have. Maintainers rebuild the list with `python -I tools/build_names.py --mirror <saved copy of the wiki> --diff`.
  174. ## Found a mistake?
  175. Open an issue: https://github.com/taosecurity/sf-papyrus-ref/issues
  176. ## Credits and License
  177. - sf-papyrus-ref is by Richard Bejtlich. It uses only the [Python](https://www.python.org/) standard library.
  178. - The function and event names and their flags are from Bethesda's [official Starfield Creation Kit wiki](https://starfield.creationkit.bethesda.net/).
  179. - The `.pex` reader is adapted from [sf-pex-tools](https://github.com/taosecurity/sf-pex-tools).
  180. - Starfield, the Creation Kit and Papyrus belong to Bethesda Softworks. This is a community tool, and Bethesda neither made nor endorses it.
  181. - [PRIVACY.md](PRIVACY.md) says what the tool reads and writes.
  182. sf-papyrus-ref is free software under the [MIT License](LICENSE), with no warranty.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.