NOTICE: This is a resource/utility for modders. Regular mod users should only download this if another mod requires it. It will do nothing for you otherwise.
Installation Requirements
1. Requires Ultimate ASI Loader (included in download).
2. Place the `.asi` file of this mod and the ASI loader (i.e., the `.dll` file) into the game's root directory (i.e., the folder containing `KingdomCome.exe`, located at `KingdomComeDeliverance2\Bin\Win64MasterMasterSteamPGO`).
Linux Users:
Proton/Wine: Add this to your Steam launch options:
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
LuaDB - KCD2 Lua Persistence Module
What is this?
This is LuaDB, a Lua persistence module designed for KCD2 modders. It stores Lua data (including tables, booleans, numbers, and strings) in an SQLite database and offers two save modes:
1. Global – Data persists across all game saves (independent of the game save).
2. Local – Bound to the game save, data is associated with a specific game save file:
- Automatically saved when the game is saved.
- Automatically loaded when the game loads that save.
Why?
Before this mod, there was no simple and safe way to persistently store Lua data in KCD2. Modders had to rely on workarounds (like entity properties), which were unreliable or limited. This mod solves that by offering:
- Permanent storage (even after game restarts)
- Easy-to-use Lua API (both simple `Set/Get` and new object-oriented `DB.Create` interface)
- Safety The storage is external (saved in the kcd2db.db file), minimizing the risk of data corruption. In the worst case, the mod may become unusable after an update, which can be resolved by removing it and any dependent mods.
- Two storage modes (global or save-specific)
- Lua object support (any Lua object encodable by json.lua)
For Whom?
- Modders: Essential for mods needing persistent data.
- Regular Players: Only needed if a mod requires it (does nothing alone).
What Does This Do?
1. Stores Lua Data
- Uses DB.Create("ModName") to create a database object for your mod.
- Use the database object's `Set` method to store data. Data is automatically converted to JSON for storage and back to Lua objects when retrieved.
- Example: local myDB = DB.Create("MyAwesomeMod"); myDB.Set("player_health", 85.6)
2. Retrieves Data
- Use the database object's `Get` method to retrieve data.
- Example: local health = myDB.Get("player_health")
3. Debugging Tools
- LuaDB.Dump() – Prints all stored data to console
- Logs (kcd2db.log) and SQLite database (kcd2db.db)
4. Use Cases
- Saving mod settings (e.g., keybinds, configurations)
- Storing player progress (e.g., custom quest states)
- Persistent inventory/outfit data (e.g., saved outfits)
- Storing complex data structures like tables and arrays.
5. Sample Code
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Introduction
This module provides SQLite-based Lua data persistence for Kingdom Come: Deliverance II mod developers, supporting
two storage modes:
- Global Storage: Persists data across game saves (APIs end with "G") with automatic save/load
- Save-associated Storage: Data bound to game save slots with automatic save/load synchronization
The source code is located at Github-kcd2db
API Documentation
DB API Documentation
- DB.Create("Your MOD") - Creates a namespace instance with the same API, automatically adding a prefix to all keys to reduce the likelihood of key conflicts. This method should always be preferred.
- DB.Get(key) - Get local key value
- DB.Set(key, value) - Set local key value
- DB.Del(key) - Delete local key value
- DB.Exi(key) - Check if local key exists
- DB.All() - Get all local key values
- DB.GetG(key) - Get global key value
- DB.SetG(key, value) - Set global key value
- DB.DelG(key) - Delete global key value
- DB.ExiG(key) - Check if global key exists
- DB.AllG() - Get all global key values
- DB.Dump() - Print all data
All methods support both . Call and : Call syntax, which can be selected according to personal preferences.
Quick Access
- DB("Your MOD") - Equivalent to DB.Create("Your MOD")
- DB.key / DB["key"] - Access local key value (If it has the same name as an existing method, it will cause a conflict, resulting in the return of the function instead of the data.)
- DB.L.key / DB.L["key"] - Access local key value, No conflict
- DB.G.key / DB.G["key"] - Access global key value, No conflict
Notes
1. Namespace names cannot contain colons, "namespace:" will be used as a key prefix in the database to isolate data from different mods.
2. When the key name is the same as an existing method, direct access will call the method instead of the key value, use. L or. G instead.
3. All values will be automatically JSON encoded/decoded (the game has built-in json.lua V0.1.1).
4. The JSON string size of a single object should not exceed 1 billion bytes (approximately 953MB), otherwise Sqlite will report an error "string or blob too big," making it impossible to store.
5. When using Dump(), $0~9 in strings will be parsed as color codes by the console. The in-game console cannot display non-ASCII characters, and DEBUG log data will be truncated to prevent lag.
Original APIs
- Key: Must be a string in LuaDB API. If using the DB API, any Lua object encodable by json.lua is acceptable.
- Value: In LuaDB API, values must be boolean, number, or string. If using the DB API, values can be any Lua object encodable by json.lua (boolean, number, string, table).
Usage Examples
- Uses SQLite3 database named `kcd2db.db` in the game root
- Operation logs are stored in `kcd2db.log` in the game root
- Startup diagnostics now include module detection and database path information
- If launched with `-console`, INFO/WARN/ERROR logs also appear in the console by default
- DEBUG logs remain in `kcd2db.log` to avoid console spam
- Console log level can be changed with:
Important Notes
This mod heavily utilizes reverse-engineered game internals and may be affected by game updates. If experiencing crashes
after game updates, try removing the mod file (or rename `.asi` extension to disable).
Installation Requirements
1. Requires Ultimate ASI Loader (included in download).
2. Place the `.asi` file of this mod and the ASI loader (i.e., the `.dll` file) into the game's root directory (i.e., the folder containing `KingdomCome.exe`, located at `KingdomComeDeliverance2\Bin\Win64MasterMasterSteamPGO`).
Linux Users:
Proton/Wine: Add this to your Steam launch options:
WINEDLLOVERRIDES="dinput8=n,b" %command%(Thanks to extract95 for testing! See Proton/Wine setup guide for more details.)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
LuaDB - KCD2 Lua Persistence Module
What is this?
This is LuaDB, a Lua persistence module designed for KCD2 modders. It stores Lua data (including tables, booleans, numbers, and strings) in an SQLite database and offers two save modes:
1. Global – Data persists across all game saves (independent of the game save).
2. Local – Bound to the game save, data is associated with a specific game save file:
- Automatically saved when the game is saved.
- Automatically loaded when the game loads that save.
Why?
Before this mod, there was no simple and safe way to persistently store Lua data in KCD2. Modders had to rely on workarounds (like entity properties), which were unreliable or limited. This mod solves that by offering:
- Permanent storage (even after game restarts)
- Easy-to-use Lua API (both simple `Set/Get` and new object-oriented `DB.Create` interface)
- Safety The storage is external (saved in the kcd2db.db file), minimizing the risk of data corruption. In the worst case, the mod may become unusable after an update, which can be resolved by removing it and any dependent mods.
- Two storage modes (global or save-specific)
- Lua object support (any Lua object encodable by json.lua)
For Whom?
- Modders: Essential for mods needing persistent data.
- Regular Players: Only needed if a mod requires it (does nothing alone).
What Does This Do?
1. Stores Lua Data
- Uses DB.Create("ModName") to create a database object for your mod.
- Use the database object's `Set` method to store data. Data is automatically converted to JSON for storage and back to Lua objects when retrieved.
- Example: local myDB = DB.Create("MyAwesomeMod"); myDB.Set("player_health", 85.6)
2. Retrieves Data
- Use the database object's `Get` method to retrieve data.
- Example: local health = myDB.Get("player_health")
3. Debugging Tools
- LuaDB.Dump() – Prints all stored data to console
- Logs (kcd2db.log) and SQLite database (kcd2db.db)
4. Use Cases
- Saving mod settings (e.g., keybinds, configurations)
- Storing player progress (e.g., custom quest states)
- Persistent inventory/outfit data (e.g., saved outfits)
- Storing complex data structures like tables and arrays.
5. Sample Code
YourMod = YourMod or (function()
-- Make LuaDB an enhancement for mods, allowing users to opt for LuaDB to achieve persistence.
local db = LuaDB and DB and select(2, pcall(DB.Create,"YourMod"))
return {
version = "__VERSION__",
localData = db and db.L or {},
globalData = db and db.G or {}
}
end)()
function YourMod:Init()
local settingA = YourMod.localData.settingA
local settingB = YourMod.globalData.settingB
-- do something with settings
end
function YourMod:Save()
YourMod.localData.settingA = "valueA"
YourMod.globalData.settingB = { a = 1, b = 2 }
-- save settings
end
function YourMod:DoSomething()
local settingA = YourMod.localData.settingA
local settingB = YourMod.globalData.settingB
-- do something with settings
-- update settings if something changed
YourMod.localData.settingA = settingA
YourMod.globalData.settingB = settingB
end
YourMod:Init()+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Introduction
This module provides SQLite-based Lua data persistence for Kingdom Come: Deliverance II mod developers, supporting
two storage modes:
- Global Storage: Persists data across game saves (APIs end with "G") with automatic save/load
- Save-associated Storage: Data bound to game save slots with automatic save/load synchronization
The source code is located at Github-kcd2db
API Documentation
DB API Documentation
-- Create a database instance (recommended for most use cases)
local myDB = DB.Create("MyModNamespace") -- Use your mod name or unique identifier
-- Store Lua object (including nested tables)
myDB.Set("player_health", 85.6)
myDB:Set("has_dragon_sword", true) -- myDB allows both .call and :call syntax
-- Example with complex object
local config = {
difficulty = "hard",
weapons = {
sword = true,
bow = false
},
greeting = "hello world"
}
myDB.Set("player_config", config)
-- Retrieve data (automatically converts back to Lua objects)
local health = myDB.Get("player_health")
local config = myDB.Get("player_config")
-- Global APIs (Cross-save)
myDB.SetG("settings", {volume = 0.8, fullscreen = true})
local settings = myDB.GetG("settings") -- return table {volume = 0.8, fullscreen = true}- DB.Create("Your MOD") - Creates a namespace instance with the same API, automatically adding a prefix to all keys to reduce the likelihood of key conflicts. This method should always be preferred.
- DB.Get(key) - Get local key value
- DB.Set(key, value) - Set local key value
- DB.Del(key) - Delete local key value
- DB.Exi(key) - Check if local key exists
- DB.All() - Get all local key values
- DB.GetG(key) - Get global key value
- DB.SetG(key, value) - Set global key value
- DB.DelG(key) - Delete global key value
- DB.ExiG(key) - Check if global key exists
- DB.AllG() - Get all global key values
- DB.Dump() - Print all data
All methods support both . Call and : Call syntax, which can be selected according to personal preferences.
Quick Access
- DB("Your MOD") - Equivalent to DB.Create("Your MOD")
- DB.key / DB["key"] - Access local key value (If it has the same name as an existing method, it will cause a conflict, resulting in the return of the function instead of the data.)
- DB.L.key / DB.L["key"] - Access local key value, No conflict
- DB.G.key / DB.G["key"] - Access global key value, No conflict
Notes
1. Namespace names cannot contain colons, "namespace:" will be used as a key prefix in the database to isolate data from different mods.
2. When the key name is the same as an existing method, direct access will call the method instead of the key value, use. L or. G instead.
3. All values will be automatically JSON encoded/decoded (the game has built-in json.lua V0.1.1).
4. The JSON string size of a single object should not exceed 1 billion bytes (approximately 953MB), otherwise Sqlite will report an error "string or blob too big," making it impossible to store.
5. When using Dump(), $0~9 in strings will be parsed as color codes by the console. The in-game console cannot display non-ASCII characters, and DEBUG log data will be truncated to prevent lag.
Original APIs
-- Store data (automatically bound to current save)
LuaDB.Set(key, value)
-- Retrieve data
local value = LuaDB.Get(key)
-- Delete data
LuaDB.Del(key)
-- Check key existence
local exists = LuaDB.Exi(key)
-- Store global data
LuaDB.SetG(key, value)
-- Retrieve global data
local value = LuaDB.GetG(key)
-- Delete global data
LuaDB.DelG(key)
-- Check global key existence
local exists = LuaDB.ExiG(key)-- View all stored data in console
LuaDB.Dump()- Key: Must be a string in LuaDB API. If using the DB API, any Lua object encodable by json.lua is acceptable.
- Value: In LuaDB API, values must be boolean, number, or string. If using the DB API, values can be any Lua object encodable by json.lua (boolean, number, string, table).
Usage Examples
-- Using the new OOP interface (recommended)
local modDB = DB.Create("MyAwesomeMod")
modDB.Set("player_stats", {
health = 100,
stamina = 85.5,
inventory = {"sword", "shield", "potion"}
})
-- Original API examples
LuaDB.Set("player_health", 85.6)
LuaDB.SetG("global_kill_count", 42)
-- View data in console
LuaDB.Dump()- Uses SQLite3 database named `kcd2db.db` in the game root
- Operation logs are stored in `kcd2db.log` in the game root
- Startup diagnostics now include module detection and database path information
- If launched with `-console`, INFO/WARN/ERROR logs also appear in the console by default
- DEBUG logs remain in `kcd2db.log` to avoid console spam
- Console log level can be changed with:
-kcd2dbConsoleLog=debug|info|warn|error|offImportant Notes
This mod heavily utilizes reverse-engineered game internals and may be affected by game updates. If experiencing crashes
after game updates, try removing the mod file (or rename `.asi` extension to disable).