Data¶
Data persistence helpers for Lilia serialized data storage, map equivalency, entity persistence, and runtime data lookup.
Overview
lia.data.encodetable(value)View Source
Purpose
Converts values into JSON-safe data before storage.
Realm
Server
Parameters
any value The value to encode. Vectors, angles, colors, and nested tables are converted recursively.
Returns
any The encoded value. Vectors become `{x, y, z}`, angles become `{p, y, r}`, colors become `{r, g, b, a}`, and tables are encoded recursively.
Example Usage
local encoded = lia.data.encodetable(Vector(1, 2, 3))
print(util.TableToJSON(encoded))
lia.data.decode(value)View Source
Purpose
Recursively restores encoded data values into their Garry's Mod types when possible.
Realm
Server
Parameters
any value The value to decode. Tables containing vector, angle, or color fields are converted recursively.
Returns
any The decoded value, including restored Vector, Angle, Color, or nested table values when recognized.
Example Usage
local decoded = lia.data.decode({x = 1, y = 2, z = 3})
print(decoded)
lia.data.serialize(value)View Source
Purpose
Serializes a value into a JSON string suitable for storage.
Realm
Server
Parameters
any value The value to encode and serialize.
Returns
string A JSON string containing the encoded value. Primitive values are wrapped in a `value` field.
Example Usage
local raw = lia.data.serialize(Color(255, 200, 150))
file.Write("example.json", raw)
lia.data.deserialize(raw)View Source
Purpose
Deserializes stored JSON or PON data and restores encoded Garry's Mod types.
Realm
Server
Parameters
string|table|any raw The stored value to deserialize. Strings are decoded as JSON first, then PON as a fallback.
Returns
any|nil The decoded value, or nil when no value could be decoded.
Example Usage
local value = lia.data.deserialize(rawData)
print(value)
lia.data.decodeVector(raw)View Source
Purpose
Attempts to decode a stored value into a Vector.
Realm
Server
Parameters
string|table|Vector|any raw The raw vector data to decode. JSON strings, PON strings, tables, and common vector string formats are supported.
Returns
Vector|any|nil A Vector when decoding succeeds, nil for nil input, or the original decoded value when it cannot be converted.
Example Usage
local pos = lia.data.decodeVector("[1 2 3]")
print(pos)
lia.data.decodeAngle(raw)View Source
Purpose
Attempts to decode a stored value into an Angle.
Realm
Server
Parameters
string|table|Angle|any raw The raw angle data to decode. JSON strings, PON strings, tables, and common angle string formats are supported.
Returns
Angle|any|nil An Angle when decoding succeeds, nil for nil input, or the original decoded value when it cannot be converted.
Example Usage
local ang = lia.data.decodeAngle("{0 90 0}")
print(ang)
lia.data.set(key, value, global, ignoreMap)View Source
Purpose
Stores a key/value pair in memory and writes it to the resolved data-file scope.
Realm
Server
Parameters
string key The data key to store.
any value The value to store. Supported typed values are encoded before writing.
boolean global optional When true, stores the value in the global/global scope.
boolean ignoreMap optional When true, stores the value in the gamemode/global scope instead of the current map scope.
Returns
string The resolved storage directory in `gamemode/map/` format.
Example Usage
lia.data.set("spawnPoint", Entity(1):GetPos())
lia.data.set("globalSetting", true, true)
lia.data.delete(key, global, ignoreMap)View Source
Purpose
Deletes a stored key from memory and removes its scoped data file when it exists.
Realm
Server
Parameters
string key The data key to delete.
boolean global optional When true, deletes the key from the global/global scope.
boolean ignoreMap optional When true, deletes the key from the gamemode/global scope instead of the current map scope.
Returns
boolean Always returns true after clearing the cached value and attempting file removal.
Example Usage
lia.data.delete("spawnPoint")
lia.data.loadTables()View Source
Purpose
Loads stored key/value data from global, gamemode-global, and current-map data scopes.
Realm
Server
Returns
nil This function does not return a value.
Example Usage
lia.data.loadTables()
lia.data.loadPersistence()View Source
Purpose
Ensures the persistence database table contains the base persistence columns.
Realm
Server
Returns
Deferred A database deferred chain for the column checks and additions.
Example Usage
lia.data.loadPersistence():next(function()
print("Persistence columns are ready")
end)
lia.data.savePersistence(entities)View Source
Purpose
Saves persistent entity data for the current gamemode and equivalent map.
Realm
Server
Parameters
table entities An array of entity persistence records. Each record should include base fields such as `class`, `pos`, `angles`, and `model`; extra fields are added as dynamic columns.
Returns
nil This function does not return a value.
Example Usage
lia.data.savePersistence({
{class = "prop_physics", pos = pos, angles = ang, model = model}
})
lia.data.loadPersistenceData(callback)View Source
Purpose
Loads persistent entity data for the current gamemode and equivalent map.
Realm
Server
Parameters
function callback optional Optional callback called with the loaded entity persistence records after the database query finishes.
Returns
nil This function does not return a value.
Example Usage
lia.data.loadPersistenceData(function(entities)
PrintTable(entities)
end)
lia.data.get(key, default)View Source
Purpose
Retrieves a cached data value by key.
Realm
Server
Parameters
string key The data key to retrieve.
any default The fallback value returned when the key is not cached.
Returns
any The stored value when present, otherwise the provided default value.
Example Usage
local spawnPoint = lia.data.get("spawnPoint", Vector(0, 0, 0))
lia.data.getPersistence()View Source
Purpose
Returns the currently cached persistence data.
Realm
Server
Returns
table The cached persistence records, or an empty table when none are loaded.
Example Usage
for _, data in ipairs(lia.data.getPersistence()) do
print(data.class)
end
lia.data.addEquivalencyMap(map1, map2)View Source
lia.data.getEquivalencyMap(map)View Source
Purpose
Returns the equivalent map name for a registered map, or the original map name when no equivalent exists.
Realm
Shared
Parameters
string map The map name to resolve.
Returns
string The registered equivalent map name, or the original map name.
Example Usage
local map = lia.data.getEquivalencyMap(game.GetMap())
Hooks
Library-specific hooks documented for this library.