LuaDB - KCD2 Lua

LuaDB - KCD2 Lua data persistence module provides KCD2 module developers with Lua data persistence function based on SQLite

LuaDB

🎯 **NOTE**: This is a resource tool for modders. Regular players only need to download this mod if other mods require it, otherwise it won't have any effect on you.

---

📥 Installation requirements

• Requires Ultimate ASI Loader (included in download package)
• Place the `.asi` file and ASI loader (i.e. `.dll` file) of this module into the root directory of the game

**Linux users**:

In Proton/Wine, add the following to the Steam launch options:

WINEDLLOVERRIDES="dinput8=n,b" %command%

---

🚀 What is LuaDB?

**LuaDB** is a Lua persistence module designed specifically for KCD2 module developers. It stores Lua data (including tables, booleans, numbers, and strings) in a SQLite database and provides two saving modes:

• **Global Storage** - data persisted across all game saves (independent of game saves)
• **Local Storage** - Bound to game saves, data is associated with specific game save files:
• Automatically **save** data when saving the game
• The game automatically **loads** data when loading archives

---

💡 Why do you need this mod?

Before this mod, there was no easy and safe way to persist Lua data in KCD2. Modders have to rely on workarounds (such as entity properties) that are unreliable or have limited functionality. This mod solves this problem with the following features:

• **Permanent Storage** (even after game restart)
• **Easy-to-use Lua API** (simple `Set/Get` and new object-oriented `DB.Create` interfaces)
• **Security** - Storage is external (saved in kcd2db.db file), minimizing the risk of data corruption
• **Two storage modes** (global or archive specific)
• **Lua object support** (any Lua object that can be encoded by json.lua)

---

👥 Who is it suitable for?

• **Mod Developer**: Essential tool for mods that need to persist data
• **Ordinary players**: Only need to install when the module requires it (used alone has no effect)

---

⚙️ Features

Storing Lua data

• Use `DB.Create("ModName")` to create a database object for your mod
• Use the `Set` method of the database object to store data
• Data is automatically converted to JSON when stored and back to Lua objects when retrieved

Retrieve data

• Retrieve data using the `Get` method of the database object

Debugging Tools

• `LuaDB.Dump()` - prints all stored data to the console
• Log (kcd2db.log) and SQLite database (kcd2db.db)

Usage scenarios

• Save **module settings** (such as key bindings, configuration)
• Store **player progress** (such as custom mission status)
• Persistent **inventory/outfit data** (such as saved outfits)
• Store **complex data structures** such as tables and arrays

---

📚 API Documentation

Recommended usage

```lua

--Create a database instance (recommended for most use cases)

local myDB = DB.Create("MyModNamespace") -- use your mod name or unique identifier

-- Store Lua objects (including nested tables)

myDB.Set("player_health", 85.6)

myDB:Set("has_dragon_sword", true) -- myDB supports .call and :call syntax

-- Retrieve data (automatically converted back to Lua object)

local health = myDB.Get("player_health")

```

Main method

• **DB.Create("Your MOD")** - Creates a namespace instance, automatically prefixing all keys to reduce key conflicts
• **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 the local key exists
• **DB.All()** - Get all local key values

Global API

• **DB.GetG(key)** - Get the global key value
• **DB.SetG(key, value)** - Set global key value
• **DB.DelG(key)** - delete global key value
• **DB.ExiG(key)** - Check if the global key exists
• **DB.AllG()** - Get all global key values

Quick access

• **DB("Your MOD")** - Equivalent to DB.Create("Your MOD")
• **DB.L.key** / **DB.L["key"]** - access local key …