Data Library

Data persistence, serialization, and management system for the Lilia framework.

---

Overview

The data library provides comprehensive functionality for data persistence, serialization, and management within the Lilia framework. It handles encoding and decoding of complex data types including vectors, angles, colors, and nested tables for database storage. The library manages both general data storage with gamemode and map-specific scoping, as well as entity persistence for maintaining spawned entities across server restarts. It includes automatic serialization/deserialization, database integration, and caching mechanisms to ensure efficient data access and storage operations.

---

lia.data.encodetable(value)

Encode vectors/angles/colors/tables into JSON-safe structures.

Before persisting data to DB or file storage.

Parameters:

any value

Returns:

any Encoded representation.

Example Usage:

    local payload = lia.data.encodetable({
        pos = Vector(0, 0, 64),
        ang = Angle(0, 90, 0),
        tint = Color(255, 0, 0)
    })

---

lia.data.decode(value)

Decode nested structures into native types (Vector/Angle/Color).

After reading serialized data from DB/file.

Parameters:

any value

Returns:

any Decoded value with deep conversion.

Example Usage:

    local decoded = lia.data.decode(storedJsonTable)
    local pos = decoded.spawnPos

---

lia.data.serialize(value)

Serialize a value into JSON, pre-encoding special types.

Before writing data blobs into DB columns.

Parameters:

any value

Returns:

string JSON string.

Example Usage:

    local json = lia.data.serialize({pos = Vector(1,2,3)})
    lia.db.updateSomewhere(json)

---

lia.data.deserialize(raw)

Deserialize JSON/pon or raw tables back into native types.

After fetching data rows from DB.

Parameters:

string|table|any raw

Returns:

any

Example Usage:

    local row = lia.db.select(...):get()
    local data = lia.data.deserialize(row.data)

---

lia.data.decodeVector(raw)

Decode a vector from various string/table encodings.

While rebuilding persistent entities or map data.

Parameters:

any raw

Returns:

Vector|any

Example Usage:

    local pos = lia.data.decodeVector(row.pos)
    if isvector(pos) then ent:SetPos(pos) end

---

lia.data.decodeAngle(raw)

Decode an angle from string/table encodings.

During persistence loading or data deserialization.

Parameters:

any raw

Returns:

Angle|any

Example Usage:

    local ang = lia.data.decodeAngle(row.angles)
    if isangle(ang) then ent:SetAngles(ang) end

---

lia.data.set(key, value, global, ignoreMap)

Persist a key/value pair scoped to gamemode/map (or global).

To save configuration/state data into the DB.

Parameters:

string key

any value

boolean global optional

boolean ignoreMap optional

Returns:

string Path prefix used for file save fallback.

Example Usage:

    lia.data.set("event.active", true, false, false)

---

lia.data.delete(key, global, ignoreMap)

Delete a stored key (and row if empty) from DB cache.

To remove saved state/config entries.

Parameters:

string key

boolean global optional

boolean ignoreMap optional

Returns:

boolean

Example Usage:

    lia.data.delete("event.active")

---

lia.data.loadTables()

Load stored data rows for global, gamemode, and map scopes.

On database ready to hydrate lia.data.stored cache.

Example Usage:

    hook.Add("DatabaseConnected", "LoadLiliaData", lia.data.loadTables)

---

lia.data.loadPersistence()

Ensure persistence table has required columns; add if missing.

Before saving/loading persistent entities.

Returns:

promise

Example Usage:

    lia.data.loadPersistence():next(function() print("Persistence columns ready") end)

---

lia.data.savePersistence(entities)

Save persistent entities to the database (with dynamic columns).

On PersistenceSave hook/timer with collected entities.

Parameters:

table entities Array of entity data tables.

Returns:

promise|nil

Example Usage:

    hook.Run("PersistenceSave", collectedEntities)

---

lia.data.loadPersistenceData(callback)

Load persistent entities from DB, decode fields, and cache them.

On server start or when manually reloading persistence.

Parameters:

function callback optional Invoked with entities table once loaded.

Returns:

promise

Example Usage:

    lia.data.loadPersistenceData(function(entities)
        for _, entData in ipairs(entities) do
            -- spawn logic here
        end
    end)

---

lia.data.get(key, default)

Fetch a stored key from cache, deserializing strings on demand.

Anywhere stored data is read after loadTables.

Parameters:

string key

any default

Returns:

any

Example Usage:

    local eventData = lia.data.get("event.settings", {})

---

lia.data.getPersistence()

Return the cached list of persistent entities (last loaded/saved).

For admin tools or debug displays.

Returns:

table

Example Usage:

    PrintTable(lia.data.getPersistence())

---

lia.data.addEquivalencyMap(map1, map2)

Register an equivalency between two map names (bidirectional).

To share data/persistence across multiple map aliases.

Parameters:

string map1

string map2

Example Usage:

    lia.data.addEquivalencyMap("rp_downtown_v1", "rp_downtown_v2")

---

lia.data.getEquivalencyMap(map)

Resolve a map name to its equivalency (if registered).

Before saving/loading data keyed by map name.

Parameters:

string map

Returns:

string

Example Usage:

    local canonical = lia.data.getEquivalencyMap(game.GetMap())

---