KenshiLua is a DLL extension for Kenshi that embeds a Lua runtime and exposes selected portions of KenshiLib to Lua.
The goal is to provide a Lua scripting workflow to mod Kenshi and lower the barrier to entry for utilizing KenshiLib through rapid iteration and scripting.
Loaded at runtime through RE_Kenshi, KenshiLua exposes selected portions of KenshiLib through a mixture of generated and hand-written Lua bindings, enabling rapid development, experimentation, and mod creation without requiring direct interaction with the underlying C++ APIs.
- Exposes KenshiLib functionality through Lua
- Allows for Lua scripts to be loaded from a mod folder at runtime or exectued dynamically from predefined dialogues using FCS Extended.
- Exposes a varierty of core gameplay events to registered scripts in the form of callbacks
- Provides a GUI that includes:
- a Script Manager detialing which scripts have been loaded from active mods
- a Script Editor for creating or editing scripts in-game
- a Console for executing simple lua commands
- and a detailed Logger which can be used to troubleshoot issues with any lua scripts
A large amount of KenshiLib has been exposed for use from Lua. KenshiLua is built against KenshiLib 0.5.0, the version RE_Kenshi ships. It covers almost all of the API that KenshiLib 0.3.0 provided and part of the classes added in 0.5.0.
- BindingsReference.md - View for a list of methods and properties available from Lua.
- EnumsReference.md - View for a list of enums available from Lua.
- CallbacksReference.md - View for a list of event callbacks available from Lua.
- ContainersReference.md - View for container methods, operators, and memory rules.
- MyGUIReference.md - View for a list of MyGUI methods and properties available from Lua.
- InGameGUI.md - Guide for using the in-game GUI, script manager, editor, console, and log viewer.
- DialogueScriptingBridge.md - Guide for executing Lua scripts from dialogue lines using FCS Extended.
- LuaLS.md - Configure Lua Language Server editor support for KenshiLua scripts.
- UnboundReference.md - View for a list of methods and properties that exist in KenshiLib 0.5.0 but are not currently exposed to Lua.
KenshiLib is a large and complex codebase, and while KenshiLua exposes a large portion of it, there are still many methods and properties that are not yet exposed to Lua. If you find that a method or property you need is not available, please open an issue on the KenshiLua GitHub repository.
Native KenshiLib plugins can discover KenshiLua at runtime through the
header-only C++ Extension SDK. The SDK does not require linking against
KenshiLua.lib or lua51.lib; it negotiates a versioned function table from
the loaded KenshiLua.dll.
See CppExtensionAPI.md for the API contract and Cpp_KenshiLib_Integration_Demo for a buildable plugin example.
- Ensure RE_Kenshi v0.3.3 or later is installed.
- Download the latest release of KenshiLua and extract the archive, placing the contents in Kenshi's mods directory.
- Activate the mod using the game's launcher like you would any other mod.
To get autocompletion and type checking for KenshiLua scripts in your editor, download KenshiLua-LuaLS-Addon-v<version>.zip from the same release and follow the README inside it. See LuaLS.md.
For example, if KenshiLib contains the class:
class GameWorld
{
void userPause(bool p);
bool paused;
}Then you can use it from Lua like this:
-- Get the global GameWorld instance.
local world = getGameWorld()
-- Call a method on the object.
world:userPause(true)
-- Read or modify one of the object's properties.
if world.paused then
world.paused = false
endThere is also a list of events that you can register callbacks for like so:
-- This will run every time the InputHandler::keyDownEvent method is called by the game.
-- OIS::KeyCode KC_V is equal to the integer 47
local KC_V = 47
-- The callback receives an InputHandler* and an OIS::KeyCode integer.
local function on_key_down(thisptr, key_code)
-- if that int is equal to 47 (the v key was pressed)
if key_code == KC_V then
toggle_prone()
end
end
-- Register a callback to InputHandler::keyDownEvent
Events.on("InputHandler::keyDownEvent", on_key_down)- When the game starts, KenshiLua will check whether any active mods contain any
.luafiles inside of their./scripts/init/directory, and if found will automatically load them. - On Steam, active mods are resolved from both
Kenshi/mods/andsteamapps/workshop/content/233860/<workshop-id>/. Workshop items are matched to the active mod's.modfile; inactive Workshop items are not loaded. - So to clarify for a mod named
MyMod, if you have a script at./mods/MyMod/scripts/init/my_script.lua, it will be loaded automatically when the game starts. - Scripts found in other directories within
./mods/MyMod/scripts/(e.g../mods/MyMod/scripts/world_scripts.lua) will not be loaded automatically. - Startup and on-demand scripts can load additional files from their own mod. All relative paths start at the mod's
scripts/directory:require("config.settings")checksscripts/config/settings.luaand thenscripts/config/settings/init.lua, whiledofile("config/settings.lua")andloadfile("config/settings.lua")check that exact path. Mod-localrequireresults are cached per script sandbox, so another mod can use the same internal module name safely. - Use ordinary
require, such asrequire("mygui.layout"), for modules shipped in KenshiLua'slib/directory. Explicit dependencies on another active mod useKenshiLua.requireFromMod("Shared Framework.mod", "api.shared"); exact cross-mod files can be loaded withKenshiLua.dofileFromModorKenshiLua.loadfileFromMod.
- Using FCS Extended (Github | Nexus) with KenshiLua enabled, you'll find a new
run lua scriptoption available for DIALOGUE, DIALOGUE_LINE, or WORD_SWAP. When the given dialogue plays, the script runs. - See DialogueScriptingBridge.md for complete details on FCS setup, mod folder structure, injected Lua globals (
currentDialogue,currentDialogueLine), and diagnostics.
*The example shown in this image, available in the repository, uses the players Dexterity and Thieving stats to give the player an advatage in a game of dice. The script runs whenever the given dialogue option is chosen by the player.
- Pressing
Ctrl+Shift+Lin-game will open KenshiLua's Main GUI. From here you can access the Script Editor and load, edit, save, and run scripts using the buttons on the Script Editor's toolbar as well as access other features.
Warning
This section is WIP and is not intended for casual users. The process is complex and requires a solid understanding of the C++ build process and toolchain used by Kenshi and KenshiLib.
-
Clone the KenshiLua repository using the --recursive flag to ensure all dependencies are also cloned:
git clone --recursive https://github.com/Genpretz/KenshiLua.git -
Change the KenshiLib headers. KenshiLua pins the
extern/KenshiLibsubmodule at11cd65d, KenshiLib 0.5.0, the version RE_Kenshi ships. Its headers need the changes below; paths are relative toextern/KenshiLib/Include/. To build a KenshiLua version that pins KenshiLib 0.3.0 (v0.2.0-alphathroughv0.3.9-alpha), follow Building KenshiLua with KenshiLib 0.3.0 instead.These classes are defined in two headers. Delete the duplicate and include the header that keeps the definition:
File Change kenshi/Globals.hDelete the namespace FoliageSystem { class EntData; }block, which conflicts withclass FoliageSystem, and add#include "FoliageSystem.h".kenshi/SaveInfo.hDelete class GameplayOptions { ... };and add#include "GameplayOptions.h".kenshi/PlayerInterface.hDelete class ContextMenu { ... };and add#include "gui/ContextMenu.h".kenshi/Campaign.hDelete class CampaignTriggerData { ... };and add#include "Dialogue.h".kenshi/PhysicsCollection.hDelete class WeatherRegion { ... };and add#include "Weather.h".kenshi/ZoneManager.h,kenshi/combat/CombatClass.hBoth define class ParticlePool. Move it into a newkenshi/ParticlePool.h(contents), delete it from both headers, and include the new file:#include <kenshi/ParticlePool.h>inZoneManager.hand#include "../ParticlePool.h"inCombatClass.h.These declarations disagree with the game or with the libraries KenshiLua links against:
File Change Without it kenshi/util/hand.hMove the virtual bool operator==(const hand& a) const;andbool _NV_operator_equal(const hand& a) const;lines abovevirtual bool operator==(bool a) const;.KenshiLua still builds, but comparing two handles calls hand::operator==(bool). MSVC places overloaded virtual functions in reverse declaration order, which swaps the twooperator==vtable slots relative to the game.kenshi/Havok.hMove enum Maskout ofhkVector4fComparisoninto a newstruct hkVector4ComparisonMaskdeclared just before it, and addtypedef hkVector4ComparisonMask::Mask Mask;tohkVector4fComparison.Link errors: KenshiLib exports the class's methods with hkVector4ComparisonMask::Maskparameters.mygui/MyGUI_ItemBox.hAdd a trailing bool update = trueparameter toinsertItemAt,addItem, andremoveItemAt.KenshiLua imports ItemBoxmethods that Kenshi'sMyGUIEngine_x64.dlldoes not export and fails to load.mygui/common/baselayout/BaseLayout.hChange class __declspec(dllimport) BaseLayouttoclass BaseLayout.Link error: the linker expects BaseLayout's constructor from a DLL. -
Replace
extern/KenshiLib/Libraries/mygui/MyGUIEngine_x64.libwith an import library generated from Kenshi'sMyGUIEngine_x64.dll, following Regenerate the MyGUI import library. Kenshi uses a customized MyGUI, and the library in the KenshiLib repository does not match it. -
Build
extern/KenshiLib/KenshiLib.vcxprojusing its Release x64 configuration. KenshiLua links the resultingextern/KenshiLib/x64/Release/KenshiLib.lib. -
Build KenshiLua using the Release configuration available in
KenshiLua.vcxproj. (Debug builds will not work as they are not compatible with the release version of Kenshi and KenshiLib and are not functional). -
KenshiLua.vcxprojincludes a post-build event that will copy the builtKenshiLua.dllalong with all the other files and directories required for KenshiLua to run to$(ProjectDir)bin/KenshiLua/
At runtime, KenshiLua uses the KenshiLib.dll that RE_Kenshi installs in the game folder, not the one built in step 4. A build loads only if that DLL and Kenshi's MyGUIEngine_x64.dll export every symbol KenshiLua imports; compare dumpbin /imports of KenshiLua.dll with dumpbin /exports of each DLL to check.
- The game and KenshiLib are built against MSVC2010-era assumptions, including C++ ABI layout and runtime library behavior. KenshiLua and all ofther dependencies must match these constraints to ensure stable integration.
- There are no official LuaJIT release binaries built for MSVC2010. Therefore, a compatible version is included in the repository. If you wish to compile LuaJIT from source, ensure you build for MSVC2010.
Originally, while working on KenshiPy, an analogous Python extension for Kenshi, I discovered that although SWIG made it possible to generate bindings with very little effort, SWIG 3.0.12 became difficult to work with when wrapping certain parts of KenshiLib. The generated bindings ended up as one huge monolithic file, totaling 259,649 lines the last time I checked. Because SWIG generates bindings as a single translation unit, they can't easily be split across multiple source files. This made the generated code difficult to manage, and with compiler optimizations enabled, build times could easily approach an hour. Combined with the fact that KenshiPy relied on the long-outdated Python 3.4, the overall development experience became increasingly frustrating. While SWIG's language-agnostic interface files would have made switching to another language relatively straightforward, changing languages alone wouldn't have solved most of these underlying issues.
Around this time, I decided that Lua was a better fit for the project. Its similarity to Python and widespread use in the modding community made it a natural choice. Lua also had relatively recent release in v5.4 with pre-built MSVC2010 binaries, but luckily building Lua 5.5 with MSVC2010 turned out to be straightforward. I explored several binding libraries, including sol2, luabind, and others, but most were not immediately compatible with the MSVC2010 toolchain used by Kenshi and KenshiLib or were limited in the version of Lua they were compatible with. In the end, I decided to write the bindings manually. Fortunately, once you've implemented the binding code for one method or member variable, the rest largely follows the same pattern, making it easy to reuse and adapt the code. I decided to leverage the use of AI tools to generate scripts for parsing KenshiLib's headers in order to generate all the simplest bindings and scaffolding needed to move forward as well as scripts for generating minimal documentation of the bindings. AI undoubtly expediated the development process, but it led to many issues including duplicated functionality, broken bindings, and orphaned code. One instance in which it was helpful was when the project switched to LuaJIT.
Further research had led me to discover LuaJIT, a just-in-time compiler based on Lua 5.1 that is often reported to deliver performance approaching native C. Since it promised better performance than standard Lua, I wanted to evaluate it before the project grew any larger. After confirming that LuaJIT could also be built with MSVC2010, I created a separate branch using it. That branch has since become the project's main branch. My own benchmarking has shown only very small performance differences between the two implementations so far, so whether LuaJIT's potential performance gains ultimately outweigh the additional language features available in Lua 5.5 remains an open question.