Installation

Quick Start (Recommended)

CRITICAL SETUP REQUIREMENT

⚠️ YOU MUST CALL PlayerState.Init(player) ON THE SERVER! PlayerState will not work without this essential step. See the Setup Guide for the required code.

TIP

The Roblox model includes ALL dependencies! If you're using the PlayerState Roblox model and haven't moved the included modules around, you do NOT need to manually install anything - it works out of the box!

Get PlayerState Model

Download the complete PlayerState model from Roblox (includes ProfileStore and Replica dependencies):

• PlayerState Model on Roblox (Complete package with all dependencies)

What's Included

PlayerState Server & Client modules
ProfileStore dependency
Replica dependency
Example DefaultData schema
Ready-to-use setup

Manual Installation (Advanced)

Click to expand manual installation

If you prefer to install components separately or are building from source, you'll need these dependencies:

Required Dependencies

1. ProfileStore - For data persistence

   • Download from: ProfileStore on Roblox
   • Will be placed in ReplicatedStorage when obtained via Roblox model

2. Replica - For real-time synchronization

   • Download from: Replica on GitHub
   • Will be placed within PlayerState when obtained via Roblox model. This is default, if moved around, you will need to modify the Server and Client modules.

Important: Only manually install dependencies if you're NOT using the Roblox model or if you've moved modules from their default locations.

Module Placement

PlayerState modules can be placed anywhere in your project. The location depends on your project structure and preferences.

NOTE

The examples below show common patterns, but feel free to organize however works best for your game!

Recommended Structure (Optional)

ReplicatedStorage
└── Libraries (or any folder name you prefer)
    └── PlayerState
        ├── PlayerStateServer (ServerScriptService or ServerStorage)
        ├── PlayerStateClient (ReplicatedStorage)
        └── DefaultData

Alternative Placements

You can place the modules anywhere that makes sense for your project:

ServerStorage
└── Modules
    └── PlayerStateServer

ReplicatedStorage  
└── Shared
    ├── PlayerStateClient
    └── DefaultData

Or even:

ServerScriptService
└── PlayerStateServer

StarterPlayer.StarterPlayerScripts
└── PlayerStateClient

ReplicatedStorage
└── DefaultData

File Setup

The PlayerState model comes with all modules included and pre-configured. You can use it immediately or reorganize files to match your project structure.

What's Included

When you get the model, you'll find:

• PlayerStateServer - Server-side module
• PlayerStateClient - Client-side module
• DefaultData - Data schema template
• PlayerStateConfig - Configuration settings
• ProfileStore & Replica - Dependencies

Default Structure

The model uses this structure by default:

PlayerState (Model)
├── PlayerStateServer
├── PlayerStateClient
├── DefaultData
├── PlayerStateConfig
└── Libraries
    ├── ProfileStore
    └── Replica

Quick Start (Recommended)

For immediate use: Simply place the entire PlayerState folder in ReplicatedStorage and start using it:

-- Server script
local PlayerState = require(game.ReplicatedStorage.PlayerState.PlayerStateServer)

-- Client script  
local PlayerState = require(game.ReplicatedStorage.PlayerState.PlayerStateClient)

Custom Organization (Optional)

If you prefer a different structure, you can move modules around. Just update the require paths at the top of each module:

Example: Moving PlayerStateServer to ServerScriptService

-- In PlayerStateServer, update the require paths:
local DefaultData = require(game.ReplicatedStorage.PlayerState.DefaultData)
local ProfileService = require(game.ReplicatedStorage.PlayerState.Libraries.ProfileStore)
local ReplicaServer = require(game.ReplicatedStorage.PlayerState.Libraries.Replica.ReplicaServer)

Path Examples

Here are some common path adjustments based on different placements:

If you use ReplicatedStorage.Modules.PlayerState:

-- Server module requires:
local DefaultData = require(game.ReplicatedStorage.Modules.PlayerState.DefaultData)

-- Client module requires:  
local DefaultData = require(script.Parent.DefaultData)

If you use ReplicatedStorage.Shared:

-- Server module requires:
local DefaultData = require(game.ReplicatedStorage.Shared.DefaultData)

-- Client module requires:
local DefaultData = require(game.ReplicatedStorage.Shared.DefaultData)

If dependencies are in different locations:

-- Example: ProfileStore in ServerStorage, Replica in ReplicatedStorage.Libraries
local ProfileService = require(game.ServerStorage.ProfileStore)
local ReplicaServer = require(game.ReplicatedStorage.Libraries.Replica.ReplicaServer)

Configuration

PlayerState uses a separate PlayerStateConfig module for configuration:

-- PlayerStateConfig.lua
local Config = {
    Server = {
        Profile = {
            Key = "PlayerData",
            Template = DefaultData,
        },
        DataStore = {
            Name = "PlayerData_ALPHA_0.02",  -- Change this for different versions
            Scope = "Production",           -- "Production" or "Testing"
        },
    },
    Client = {
        CacheDuration = 0.1,
        MaxCacheSize = 1000,
    },
}

Configuration Options

• Server.DataStore.Name: Change this when you need to reset player data or for different game versions
• Server.DataStore.Scope: Use "Testing" for development, "Production" for live games
• Server.Profile.Key: Base key for ProfileStore (usually keep as "PlayerData")
• Client settings: Cache duration and size limits for performance tuning

TIP

See the Setup Guide for complete configuration documentation and examples.

Version Information

This is PlayerState V1 - The foundation is solid and production-ready, but I'm actively developing new features and improvements based on community feedback and real-world usage. Updates are frequent with bug fixes and enhancements.

Found an issue or have suggestions? Please report them - your feedback shapes future versions!

Verification

After installation, test the setup with the correct require paths:

-- In a server script - adjust path to your PlayerStateServer location
local PlayerState = require(game.ServerScriptService.PlayerStateServer) -- Adjust this path

game.Players.PlayerAdded:Connect(function(player)
    local success = PlayerState.Init(player)
    if success then
        print("PlayerState initialized for", player.Name)
    end
end)

-- In a client script - adjust path to your PlayerStateClient location
local PlayerState = require(game.ReplicatedStorage.PlayerStateClient) -- Adjust this path

local coins = PlayerState.Get("Coins")
print("Player coins:", coins)

Next Steps

• Setup Guide - Initialize PlayerState in your game
• API Reference - Learn the available functions
• Examples - See common usage patterns