DataStore API

DataStore is a persistent, per-block key-value store. Each DataStore block holds its own independent data identified by a stable UUID that never changes, even if the block is moved within an entity. Data is written to disk on every mutation and survives server restarts.

Access is controlled by physically placing permission module blocks adjacent to the DataStore in the world.

Access levels

Adjacent block

Who can access

None

Only computers on the same entity as the DataStore

FACTION_PERMISSION_MODULE (ID 936)

Any computer in the same faction as the DataStore’s owning entity

PUBLIC_PERMISSION_MODULE (ID 346)

Any computer, regardless of faction

PASSWORD_PERMISSION_MODULE (Logiscript)

Any computer whose faction has called auth(password) successfully

Multiple permission modules can coexist. The most permissive adjacent module wins. Access is checked on every call — changing adjacent blocks takes effect immediately without restarting the script.

Typical usage

-- Wrap the DataStore block adjacent to this computer
local ds = console.getBlock():getEntity():getBlockAt(vec3i(1, 0, 0)):wrapAs("datastore")

-- If protected by a PASSWORD_PERMISSION_MODULE, authenticate first
if ds:getAccessLevel() == "password" then
    assert(ds:auth("mySecret"), "Wrong password")
end

-- Basic read/write
ds:set("status", "online")
print(ds:getValue("status"))  -- "online"

-- Delete a key
ds:delete("status")

-- List keys with a prefix
local keys = ds:keys("sensor/")
for i = 1, #keys do
    print(keys[i], ds:get(keys[i]))
end

Reference

  • auth(password: String) Verifies password against any adjacent PASSWORD_PERMISSION_MODULE blocks. On success, registers the computer’s faction in the auth manager for 5 minutes, granting access to this DataStore and any other blocks protected by the same module. Returns true if at least one adjacent module accepted the password.

  • getValue(key: String) Returns the value stored at key, or nil when absent.

  • set(key: String, value: String) Stores value under key. Pass nil as the value to delete the key.

  • delete(key: String) Removes key. Returns true when a key was actually present.

  • has(key: String) Returns true when key exists in the store.

  • keys() Returns a table (array) of all keys in this store.

  • keys(prefix: String) Returns a table (array) of all keys that begin with prefix.

  • size() Returns the total number of keys currently stored.

  • getStoreId() Returns the persistent UUID string that identifies this block’s data file.

  • getOwnerFactionId() Returns the integer faction ID of the entity this DataStore is installed on.

  • getAccessLevel() Returns the effective access level as a string: "public", "faction", "password", or "entity".

Limits

Item

Limit

Key length

256 characters

Value length

65 536 characters (64 KiB)

Keys per store

10 000

Exceeding any limit raises a Lua error on the offending set() call.

Notes

  • Data is per-block: each DataStore block has its own independent key-space. Place multiple blocks for isolated namespaces on the same ship.

  • The block’s UUID is assigned the moment it is placed and never changes, so data is not lost if blocks are rearranged within an entity.

  • Data is stored at <worldData>/datastores/<uuid>.json.

  • Faction ID 0 is the “no faction” / wilderness faction. Cross-faction access via FACTION_PERMISSION_MODULE is denied when either the DataStore or the accessing computer has faction ID 0.