Player Entity Structure

Bulletin Board
#1

Player Entity Structure by SPycre

This player entity structure allows you to easily manipulate players data in game. You can easily retrive any player data and manipulate it using pre-made functions.
This code can be combined with my Database Singleton, avalaible at TN Tech

Modules :

PlayerHandler

This module is used, to create, get and remove any player entity. Its the interface between the running server and the data.

Functions

  • PlayerHandler.Add(player : Player) : entity
Create a Player entity instance with the provided player 
( Automatically loads its data within the returned entity )
  • PlayerHandler.Get(player : Player) : entity
Get an existing Player entity with the provided player,
returns nil if the entity doesn't exist already
  • PlayerHander.Remove(player : Player) : boolean
Remove an existing Player entity with the provided player
It will also return the success of the operation.
( Automatically save data linked to the entity )

PlayerController

This module is used to store any large functions related with the player Entity.
By default I added the CharacterAdded function to this controller.

Functions

  • Controller.CharacterAdded(Entity, character : Model)
This function is built empty by default, for the user to customize it following
its needs.

Player

This module represents the entity. It contains the data related to the user, and the methods
you’ll have to use to manipulate those data, and the user.

Functions

  • Player.new(player : Player) : entity
    This function should always be called using PlayerHandler.Add(player : Player).
This function generates the entity from the provided player, returning entity
containing the data of the player and all of the methods to manipulate them.
( Automatically loads its data from datastore )
  • Entity:Destroy() : boolean
    This function should always be called using PlayerHandler.Remove(player : Player).
This function will remove the user data and saves them to the datastore. 
It will also return the success of the operation.
( Automatically save its data to datastore )
  • Entity:setMoney(value : number)
This function should always be used to update the player's money. Note that you 
can modify the function to add more operations, such as updating the user's
interface.
  • Entity:setDistance(value : number)
This function should always be used to update the player's distance. Note that
you can modify the function to add more operations, such as updating the user's
interface.
  • Entity:addVehicle(value : string)
This function should always be used to add new vehicles in the player's inventory.
This function will add the data { 0, 100} for distance and fuel at the index
"value" ( as vehicle name ) inside the player's inventory. Such as :
self.vehicles["Bus"] = { 0, 100}

Example

Below is a little example of what a server script could look like for a game to load and save player data. And with the possibility to spawn vehicles from the user’s inventory.
Not that this code won’t work alone even if you setup the Entity Structure, but it should serve as an example of what a very basic game could look like.

local PlayerHandler = require(game.ServerStorage.Server.Handler.PlayerHandler)

game.Players.PlayedAdded:Connect(function(player : Player)

    local entity = PlayerHandler.Add(player) -- Create the entity and load the player's data inside of it
    entity:setMoney( entity.money + 50 ) -- Gives 50 money to the user
    entity:setDistance( entity.distance + 50 ) -- Gives 50 distance to the user
    entity:addVehicle("Basic Car") -- Add the vehicle named "Basic Car" in the user's inventory

end)

game.ReplicatedStorage.Remotes.SpawnVehicleRemote.OnServerEvent:Connect(function(player : Player, vehicle_name : string)

    local entity = PlayerHandler.Get(player) -- Retrieve the existing entity of the provided user
    if entity.vehicles[vehicle_name] ~= nil then -- Check if player own the vehicle
        -- Player owns vehicle, spawn the vehicle
    else
        -- Player don't own the vehicle, do something else
    end

end)

game.Players.PlayerRemoving:Connect(function(player : Player)

    local success = PlayerHandler.Remove(player) -- removes the player's entity and save its data
    if (success) then -- Check if data saved successfully
        print("Saved successfully")
    else
        print("Didn't save successfully")
    end

end)

Combine with Database Singleton

This structure can be combined with my database singleton module for safer loading and saving of user’s data.

How to setup Database Singleton with the structure

  • Simply move the Database module inside the structure folder Server>Common. Which should be found at game.ServerStorage.Server.Common
  • Once done, inside of the “Player” module, you can initialize the Database module using :
local Database = require(game.ServerStorage.Server.Common.Database)("datastore_name")
  • Then, inside of Player.new() to load data, replace the current “local success, data…” line to :
local success, data = Database:Load(self.key)
  • And finally, inside of Player:Destroy() to save data, replace the current “local success, data…” line to :
local success, data = Database:Save(self.key, data)
SPycre's Scripts Catalog for TN Tech