Summary

This page will summarize the previous guides and create a basic project setup for replecs.

Create your world and require replecs. This is to avoid creating a world before requiring replecs.
- Directorysrc
  - Directoryshared
    world.lua
- world.luau
local jecs = require("@pkg/jecs") require("@pkg/replecs") return jecs.world()

Create a Replicator in shared and re-export the client and server entries:

Directorysrc
- Directoryclient
  - replicator.lua
- Directoryserver
  - replicator.lua
- Directoryshared
  - replicator.lua
  - world.lua

local replecs = require("@pkg/replecs")
local world = require("@shared/world")

return replecs.create(world)

local replicator = require("@shared/replicator")

return replicator.server

local replicator = require("@shared/replicator")

return replicator.client

Create your components and mark them as shared:

Directorysrc
- Directoryclient
  - replicator.lua
- Directoryserver
  - replicator.lua
- Directoryshared
  - components.lua
  - replicator.lua
  - world.lua

components.luau

local jecs = require("@pkg/jecs")
local replecs = require("@pkg/replecs")
local world = require("@shared/world")

local components = {
    position = world:component(),
    velocity = world:component(),
    player = world:component(),
    health = world:component(),
    alive = world:tag(),
}

for name, component in components do
    world:add(component, replecs.shared)
    world:set(component, jecs.Name, name)
end

Initialize replicators. The client requests the full state of the world, the server queues the player and activates it inside the replication system in the next step:

Directorysrc
- Directoryclient
  - replicator.lua
  - init.client.lua
- Directoryserver
  - pending-players.lua
  - replicator.lua
  - init.server.lua
- Directoryshared
  - components.lua
  - replicator.lua
  - world.lua

local replicator = require("@server/replicator")
local remotes_server = require("@shared/remotes").server
local pending_players = require("@server/pending-players")

replicator:init()

-- players are activated by the replecs-server system, not here
remotes_server.request_full:on(function(player)
    table.insert(pending_players, player)
end)

local replicator = require("@client/replicator")
local remotes_client = require("@shared/remotes").client

replicator:init()

remotes_client.receive_full:on(function(buf, variants)
    replicator:apply_full(buf, variants)
end)
remotes_client.request_full:fire()

-- players waiting for the full state of the world
local pending_players: { Player } = {}

return pending_players

Create systems to send updates and unreliable values. Pending players are activated right before collect_updates, any change made between get_full and collect_updates would be silently dropped for that player:

Directorysrc
- Directoryclient
  - Directorysystems
    replecs-client.lua
  - replicator.lua
- Directoryserver
  - Directorysystems
    replecs-server.lua
  - pending-players.lua
  - replicator.lua
- Directoryshared
  - Directoryutils
    collect.lua
    interval.lua
  - components.lua
  - replicator.lua
  - world.lua

local replicator = require("@server/replicator")
local pending_players = require("@server/pending-players")
local interval = require("@utils/interval")

local updates_interval = interval(1 / 20)
local unreliables_interval = interval(1 / 30)

function replecs_server()
    if updates_interval() then
        -- activate new players right before collecting updates
        for _, player in pending_players do
            if not player.Parent then
                continue
            end
            replicator:mark_player_ready(player)
            local buf, variants = replicator:get_full(player)
            remotes_server.receive_full:fire(player, buf, variants)
        end
        table.clear(pending_players)

        for player, buf, variants in replicator:collect_updates() do
            remotes_server.send_updates:fire(player, buf, variants)
        end
    end

    if unreliables_interval() then
        for player, buf, variants in replicator:collect_unreliable() do
            remotes_server.send_unreliables:fire(player, buf, variants)
        end
    end
end

return replecs_server

local replicator = require("@client/replicator")
local collect = require("@utils/collect")

local updates = collect(remotes_client.send_updates)
local unreliables = collect(remotes_client.send_unreliables)

function replecs_client()
    for buf, variants in updates do
        replicator:apply_updates(buf, variants)
    end
    for buf, variants in unreliables do
        replicator:apply_unreliable(buf, variants)
    end
end

return replecs_client

local function collect(event)
    local storage = {}
    local mt = {}
    local iter = function()
        local n = #storage
        return function()
            if n <= 0 then
                mt.__iter = nil
                return nil
            end

            n -= 1
            return n + 1, unpack(table.remove(storage, 1) :: any)
        end
    end

    if type(event) == "function" then
        event(function(...)
            table.insert(storage, { ... })
            mt.__iter = iter
        end)
    else
        event:Connect(function(...)
            table.insert(storage, { ... })
            mt.__iter = iter
        end)
    end

    setmetatable(storage, mt)
    return (storage :: any) :: () -> (number, ...any)
end

return collect

local function interval(s: number)
    local pin: number = nil :: any

    local function throttle()
        if not pin then
            pin = os.clock()
        end

        local elapsed = os.clock() - pin > s
        if elapsed then
            pin = os.clock()
        end

        return elapsed
    end
    return throttle
end

return interval