The Router API (v0)

A router splits one game into blocks (see block-manifest.md). The Router API is how a router tells the game's kit where those blocks are inside the game: which character is the player, which objects are its NPCs, how to get from the main menu into the world.

It's made to need as little as possible:

1. The kit guesses first. Every kit knows its engine's conventions (on Unreal: player controller 0's pawn is the player, characters are Character actors). Most of a router is already done before you write anything.
2. Data next. What the kit can't guess goes in router.toml, under each block's [block.bind]. Fusion checks it like the rest of the manifest.
3. Lua last. Only what data can't say (clicking through a character creation screen) goes in router.lua, next to router.toml.

The same names work on every kit. The Unreal kit (kits/unreal) and the Unity kit (kits/unity, step 7.1) both read the data and run router.lua (see "On the Unity kit" below for what differs). The example is VEIN's router: routers/vein/router.toml and routers/vein/router.lua.

What the kit does by itself¶

Data: [block.bind]¶

[[block]]
id = "vein.world"
kind = "world"
gives = ["layer:color+depth", "collision"]
...
[block.bind]
map = "/Game/Vein/Maps/ChamplainValleyDemo"   # opened from the main menu
player = "BP_VeinPlayerCharacter_C"           # in the world once the player is one
player_follows_camera = true                  # the game loads its world around the player

[[block]]
id = "vein.npcs"
kind = "npc_group"
gives = ["entities"]
...
[[block.bind.entity]]
class = "BP_Zombie_C"                 # exactly this class
kind = "zombie"
name = "Zombie"
health = "Health.Health"              # field paths
max_health = "Health.MaxHealth"
team = 2
spawn = "/Game/Vein/Zombies/BP_Zombie"  # what to spawn when Fusion asks for a "zombie"

[[block.bind.entity]]
is_a = "/Script/Vein.BaseVehicle"     # this class or any class made from it
kind = "vehicle"                      # name defaults to the class, made readable

Each entity rule has class or is_a, a kind, and optionally name, health, max_health (field paths like Health.Health), team and spawn (an asset or class path). Two rules can't spawn the same kind.

Lua: router.lua¶

The script runs once when the game starts. It gives blocks functions:

Router.block "vein.world" {
    enter = function()
        if Game.class_name(Game.player()) ~= "BP_CharacterCreationPawn_C" then
            return
        end
        local create = Game.widget("WBP_CharacterCreation_C")
        if create then
            create:OnRandomNameSet("Fusion Scout")
            ...
        end
    end,
}

info is { world, controller, pawn, anchor }. Router.settings holds the scenario's choices for the router's block settings ([[block.setting]], see block-manifest.md), by setting id, as text (tonumber(Router.settings.walkers)); Fusion sends them when it connects. Positions are in the game's own units and axes (router.toml's units), as { X, Y, Z }; rotations as { Pitch, Yaw, Roll }.

A mistake stops the script with its line and what's allowed:

router.lua:15: Router.block "vein.world": unknown field `entr` (a world block can have: anchor, enter, hidden, ready)

The kit then logs it in fusion_kit.log (next to the kit's main.dll) and does nothing else, so a broken router can't half-run.

Game: the game's objects¶

Objects also have the game's own fields and methods: zombie.Health.MaxHealth, widget:OnRandomNameSet("Fusion Scout"). Use Game.get when a field might be missing.

The sandbox¶

The script sees Router, Game, and Lua's safe libraries (math, string, table, utf8, os.clock/time/date, pairs, pcall, ...). It can't open files, run programs, load other code (require, load) or use the kit's own functions. It can do anything the game itself can do through its objects: that's what reflection is (trust tiers, step 6.2, decide who may publish what).

Language and types¶

Router scripts are Lua 5.4 (on Unreal, UE4SS's own Lua), not Luau like addons: docs/decisions/0004-router-api.md says why. Keep to the common subset when you can. docs/types/router-api.lua has the types for lua-language-server, so an editor or lua-language-server --check catches a wrong function name or argument before the game starts.

Installing a router into a game¶

Fusion's one-click setup copies the kit and the router (its router.toml and router.lua) into the game ([router.setup], see block-manifest.md). For development: kits\unreal\install.ps1 -Game vein [-Dev].

Router Studio¶

Router Studio (F4 in a session, or "Router Studio" in the main menu) writes the same [block.bind] data by pointing at the running game's objects: "This is the player", "This map", "These are NPCs" (with health fields found by clicking through an object's fields). "Test live" has the kit try the router on the running game, "Apply live" makes the game use it now (the kit's reload). fusion-cli game asks the same questions from the command line, e.g. fusion-cli game find zombie --game-id vein.

Not in v0 yet¶

• Playing as the character on the Unity kit (no common way to move a Unity game's player).
• Hooks on the game's own functions ("when a zombie dies").
• Reloading router.lua by itself without restarting the game (step 5.7); a new router.toml reloads live (Router Studio's "Apply live"), and runs router.lua again with it.
• router check running the types and these checks before the game starts (step 5.7).

On the Unity kit (step 7.1, v0)¶

The Unity kit (kits/unity, a MelonLoader mod; kits/unity/README.md) reads the same [block.bind] data. What it does by itself:

| The player | bind.player (a component class), or the GameObject tagged Player | bind.player | | In the world | the scene is bind.map (if set) and no scene loaded for a second | Lua enter, ready | | Spawning | a copy of the spawn prefab of the entity kind Fusion asks for (a prefab or object the game has loaded, by name, or a Resources path), on the ground there | bind.entity.spawn, Lua spawn | | Teleport | moves the player (its CharacterController off while it moves) | | | Actions | remove, set_health (the rule's health field), move_to and stop (the entity's NavMeshAgent) | Lua actions |

router.lua on Unity runs in the kit's own Lua 5.4 (inside fusion_unity.dll), with the same Router.block checks and sandbox. Game.* reaches the game's objects through Il2CppInterop's reflection: o.field, o.field = v and o:Method(...) work on any component (panel:IsEnabled(), ai.m_CurrentHP), o.gameObject.name follows properties, list[1] reads an element (counting from 1). Enums arrive as their names ("Wolf"). Positions are { X, Y, Z } (also x, y, z), Unity's own meters. Unity has no player controllers or console (Game.controller() is nil, Game.console() false), and adds:

Game.class(name) is what to spawn: a loaded prefab or object by name, or a Resources path.

Try any of it on the running game: fusion-cli game lua "Game.find('Panel_MainMenu'):IsEnabled()" --game-id thelongdark runs the snippet in the router's sandbox and prints what it returns.

Not yet on the Unity kit: player_follows_camera, possessing a Character block.