Getting started

This guide is for people who write a game mode: server packages, client packages and assets. It uses tools/nextmp.cjs, which is the developer command in the source tree and in the server files. It needs Node.js 22 or newer.

node tools/nextmp.cjs help

On Windows, tools\nextmp.cmd runs the same command with the Node.js bundled next to it.

1. Create a project

node tools/nextmp.cjs init my-server --template typescript --sdk sdk

--sdk <dir> points the project at the SDK packages shipped in the server files (sdk/npm, sdk/nuget), so npm install and dotnet build work offline. Without it, the project asks the package registries for the matching version.

my-server/
  conf.json              server settings (docs/server-configuration.md)
  packages/gamemode/     a server package
  client_packages/       code sent to players; index.js requires each folder
  game_resources/dlcpacks/   DLC packs (*.rpf or <pack>/dlc.rpf)
  plugins/               trusted native plugins
  tests/                 unit tests with @nextmp/testing

2. Add more parts

node tools/nextmp.cjs create resource inventory --project my-server --typescript --depends core
node tools/nextmp.cjs create client-resource hud --project my-server
node tools/nextmp.cjs create plugin metrics --project my-server

A package folder starts from index.js by convention. An nextmp.json is optional and has exactly three keys: runtime (js or csharp), main, and dependencies, a list of package names that must start first.

{ "runtime": "js", "main": "dist/index.js", "dependencies": ["core", "database"] }

The server starts packages in dependency order and stops them in reverse. It refuses a missing dependency or a cycle and names it. A restart also restarts the packages that depend on the restarted one. Any other key in nextmp.json is an error, because a typo such as "mian" would otherwise leave a package without its entry point.

3. Test without the game

cd my-server
npm install
npm test               # or: node ../tools/nextmp.cjs test

Unit tests load your package into @nextmp/testing, which provides a documented subset of mp.* and fails loudly on anything else. See testing (docs/developer/testing.md) for the harness, bots and what each one can and cannot prove.

4. Run a server

From the project folder, with the server installed:

nextmp-server --config conf.json
node tools/nextmp.cjs config validate     # the server's own parser, no side effects
node tools/nextmp.cjs config describe     # every setting, its value and where it came from

To control a running server (start, stop or reload a package; resmon; tracing), enable the loopback admin service (docs/admin.md (docs/admin.md)) and use the resource and admin commands:

node tools/nextmp.cjs resource list --token-file operator.token
node tools/nextmp.cjs resource reload inventory --token-file operator.token

5. Debug

• Errors in packages name the resource, file, line, column, what the resource was doing (event or procedure) and the stack, mapped back to TypeScript through source maps.
• node tools/admin.cjs trace, events, resmon, net and inspect show what the server is doing without logging every packet.

All of it is described in debugging (docs/developer/debugging.md).

6. Assets

node tools/nextmp.cjs assets validate --manifest assets.json

See assets (docs/developer/assets.md).

7. Upgrading the platform

node tools/nextmp.cjs upgrade check            # findings only
node tools/nextmp.cjs upgrade check --fix      # also raises SDK versions in package.json

The check reports:

• SDK versions that differ from the platform;
• nextmp.json files the server would refuse;
• conf.json problems, using the server's own parser;
• deprecated calls, with file, line and column;
• calls to APIs this release does not have;
• release notes between your SDK version and the platform.

It never rewrites your code. --fix changes only package.json versions.

At run time, the first use of a deprecated API logs one line per resource and API, with its place in your source. On the server it is a warning; on the client it is debug-level, because players cannot act on it. Example: Resource gamemode uses deprecated toArrayFast at packages/gamemode/src/index.ts:12:28; use toArray instead.

The compatibility rules between clients, servers, launchers, plugins and packages are in the compatibility matrix (docs/compatibility-matrix.md).

SDK packages

The server files carry SDK packages built for that exact release:

Declaration packages contain no runtime code: the server provides mp itself. The C# package is a compile-time reference and is never copied next to your package, because the server binds every package to its own NextMP.Server.dll. Rebuild the packages from source with node tools/nextmp.cjs sdk pack --out dist/sdk.

Finding the API

• node tools/nextmp.cjs docs writes one offline page that searches every catalogued server and client API, mp.game.* natives and their status.
• Server API, client API, C# API, game natives (docs/compat/game-native-reference.md).
• Cookbook: small, type-checked examples.

Not covered by these tools

Nothing here launches GTA V or the in-game browser. Unit tests, bots and type checks prove server logic, protocol behaviour and API shapes. What a player sees in the game is covered by live certification, which is a separate step.