Setting Up

Creating Replicators

To start you need to create a Replicator for the server and the client.

Replecs exports replecs.create. This creates a holder that will have both client and server entries. These entries will only be present on the client and server respectively.

You can then export each replicator type from their sides.

Shared

@shared/replicator.luau

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

return replecs.create(world)

Server

@server/replicator.luau

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

return replicator.server

Client

@client/replicator.luau

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

return replicator.client

---

Having a holder that has both client and server is useful for methods that would be used in a shared file where you cant require the client or server replicators directly.

An example of this is the method for hooking after replication which most of the time will be called inside signals for shared components, but it’s exclusive to the client.

---

Additionally, you can create the client and server replicators separately using:

• replecs.create_client
• replecs.create_server.

Server

local replecs = require("@pkg/replecs")
return replecs.create_server(world)

Client

local replecs = require("@pkg/replecs")
return replecs.create_client(world)

---

Providing Your World

Your world can be provided to the replicator to be used in two ways:

• Directly to the replicator constructor, as seen in the previous examples.
• When initialiazing the replicator calling replicator:init(world)

Danger

Replecs uses preregisted components. You need to require replecs before creating a world, so these components are globally available. Not doing so causes weird behaviours that are hard to debug.

The easiest way to make sure this is done properly is to require replecs right before creating the world in your world.lua file.

---

Marking Shared Components

After creating your replicators. You must add replecs.shared to every single component/tag that can be replicated. These components also need to be named with jecs.Name.

They need to be equally marked in both the client and server, This means that a marked component can’t be missing from one of the two.

Easiest way to do this is to save your components in a table and then iterate over them.

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

-- create a table with all your components
local shared_components = {
    foo = world:component(),
    baz = world:entity(),
}

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

Note

Attempting to replicate a component without shared will result in the following error:
attempted to replicate a non-shared component

---

Initializing Replicators

After creating your replicators. You need to initialize them by calling replicator:init() before using them.

You can also provide your world here if you did not provide it in the constructor. This is useful in workflows where the world is not exported as a singleton.