WFramework — getting started

WFramework is the official roleplay framework of WildM, in the spirit of ox_core + ox_inventory (or QBCore / ESX) on FiveM. It gives a server:

• players identified by their linked WFX.re account, with several characters per account (first name, last name, date of birth);
• money: cash and bank, integers only, every movement logged;
• jobs and grades (with salaries), groups (factions, gangs) and permission groups (user, mod, admin);
• an inventory with item definitions, weight limits, stacks, vehicle trunks, stashes and items on the ground — validated 100 % on the server;
• persistence in a single SQLite file.

Status: v1, server side ready, runtime wiring in progress

The server logic and its tests are finished. Its connection to the WildM scripting runtime (server_host, client UI natives) depends on the runtime and is still being agreed on — see Runtime host interface. Until then, players cannot use it in game yet.

Layout

game-server/
├── data/wframework.db          ← the database (created on first start, never in git)
├── resources/wframework/
│   ├── wf_core/                ← players, characters, money, jobs, groups, permissions
│   │   ├── resource.json
│   │   ├── config.json
│   │   ├── data/jobs.json
│   │   ├── data/groups.json
│   │   ├── server/             ← JS, server only (never sent to players)
│   │   └── client/             ← Lua, sent to players
│   └── wf_inventory/           ← inventory
│       ├── resource.json
│       ├── config.json
│       ├── data/items.json
│       ├── server/
│       └── client/
└── tests/wframework/           ← node --test

wf_inventory depends on wf_core and starts after it.

Database

WFramework uses SQLite through node:sqlite, built into Node.js 22.5+ (the game server runs on Node 26). There is no native module to compile and nothing to install. The file lives at game-server/data/wframework.db (setting database in wf_core/config.json, relative to the wf_core folder). WAL mode is on; back up the .db, .db-wal and .db-shm files together, or stop the server first.

Every operation is atomic: the new state is computed on copies, validated, written in one transaction, and only then applied in memory. A failure at any step leaves memory and database unchanged.

Configure

wf_core/config.json:

Key	Default	Meaning
database	../../../data/wframework.db	SQLite file, relative to wf_core/
identity	"wfx"	"wfx": a verified WFX.re account is required. "wfx+guest": players without one get guest:<name> (LAN and bots only — a name proves nothing)
admins	[]	identifiers given the admin group on join, e.g. "wfx:myname"
maxCharacters	3	characters per account
startingCash / startingBank	500 / 2500	money of a new character
autoSelectCharacter	true	load the last played character on join
autoCreateCharacter	true	create a placeholder character from the player name when the account has none
paycheckMinutes	15	salary of the job grade, paid into the bank (0 = off)
paycheckRequiresDuty	true	only characters on duty are paid (the unemployed allowance always is)
status	hunger 0.5, thirst 0.8	needs and how much they drop per minute, see needs
defaultAppearance	{ "preset": "base" }	outfit of a new character
savePositionSeconds	60	how often positions are saved (also saved on leave)

wf_inventory/config.json: slots and max weight (grams) of player, trunk, stash and drop inventories, interactDistance (metres, for giving and ground items), useCooldownMs, startingItems, idCard (an ID card item is given to new characters).

Become admin

Put your identifier in admins, then reconnect:

"admins": ["wfx:yourname"]

From the server console (source 0, which has every permission): addgroup <playerId> admin.

Run the tests

cd game-server
node --test tests/wframework/

The tests cover characters, money, permissions, weight, stacks, transfers, stashes, trunks, ground items, item use, persistence across a restart, and the full v1 scenario (join → saved character → persistent inventory → give an item to another player) through a fake runtime.

Next

• Characters & money
• Inventory
• Exports & events