How Palforge works

Palforge turns an unmodifiable Unreal Engine 5.1 dedicated server into a .NET plugin host — without patching the executable and without baking in a single memory offset. This page explains how: how it boots, how it learns the game's object layout, and the threading model that keeps your code from crashing the server.

The two pieces

Palforge is two assemblies with very different jobs:

The boot sequence

Layout derivation

Palworld's server is a shipping UE5.1 build with no symbols, and its struct layouts differ from stock UE. Palforge never hardcodes those offsets. Instead it derives them from the live process and only trusts a value it can prove.

Probes and the unanimity rule

Derivation runs a chain of structural probes, each building on the last:

ObjectArrayProbe → ObjectBaseProbe → StructProbe → PropertyProbe → FunctionProbe

Each probe reasons about the shape of memory rather than reading a fixed address. For example:

• ObjectArrayProbe brute-forces the global object array's stride and item shape, accepting a combination only when many sampled objects each store their own index where UObjectBase.InternalIndex should be.
• ObjectBaseProbe finds ClassPrivate as the pointer that mostly points at another object and has exactly one fixed point (the class whose class is itself — UClass), then NamePrivate, OuterPrivate and ObjectFlags by similar structural tests.
• PropertyProbe anchors on structs whose layout is known a priori — Vector{X,Y,Z} at 0/8/16, Guid{A,B,C,D} at 0/4/8/12 — and walks their property lists to recover the FProperty field offsets.

Every candidate offset is passed through a unanimity check: it is accepted only if all the evidence agrees on exactly one value. Two disagreeing answers, or none, leave the member undetermined — never guessed.

Provenance and the fallback table

Each offset records where it came from:

The stock UE5.1 table only fills genuine gaps — a derived offset is never overwritten by the table. If a derived value disagrees with the table, Palforge keeps the derived one and logs that the build is forked.

Validation, or fail closed

Before the layout is accepted, Palforge proves it end-to-end: it walks the root chain Object → Field → Struct → Class, checks that Object has a null super and that Object's class-default object is named exactly Default__Object, then fingerprints the verified table. If any of this fails, the runtime enters the Disabled state:

The game thread

Palforge reads and writes the game's own memory because it runs inside the game process. That makes reads cheap, but it also means the engine's single game thread is sacred.

One thread, hard-enforced

Palforge installs its work on UGameEngine::Tick, and the first tick marks that thread as the game thread. From then on:

• Reads are safe from any thread. Every read goes through a fault-free memory primitive — a bad pointer returns false instead of crashing — so you can inspect live objects from a background thread.
• Writes and engine calls are game-thread-only. Writing a property, calling a UFunction (ProcessEvent), allocating/freeing native memory, spawning or destroying actors, and loading assets all assert the game thread and throw if called from anywhere else.

Getting onto the game thread

Your OnStart already runs on the game thread (plugins start from inside the derivation callback). When you are on a background thread — a timer, a Task, an incoming network callback — hop over first:

await GameThread.SwitchTo();   // continues on the engine tick thread
actor.Set<double>("Hp", 9999.0);

Or post a one-shot action to the next tick:

GameThread.Post(() => actor.Set<double>("Hp", 9999.0));

The plugin scope also gives you tick- and time-based scheduling (OnTick, Every, After) that already runs on the game thread, so most plugins never touch GameThread directly. Exceptions thrown on the game thread by your callbacks are caught and logged, so one buggy handler cannot take down the server.

Runtime states

The runtime moves through three states, and reflection is only available in one:

On-disk layout

Everything Palforge uses lives under a Palforge folder next to the server executable:

…\PalServer\Pal\Binaries\Win64\
├─ version.dll                 Palforge proxy
└─ Palforge\
   ├─ Configuration.cfg        runtime configuration (required)
   ├─ Core\                    the managed runtime + bundled .NET (self-contained)
   ├─ Logs\                    Palforge-<date>.log and <Plugin>-<date>.log
   ├─ Plugins\                 one folder per plugin
   ├─ Sdk\                     generated SDK output (when enabled)
   └─ Dumps\                   drop a '.dump' file to trigger a reflection dump

Next steps