Skip to main content

Replica

The client side of an enemy: a rig, a table of client states, and three inputs the game's remote handlers call. Runs on the client; the package is shared realm so it is there. 

local replica = VluxyAI.Sync.Replica.new({
	Entity = model,
	Visuals = {
		Hunt = {
			Enter = function(replica) replica.Data.Highlight.Enabled = true end,
			Exit = function(replica) replica.Data.Highlight.Enabled = false end,
		},
	},
})
replica:On("Kill", function(payload) ... end)

syncRemote.OnClientEvent:Connect(function(message)
	if message.Kind == "State" then replica:SetState(message.State)
	elseif message.Kind == "Position" then replica:SetPosition(message.Position, message.Yaw)
	elseif message.Kind == "Event" then replica:Receive(message.Name, message.Payload) end
end)

Types​

Replica​

</>
interface Replica {
Entity: PVInstance--

The rig.

Data: {[string]: any}--

Yours: highlights, sounds, whatever a visual state makes.

StateChanged: Signal<(
string,
string?
)>--

Fired by SetState.

Events: Signal<(
string,
any
)>--

Fired by Receive, for every event.

Destroyed: Signal<()>--

Fired once by Destroy, after the last Exit; tie what you attached to the rig to it.

GetState: (self: Replica) → string?
SetState: (
self: Replica,
name: string
) → ()
SetPosition: (
self: Replica,
position: Vector3,
yaw: number?
) → ()
ApplySnapshot: (
self: Replica,
snapshot: Snapshot
) → ()
On: (
self: Replica,
name: string,
handler: (payload: any) → ()
) → Connection
Receive: (
self: Replica,
name: string,
payload: any
) → ()
Step: (
self: Replica,
deltaTime: number
) → ()
Destroy: (self: Replica) → ()
}

What new returns, and what every visual state receives.

Functions​

new​

</>
Replica.new(options: ReplicaOptions) → Replica

Types

​

interface ReplicaOptions {
Entity: PVInstance--

The rig, or anything with GetPivot and PivotTo.

Visuals: Visuals?--

Client states keyed by server state name. Missing states are fine.

Puppet: boolean?--

true to move the rig toward streamed positions. Default false.

Smoothing: number?--

Studs per second of catch-up in puppet mode; 0 snaps. Default 24.

TurnSmoothing: number?--

Radians per second of turning in puppet mode; 0 snaps. Default 12.

HeightOffset: number?--

Added to streamed positions, for a client rig whose pivot sits higher than the server's. Default 0.

}

GetState​

</>
Replica.GetState(self: ReplicaClass) → string?--

The last state set, nil before the first.

SetState​

</>
Replica.SetState(
self: ReplicaClass,
name: string--

The server state's name.

) → ()

Runs the current visual state's Exit, then the new one's Enter, and fires StateChanged. A state with no visuals is tracked all the same. Setting the current state again re-enters it. A SetState made from inside Exit does not run that Exit again; an Exit or Enter that errors is warned about and the state still moves on.

SetPosition​

</>
Replica.SetPosition(
self: ReplicaClass,
position: Vector3,--

The server rig's pivot position from the stream.

yaw: number?--

Facing in radians about Y, as the Broadcaster samples it.

) → ()

Where the rig should be. In puppet mode the rig smooths toward it every frame; in mirror mode it is recorded and nothing moves.

ApplySnapshot​

</>
Replica.ApplySnapshot(
self: ReplicaClass,
snapshot: Snapshot
) → ()

Applies a Broadcaster snapshot: the position, then the state.

On​

</>
Replica.On(
self: ReplicaClass,
name: string,
handler: (payload: any) → ()
) → Connection

Runs handler for every received event of that name. Events fires for all of them too.

Receive​

</>
Replica.Receive(
self: ReplicaClass,
name: string,
payload: any
) → ()

Hands an event the server emitted to its handlers and to Events.

Step​

</>
Replica.Step(
self: ReplicaClass,
deltaTime: number
) → ()

One frame: puppet smoothing toward the latest sample, then the current visual state's Update. Driven by Heartbeat; a test calls it directly.

Destroy​

</>
Replica.Destroy(self: ReplicaClass) → ()

Runs the current visual state's Exit, stops, and fires Destroyed. The rig is yours; it is not destroyed.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "",
            "params": [
                {
                    "name": "options",
                    "desc": "",
                    "lua_type": "ReplicaOptions"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Replica"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 166,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "GetState",
            "desc": "",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "ReplicaClass"
                }
            ],
            "returns": [
                {
                    "desc": "The last state set, `nil` before the first.",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 214,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "SetState",
            "desc": "Runs the current visual state's `Exit`, then the new one's `Enter`, and fires `StateChanged`.\nA state with no visuals is tracked all the same. Setting the current state again re-enters it.\nA `SetState` made from inside `Exit` does not run that Exit again; an Exit or Enter that errors\nis warned about and the state still moves on.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "ReplicaClass"
                },
                {
                    "name": "name",
                    "desc": "The server state's name.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 227,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "SetPosition",
            "desc": "Where the rig should be. In puppet mode the rig smooths toward it every frame; in mirror\nmode it is recorded and nothing moves.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "ReplicaClass"
                },
                {
                    "name": "position",
                    "desc": "The server rig's pivot position from the stream.",
                    "lua_type": "Vector3"
                },
                {
                    "name": "yaw",
                    "desc": "Facing in radians about Y, as the [Broadcaster] samples it.",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 263,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "ApplySnapshot",
            "desc": "Applies a [Broadcaster] snapshot: the position, then the state.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "ReplicaClass"
                },
                {
                    "name": "snapshot",
                    "desc": "",
                    "lua_type": "Snapshot"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 274,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "On",
            "desc": "Runs `handler` for every received event of that name. `Events` fires for all of them too.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "ReplicaClass"
                },
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "handler",
                    "desc": "",
                    "lua_type": "(payload: any) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Connection"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 292,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "Receive",
            "desc": "Hands an event the server emitted to its handlers and to `Events`.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "ReplicaClass"
                },
                {
                    "name": "name",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "payload",
                    "desc": "",
                    "lua_type": "any"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 323,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "Step",
            "desc": "One frame: puppet smoothing toward the latest sample, then the current visual state's\n`Update`. Driven by Heartbeat; a test calls it directly.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "ReplicaClass"
                },
                {
                    "name": "deltaTime",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 346,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "Destroy",
            "desc": "Runs the current visual state's `Exit`, stops, and fires `Destroyed`. The rig is yours; it is\nnot destroyed.",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "ReplicaClass"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 390,
                "path": "lib/Sync/Replica.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "ReplicaOptions",
            "desc": "",
            "fields": [
                {
                    "name": "Entity",
                    "lua_type": "PVInstance",
                    "desc": "The rig, or anything with `GetPivot` and `PivotTo`."
                },
                {
                    "name": "Visuals",
                    "lua_type": "Visuals?",
                    "desc": "Client states keyed by server state name. Missing states are fine."
                },
                {
                    "name": "Puppet",
                    "lua_type": "boolean?",
                    "desc": "`true` to move the rig toward streamed positions. Default `false`."
                },
                {
                    "name": "Smoothing",
                    "lua_type": "number?",
                    "desc": "Studs per second of catch-up in puppet mode; `0` snaps. Default `24`."
                },
                {
                    "name": "TurnSmoothing",
                    "lua_type": "number?",
                    "desc": "Radians per second of turning in puppet mode; `0` snaps. Default `12`."
                },
                {
                    "name": "HeightOffset",
                    "lua_type": "number?",
                    "desc": "Added to streamed positions, for a client rig whose pivot sits higher than the server's. Default `0`."
                }
            ],
            "source": {
                "line": 45,
                "path": "lib/Sync/Replica.luau"
            }
        },
        {
            "name": "Replica",
            "desc": "What `new` returns, and what every visual state receives.",
            "fields": [
                {
                    "name": "Entity",
                    "lua_type": "PVInstance",
                    "desc": "The rig."
                },
                {
                    "name": "Data",
                    "lua_type": "{ [string]: any }",
                    "desc": "Yours: highlights, sounds, whatever a visual state makes."
                },
                {
                    "name": "StateChanged",
                    "lua_type": "Signal<(string, string?)>",
                    "desc": "Fired by `SetState`."
                },
                {
                    "name": "Events",
                    "lua_type": "Signal<(string, any)>",
                    "desc": "Fired by `Receive`, for every event."
                },
                {
                    "name": "Destroyed",
                    "lua_type": "Signal<()>",
                    "desc": "Fired once by `Destroy`, after the last Exit; tie what you attached to the rig to it."
                },
                {
                    "name": "GetState",
                    "lua_type": "(self: Replica) -> string?",
                    "desc": ""
                },
                {
                    "name": "SetState",
                    "lua_type": "(self: Replica, name: string) -> ()",
                    "desc": ""
                },
                {
                    "name": "SetPosition",
                    "lua_type": "(self: Replica, position: Vector3, yaw: number?) -> ()",
                    "desc": ""
                },
                {
                    "name": "ApplySnapshot",
                    "lua_type": "(self: Replica, snapshot: Snapshot) -> ()",
                    "desc": ""
                },
                {
                    "name": "On",
                    "lua_type": "(self: Replica, name: string, handler: (payload: any) -> ()) -> Connection",
                    "desc": ""
                },
                {
                    "name": "Receive",
                    "lua_type": "(self: Replica, name: string, payload: any) -> ()",
                    "desc": ""
                },
                {
                    "name": "Step",
                    "lua_type": "(self: Replica, deltaTime: number) -> ()",
                    "desc": ""
                },
                {
                    "name": "Destroy",
                    "lua_type": "(self: Replica) -> ()",
                    "desc": ""
                }
            ],
            "source": {
                "line": 109,
                "path": "lib/Sync/Replica.luau"
            }
        }
    ],
    "name": "Replica",
    "desc": "The client side of an enemy: a rig, a table of client states, and three inputs the game's\nremote handlers call. Runs on the client; the package is `shared` realm so it is there.\n\n```lua\nlocal replica = VluxyAI.Sync.Replica.new({\n\tEntity = model,\n\tVisuals = {\n\t\tHunt = {\n\t\t\tEnter = function(replica) replica.Data.Highlight.Enabled = true end,\n\t\t\tExit = function(replica) replica.Data.Highlight.Enabled = false end,\n\t\t},\n\t},\n})\nreplica:On(\"Kill\", function(payload) ... end)\n\nsyncRemote.OnClientEvent:Connect(function(message)\n\tif message.Kind == \"State\" then replica:SetState(message.State)\n\telseif message.Kind == \"Position\" then replica:SetPosition(message.Position, message.Yaw)\n\telseif message.Kind == \"Event\" then replica:Receive(message.Name, message.Payload) end\nend)\n```",
    "source": {
        "line": 160,
        "path": "lib/Sync/Replica.luau"
    }
}