Edit an HKS or AI Lua script

The Script Editor is an editor tab in Smithbox for Nightreign and Elden Ring projects. It opens character Havok Script (action/script/*.hks) and enemy AI Lua (the entries of script/*.luabnd.dcx), shows compiled scripts decompiled, and can write a test copy that overrides a script in game without touching the original.

What was checked for this page: every label, key and path was read from the code. Nothing was run. The part about the game picking up a reload request is marked below: it depends on debug DLL code that is not in the shipped DLL.

Before you start

• A Nightreign or Elden Ring project. Other games show "The Script Editor supports Elden Ring and Nightreign combat scripts."
• The editor must be on for the project: the Script Editor checkbox in the project's configuration. It is on by default.
• For test copies: either the project has an Additional Mod Folder (the first one that exists is used), or you set a Test copy folder yourself. See project-setup.md for mod folders.

Open a script

1. Click the Script Editor tab.
2. The left list has two groups: Havok Script (action/script) and AI Lua (script/*.luabnd.dcx -> entries). Type in the filter above it to narrow the list. Rows show a name next to the id: a character's community name for c####.hks, and the NpcThinkParam row name for AI binders when params are loaded.
3. Click a row. AI Lua binders open into their entries; click an entry.
4. Each row says where the file comes from: project, additional mod, vanilla or Test copy.

Go > Go to file... (Ctrl+P) opens a file by script id or character name.

What you can edit

• Only a file in your own project folder, or a test copy, can be edited.
• Everything else is read-only and shows: "This file is read-only. Make a test copy to edit it; the test copy overrides the original in the game until you delete it."
• Compiled scripts are decompiled inside Smithbox when opened. The text starts with -- Decompiled from bytecode by Smithbox (DSLuaDecompiler, ElaDiDu fork). followed by any decompiler warnings. Decompiled text is read-only until you make a test copy of it.
• If the decompiler cannot handle a file you see "Compiled bytecode. Decompile with the Cereus hks tool to edit." For Havok Script, a Decompile (Cereus hks-cli) button appears when the hks-cli path is set (see Settings).
• Entries that are not text show "This entry is not plain text and cannot be edited here."

Make a test copy and try it in game

A test copy is the script text written into a folder the game loads. The original file is not changed.

1. Open the script.
2. Test copies > Make test copy (also in the row's right-click menu).
   • A .hks is written as a plain text file to <test folder>\action\script\c####.hks.
   • An AI Lua entry is written into a copy of its binder at <test folder>\script\NNNNNN_battle.luabnd.dcx (or _logic). The rest of the binder is taken as the game sees it.
   • If a file already sits at that place it is first moved to <path>.smithbox-orig.
3. Edit the text and save (File > Save, or Save All Modified).
4. Reload the character in game (next section) or restart the game.
5. When done: Test copies > Delete test copy, or Delete all test copies (N). The file that was there before is moved back.

Test copies > Only test copies filters the list to them. Smithbox keeps the list of its test copies in <project>\.smithbox\Project\SCRIPT\script-test-copies.json. Only files in that list are ever deleted or restored.

If you save a test copy with syntax errors the log says "Saved test copy ... with N syntax error(s). The game will not load it."

Saving a project file (not a test copy) writes it into the project folder. The first save of a file in a session keeps the earlier version beside it as .bak.

Reload the character in game

Smithbox does not talk to the game. It appends a character id to a text file, and the Team Cereus debug DLL is meant to read that file.

What Smithbox does (checked in the code):

• The file is chr-reload.request in the natives folder. That folder is, in order: the Nightreign natives folder setting; else a natives folder beside the project folder; else a natives folder inside it. The toolbar shows the resolved path as "Request file: ...". If the folder does not exist nothing is written and you see "Natives folder does not exist: ...".
• One line per request: the character id, such as c2500.
• Reload in game on save (on by default): after saving a Nightreign c####.hks, or after making or deleting its test copy, the id is appended. Elden Ring projects and AI Lua never write a request.
• Reload character: type an id in the Character id box and press the button.
• The Time Act Editor appends the id after saving a Nightreign character anibnd, under the same checkbox. The Havok Editor's Havok Script Reloader tool writes to the same file.
• AI Lua has no request. The tooltip says enemy AI luabnd files "are picked up by the debug DLL without a request" (that is the DLL's [hot_reload] section).

What the debug DLL does with it (read from chr_reload.rs, not proven in game):

• The section is [chr_reload] in debug-nightreign.toml. It is off by default and marked dev only.
• With it on, a watcher polls request_file (default chr-reload.request beside the DLL), queues each line, and empties the file. It also watches watch_dirs (default ..\mod\chr and ..\mod\action\script) for changed c#### files, so a saved test copy in the mod folder can queue a reload even without a request.
• A queued id is handed to the game's own debug character reload on the game thread. The log is chr-reload.log.
• The source file itself says: "The reload itself is not verified in game."
• Where this code is: on the main checkout of fromsoftware-rs the files chr_reload.rs, reload_status.rs (reload events for the DLL's dashboard) and script_view.rs (a read-only script list for the dashboard) are not committed and not part of the build. They are wired in, with the [chr_reload] config, only as uncommitted work in the worktree S:\fromsoftware-rs-wt-hotreload (branch debug-nightreign/hot-reload-ext). So a released Eclipse DLL does not act on chr-reload.request. Until that lands, restart the game to see a changed HKS.

Find your way around a script

• Outline (View > Outline): the file's Functions and Globals, with a filter and Sort A-Z.
• Problems (View > Problems): the live syntax check. The status reads "No syntax errors" or the error count. On decompiled text it adds: "Problems here come from the decompiler's output, not from a script someone wrote."
• Search results (View > Search results): text search and references. Scopes are Current file, Open documents, All HKS, All AI Lua and Everything, with Match case and Whole word.
• Go to definition and find references across files need the index. It builds by itself the first time one of them needs it. View > Index all scripts starts it by hand; View > Rescan scripts re-reads files changed outside the editor. While it builds, results say "index still building".
• Hovering an identifier shows "Defined in ...".
• View > Show id names: after lines that call env(id) or act(id) the name of the id is shown. Nightreign Havok Script only. The names come from Assets/Scripts/NR/hks-ids.json.
• Also under View: Indent guides, Highlight occurrences, Bracket matching.

Settings

In the toolbar, open Script tool paths:

With hks-cli set, a Compile to bytecode on save checkbox appears for Havok Script. It is off by default; the game accepts text .hks files.

What goes wrong