Documentation/NEXM Core
NEXM CORE / DEVELOPER DOCUMENTATION

NEXM Core

Server-first FiveM infrastructure SDK documentation for framework abstraction, player state, economy, inventory, RPC, notifications and restart-safe temporary appearance recovery.

1.0.0-rc.1.hotfix.4Release CandidateFree
Verified documentationUpdated from the supplied NEXM Core 1.0.0-rc.1.hotfix.4 package, including release, API, compatibility and validation documents.
NEXM CORE

Overview

Current runtime: 1.0.0-rc.1.hotfix.4

NEXM Core is a free, server-first FiveM infrastructure SDK for NEXM products. It normalizes framework/player lifecycle, money, inventory, RPC/security, notifications, localization, audit, services, integrations, components, migrations and diagnostics behind one stable Core contract.

Release scope

Public version 1.0.0-rc.1.hotfix.4, internal build mvp_rc1_tempappearance_7f2c4a91, release scope MVP_RC_TEMP_APPEARANCE_RECOVERY. This is still a release candidate, not final 1.0.0.

Framework adaptersESX · QBCore · Qbox
Verified runtime profiles5
Required DB dependencyoxmysql
ArchitectureServer-first SDK

Hotfix.4 keeps the validated framework/inventory matrix and adds generic restart-safe Temporary Appearance Recovery for NEXM-controlled temporary outfits. It is not a wardrobe, clothing shop, skin database or character creator.

NEXM CORE

Installation

Get NEXM Core from the official GitHub repository, place nexm_core in the server resources directory and configure config.lua. oxmysql must start before Core. Start the selected framework and any integrations required by your NEXM product before the dependent product.

Official GitHub repository

nexmstore/Nexm_Core ↗

Example ESX + ox_inventory order

SERVER.CFGcfg
ensure oxmysql
ensure ox_lib
ensure es_extended
ensure ox_inventory
ensure nexm_core
ensure <nexm_product>

Consumer resource manifest

Every NEXM consumer resource must load the Core import shim as a shared script before its own shared/server/client scripts.

FXMANIFESTLua
dependency 'nexm_core'
shared_script '@nexm_core/import.lua'

Acquire the Core facade

SERVER / CLIENTLua
local NEXM = exports['nexm_core']:GetCoreObject()
Core restart policy

Deploy hotfix.4 with a full FXServer restart because the Core/import build identity changes. nexm_core is not intended to be hot-restarted in production. Dependent resources such as nexm_notify may restart independently when their own contract allows it.

After startup, run nexm:status or nexm:status verbose from the server console.

NEXM CORE

Configuration

Config.Frameworkauto, supported framework name, or standalone policy.
Config.Inventoryauto, none, or a supported inventory adapter.
Config.Notifyauto, none, nexm_notify, ox_lib, esx, qbcore, qbox or custom. Shipped default: nexm_notify.
Config.NotifyFallbackAllows deterministic temporary fallback when the sticky primary provider is unavailable.
Config.NotifyPriorityOrdered preference such as { 'nexm_notify', 'ox_lib', 'framework' }.
Config.LocaleRequested locale; fallback defaults to en.
Config.Logging.levelMinimum local log level.
Config.AuditAudit enablement, backends, queue limits and optional webhook.

Startup validation rejects invalid selectors, locale identifiers, log levels, unsafe money/RPC limits, malformed network bounds and invalid audit settings with structured startup failure.

Temporary appearance settings

CONFIG.LUALua
Config.TemporaryAppearance = {
    restoreModel = true,
    modelLoadTimeoutMs = 5000,
    verifyDelayMs = 50,
    maxPayloadBytes = 16384,
    maxOwnerLength = 128,
    maxDrawable = 4096,
    maxTexture = 4096,
    maxPalette = 3
}
NEXM CORE / HOTFIX.4

Temporary Appearance Recovery

This service protects players from being stranded in a NEXM-controlled temporary outfit after resource restart, reconnect, abnormal disconnect, death flow or full FXServer restart.

Scope

It is generic recovery infrastructure, not a wardrobe, skin database, clothing shop, character creator or framework clothing compatibility layer.

Server-side records are cached in memory and persisted to data/temporary_appearances.json. Records are keyed by Core's canonical player identity and the calling resource owner. Disconnect does not clear a pending recovery record.

Before applying a temporary outfit

SERVERLua
local ok, resultOrErr = NEXM.TemporaryAppearance.Save(source, snapshot)
if not ok then
    -- Do not apply the temporary outfit.
    return
end

An existing owner record is preserved by default so a retry while the player is already in a temporary outfit does not overwrite the original civilian snapshot.

Recover and acknowledge

SERVERLua
local record, err = NEXM.TemporaryAppearance.Get(source)
if not record then return end

-- Restore record.appearance on the client.
-- Only after client restore + verification succeeds:
local ok, err = NEXM.TemporaryAppearance.AcknowledgeRestore(source)

If restore or verification fails, do not acknowledge it. The record remains available for another recovery attempt.

Client helpers

CLIENTLua
local snapshot, err = NEXM.TemporaryAppearance.Capture()
local ok, err = NEXM.TemporaryAppearance.Restore(snapshot)
local verified, err = NEXM.TemporaryAppearance.Verify(snapshot)

Version 1 snapshots store ped model hash, components 0..11 (drawable, texture, palette) and props 0..7 (drawable, texture). Persisted payloads are normalized and size-bounded.

Live product-flow gate

The supplied Core artifact records Core-only static and isolated harness validation as passed. Product-specific save/apply/restore/ack flows and full live FXServer product integration remain separate consumer-resource validation gates in the supplied release documentation.

NEXM CORE

Player & Jobs

NEXM.Player exposes normalized active-character snapshots and identifier helpers. Public helpers include Get, Exists, GetIdentifier, GetCharacterIdentifier, GetAccountIdentifier, GetLicense, GetCharacterName, GetJob, GetJobGrade, GetSource, IsOnline and GetFrameworkObject.

NEXM.Jobs exposes Get, Has, HasAny, MinimumGrade and IsOnDuty.

NEXM CORE

Money & Inventory

Money

Money is server-only. Public methods are Get, Add, Remove and CanAfford.

Inventory

Inventory is server-only and independent of framework selection. Public methods are HasItem, GetItemCount, AddItem, RemoveItem, CanCarry and GetItems.

qb-inventory intentionally does not claim metadata-filtering support. ESX native inventory also does not claim modern metadata-filtering semantics. qs-inventory has adapter architecture but is not included in the verified runtime matrix.

NEXM CORE

Permissions

Permissions are server-only and resource-owned. Public methods are Define, Has and HasAny.

SERVER EXAMPLELua
NEXM.Permissions.Define('manage', {
    mode = 'any',
    ace = { 'nexm.example.manage' },
    jobs = {
        police = {
            minimumGrade = 3,
            requireDuty = true
        }
    }
})

local allowed, err = NEXM.Permissions.Has(source, 'manage')
NEXM CORE

Public API

The 1.0 API freeze includes the following server namespaces:

RootIsReady · GetStatus
VersionGet · Compare · Satisfies · Require
ValidateShared validation helpers
LogDebug · Info · Warn · Error · IsEnabled
DBQuery · Single · Scalar · Insert · Update · Transaction
MigrationsRegister · Run
ResourcesRegister · IsRunning · Get · GetAll
ServicesRegister · Get · Has · GetMetadata
FeaturesRegister · Has · Get · GetMetadata
IntegrationsGetName · IsAvailable · GetCapabilities · GetState · IsHealthy
ComponentsGet · GetAll
PlayerGet · Exists · identifier / character / job / source helpers
TemporaryAppearanceSave · Get · Has · Clear · AcknowledgeRestore
JobsGet · Has · HasAny · MinimumGrade · IsOnDuty
MoneyGet · Add · Remove · CanAfford
InventoryHasItem · GetItemCount · AddItem · RemoveItem · CanCarry · GetItems
NotifySend
LocaleRegister · Get · SetFallback
AuditLog
CallbackRegister
RateLimitCheck · Reset
PermissionsDefine · Has · HasAny
EventsOnReady · On · Emit · player/job/duty lifecycle listeners

Client facade

The client facade is intentionally limited to Player, Callback.Await, Notify.Send, TemporaryAppearance.Capture/Restore/Verify, Locale, lifecycle Events, Validate and Version.Get.

Server authority

There is no client Money, Inventory, Permissions, Audit or RateLimit namespace. Sensitive authorization and mutations remain server-side.

NEXM CORE

Callbacks / RPC

The generic RPC direction is client → server → client response.

SERVER REGISTERLua
NEXM.Callback.Register('getData', function(source, payload, context)
    return { message = 'Hello' }
end, {
    permission = 'manage',
    requireCharacter = true
})
CLIENT AWAITLua
local data, err = NEXM.Callback.Await('getData', {})

Requests and responses are bounded, validated, rate-limited and session-aware.

NEXM CORE

Notifications

Core exposes one normalized notification API:

SERVERLua
NEXM.Notify.Send(source, message, type, duration, options)
CLIENTLua
NEXM.Notify.Send(message, type, duration, options)

The hotfix.4 package retains the notification-provider behavior from the validated hotfix.3/hotfix.2 line. The shipped production default is nexm_notify, with fallback support for existing providers.

Recorded NEXM Notify baseline

The supplied Core package documents nexm_notify v1.0.3 as the recommended provider baseline. The separate Notify v1.4.0 package keeps the existing notification exports/events compatible, retains the owner-aware multi-prompt handling introduced in v1.3.0, and adds reusable world-space UI panels.

NEXM CORE

Compatibility

The supplied Core release records five framework/inventory profiles as verified in a real FiveM runtime:

ProfileFrameworkInventoryNotifyStatus
A_ESX_OXESXox_inventoryox_libVerified / live tested
B_QB_QBINVQBCoreqb-inventoryQBCoreVerified / live tested
C_QB_OXQBCoreox_inventoryox_libVerified / live tested
D_QBOX_OXQboxox_inventoryQbox / ox_libVerified / live tested
E_ESX_NATIVEESXESX nativeESXVerified / live tested
N_NATIVE_NOTIFYAny supported frameworkAny supported inventorynexm_notify v1.0.3Supported / recommended
Important distinction

The supplied compatibility matrix does not claim separate live-certification evidence for N_NATIVE_NOTIFY. Adapter availability and live qualification are tracked separately.

NEXM CORE

Validation Status

For hotfix.4 itself, the supplied validation report records:

Lua syntax73 / 73 PASS, 0 FAIL.
Manifest path audit72 / 72 local Lua paths present.
Version/build coherencePASS.
Persistence JSON schemaPASS.
Server isolated harnessDuplicate-save preservation, reconnect lookup, owner isolation, clear-one-owner-only and persistence rollback: PASS.
Client isolated harnessCapture, restore/verify, safe model mismatch and configured model recovery: PASS.
Not claimed by this Core-only artifact

Real FXServer product integration tests for the new Temporary Appearance Recovery flow are marked pending in the supplied TEST_RESULTS.md. The earlier five-profile framework/inventory runtime matrix remains the validated runtime baseline.

NEXM CORE

Troubleshooting

nexm:statusCore/component state overview.
nexm:status verboseCapabilities, resource requirements, service/API versions, integration states, pending RPC/rate counts and audit queue metrics.
Inventory DISABLEDIntentional Config.Inventory='none'.
Inventory UNAVAILABLENo usable automatic inventory; Core can remain READY.
Notify UNAVAILABLECore remains READY; check provider, fallback policy and client resources.
CAPABILITY_UNAVAILABLEA product requirement exceeds the selected adapter capability.
Audit DEGRADEDInspect DB/webhook/custom backend state; gameplay remains independent.
Migration checksum mismatchAn applied historical migration changed and must not be silently overwritten.

Temporary appearance debug

With Config.Debug = true, /nexmtempappearance reports safe summary data about pending recovery records. It does not print canonical identifiers to the player console.

SUPPORT

Need help with NEXM Core?

Use the support page for installation, compatibility or API questions.

Open Support