Netcade Multiplayer Framework Documentation

Overview

NMF is designed to feel like a real studio framework: your game calls GameplayTag-named endpoints, the plugin resolves those tags through a registry asset, then a single subsystem handles the request, headers, auth, logging, and (optional) retries.

Your gameplay should never care whether your backend is Node, PHP, WordPress, or AWS. If the server matches the contract, the client code stays the same.

Install & Setup

1) Enable the plugin

Enable Netcade Multiplayer Framework inside the Unreal Editor Plugins window, then restart. After restart, you’ll see a new settings panel in Project Settings and you’ll be able to create the registry data asset.

2) Add Gameplay Tags (your contract IDs)

NMF uses tags as the “public API surface”. You create tags like NMF.Auth.Login and assign them to endpoint specs in your registry. This makes Blueprint usage clean, searchable, and hard to break.


Project Settings → Gameplay Tags → Gameplay Tag List

NMF.Http.Ping
NMF.Auth.Login
NMF.Auth.Register
NMF.Auth.Refresh

3) Create your Endpoint Registry (Data Asset)

In your Content Browser, create a NMFEndpointRegistry data asset and add endpoint rows. Each row maps a GameplayTag to a relative path, HTTP verb, body type, whether auth is required, and optional default headers.

Registry entries are loaded once per GameInstance and cached by the HTTP subsystem. If you change the asset, restart PIE to be safe.

4) Configure Project Settings

Open Project Settings → Plugins → NMF HTTP Settings. Set your BaseUrl, and point EndpointRegistry to the data asset you created. During development, keep logging enabled so you can see every request in the output log.


Project Settings → Plugins → NMF HTTP Settings

BaseUrl = https://example.com
EndpointRegistry = DA_NMF_EndpointRegistry
bLogRequests = true
TimeoutSeconds = 30

5) Test Ping

Add a single “Ping” endpoint to your registry (for example, NMF.Http.Ping → api/ping.php). Then in any Blueprint (a test Actor works), call the async node CallApiByTag with that tag. If you see a success response, your tags + registry + settings are correctly wired.

Quickstart

First call (by tag)

The recommended path is always tag-based calls. In Blueprint, you’ll pass a GameplayTag and (optionally) a Fields map. GET requests automatically convert Fields into a query string; POST/PUT/PATCH encode Fields as JSON or form-url-encoded depending on BodyType.

If you already have a nested payload (arrays/objects/numbers/bools), send it through RawBodyJson. When RawBodyJson is present, it is sent “as-is” (no string-map conversion).

Create a login endpoint spec in the registry (for example: NMF.Auth.Login → api/login.php, Verb POST, BodyType JSON, RequiresAuth false). In your Login widget, call CallApiByTag on button click. For simple payloads you can use the Fields map. For advanced payloads you can pass a JSON string in RawBodyJson.


RawBodyJson example:

{
  "email": "[email protected]",
  "password": "hunter2"
}

Store token (and apply it to future calls)

After login succeeds, your backend should return a token in the standard response envelope. Store it in your own runtime manager (GameInstance / Subsystem). Then apply it on future calls as: Authorization: Bearer <token>.

Best practice is to keep “runtime auth” out of Project Settings. The next upgrade step is an Auth Provider interface so the subsystem can ask for tokens at runtime.

HTTP Contract

Response envelope

NMF standardizes responses so client code can behave consistently even across different backends. The plugin treats a request as successful only when the HTTP status is 2xx and the envelope has ok=true.


{
  "ok": true,
  "code": "AUTH_OK",
  "message": "Login success",
  "data": { "token": "..." }
}

Errors & retries

Retries are intentionally conservative. As a default rule, only retry safe requests (GET/list operations) unless you explicitly allow retries for non-GET calls. Typical retry-worthy failures are transport failures (no response), 429 rate limiting, or transient 5xx errors.

Endpoints

Keep registry paths relative (example: api/login.php) and let NMF join them with BaseUrl. This makes it easy to swap environments (local dev, staging, production) without touching Blueprints.

Authentication

Email / Password

This is the simplest cross-platform account flow. Your backend validates credentials and returns a session token in data.token. The client stores the token and includes it on all authenticated endpoints.

Sessions / JWT

Tokens should expire and be refreshable. A clean contract usually includes expires_in and a refresh endpoint (example: NMF.Auth.Refresh). The exact token format is up to your backend adapter.

Best practice

Don’t let UI widgets “own” authentication. Store auth state in a persistent runtime place (GameInstance/SubSystem), so menus, gameplay, and reconnect logic can all share it without copy/paste.

Characters

GetCharList

Returns the character roster for the current account.

CreateChar

Create a new character with validated name/class/race, etc.

DeleteChar

Delete (or soft-delete) an existing character.

Invite/leave/kick/ready checks and party state replication from backend.

Friend list, presence, blocking, and invites.

Start with HTTP for history + WebSocket later for realtime channels.

MMO/MOBA Services

Inventory

Item grants, currency, equipment, cosmetics, and entitlement checks.

Stats / Leaderboards

Record match stats, retrieve leaderboard slices, and player stat history.

Matchmaking

Queue, role selection, MMR, party-aware matchmaking rules.

Dedicated Servers

Server List

Return available regions/servers (and health/ping data).

Host Requests

Queue host requests, allocate servers, return connection details securely.

Cloud adapters

Adapters can target AWS (GameLift/EC2), OVH, Hetzner, etc. The client contract stays the same.

Server Adapters

NMF does not force a backend. If the adapter matches the contract, the client stays identical.

Node Starter (recommended learning path)

The Node starter is the easiest way for new buyers to succeed: it’s consistent across platforms, Docker-friendly, and simple to debug. If you ship one “official” reference adapter, this is the cleanest default.

Plain PHP

PHP is the fastest path to deployment on any domain and works great for simpler projects. It’s also perfect for quick prototyping when you want endpoints online in minutes.

WordPress

WordPress is excellent when your community and accounts already live in WP. It also pairs naturally with creator portals, dashboards, and web-based tooling.

AWS Serverless

Ideal for scaling, but it introduces more moving parts (IAM, deployment, observability). The NMF client contract stays the same; only the adapter changes.

Glossary

Envelope: Standard response wrapper with ok/code/message/data.
Registry: Data asset mapping GameplayTags to endpoint specs.
Subsystem: Central HTTP service that applies consistent headers/auth/retries.
Adapter: Backend implementation that satisfies the NMF contract.
Token: Game auth token issued by your backend (not Steam’s ticket).

Changelog

v0.1 — Registry-driven HTTP contract, async call node, and subsystem-based request pipeline.

Support

Questions? Link your official support channel here (Discord, email, or ticket portal).

Netcade Multiplayer Framework (NMF)