Extending Players

BDSC supports dynamic, runtime-safe extension of player objects with custom data and methods. This lets you build modular logic without touching the core.

Add Data

Adds custom data to the player. Optionally replicated to the client.

Example

player:add_data("stats", { health = 100, stamina = 50 }, true)

Parameters

stats – key name for the data entry.
{ health = 100, stamina = 50 } – table to store.
true – replicate to client (optional).

Add Methods

Attach custom methods that can later be executed via run_method.

Example

player:add_method("stats", "get_health", function(self)
    local stats = self:get_data("stats")
    return stats and stats.health or 0
end)

Usage

player:run_method("stats", "get_health")

Update Data

Modify an existing data block and optionally sync it.

Example

local stats = player:get_data("stats")
stats.health = stats.health - 10
player:set_data("stats", stats, true)

Remove Data

Removes a data key.

Example

player:remove_data("job")

Sync Data

Force a sync of all replicated data to the client.

Example

player:sync_data()

Dump All Data

Logs all currently stored player data.

Example

local data = player:get_data()
for k, v in pairs(data) do
    print(k .. ": " .. json.encode(v))
end

Here’s a concise section explaining how the on_save and on_destroy methods work when registered via namespaces:

Lifecycle Hooks

BDSC supports namespace-specific lifecycle methods that automatically run when certain player events occur.

These methods are defined under a specific namespace using add_method and are called internally during key moments in the player's lifecycle.

Supported Hooks

Hook Name

Description

on_save

Called when player:save() is triggered (e.g., on disconnect or manually).

on_destroy

Called when player:destroy() is triggered (e.g., on player drop).

How It Works

When a lifecycle event runs, BDSC will automatically check each namespace for these methods and call them in order.

Example

player:add_method("stats", "on_save", function(self)
    print("Saving stats for player:", self.meta.username)
end)

player:add_method("inventory", "on_destroy", function(self)
    print("Cleaning up inventory for:", self.meta.username)
end)

You do not need to manually call these - BDSC will handle them as long as they are added under a namespace using add_method(namespace, "on_save" | "on_destroy", fn).

Avoid long-running operations inside these hooks — keep them lightweight for stability.

Missing Method Safety

Calling a non-existent method will return nil.

Example

local result = player:run_method("missing")
print("Result:", result or "nil")

No Internal Access

Only the meta table is exposed. All other functionality data, methods, syncing - must be accessed via the public API.

Direct access to _extensions._data, _extensions._methods, or other internals is not possible and never required.

Quick Example

Below is a minimal, self-contained example that demonstrates how to create a player object and extend it externally using basic commands.

This includes:

Adding a stats data block
Defining custom methods (like get_health)
Syncing data to the client
Simulating damage
Handling save logic

local core = exports.bdsc:import()

-- Create and initialize a new player
RegisterCommand("make", function(src)
    local player = core.create_player(src)
    if not player then print("Failed to create player") return end

    -- Add initial stats
    player:add_data("stats", {
        health = 100,
        stamina = 50
    }, true)

    -- Add method to retrieve health
    player:add_method("stats", "get_health", function(self)
        local stats = self:get_data("stats")
        return stats and stats.health or 0
    end)

    -- Add save lifecycle method
    player:add_method("stats", "on_save", function()
        print("saving player stats")
    end)

    print("Player created and methods attached.")
end, false)

-- Check player health
RegisterCommand("hp", function(src)
    local player = core.get_player(src)
    if not player then print("No player found.") return end

    local hp = player:run_method("stats", "get_health")
    print("Health:", hp)
end, false)

-- Apply damage to the player
RegisterCommand("damage", function(src, args)
    local player = core.get_player(src)
    if not player then print("No player found.") return end

    local amount = tonumber(args[1]) or 10
    local stats = player:get_data("stats")
    stats.health = stats.health - amount

    player:set_data("stats", stats, true)
    print("Damaged player for", amount)
end, false)

Tip: Every player object supports runtime extension. You can safely add new data or methods at any point — even after creation.

Last updated 1 day ago