Getting Started

This guide will walk you through the basics of Coppermind.

---

📦 Installation

Manual

1. Download the latest release from GitHub
2. Add the src folder to your project
3. Require the module in your code

---

📋 Defining a Schema

Schemas define the structure and default values for your data. Start by registering one:

local Coppermind = require(path.to.Coppermind)

local PlayerSchema = Coppermind.registerSchema({
    name = "PlayerData",
    dataTemplate = {
        coins = 0,
        gems = 0,
        inventory = {},
        stats = {
            level = 1,
            xp = 0,
        },
    },
    migrations = {},
})

Schema Properties

Property	Type	Description
name	string	Unique identifier for the schema (used as DataStore name)
dataTemplate	table	Default values for new data
migrations	{function}	Array of migration functions for schema evolution

---

📂 Loading a Store

A store represents a single data entry (e.g., one player's data):

local store = Coppermind.loadStore(PlayerSchema, tostring(player.UserId), {
    sessionLocked = true,  -- Prevent other servers from loading this data
    autoSave = 60,         -- Auto-save every 60 seconds
})

Configuration Options

Option	Type	Default	Description
sessionLocked	boolean?	false	Lock data to this server session
autoSave	number?	nil	Auto-save interval in seconds

---

⏳ Waiting for Data

Stores load asynchronously. Wait for the data to be ready:

-- Using the onReady event
store.onReady:Connect(function(store)
    print("Data is ready!")
end)

-- Or check the state
if store.state == "READY" then
    -- Data is available
end

Store States

State	Icon	Description
LOADING	🔄	Data is being loaded from DataStore
READY	✅	Data is loaded and available
SAVING	💾	Data is being saved
UNLOADING	📤	Store is being unloaded
UNLOADED	⬜	Store has been unloaded
ERROR	❌	An error occurred
SESSION_LOCKED	🔒	Another server has locked this data

---

📖 Reading Data

Use getData to read the current data:

local data = Coppermind.getData(PlayerSchema, tostring(player.UserId))

if data then
    print("Coins:", data.coins)
    print("Level:", data.stats.level)
end

Data is Immutable

The data returned by getData is frozen and cannot be modified directly. Use updateData to make changes.

---

✏️ Updating Data

Use updateData to modify data safely:

Mutation Style

Modify the data directly and return nil:

Coppermind.updateData(PlayerSchema, tostring(player.UserId), function(data)
    data.coins += 100
    data.stats.xp += 50
    table.insert(data.inventory, "sword")
    return nil  -- Return nil to apply mutations
end)

Replacement Style

Return a new data table to replace the entire data:

Coppermind.updateData(PlayerSchema, tostring(player.UserId), function(data)
    return {
        coins = data.coins + 100,
        gems = data.gems,
        inventory = data.inventory,
        stats = {
            level = data.stats.level,
            xp = data.stats.xp + 50,
        },
    }
end)

---

💾 Saving Data

Manual Save

Coppermind.saveStore(PlayerSchema, tostring(player.UserId))

Auto-Save

Configure auto-save when loading the store:

local store = Coppermind.loadStore(PlayerSchema, key, {
    autoSave = 60,  -- Save every 60 seconds
})

---

📤 Unloading a Store

Always Unload

Always unload stores when they're no longer needed to save data and release session locks!

game.Players.PlayerRemoving:Connect(function(player)
    Coppermind.unloadStore(PlayerSchema, tostring(player.UserId))
end)

---

📡 Global Events

Coppermind provides global events for monitoring all stores:

-- Fires when any store is loaded
Coppermind.onLoaded:Connect(function(store)
    print("Store loaded:", store.key)
end)

-- Fires when any store is saved
Coppermind.onSaved:Connect(function(store)
    print("Store saved:", store.key)
end)

-- Fires when any store encounters an error
Coppermind.onError:Connect(function(store, errorMessage)
    warn("Store error:", store.key, errorMessage)
end)

-- Fires when any store is unloaded
Coppermind.onUnloaded:Connect(function(store)
    print("Store unloaded:", store.key)
end)

---

🎯 Next Steps

Guide	Description
📋 Schemas	Data templates and type safety
📂 Stores	Session locking and store management
✏️ Data Operations	Reading and updating data
🔄 Migrations	Evolving your data schema
💱 Transactions	Atomic operations across stores
🧪 Testing	Mock mode and testing patterns