API

SimpleStore

An alternative DataStore library that focuses on simplicity over features.

This DataStore library internally relies on the latest version of DubitStore, so your data will inherit all of the constraints and benefits DubitStore provides.

Functions

GetPlayerStore

SimpleStore:GetPlayerStore(key: Player, datastoreName: string?): PlayerDataStore

Will get a PlaterDataStore instance based off of the parameter 'key' (key represents the Player!), optionally, if you would like to seperate player data from being in the same datastore, a second parameter is provided so you can define your own datastore.

This will create a new PlayerDataStore if the player has not been allocated a PlayerDataStore already.

Example Usage

local playerStore = SimpleStore:GetPlayerStore(player)

playerStore:Set({
    progression = {
        exp = 0,
        level = 1
    }
})
playerStore:SetKey("progression.level", 2)

PlayerDataStore

A simple wrapper for Player orientated datastores, this is the primary datastore object that developers will be interacting with, it's goal is to make the interaction between loading, saving and manipulating player datastores easier for developers.

PlayerDataStore's also rely on Session Locking, after 60 seconds, the Session Lock will be overwritten so that the players data isn't stuck forever. A players data is only released when Destroy has been called from the active server.

Properties

Changed

PlayerDataStore.Changed: Signal

---

IsNewPlayer

PlayerDataStore.IsNewPlayer: boolean

---

Id

PlayerDataStore.Id: number

---

Key

PlayerDataStore.Key: string

---

AutosaveId

PlayerDataStore.AutosaveId: string

Functions

:Get

PlayerDataStore:Get(fallback: any): (any, boolean)

Danger

This function yields.

Get's the players data from datastore, provides a fallback so if no data is found, the fallback is returned instead.

Example Usage

local defaultPlayerData = {
    progression = {
        experience = 0,
        level = 0
    }
}

local playerStore = SimpleStore:GetPlayerStore(player)

local playerData = playerStore:Get(defaultPlayerData)

Warning

There is no reconciliation happening in the background, meaning if a players data changes over time, there's no guarantee that the new data exists for older users.

One of the ways of getting reconciliation is to use DubitUtils package and use DubitUtils.Table.mergeDeep to update old data with new data values!

---

:GetKey

PlayerDataStore:GetKey(path: string, fallback: any): any

Danger

This function yields.

If the players data represents a table, you can use this function to get specific parts of that players data.

Example Usage

local defaultPlayerData = {
    progression = {
        experience = 0,
        level = 0
    }
}

local playerStore = SimpleStore:GetPlayerStore(player)

playerStore:Set(defaultPlayerData)

local experience = playerStore:GetKey("progression.experience", 0)
local level = playerStore:GetKey("progression.level", 1)

---

:Set

PlayerDataStore:Set(data: any): ()

Danger

This function yields.

Overwrite the current players data with a new set of data.

Example Usage

local playerStore = SimpleStore:GetPlayerStore(player)

playerStore:Set({ text = "Hello, World!" })

print(playerStore:GetKey("text")) --> Hello, World!

playerStore:Set({ text = "Hello, Something else!" })

print(playerStore:GetKey("text")) --> Hello, Something else!

---

:SetKey

PlayerDataStore:SetKey(path: string, data: any): ()

Danger

This function yields.

If the players data represents a table, you can use this function to overwrite specific parts of that players data.

Example Usage

local playerStore = SimpleStore:GetPlayerStore(player)

playerStore:Set({
    pets = {
        currentAnimal = {
            animalName = "Fluffy"
        }
    }
})

print(playerStire:GetKey("pets.currentAnimal.animalName")) --> Fluffy
playerStore:SetKey("pets.currentAnimal.animalName", "Joey")
print(playerStire:GetKey("pets.currentAnimal.animalName")) --> Joey

---

:Merge

PlayerDataStore:Merge(tableToBeMerged: { [any]: any }): ()

Danger

This function yields.

Merge the current player data with an input table, the input table takes priority so it'll overwrite keys in the current player data.

Example Usage

local playerStore = SimpleStore:GetPlayerStore(player)

playerStore:Set({
    text = "Hello, World!",
    boolean = true
})

print(playerStire:GetKey("text")) --> Hello, World!
print(playerStire:GetKey("boolean")) --> true

playerStore:Merge({
    text = "Hello, Something else!"
})

print(playerStire:GetKey("text")) --> Hello, Something else!
print(playerStire:GetKey("boolean")) --> true

---

:MergeKey

PlayerDataStore:MergeKey(path: string): ()

Danger

This function yields.

If the players data represents a table, you can use this function to merge tables under the player data together, the input table takes priority so it'll overwrite keys in the current player data.

Example Usage

local playerStore = SimpleStore:GetPlayerStore(player)

playerStore:Set({
    pets = {
        currentAnimal = {
            animalName = "Fluffy",
            animalLevel = 0,
            animalExperience = 0,
        }
    }
})

print(playerStore:GetKey("pets.currentAnimal.animalLevel")) --> 0
print(playerStore:GetKey("pets.currentAnimal.animalName")) --> Fluffy

playerStore:MergeKey("pets.currentAnimal", {
    animalLevel = 1
})

print(playerStore:GetKey("pets.currentAnimal.animalLevel")) --> 1
print(playerStore:GetKey("pets.currentAnimal.animalName")) --> Fluffy

---

:Update

PlayerDataStore:Update(transformFunction: ((serverData: any) -> any)): ()

Danger

This function yields.

Given a transform function, this function will call the transform function with the most up-to-date player data, and will save the return of the transform function.

Example Usage

local playerStore = SimpleStore:GetPlayerStore(player)

playerStore:Update(function(latestPlayerData)
    latestPlayerData.SomethingHasChnaged = true

    return latestPlayerData
end)

---

:UpdateKey

PlayerDataStore:UpdateKey(path: string, transformFunction: ((serverData: any) -> any)): ()

Danger

This function yields.

Given a transform function, this function will call the transform function with the most up-to-date player data, and will save the return of the transform function.

Example Usage

local playerStore = SimpleStore:GetPlayerStore(player)
--[[
    {
        pets = {
            currentAnimal = {
                animalName = "Fluffy",
                animalLevel = 0,
                animalExperience = 0,
            }
        }
    }
]]

playerStore:UpdateKey("pets.currentAnimal", function(currentAnimalData)
    currentAnimalData.animalName = "Joey"

    return currentAnimalData
end)

---

:Save

PlayerDataStore:Save(): ()

Danger

This function yields.

Save the player data to datastore.

---

:Destroy

PlayerDataStore:Destroy(): ()

Danger

This function yields.

Destroys this player data's instance on this server. Should be called when the player leaves the game.