Product

A kernel that decides, validates and commits — once, on the server.

Actorvia is built around a single execution path. Everything else — adapters, domain packs, planners, external evaluation — plugs into that path without being able to route around it.

Execution: Server-authoritative
Determinism: Seeded local planner
Extension: Adapters and domain packs
Status: Generally available

Kernel

Eight subsystems, each with one responsibility.

Knowing which subsystem owns a behaviour is usually enough to know where a problem lives.

Kernel subsystems with their inputs and outputs
Subsystem	Responsibility	In	Out
Observation	Collects the declared fields from every attached adapter and freezes them for the tick, so a plan is never built against state that moved underneath it.	Adapter observe() results	Immutable observation frame
Manifest resolution	Resolves the role for an actor into a concrete capability set, constraint set and resource budget by composing the domain packs in scope.	Role id, domain packs	Resolved authority envelope
Planner	Turns a normalised goal into an ordered sequence of declared actions. Deterministic and seeded; it cannot invent an action that is not in the surface.	Goal, observation frame, action surface	Candidate plan
Authority validator	Checks each candidate action against capability, constraint, ownership and world preconditions, and returns a typed verdict with the evidence it decided from.	Candidate plan, authority envelope	Verdict per action
Resource ledger	Reserves and settles declared resources inside one transaction. A plan that cannot pay for itself is discarded before anything actuates.	Validated plan, declared costs	Atomic resource transaction
Executor	Drives the adapter’s apply() for approved actions and tracks completion, interruption and timeout against the actor’s embodiment.	Approved action	Actuation result
Commit	Writes the resulting world state on the server and publishes the replicated view. This is the only writer in the system.	Actuation result	Authoritative world state
Diagnostics	Records goal, plan, verdicts, spend and outcome per tick under the same redaction rules as observation, so inspecting an agent cannot widen what leaves the server.	Every stage above	Redacted trace

Execution path

The order is fixed.

No configuration reorders these steps, and no extension point can skip one. That is the property everything else depends on.

Creator model or controller
Authored
Any Instance you already own — a character rig, a vehicle chassis, a boat hull, a conveyor line, a flock controller.
Actor adapter
Authored
Binds that model’s parts, attributes, seats and motors to a normalised observation and actuation surface. Embodiment lives here, not in the kernel.
Role and capability manifest
Authored
Declares what this actor may perceive, may attempt, and may spend. Anything absent from the manifest is not reachable at runtime.
Goal and planner
Server
A normalised goal resolves into an ordered plan built only from declared actions, against the actor’s current observation.
Optional side path
External evaluation
An external model may read a redacted view of the actor’s observation and return a candidate goal, a ranking, or a suggested plan. Its output re-enters at step 05 as a proposal and is validated exactly like any other — it holds no capability of its own.
- Can read a redacted observation
- Can propose a goal, a ranking or a plan
- Cannot bypass validation at step 05
- Cannot move resources at step 06
- Cannot reach the commit at step 08
Authority and safety validation
Server
Every proposed action is checked against capability, constraint, ownership and world preconditions. Rejection is a normal outcome, not an error path.
Resource transaction
Server
Currency, stock, fuel, cargo and charges move atomically. A partially applied plan is never observable.
Action execution
Server
The approved action runs through the adapter’s actuation surface — the same interface for a humanoid step, a throttle input and a crane slew.
Server-authoritative commit
Server
World state is written on the server. Clients receive the result. No client message can substitute for this step.

Steps 01–03 are authored once. Steps 04–08 run per decision on the server. The dashed branch is optional and advisory: it can propose, and it can be switched off entirely without changing the behaviour of the path above.

Adapter contract

Three functions describe an embodiment.

An adapter is small on purpose. If it is getting large, the behaviour probably belongs in a domain pack instead.

Normalise state inward
Returns the declared observation fields for one instance. This is an allowlist: what you do not return does not exist as far as the planner, the diagnostics and any external provider are concerned.
Declare the action surface
Each action names its parameters, its preconditions and its cost against declared resources. The planner composes plans only from this set.
Actuate an approved action
Runs after validation and resource settlement have already succeeded. An adapter never decides whether something is allowed — by the time it is called, that question has been answered.

adapters/machine/gantry.luauLuau · Abridged for readabilityLuau

return Runtime.defineAdapter({
    id = "machine/gantry",

    -- Normalise the model into the observation the kernel reasons over.
    observe = function(model)
        return {
            boom_angle  = model.Boom:GetAttribute("Angle"),
            hoist_height = model.Hoist.Position.Y,
            payload      = model:GetAttribute("PayloadId"),
            envelope     = { radius = 42, height = 28 },
            faults       = model:GetAttribute("Faults") or {},
        }
    end,

    -- Everything this embodiment can be asked to attempt.
    actions = {
        slew    = { params = { angle = "number" },  cost = { power = 2 } },
        hoist   = { params = { height = "number" }, cost = { power = 3 } },
        grip    = { params = { target = "Instance" } },
        release = {},
    },

    -- Actuation only. Validation and resource settlement already happened.
    apply = function(model, action, params)
        if action == "slew" then
            model.Boom:SetAttribute("TargetAngle", params.angle)
        end
    end,
})

Humanoids and characters
Guards · Villagers · Companions · Crowd extras
Merchants and service actors
Shopkeepers · Quest givers · Repair stations · Brokers
Ground vehicles
Cars · Trucks · Trams · Service vehicles
Aircraft
Fixed wing · Rotorcraft · Drones · Airport ground traffic
Boats and watercraft
Ferries · Cargo vessels · Patrol craft · Dock tenders
Animals and wildlife
Herds · Predators · Mounts · Ambient fauna
Swarms and formations
Flocks · Drone groups · Convoys · Crowd units
Robots and machines
Cranes · Robotic arms · Conveyors · Turrets · Drills
Infrastructure and systems
Signals · Doors and gates · Power grids · Logistics networks
Creator-defined actors
Anything with observable state and a way to act on it

One adapter serves every instance of its class. A port with forty cranes needs one gantry adapter, not forty.

Authority

Validation is not a middleware you can remove.

Every action passes the same gate, and a rejection carries the reason and the evidence it was decided from.

server/validation.server.luauLuau · Abridged for readabilityLuau

-- Every proposed action passes the same gate before anything moves.
local verdict = Runtime.validate(actor, {
    action = "hoist",
    params = { height = 26 },
})

-- verdict.allowed  -> boolean
-- verdict.reason   -> "constraint.max_payload_tonnes" | "capability.missing" | ...
-- verdict.evidence -> the observation fields the decision was made from

if not verdict.allowed then
    -- Rejection is an ordinary outcome. The actor re-plans; it does not retry blindly.
    Runtime.replan(actor, { excluding = verdict.reason })
end

What each participant is permitted to do in the execution path
Capability	Client	Server runtime	External model
Read world state	Replicated view only	Full authoritative state	Redacted observation, if enabled
Submit a goal	As a request, subject to validation	Directly	As a proposal
Select the next action	Never	Planner output	May rank or suggest
Skip authority validation	Never	Validation is not optional	Never
Move resources	Never	Atomic transaction	Never
Commit world state	Never	Sole writer	Never

External intelligence

Optional, redacted, advisory — and switchable off.

External evaluation is a feature of the planner, not a dependency of the runtime. Disabling it changes what an actor chooses, never what it is permitted to do.

What it receives

Only the observation fields you enumerate. Not the full frame, not the world, not player identity. The payload is built from the allowlist, so widening it is an explicit edit rather than an accident.

What it returns

A proposal — a goal, a ranking over candidate goals, or a suggested plan. It re-enters at validation and is checked exactly like a locally generated plan.

server/evaluation.server.luauLuau · Abridged for readabilityLuau

-- External evaluation is opt-in, redacted, and advisory.
Runtime.configureEvaluation({
    enabled = true,
    provider = "your-provider",

    -- Only these observation fields ever leave the server.
    expose = { "inbound_queue.depth", "weather.state", "berth.availability" },

    -- The provider returns a proposal. It is validated like any other input.
    accepts = { "goal_ranking" },

    -- If it is slow or unavailable, the deterministic planner continues alone.
    on_timeout = "fall_back_to_local",
    timeout_ms = 400,
})

Boundaries

What this does not do.

Worth reading before you plan around it.

It does not write your gameplay rules: The runtime decides what an actor attempts and enforces whether it is permitted. What a successful action means for your economy, your progression or your scoring is still yours.
Adapters are work: A new class of embodiment needs an adapter. Studio can scaffold one from a model, but a good observation surface is a design decision, not a generated artefact.
Determinism ends where you break it: Enabling external evaluation, reading wall-clock time in an adapter, or observing unsynchronised client state all reintroduce non-determinism. The runtime cannot restore a property you removed.
Interfaces change on major releases: Adapters and packs are code you will revise. Interface changes land only in a major release and always ship with a migration note, but they do land — keeping adapters small is what makes revising them cheap.

Developer workflow Worked examples Security posture

A kernel that decides, validates and commits — once, on the server.

Actorvia is built around a single execution path. Everything else — adapters, domain packs, planners, external evaluation — plugs into that path without being able to route around it.

Execution

Server-authoritative

Determinism

Seeded local planner

Extension

Adapters and domain packs

Status

Generally available

Subsystem

Responsibility

Out

Observation

Collects the declared fields from every attached adapter and freezes them for the tick, so a plan is never built against state that moved underneath it.

Adapter observe() results

Immutable observation frame

Manifest resolution

Resolves the role for an actor into a concrete capability set, constraint set and resource budget by composing the domain packs in scope.

Role id, domain packs

Resolved authority envelope

Planner

Turns a normalised goal into an ordered sequence of declared actions. Deterministic and seeded; it cannot invent an action that is not in the surface.

Goal, observation frame, action surface

Candidate plan

Authority validator

Checks each candidate action against capability, constraint, ownership and world preconditions, and returns a typed verdict with the evidence it decided from.

Candidate plan, authority envelope

Verdict per action

Resource ledger

Reserves and settles declared resources inside one transaction. A plan that cannot pay for itself is discarded before anything actuates.

Validated plan, declared costs

Atomic resource transaction

Executor

Drives the adapter’s apply() for approved actions and tracks completion, interruption and timeout against the actor’s embodiment.

Approved action

Actuation result

Commit

Writes the resulting world state on the server and publishes the replicated view. This is the only writer in the system.

Actuation result

Authoritative world state

Diagnostics

Records goal, plan, verdicts, spend and outcome per tick under the same redaction rules as observation, so inspecting an agent cannot widen what leaves the server.

Every stage above

Redacted trace

return Runtime.defineAdapter({ id = "machine/gantry", -- Normalise the model into the observation the kernel reasons over. observe = function(model) return { boom_angle = model.Boom:GetAttribute("Angle"), hoist_height = model.Hoist.Position.Y, payload = model:GetAttribute("PayloadId"), envelope = { radius = 42, height = 28 }, faults = model:GetAttribute("Faults") or {}, } end, -- Everything this embodiment can be asked to attempt. actions = { slew = { params = { angle = "number" }, cost = { power = 2 } }, hoist = { params = { height = "number" }, cost = { power = 3 } }, grip = { params = { target = "Instance" } }, release = {}, }, -- Actuation only. Validation and resource settlement already happened. apply = function(model, action, params) if action == "slew" then model.Boom:SetAttribute("TargetAngle", params.angle) end end, })

-- Every proposed action passes the same gate before anything moves. local verdict = Runtime.validate(actor, { action = "hoist", params = { height = 26 }, }) -- verdict.allowed -> boolean -- verdict.reason -> "constraint.max_payload_tonnes" | "capability.missing" | ... -- verdict.evidence -> the observation fields the decision was made from if not verdict.allowed then -- Rejection is an ordinary outcome. The actor re-plans; it does not retry blindly. Runtime.replan(actor, { excluding = verdict.reason }) end

Capability

Client

Server runtime

External model

Read world state

Replicated view only

Full authoritative state

Redacted observation, if enabled

Submit a goal

As a request, subject to validation

Directly

As a proposal

Select the next action

Never

Planner output

May rank or suggest

Skip authority validation

Never

Validation is not optional

Never

Move resources

Never

Atomic transaction

Never

Commit world state

Never

Sole writer

Never

-- External evaluation is opt-in, redacted, and advisory. Runtime.configureEvaluation({ enabled = true, provider = "your-provider", -- Only these observation fields ever leave the server. expose = { "inbound_queue.depth", "weather.state", "berth.availability" }, -- The provider returns a proposal. It is validated like any other input. accepts = { "goal_ranking" }, -- If it is slow or unavailable, the deterministic planner continues alone. on_timeout = "fall_back_to_local", timeout_ms = 400, })

A kernel that decides, validates and commits — once, on the server.

Creator model or controller

Actor adapter

Role and capability manifest

Goal and planner

Authority and safety validation

Resource transaction

Action execution

Server-authoritative commit

Normalise state inward

Declare the action surface

Actuate an approved action

Humanoids and characters

Merchants and service actors

Ground vehicles

Aircraft

Boats and watercraft

Animals and wildlife

Swarms and formations

Robots and machines

Infrastructure and systems

Creator-defined actors

What it receives

What it returns

A kernel that decides, validates and commits — once, on the server.

Creator model or controller

Actor adapter

Role and capability manifest

Goal and planner

Authority and safety validation

Resource transaction

Action execution

Server-authoritative commit

Normalise state inward

Declare the action surface

Actuate an approved action

Humanoids and characters

Merchants and service actors

Ground vehicles

Aircraft

Boats and watercraft

Animals and wildlife

Swarms and formations

Robots and machines

Infrastructure and systems

Creator-defined actors

What it receives

What it returns