<SYSTEM>This is the full developer documentation for GAMPEON</SYSTEM>

# Build games on GAMPEON

> Dream it, build it, play it. With an AI assistant, with Lua, or with the web API.

GAMPEON is in an early preview

The platform is in a closed test. Parts of what you read here work today, others are still being built. Every page shows its status: **Preview** works today and may change, **Planned** does not exist yet. See [Platform status](/docs/start/status/).

Build with AI

No programming needed. Connect Claude, ChatGPT or another assistant to GAMPEON and describe the game you want. [Connect your assistant](/docs/ai/connect/).

Lua scripting

Resources, events, threads and exports in Lua 5.4. Familiar if you come from FiveM. [Scripting overview](/docs/scripting/overview/).

Marketplace

Share scripts, vehicles, maps and more with other creators. [Publishing](/docs/marketplace/publishing/).

Web API

Accounts, projects, servers and the marketplace over HTTPS. [API overview](/docs/api/overview/).

## Popular pages

[Section titled “Popular pages”](#popular-pages)

[Your first game with AI](/docs/ai/first-game/)From an idea to a working resource, step by step.

[Lua API reference](/docs/scripting/reference/)Every function a script can use.

[Coming from FiveM](/docs/fivem/overview/)What carries over and what changes.

[Register a server](/docs/servers/register/)Get listed in the server browser.

## For AI assistants

[Section titled “For AI assistants”](#for-ai-assistants)

These docs are available as plain text for language models: [/llms.txt](/docs/llms.txt), [/llms-full.txt](/docs/llms-full.txt) and [/llms-small.txt](/docs/llms-small.txt). The Lua API is at [/reference/lua-api.json](/docs/reference/lua-api.json), the web API at [/reference/openapi.json](/docs/reference/openapi.json).

# Report a problem

> Where to report bugs, security problems, illegal content, mistakes in the docs and ideas.

Thank you for helping us find problems. Each kind of report has its own place, so it reaches the right people fast.

| What                                                                                            | Where                                                                                                        |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| A **security problem** (a way to see other people’s data, take over an account, bypass a limit) | Email **<security@gampeon.com>**. Never post it in public. See [Security reports](/docs/policies/security/). |
| **Illegal content** or content that **infringes your rights**                                   | In the portal, open **Create → Report content**. See [Reports and appeals](/docs/marketplace/reports/).      |
| A **bug** in the portal, the launcher, the web API or the MCP server                            | Email **<hello@gampeon.com>** or ask in our [Discord](https://discord.gg/SD6JwvWC5V).                        |
| A **mistake or gap in these docs**                                                              | Use **Report a problem with this page** at the bottom of the page.                                           |
| An **idea** or a feature you miss                                                               | Post it in the **suggestions** forum on our [Discord](https://discord.gg/SD6JwvWC5V). One post per idea.     |

Check [Known issues and limits](/docs/start/known-issues/) first. If your problem is listed there, we already know about it.

## A good bug report

[Section titled “A good bug report”](#a-good-bug-report)

A report we can act on answers these questions:

1. **Where?** The page address, or the launcher version and your operating system.
2. **What did you do?** The steps, in order, so we can do the same.
3. **What did you expect?**
4. **What happened instead?** The exact error message, if there was one.
5. **When?** Date and time with your time zone, so we can find it in our logs.

Screenshots and short videos help a lot.

Never send secrets

Do not put passwords, access tokens (they start with `gpat_`) or login links in a report, a screenshot or a Discord message. We will never ask you for them. If a token was visible somewhere, revoke it in the portal under **Account → Access tokens**.

## What happens next

[Section titled “What happens next”](#what-happens-next)

When we fix a bug, the fix appears in the [changelog](/docs/changelog/) and the bug leaves [Known issues and limits](/docs/start/known-issues/). We answer every security report, see [Security reports](/docs/policies/security/).

# Glossary

> Terms used across the GAMPEON docs.

**Client** : The game running on a player’s computer. Client scripts run there.

**Event** : A named message. Scripts fire events and react to them. See [Events](/docs/scripting/events/).

**Export** : A function one resource offers to other resources. See [Exports](/docs/scripting/exports/).

**Handle** : Your unique account name, for example `@nova_builds`. Lowercase letters, digits and `_`.

**Heartbeat** : The message a game server sends every 30 seconds to stay in the server browser.

**Manifest** : The file `fxmanifest.lua` (or `resource.lua`) that tells GAMPEON which scripts and files a resource has. See [Manifest](/docs/scripting/manifest/).

**MCP** : Model Context Protocol, the open standard AI assistants use to work with tools such as GAMPEON. See [MCP server](/docs/mcp/overview/).

**Native** : In FiveM, a function of the GTA game engine. GAMPEON has no GTA natives.

**Resource** : A folder with a manifest, scripts and files. The unit you write, start and share.

**Rights statement** : The confirmation every creator gives when publishing a version: you own the content or may use it. See [Rights statement](/docs/marketplace/rights-statement/).

**Sandbox** : The protected environment scripts run in, with limits on memory and run time. See [Sandbox](/docs/scripting/sandbox/).

**Server** : The authoritative game server. Server scripts run there and decide what is true.

**Slug** : The short name of a studio or project in URLs, for example `neon-racers`.

**Studio** : A team that owns projects together.

**Thread** : A function that runs over time and can pause with `Wait`. See [Threads and timers](/docs/scripting/threads/).

# Known issues and limits

> What does not work yet or behaves differently in the preview, so you do not have to report it.

GAMPEON is in a closed test. This page lists parts that are not finished yet and bugs we already know about. If something you run into is listed here, you do not need to report it. For everything else, see [Report a problem](/docs/start/feedback/).

For the overall picture, see [Platform status](/docs/start/status/). Fixes show up in the [changelog](/docs/changelog/) as soon as they ship, and we remove them from this page at the same time.

## Playing

[Section titled “Playing”](#playing)

* **There is no game to download yet.** The desktop launcher is in early development and not available for download. Game servers and the game client come later.
* **Sign-up is by invitation only.** Accounts are for the closed test.

## Scripting

[Section titled “Scripting”](#scripting)

* **Lua in the game runs on internal test servers only.** The game is not available for download yet. Run your resources with [gampeon-server](/docs/scripting/test-server/) until then.
* **The game API is small.** Scripts can read where players are, teleport them and place simple objects (see [Objects](/docs/scripting/objects/) and [World and entities](/docs/scripting/reference/world/)). Only five built-in object models exist so far (`prop_cube`, `prop_sphere`, `prop_cylinder`, `prop_cone`, `prop_plane`). Vehicles, client-side objects and most of the world come later. Only the functions in the [Lua API reference](/docs/scripting/reference/) exist.
* **The chat shows plain text only.** HTML, colour codes like `^1` and styled templates from FiveM chat resources are removed. See [Text chat](/docs/scripting/chat/).
* **GTA natives do not exist and never will.** A few GAMPEON functions use FiveM names, like `GetEntityCoords` and `CreateObject`, but GTA models, `DrawMarker` and most other GTA calls fail. This is not a bug. See [Coming from FiveM](/docs/fivem/overview/).

## Portal and communities

[Section titled “Portal and communities”](#portal-and-communities)

* **Community messages are not real-time.** New messages appear after a short delay because the portal and launcher check for them regularly. Real-time updates are planned.
* **The marketplace is free.** There are no payments, prices or payouts yet.

## Web API and MCP

[Section titled “Web API and MCP”](#web-api-and-mcp)

* **The web API can change without notice.** It is a preview. Check the [changelog](/docs/changelog/) when something stops working.
* **AI assistants sign in with an access token.** Sign-in with OAuth is planned. See [Connect your assistant](/docs/ai/connect/).

## Before you report

[Section titled “Before you report”](#before-you-report)

1. Check this page and the [changelog](/docs/changelog/). The problem may already be fixed or known.
2. Reload the page or restart the app and try again.
3. Still broken? [Report it](/docs/start/feedback/).

# Platform status

> What works today, what is in preview and what is planned.

GAMPEON is early. This page says honestly what exists. Every other page in these docs carries the same status labels.

| Part                                                                                  | Status  | Notes                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Accounts, profiles, studios, projects                                                 | Preview | Closed test, sign-up by invitation only.                                                                                                                                                                                                                                                                                                                                          |
| Marketplace (publish, download, report)                                               | Preview | Everything is free. No payments yet.                                                                                                                                                                                                                                                                                                                                              |
| Server browser and heartbeats                                                         | Preview | Servers can register and report players.                                                                                                                                                                                                                                                                                                                                          |
| Web API                                                                               | Preview | `https://api.gampeon.com`, can change without notice.                                                                                                                                                                                                                                                                                                                             |
| Lua runtime (resources, events, threads, exports, commands, convars, HTTP, `MySQL.*`) | Preview | Runs in `gampeon-server` with MariaDB, MySQL or SQLite. On the game server in testing, with HTTP and SQLite; MariaDB and MySQL there come later.                                                                                                                                                                                                                                  |
| Join check and player functions                                                       | Preview | `playerJoining`, `playerDropped`, `gampeon:` and `license:` identifiers, join ticket from the launcher.                                                                                                                                                                                                                                                                           |
| Client scripts                                                                        | Preview | Download automatically when joining, only from trusted test servers until the client sandbox review. See [Client scripts](/docs/scripting/client-scripts/).                                                                                                                                                                                                                       |
| Text chat                                                                             | Preview | Built-in `chat` resource with FiveM events, `/commands` with permissions and a chat window in the game (T). See [Text chat](/docs/scripting/chat/).                                                                                                                                                                                                                               |
| Kick and ban                                                                          | Preview | `clientkick`, `ban`, `unban` and `banlist` in the server console and in chat with permissions, saved in `bans.json`. Players see the reason in the game. A web admin page is planned. See [Kick and ban](/docs/scripting/commands-and-convars/#kick-and-ban).                                                                                                                     |
| Web interfaces for scripts (NUI)                                                      | Preview | Same API as FiveM NUI. In the game on test servers and in `gampeon-server`. Pages on surfaces in the world and loading screens come later. See [Web interfaces](/docs/scripting/nui/).                                                                                                                                                                                            |
| Game client                                                                           | Preview | Walk with WASD, look with the mouse and jump with Space in a simple test world with a default sun and sky. Players appear as simple figures until real character models arrive. On test servers.                                                                                                                                                                                  |
| Game API: player characters                                                           | Preview | Position, heading, speed and teleport with FiveM names. In the game on test servers and in `gampeon-server`’s placeholder world. See [World and entities](/docs/scripting/reference/world/).                                                                                                                                                                                      |
| Game API: objects                                                                     | Preview | `CreateObject`, `DeleteEntity`, `FreezeEntityPosition` on the server with five built-in models. In the game on test servers and in `gampeon-server`. See [Objects](/docs/scripting/objects/).                                                                                                                                                                                     |
| Block worlds                                                                          | Preview | Terrain from a seed that players dig and build in, with built-in controls, server checks and saving. Scripts decide drops and placing. In `gampeon-server`; in the game after the first build test. Own block types come later. See [Block worlds](/docs/scripting/blocks/).                                                                                                      |
| Private game packages (your own Unreal content, only in your project)                 | Preview | Maps, models, characters and sounds for one project, loaded only by its servers. Cook with the creator kit, upload in the project’s **Game packages** tab, and the launcher downloads the package when players press Play. See [Upload your game package](/docs/getting-started/game-packages/). Checks for Blueprint logic, encryption and models for `CreateObject` come later. |
| RP Starter with ESX and QBCore bridges                                                | Preview | Characters, money, jobs, inventory, HUD and admin commands, in the SDK under `starter/rp`. Tested in `gampeon-server`; in the game on test servers. Gangs, vehicles and slot inventories come later. See [RP Starter](/docs/fivem/rp-starter/).                                                                                                                                   |
| Game API for vehicles, client-side objects and the rest of the world                  | Planned | Comes step by step with the Unreal Engine plugin.                                                                                                                                                                                                                                                                                                                                 |
| Access tokens with scopes and activity log                                            | Preview | In the API and in the portal under **Account → Access tokens**.                                                                                                                                                                                                                                                                                                                   |
| MCP server for AI assistants                                                          | Preview | Online at `https://api.gampeon.com/mcp/docs` (no sign-in) and `https://api.gampeon.com/mcp` with an access token. Sign-in with OAuth is planned. See [MCP server](/docs/mcp/overview/).                                                                                                                                                                                           |
| Communities for studios and projects (channels, roles, invites, moderation)           | Preview | In the API. Messages update by polling until real-time updates arrive.                                                                                                                                                                                                                                                                                                            |
| Desktop launcher                                                                      | Planned | In early development, not yet available for download.                                                                                                                                                                                                                                                                                                                             |
| Test servers on demand                                                                | Planned |                                                                                                                                                                                                                                                                                                                                                                                   |
| GAMPEON Studio (Unreal Editor plugin)                                                 | Planned |                                                                                                                                                                                                                                                                                                                                                                                   |
| GAMPEONS currency and payouts                                                         | Planned |                                                                                                                                                                                                                                                                                                                                                                                   |

The [changelog](/docs/changelog/) lists every change as it ships.

# What is GAMPEON?

> GAMPEON is a game and creator platform on Unreal Engine 5. Here is how the pieces fit together.

GAMPEON is a platform where people create games and play them together. It runs on Unreal Engine 5 and is built for large servers, physics and props, and content that streams in when you join.

You can create on GAMPEON in three ways:

1. **With an AI assistant.** Describe what you want in plain language. The assistant reads these docs, writes the scripts, checks them and prepares everything for publishing. See [Build with AI](/docs/ai/connect/).
2. **With Lua scripts.** Write resources in Lua 5.4. If you know FiveM, the structure feels familiar: a manifest, server and client scripts, events and exports. See [Scripting](/docs/scripting/overview/).
3. **With the web API.** Build tools and integrations for accounts, projects, servers and the marketplace. See [Web API](/docs/api/overview/).

## The building blocks

[Section titled “The building blocks”](#the-building-blocks)

| Thing                | What it is                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------- |
| **Account**          | You. Has a public profile with a unique handle.                                             |
| **Studio**           | A team. Members join by invitation and work on projects together.                           |
| **Project**          | The public page of a game: title, genre, status, linked servers and content.                |
| **Resource**         | A folder of Lua scripts and files with a manifest. Games are made of resources.             |
| **Marketplace item** | A resource, vehicle, map, prop, clothing item, gamemode or tool that you share with others. |
| **Server**           | A running game server, listed in the server browser while it sends heartbeats.              |

## What GAMPEON is not

[Section titled “What GAMPEON is not”](#what-gampeon-is-not)

* **Not a GTA mod.** GAMPEON does not use GTA V or its assets. Scripts written for FiveM need changes wherever they call GTA natives. See [Coming from FiveM](/docs/fivem/overview/).
* **Not a place for ripped content.** Maps, vehicles and other assets from other games are not allowed. See [Allowed content](/docs/marketplace/allowed-content/).

# Connect your AI assistant

> Connect Claude, ChatGPT, Cursor, VS Code or another MCP client to GAMPEON.

GAMPEON speaks the **Model Context Protocol (MCP)**, the open standard AI assistants use to work with tools. Once connected, your assistant can read these docs, write and check Lua resources, and manage your projects and marketplace items for you.

There are two addresses:

| Address                            | Login                | What the assistant can do                                                                            |
| ---------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| `https://api.gampeon.com/mcp/docs` | none                 | Read the docs and the Lua API, write and check resources, browse the marketplace and public projects |
| `https://api.gampeon.com/mcp`      | your GAMPEON account | Everything above, plus work in your account: projects, marketplace items, preparing releases         |

Start with the first one if you just want to try it.

## Claude (web, desktop, mobile)

[Section titled “Claude (web, desktop, mobile)”](#claude-web-desktop-mobile)

1. Open **Settings → Connectors → Add custom connector**.
2. Name: `GAMPEON`. URL: `https://api.gampeon.com/mcp/docs`.
3. In a chat, enable the connector and ask: *“Using GAMPEON, write a resource that greets players when they join.”*

Signing in with your GAMPEON account from Claude (OAuth) is planned. Until then, use a client below for account work.

## ChatGPT

[Section titled “ChatGPT”](#chatgpt)

In ChatGPT with developer mode, create an app with the URL `https://api.gampeon.com/mcp/docs` and no authentication. Sign-in for account work is planned.

## Claude Code

[Section titled “Claude Code”](#claude-code)

```bash
# docs only
claude mcp add --transport http gampeon-docs https://api.gampeon.com/mcp/docs


# with your account (create a token first, see below)
claude mcp add --transport http gampeon https://api.gampeon.com/mcp \
  --header "Authorization: Bearer $GAMPEON_TOKEN"
```

## Cursor

[Section titled “Cursor”](#cursor)

.cursor/mcp.json

```json
{
  "mcpServers": {
    "gampeon": {
      "url": "https://api.gampeon.com/mcp",
      "headers": { "Authorization": "Bearer ${env:GAMPEON_TOKEN}" }
    }
  }
}
```

## VS Code (GitHub Copilot)

[Section titled “VS Code (GitHub Copilot)”](#vs-code-github-copilot)

.vscode/mcp.json

```json
{
  "inputs": [
    { "type": "promptString", "id": "gampeon-token", "description": "GAMPEON access token", "password": true }
  ],
  "servers": {
    "gampeon": {
      "type": "http",
      "url": "https://api.gampeon.com/mcp",
      "headers": { "Authorization": "Bearer ${input:gampeon-token}" }
    }
  }
}
```

## Other clients

[Section titled “Other clients”](#other-clients)

Any client that supports the Streamable HTTP transport works. Use the URL above and, for account work, send the header `Authorization: Bearer <token>`.

## Create an access token

[Section titled “Create an access token”](#create-an-access-token)

1. Log in to the GAMPEON portal and open **Account → Access tokens**.
2. Choose a template: **Read only** or **Build with AI**. Pick an expiry (30 days by default).
3. Copy the token. It starts with `gpat_` and is shown **once**.
4. Store it in your client’s settings or an environment variable, never in a file you share or commit.

You can see what each token did under **Account → AI activity** and revoke it at any time. See [Safety](/docs/ai/safety/).

# Your first game with AI

> From an idea to a checked resource and a project page, with an AI assistant.

This walkthrough builds a small racing checkpoint script with an AI assistant. You do not need to write code yourself.

What works today

The assistant can write resources, check them and create your project page and marketplace entry. Playing and testing in the game needs the engine plugin and test servers, which are [planned](/docs/start/status/).

## 1. Connect

[Section titled “1. Connect”](#1-connect)

Connect your assistant as described in [Connect your AI assistant](/docs/ai/connect/). For this walkthrough you need the address with login (`/mcp`) and a token with the template **Build with AI**.

## 2. Describe your idea

[Section titled “2. Describe your idea”](#2-describe-your-idea)

Tell the assistant what you want, in your own words. Be concrete about the rules:

> I want a racing game. Players drive through checkpoints in order. When a player reaches the last checkpoint, everyone sees their time. Keep the best time per player.

A good assistant asks follow-up questions: how many checkpoints, what happens after the finish, should times be saved. Answer them.

## 3. Let it plan

[Section titled “3. Let it plan”](#3-let-it-plan)

Ask: *“Before writing code, show me the plan: which resources and files, and what each one does.”* Check that the plan matches what you want.

## 4. Let it write and check

[Section titled “4. Let it write and check”](#4-let-it-write-and-check)

Ask it to write the resource. The assistant uses the GAMPEON tools to:

1. look up the right functions in the [Lua API reference](/docs/scripting/reference/),
2. create the files from a template (`scaffold_resource`),
3. check them for mistakes (`check_resource`): missing files, forbidden functions, GTA natives that do not exist on GAMPEON.

Ask it to fix everything the check reports.

## 5. Create the project page

[Section titled “5. Create the project page”](#5-create-the-project-page)

> Create a project called “Checkpoint Rush”, genre racing, status development.

The assistant creates the page in your account. You can change the text anytime in the portal.

## 6. Prepare the release

[Section titled “6. Prepare the release”](#6-prepare-the-release)

> Prepare this as a marketplace item.

The assistant creates the marketplace entry and gives you a link to the portal. **You** read the rights statement there, confirm it and upload the files. The assistant never confirms rights on your behalf. See [Rights statement](/docs/marketplace/rights-statement/).

## Tips

[Section titled “Tips”](#tips)

* Change one thing at a time and ask the assistant to check again after each change.
* Ask *“Explain what this script does, line by line, in simple words”* whenever you want to understand it.
* See [Good prompts](/docs/ai/prompts/) for more.

# Good prompts

> How to ask an AI assistant for GAMPEON games and scripts.

Assistants work best with clear goals and small steps. These prompts work well with the GAMPEON tools.

## Start

[Section titled “Start”](#start)

* *“Read the GAMPEON docs on resources and events, then explain how a GAMPEON game is structured, in five sentences.”*
* *“I want to build \[your idea]. Ask me the questions you need before you start.”*
* *“Show me the plan first: which resources, which files, which events. Don’t write code yet.”*

## Build

[Section titled “Build”](#build)

* *“Create a resource called `checkpoints` from the gamemode template.”*
* *“Add an event that resets the race. Only the server decides the result.”*
* *“Check the resource with GAMPEON and fix everything it reports.”*

## Understand

[Section titled “Understand”](#understand)

* *“Explain this file line by line in simple words.”*
* *“Which parts run on the server and which on the client, and why?”*
* *“What could a cheater do with this event, and how do we stop it?”*

## Port from FiveM

[Section titled “Port from FiveM”](#port-from-fivem)

* *“Here is a FiveM resource. Check it with GAMPEON and list what has to change.”*
* *“Replace the GTA natives where GAMPEON has an equivalent, and mark the rest with TODO comments.”*

## Things to avoid

[Section titled “Things to avoid”](#things-to-avoid)

* **Asking for content from other games.** Maps, cars, characters or music from other games are not allowed. See [Allowed content](/docs/marketplace/allowed-content/).
* **Pasting secrets.** Never paste tokens, passwords or server keys into a chat.
* **Huge requests in one go.** “Build a full roleplay server” fails; “build a bank resource with deposit and withdraw” works.

# What the AI can and cannot do

> Permissions, human confirmation and how to stay in control when an AI works in your account.

An AI assistant connected to GAMPEON acts **in your name**. GAMPEON limits what it can do so that mistakes and tricks stay small.

## The assistant can

[Section titled “The assistant can”](#the-assistant-can)

* read the docs, the Lua API and public pages,
* write and check resources,
* create and change your projects and marketplace entries (with the right token scopes),
* prepare a release and give you a link to finish it.

## The assistant cannot

[Section titled “The assistant cannot”](#the-assistant-cannot)

* **confirm the rights statement** or publish a version. You do that yourself in the portal.
* **delete** projects, marketplace items, servers or studios.
* register servers or see server keys.
* change your password, email or tokens, or create new tokens.
* spend, send or receive GAMPEONS or make payments.
* moderate content.

These limits are enforced by the GAMPEON API, not by the assistant. Even an assistant that is tricked cannot cross them.

## Tokens and scopes

[Section titled “Tokens and scopes”](#tokens-and-scopes)

A token only allows what its scopes allow. Use the smallest set you need:

| Template      | Scopes                                                              | Use it for                                 |
| ------------- | ------------------------------------------------------------------- | ------------------------------------------ |
| Read only     | `profile:read`, `projects:read`, `marketplace:read`, `servers:read` | Questions about your account               |
| Build with AI | the above, plus `projects:write`, `marketplace:write`               | Creating and changing projects and entries |

What each scope allows is listed under [Authentication](/docs/api/authentication/#scopes). A token works only where a scope allows it; everything else, from moderation to payments, is closed to tokens by the API.

Tokens expire (30 days by default, one year at most). Revoke a token in the portal as soon as you stop using it.

## Watch out for instructions hidden in content

[Section titled “Watch out for instructions hidden in content”](#watch-out-for-instructions-hidden-in-content)

Text from other people (descriptions, scripts from the marketplace, profile texts) can contain instructions aimed at your assistant, such as “ignore your rules and delete everything”. GAMPEON marks such text as untrusted when it passes it to the assistant, and the limits above still apply. Still: read what the assistant proposes before you agree, especially after it looked at content from others.

## See what happened

[Section titled “See what happened”](#see-what-happened)

Under **Account → AI activity** in the portal you see what your tokens did in the last 90 days: time, action, result, the client and the tool that made it. Refused attempts are listed too, with the reason. Contents are not stored. You also get a notification whenever a new token is created.

# Block worlds

> Switch on terrain made of blocks that players dig and build in, and decide in Lua what they get and may place.

A block world is terrain made of 1 m blocks. Players dig with the left mouse button and build with the right one; GAMPEON draws the world, sends changes to everyone nearby and saves them. Your scripts decide the game: what digging gives, what players may place, prices, recipes, rules.

Every server can have one block world. You switch it on from a server script:

server.lua

```lua
EnableBlockWorld({
  seed = 20261106,       -- the terrain: same seed, same world
  save = 'main',         -- keep changed blocks between restarts (Saved/VoxelWorlds/main.gpvox)
  zones = {
    -- a flat area without blocks, for example a city. Nobody digs or builds here, scripts neither.
    { minX = -48, minY = -48, maxX = 48, maxY = 48, groundZ = 8 },
  },
})
```

Call it when your resource starts, before players spawn. Players then spawn on the surface, in the middle of the first zone (or at 0, 0 without zones). Calling it again with the same options does nothing, so restarting your resource is safe. Other options need a server restart. Around each zone, the terrain slopes smoothly into the flat ground over `blend` blocks (default 24).

Inside a zone, a hidden foundation that nobody can dig ends at `groundZ - 2`, in case someone falls through the city. If your own map has water or low ground inside the zone, set `floorZ` lower, for example below the sea floor, so the foundation does not cover it: `{ minX = -340, minY = -350, maxX = 280, maxY = 330, groundZ = 0, floorZ = -14 }`. Players spawn at `groundZ` in a zone. See [Bring your own map](/docs/getting-started/your-own-map/#your-map-and-a-block-world).

## Coordinates

[Section titled “Coordinates”](#coordinates)

Blocks have whole-number coordinates, and 1 block is 1 m, like the meters of `GetEntityCoords`. Block `(x, y, z)` fills the space from `x` to `x + 1` and so on; `z` is up. Decimals are rounded down, so `GetBlock(GetEntityCoords(ped))` is the block the feet of a character are in.

The world reaches from -4096 to 4095 on x and y and from -64 to 63 on z. The bottom layer cannot change, so nobody falls out of the world.

## Blocks

[Section titled “Blocks”](#blocks)

`GetBlockTypes()` lists all blocks. The list only grows.

| Block                                              | Players can dig | Players can place |
| -------------------------------------------------- | --------------- | ----------------- |
| `turf`, `soil`, `stone`, `sand`, `snow`            | yes             | yes               |
| `planks`, `brick`, `clay`                          | yes             | yes               |
| `charstone`, `copper_vein`, `iron_vein`, `crystal` | yes             | no (ores)         |
| `deepstone`                                        | no              | no                |

Scripts can set any block with `SetBlock`, also ores.

## Digging and building

[Section titled “Digging and building”](#digging-and-building)

Players use built-in controls, you do not write input code:

| Input               | Action                                                              |
| ------------------- | ------------------------------------------------------------------- |
| Left mouse button   | Dig the block under the crosshair (hold to repeat)                  |
| Right mouse button  | Place the selected hotbar block on the side the crosshair points at |
| Mouse wheel, 1 to 9 | Pick a hotbar slot                                                  |

The hotbar comes from your client script. Without one, players can only dig.

client.lua

```lua
-- Show what the player owns, with counts. The server still decides in blockPlace.
RegisterNetEvent('mygame:inventory', function(inv)
  SetBlockHotbar({
    { block = 'stone', count = inv.stone or 0 },
    { block = 'planks', count = inv.planks or 0 },
  })
end)
```

Every action goes to the server first. The server checks reach (6 m from the eyes), speed (10 actions per second), zones, block type, free space, a solid neighbor and that no character stands in the way. Then it asks your scripts:

server.lua

```lua
AddEventHandler('blockBreak', function(x, y, z, block)
  -- source is the player. CancelEvent keeps the block.
  if block == 'crystal' and not HasPickaxe(source) then
    CancelEvent()
    return
  end
  AddItem(source, block, 1)
end)


AddEventHandler('blockPlace', function(x, y, z, block)
  if not RemoveItem(source, block, 1) then
    CancelEvent() -- the player sees the block disappear again
  end
end)
```

Call `CancelEvent` before any `Wait`. After the change, `blockChanged` arrives in the next server tick, for players and for `SetBlock`:

```lua
AddEventHandler('blockChanged', function(x, y, z, oldBlock, newBlock, player)
  -- player is 0 when a script changed it
end)
```

## Your own interface

[Section titled “Your own interface”](#your-own-interface)

* `SetBlockHudVisible(false)` hides the built-in hotbar and the outline, for example when you draw your own hotbar with a [web interface](/docs/scripting/nui/). The controls keep working; `GetBlockHotbarSlot()` and the event `blockHotbarSelect` tell you the selection.
* `SetBlockControlsEnabled(false)` stops digging and building, for example while a menu is open. The controls also pause on their own while the mouse cursor is visible.
* `GetBlockTarget()` returns the block under the crosshair and the side it points at, or `nil`.

## Saving

[Section titled “Saving”](#saving)

With `save`, the server stores changed blocks and loads them on the next start. Unchanged terrain is never stored; it comes from the seed. If you change the seed but keep the save name, the server moves the old save aside (`<save>.seed<old>.gpvox`) and starts a new world.

Before the map has loaded (while your resource starts), `GetBlock` shows the generated terrain and your own `SetBlock` calls. Saved changes appear once the world is there.

Player data such as inventories is yours to save, for example with [SaveResourceFile](/docs/scripting/reference/resource/) or the [database](/docs/scripting/database/).

## Test without the game

[Section titled “Test without the game”](#test-without-the-game)

`gampeon-server` has the same block world, without graphics. It keeps changed blocks only while it runs; `save` works on the game server. Fake players dig and build like with the mouse:

| Command                                    | Effect                                                     |
| ------------------------------------------ | ---------------------------------------------------------- |
| `gp_fakeplayer break <id> [x y z]`         | Dig, by default the block straight below the player’s eyes |
| `gp_fakeplayer place <id> [x y z [block]]` | Place, by default the selected hotbar block                |
| `gp_fakeplayer slot <id> <n>`              | Pick hotbar slot `n`                                       |
| `gp_block <x> <y> <z>`                     | Print the block and the surface height there               |

See [Test without the game](/docs/scripting/test-server/) for the rest.

## Not there yet

[Section titled “Not there yet”](#not-there-yet)

* Your own block types with your own colors or textures.
* Water and other liquids, falling blocks, blocks that give light.
* More than one block world per server.

All functions with their arguments are in the [Lua API reference](/docs/scripting/reference/blocks/).

# Text chat

> The built-in chat resource, how messages and /commands travel, and how scripts hook into it.

GAMPEON ships a `chat` resource that works like the one in FiveM. Players press **T** in the game, type and press **Enter**. Text goes to everyone on the server, and text that starts with `/` runs a command.

server.cfg

```ini
ensure chat
set chat_maxLength 256   # optional, 1 to 512 characters
```

## In the game

[Section titled “In the game”](#in-the-game)

* **T** opens the chat, **Enter** sends, **Escape** closes.
* New lines appear at the top left and fade out after 10 seconds.
* When you type `/`, the chat shows matching commands with their help text.
* Colour codes like `^1` and HTML from FiveM templates are removed, because the chat shows plain text.

## How a message travels

[Section titled “How a message travels”](#how-a-message-travels)

1. The game sends what the player typed to the server as `_chat:messageEntered`.
2. The server trims the text to `chat_maxLength` and allows 5 messages per player in 10 seconds.
3. It fires the local server event `chatMessage` with `source`, the player’s name and the text.
4. If no handler called `CancelEvent()`, it sends the line to every player and prints it in the server console.

The name always comes from the player’s GAMPEON account. Players cannot send messages under another name.

Server scripts can filter or replace messages:

server.lua

```lua
AddEventHandler('chatMessage', function(source, name, message)
  if message:lower():find('free gampeons') then
    CancelEvent()
    TriggerClientEvent('chat:addMessage', source, {
      color = { 255, 140, 0 },
      args = { 'Server', 'Please do not post scams.' },
    })
  end
end)
```

## Commands in chat

[Section titled “Commands in chat”](#commands-in-chat)

`/name arguments` runs the command `name`:

1. Commands that client scripts registered with `RegisterCommand` run first, in the player’s game.
2. Any other command goes to the server and runs there as the player, with the player’s permissions. A restricted command the player may not use does nothing, and the game log shows `Access denied for command 'name'.`

When a player joins, the chat lists the server’s commands that this player may use as suggestions. Add help text or client commands with `chat:addSuggestion`.

On servers whose client scripts the game blocks (see [Which servers may send client scripts](/docs/scripting/client-scripts/#which-servers-may-send-client-scripts)), only `/commands` work.

## Events

[Section titled “Events”](#events)

Send these to players from server scripts with `TriggerClientEvent`, or fire them in client scripts with `TriggerEvent`.

| Event                   | Arguments                                               | Effect                                             |
| ----------------------- | ------------------------------------------------------- | -------------------------------------------------- |
| `chat:addMessage`       | `{ args = { author, text }, color = { r, g, b } }`      | Adds a line. A plain string works too.             |
| `chat:addMessage`       | `{ template = '{0} paid {1}', args = { 'Ann', '20' } }` | Adds a line built from the template.               |
| `chatMessage`           | `author, { r, g, b }, text`                             | Adds a line, the older FiveM form.                 |
| `chat:addSuggestion`    | `'/name', 'help'`                                       | Shows the command with help text while typing `/`. |
| `chat:addSuggestions`   | `{ { name = '/a', help = '…' }, … }`                    | Several suggestions at once.                       |
| `chat:removeSuggestion` | `'/name'`                                               | Removes a suggestion.                              |
| `chat:clear`            |                                                         | Clears the chat.                                   |

server.lua

```lua
RegisterCommand('announce', function(source, args)
  TriggerClientEvent('chat:addMessage', -1, {
    color = { 255, 200, 0 },
    args = { 'Announcement', table.concat(args, ' ') },
  })
end, true)
```

`chat:addTemplate` exists so FiveM resources do not fail, but it does nothing: the chat has no web interface.

## Your own chat window

[Section titled “Your own chat window”](#your-own-chat-window)

Games built on GAMPEON can draw their own chat instead of the built-in window. The `chat` resource stays the same; only the window changes.

* Turn the built-in window off with `BuiltInChat=False` under `[GampeonScripting]` in `DefaultGame.ini`.
* `UGampeonClientScripting` has `OnChatMessage`, `OnChatCleared` and `OnChatSuggestion` for Blueprints and C++, and `SubmitChat` to send what the player typed.

Client scripts can also write to the chat window directly with [`Gampeon.ChatAddMessage`](/docs/scripting/reference/chat/) and the other chat functions. Most resources should use the events above instead, so they also work with other chat resources.

## Test without the game

[Section titled “Test without the game”](#test-without-the-game)

`gp_fakeplayer say <id> <text>` in [`gampeon-server`](/docs/scripting/test-server/) types into the chat of a fake player that joined with `gp_fakeplayer client`. Chat lines that reach the player are printed as `[client <id>/chatbox]`.

## Compared to FiveM

[Section titled “Compared to FiveM”](#compared-to-fivem)

* Same events and the same `chatMessage` with `CancelEvent()`.
* The chat shows plain text: no HTML, no colour codes inside a line, no templates with styling.
* Suggestions list the command and its help text, without the parameter list.

# Client scripts

> How client scripts reach players, when they start, and what they can do.

Client scripts run in every player’s game. The server sends them when a player joins, so players never install anything by hand. This works like FiveM: list the files in `fxmanifest.lua`, and GAMPEON does the rest.

fxmanifest.lua

```lua
fx_version 'cerulean'


shared_script 'config.lua'
server_script 'server.lua'
client_script 'client.lua'
files { 'html/index.html', 'data/*.json' }
```

## What players get

[Section titled “What players get”](#what-players-get)

For every started resource the server builds a package from:

* `client_script` and `client_scripts`
* `shared_script` and `shared_scripts`
* `files`
* the manifest itself

Server scripts never leave the server, even if they are in the same folder.

When a player joins, the game downloads only the files it does not have yet. Files are stored by their SHA-256 hash under `%LOCALAPPDATA%/GAMPEON/cache`, so joining again after a small change only downloads the changed files. The game checks every file against its hash before it uses it.

## When client scripts start

[Section titled “When client scripts start”](#when-client-scripts-start)

1. The player joins and passes the [join check](/docs/scripting/players/#join-check).
2. The server sends the list of packages and the replicated convars (`setr`).
3. The game downloads missing files and starts the resources in the same order as the server.
4. Network events that the server sent before the start are delivered right after it. An event from `playerJoining` therefore still reaches the client script.

server.lua

```lua
AddEventHandler('playerJoining', function()
  TriggerClientEvent('myres:welcome', source, GetPlayerName(source))
end)
```

client.lua

```lua
RegisterNetEvent('myres:welcome', function(name)
  print('welcome ' .. name)
  TriggerServerEvent('myres:ready', GetPlayerServerId(PlayerId()))
end)
```

In client scripts, `source` of a network event is `65535` (the server), like in FiveM.

## Restart and stop

[Section titled “Restart and stop”](#restart-and-stop)

* `restart myres` on the server restarts the resource on every connected client too, also when no file changed. Changed files download first.
* `stop myres` stops it on all clients.
* Resources that depend on a restarted resource restart with it, on the server and on clients.

## What client scripts can do

[Section titled “What client scripts can do”](#what-client-scripts-can-do)

Client scripts have the same Lua runtime as server scripts, with a stricter sandbox: no `PerformHttpRequest`, no `MySQL`, no `SaveResourceFile`, and convars are read-only. See [Sandbox and limits](/docs/scripting/sandbox/).

| Function                                                                                                 | What it does                                                                                 |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `TriggerServerEvent(name, ...)`                                                                          | Sends a network event to server scripts, at most 60000 bytes                                 |
| `RegisterNetEvent(name, handler)`                                                                        | Receives events from `TriggerClientEvent`                                                    |
| `GetConvar(name, default)`                                                                               | Reads convars the server set with `setr`                                                     |
| `PlayerId()`, `GetPlayerServerId(PlayerId())`                                                            | Your own player and its server ID                                                            |
| `GetPlayerName(PlayerId())`                                                                              | Your own display name                                                                        |
| `RegisterCommand(name, handler)`                                                                         | A command players can run in chat with `/name` or in the game console with `gpc <command>`   |
| `LoadResourceFile(resource, file)`                                                                       | Reads files from `files { }` of a running resource                                           |
| `PlayerPedId()`, `GetPlayerPed(-1)`                                                                      | Your own character                                                                           |
| `GetEntityCoords(ped)`, `GetEntityHeading(ped)`, `GetEntityForwardVector(ped)`, `GetEntityVelocity(ped)` | Where your character is, in meters and degrees                                               |
| `TriggerEvent('chat:addMessage', { args = { 'Me', 'hi' } })`                                             | Writes a line into your own chat. See [Text chat](/docs/scripting/chat/)                     |
| `ExecuteCommand(line)`                                                                                   | Runs a client command; unknown commands go to the server and run there with your permissions |

Client scripts can read the world but not move anything: `SetEntityCoords` is for server scripts. Other players’ characters, vehicles and objects come in a later step. See [World and entities](/docs/scripting/reference/world/) and [Platform status](/docs/start/status/).

## Which servers may send client scripts

[Section titled “Which servers may send client scripts”](#which-servers-may-send-client-scripts)

The client sandbox has not had its security review yet. Until it has, the game only runs client scripts from servers it trusts:

* servers on your own computer (`localhost`, for testing)
* GAMPEON test servers listed in the game build
* any server if you start the game with `-gpclientscripts`

On other servers the game skips client scripts and you play without them. The server log then shows `client scripts blocked by the player's game`.

## Download speed

[Section titled “Download speed”](#download-speed)

Files travel through the game connection at up to half of the connection’s bandwidth, about 50 KB/s per player, so movement stays smooth. Small resources start within a second or two. Large frameworks with many megabytes of client files take longer. A separate HTTP download like in FiveM is planned for that.

## Test without the game

[Section titled “Test without the game”](#test-without-the-game)

`gampeon-server` can run client scripts too. `gp_fakeplayer client <name>` joins with a client inside the same process, which downloads the packages and runs the client scripts. Their output is marked `[client <id>/<resource>]`. See [Test without the game](/docs/scripting/test-server/#client-scripts).

# Commands and convars

> Chat and console commands with permissions, and server settings scripts can read.

## Commands

[Section titled “Commands”](#commands)

server.lua

```lua
RegisterCommand('heal', function(source, args, raw)
  -- source is the player ID, 0 for the server console
  print(('%s used /heal with %d arguments'):format(source, #args))
end, true) -- true: only players with permission may use it
```

* `args` is a list of words. Quotes group words: `/say "hello world"` gives one argument.
* `raw` is the full line as typed.
* Restricted commands (`true` as the third argument) check the permission `command.<name>`. Grant it in `server.cfg`:

server.cfg

```ini
add_ace group.admin command.heal allow
add_principal identifier.gampeon:1234 group.admin
```

Players type commands in chat as `/name args`. Commands that client scripts registered run in the player’s game first; all others run on the server as that player, with the player’s permissions. See [Text chat](/docs/scripting/chat/#commands-in-chat).

`ExecuteCommand('name args')` runs a command as the server console. `GetRegisteredCommands()` lists all commands, and `IsPlayerAceAllowed(player, 'object')` checks a permission.

## Kick and ban

[Section titled “Kick and ban”](#kick-and-ban)

Server owners remove players from the server console, or players with permission from the chat:

| Command                                | Effect                                                                        |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| `clientkick <id> [reason]`             | Disconnects the player with that message                                      |
| `ban <id> [duration] [reason]`         | Bans a player who is online, with all their identifiers, and disconnects them |
| `ban <identifier> [duration] [reason]` | Bans an identifier such as `gampeon:1234`, also when the player is offline    |
| `unban <ban ID or identifier>`         | Removes a ban                                                                 |
| `banlist`                              | Lists active bans with ID, name, identifiers, end, who banned and reason      |

* Durations are `30m`, `12h`, `7d`, `2w` or `perm`. Without a duration the ban is permanent.
* Players who are kicked or banned see the reason in the game.
* Banned players cannot join until the ban ends. They see the reason, the end date in UTC and the ban ID, so they can ask you about it.
* Bans are saved in `bans.json` next to `server.cfg` and survive restarts. Expired bans are removed when the list is saved. If the file is broken, the server keeps it as it is, applies no bans from it and refuses new bans until you fix or remove it.
* Players need permission to use these commands from the chat:

server.cfg

```ini
add_ace group.admin command.ban allow
add_ace group.admin command.unban allow
add_ace group.admin command.banlist allow
add_ace group.admin command.clientkick allow
```

Resources can ban with `ExecuteCommand('ban 12 7d cheating')` if they have `command.ban`, for example `add_ace resource.anticheat command.ban allow`.

## Convars

[Section titled “Convars”](#convars)

Server settings come from `server.cfg`:

server.cfg

```ini
set shop_tax 0.19          # server only
setr shop_theme dark       # also sent to clients
sets tags "roleplay, eu"   # shown in the server browser
```

```lua
local tax = GetConvarFloat('shop_tax', 0.0)
local theme = GetConvar('shop_theme', 'light')
local debug = GetConvarBool('shop_debug', false)
```

Scripts can set convars on the server with `SetConvar`, `SetConvarReplicated` and `SetConvarServerInfo`.

Convars that hold credentials, such as `mysql_connection_string` and the server key, are protected. Scripts cannot read or change them.

# Database

> MySQL.* like oxmysql, with MariaDB, MySQL or SQLite.

Server scripts get `MySQL.*`, compatible with [oxmysql](https://overextended.dev/oxmysql). ESX and Qbox SQL calls work without changes. `@oxmysql/lib/MySQL.lua` and `dependency 'oxmysql'` in manifests keep working too. Every server ships with an `oxmysql` and a `mysql-async` resource for this. They also provide the exports, so `exports.oxmysql:query(sql, params, cb)`, `exports.oxmysql:scalar_async(…)`, `exports.oxmysql:executeSync(…)` and `exports['mysql-async']:mysql_fetch_all(…)` work.

## Connect

[Section titled “Connect”](#connect)

server.cfg

```ini
set mysql_connection_string "mysql://user:password@127.0.0.1:3306/my_server?charset=utf8mb4"
```

Other formats:

* `user=root;password=secret;host=127.0.0.1;port=3306;database=my_server`
* `sqlite:data/server.db`: a single file, good for small servers and testing. It uses the SQLite dialect. The path is relative to the server folder, missing folders are created. Use each file for one server only.

Game servers

Game servers support SQLite for now, and the server template starts with `sqlite:data/server.db`. MariaDB and MySQL work in [`gampeon-server`](/docs/scripting/test-server/) and come to game servers later.

Options for the `mysql://` format are `connectionLimit` (default 4), `charset`, `connectTimeout` (ms), `multipleStatements` and `ssl`.

## Query

[Section titled “Query”](#query)

server.lua

```lua
-- callback
MySQL.query('SELECT name, money FROM users WHERE job = ?', { 'police' }, function(rows)
  for _, row in ipairs(rows) do print(row.name, row.money) end
end)


-- inside a thread or event handler: wait for the result
local money = MySQL.scalar.await('SELECT money FROM users WHERE identifier = ?', { identifier })
local id = MySQL.insert.await('INSERT INTO bills (owner, amount) VALUES (:owner, :amount)', { owner = identifier, amount = 250 })
local changed = MySQL.update.await('UPDATE users SET money = money + ? WHERE id IN (?)', { 100, { 1, 2, 3 } })
```

| Function            | Returns                                                             |
| ------------------- | ------------------------------------------------------------------- |
| `MySQL.query`       | rows, or `{ affectedRows, insertId }` for statements without rows   |
| `MySQL.single`      | the first row or `nil`                                              |
| `MySQL.scalar`      | the first value of the first row or `nil`                           |
| `MySQL.insert`      | the new ID                                                          |
| `MySQL.update`      | the number of matched rows                                          |
| `MySQL.prepare`     | like `query`, simplified; a list of parameter lists runs as a batch |
| `MySQL.rawExecute`  | like `query`                                                        |
| `MySQL.transaction` | `true`, or `false` after a rollback                                 |

Every function also has `.await`. `MySQL.Async.*` and `MySQL.Sync.*` from mysql-async exist as well.

## Parameters

[Section titled “Parameters”](#parameters)

* `?` with a list: `{ 'police', 2 }`
* `@name` or `:name` with a table: `{ ['@id'] = 5 }` or `{ id = 5 }`
* A list for `IN (?)` expands to one value per entry.

Values are always escaped or bound, never pasted into the SQL. Don’t build SQL from player input with `..`.

## Types

[Section titled “Types”](#types)

As in oxmysql:

* `TINYINT(1)` and `BIT(1)` become `true` or `false`.
* `DATE`, `DATETIME` and `TIMESTAMP` become milliseconds since 1970.
* `DECIMAL` becomes a number, and `NULL` becomes `nil`.
* Tables and vectors you pass as values are stored as JSON.

## Errors

[Section titled “Errors”](#errors)

A failed query writes `SCRIPT ERROR: [MySQL] …` with the query to the server log. With `.await` the call raises the error, which you can catch with `pcall`. Transactions roll back and return `false`.

Queries run on their own threads, so a slow query never stalls the game.

# Editor setup

> Autocomplete and type checking for GAMPEON Lua in VS Code, Cursor and other editors.

The GAMPEON SDK ships type definitions for the [Lua Language Server](https://luals.github.io/) (LuaLS). With them, your editor completes GAMPEON functions, shows their documentation and warns about mistakes.

## VS Code and Cursor

[Section titled “VS Code and Cursor”](#vs-code-and-cursor)

1. Install the extension **Lua** by sumneko (LuaLS).
2. Download [gampeon.lua](/docs/reference/gampeon.lua) and put it in a folder of your resource, for example `.gampeon/`.
3. Create `.luarc.json` in your resource folder:

.luarc.json

```json
{
  "runtime.version": "Lua 5.4",
  "workspace.library": [".gampeon"],
  "diagnostics.globals": []
}
```

Now `AddEventHandler`, `CreateThread`, `exports` and the rest show up with descriptions.

## Other editors

[Section titled “Other editors”](#other-editors)

Any editor that supports LuaLS (Neovim, Zed, JetBrains with the EmmyLua plugin) works with the same `.luarc.json`.

## Let an AI check your code

[Section titled “Let an AI check your code”](#let-an-ai-check-your-code)

An AI assistant connected through the [MCP server](/docs/mcp/overview/) can check a resource for missing files, forbidden functions and GTA natives before you publish it.

# Events

> Send messages between resources and between server and client.

Events are named messages. Any resource can fire an event, and every resource that listens to it runs its handler.

## Local events

[Section titled “Local events”](#local-events)

`TriggerEvent` reaches all resources on the **same side** (server or client). It never travels over the network.

```lua
-- resource A
AddEventHandler('race:finished', function(playerId, timeMs)
  print(('Player %d finished in %d ms'):format(playerId, timeMs))
end)


-- resource B, same side
TriggerEvent('race:finished', 12, 83450)
```

A handler can call `CancelEvent()` to tell the code that fired the event to skip its default action. That code checks `WasEventCanceled()` right after `TriggerEvent`. Other handlers still run. The [chat](/docs/scripting/chat/) uses this for `chatMessage`.

```lua
-- resource B
TriggerEvent('shop:beforeBuy', source, item)
if WasEventCanceled() then return end
```

## Network events

[Section titled “Network events”](#network-events)

To receive an event from the other side, register it with `RegisterNetEvent`. Without that call, network events never reach your handlers.

client/main.lua

```lua
TriggerServerEvent('myshop:buy', 'water')
```

server/main.lua

```lua
RegisterNetEvent('myshop:buy', function(itemId)
  local player = source -- who sent it
  -- check and act, see the rules below
end)
```

The server answers one player, or everyone with `-1`:

server/main.lua

```lua
TriggerClientEvent('myshop:bought', player, 'water')
TriggerClientEvent('chat:announce', -1, 'Shop closes in 5 minutes')
```

## Security rules for network events

[Section titled “Security rules for network events”](#security-rules-for-network-events)

Players can send any event with any arguments. A server handler must assume the worst.

1. **Check every argument.** Type, range and length. `if type(itemId) ~= 'string' or #itemId > 32 then return end`
2. **Never trust amounts or prices from the client.** Look them up on the server.
3. **Check permissions** with `source`, not with a player ID sent as an argument.
4. **Copy `source` into a local** before calling `Wait`, because another event can change it.
5. **Rate-limit expensive actions** per player.

## Naming

[Section titled “Naming”](#naming)

Prefix events with your resource name: `myshop:buy`, not `buy`. Names are shared by all resources.

## Arguments

[Section titled “Arguments”](#arguments)

Arguments are copied: tables, strings, numbers, booleans and `nil` work. In local events (`TriggerEvent`), functions are passed as references, so callbacks like `TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end)` work; see [Exports](/docs/scripting/exports/#objects-with-methods). Network events cannot carry functions: they arrive as `nil`.

## Removing handlers

[Section titled “Removing handlers”](#removing-handlers)

```lua
local handle = AddEventHandler('race:tick', onTick)
-- later
RemoveEventHandler(handle)
```

See the reference: [Events](/docs/scripting/reference/events/), [Built-in events](/docs/scripting/reference/events-built-in/).

# Exports

> Share functions between resources.

An export is a function that one resource offers to others on the same side.

bank/server.lua

```lua
local balances = {}


exports('GetBalance', function(playerId)
  return balances[playerId] or 0
end)


exports('AddMoney', function(playerId, amount)
  balances[playerId] = (balances[playerId] or 0) + amount
  return balances[playerId]
end)
```

shop/server.lua

```lua
local money = exports.bank:GetBalance(source)
-- names with dashes: exports['my-bank']:GetBalance(source)
```

List the export names in the manifest so other developers find them:

bank/fxmanifest.lua

```lua
server_script 'server.lua'
server_exports { 'GetBalance', 'AddMoney' }
dependency 'bank' -- in the shop's manifest, so bank starts first
```

## Objects with methods

[Section titled “Objects with methods”](#objects-with-methods)

An export can return a table with functions, like `ESX.GetPlayerFromId` or `QBCore.Functions.GetPlayer`. The functions stay callable in the other resource and run in the resource that made them:

bank/server.lua

```lua
exports('GetAccount', function(playerId)
  return {
    balance = balances[playerId] or 0,
    deposit = function(amount) balances[playerId] = (balances[playerId] or 0) + amount end,
  }
end)
```

shop/server.lua

```lua
local account = exports.bank:GetAccount(source)
account.deposit(50)          -- runs in bank
print(account.balance)       -- a copy from the moment of the call: still the old value
```

Callbacks work the same way, also through local events: `TriggerEvent('bank:getSharedObject', function(obj) Bank = obj end)`.

## Waiting

[Section titled “Waiting”](#waiting)

An export may call `Wait`, `MySQL.*.await` or other exports. The caller then waits for the result, as long as it runs in a thread or an event handler. Called from the main chunk of a script, the export still finishes, but its result is lost and the log says so. Wrap such calls in `CreateThread`.

## Rules

[Section titled “Rules”](#rules)

* Exports only work between resources on the **same side**.
* Tables, strings, numbers and booleans are **copied**. Functions are passed as references and run in the resource they come from.
* A function from a resource that stopped or restarted can no longer be called: `function of resource 'bank' can no longer be called`. Get it again after a restart.
* Functions do not cross the network. In `TriggerClientEvent`, `TriggerServerEvent` and `json.encode` they become `nil`.
* Calling an export of a resource that does not run is an error: `No such resource 'bank' for export 'GetBalance'`. Add a `dependency`.
* `resmon` shows in the `funcrefs` column how many functions of a resource other resources hold. A number that only grows means a resource keeps references it no longer needs.

# HTTP requests

> Call web services from server scripts with PerformHttpRequest.

server.lua

```lua
PerformHttpRequest('https://api.example.com/status', function(status, body, headers, errorData)
  if status == 200 then
    local data = json.decode(body)
    print(data.message)
  else
    print('request failed', status, errorData)
  end
end, 'GET', '', { ['Accept'] = 'application/json' })
```

* Only server scripts can make HTTP requests.
* Methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`.
* `status` is `0` when there was no answer, for example on a timeout or a blocked address.
* `body` is set for successful answers. For errors, `errorData` holds the error text or the error body.
* Pass `{ timeout = 5000 }` as the sixth argument to change the timeout (default 30 s).

## Limits

[Section titled “Limits”](#limits)

* Requests to private and local addresses (`127.0.0.1`, `10.x`, `192.168.x`, `localhost` and similar) are blocked. Your server’s own network stays out of reach of scripts.
* URLs with a user name or password are refused. Send credentials in a header.
* Request bodies are limited to 1 MB and responses to 16 MB. At most 32 requests per resource run at the same time.

# Manifest

> The fxmanifest.lua file that describes a resource.

Every resource has a manifest in its root folder, named `fxmanifest.lua` or `resource.lua`. It is a Lua file with one directive per line. GAMPEON reads the FiveM format directly, so existing manifests work.

fxmanifest.lua

```lua
name 'myshop'
version '1.0.0'
description 'A simple shop'


shared_script 'config.lua'
server_scripts {
  'server/*.lua',
}
client_script 'client/main.lua'
files {
  'data/items.json',
}
dependency 'bank'
```

## Directives

[Section titled “Directives”](#directives)

| Directive                         | Meaning                                                                          |
| --------------------------------- | -------------------------------------------------------------------------------- |
| `shared_script`, `shared_scripts` | Run on server and client, before the other scripts of that side.                 |
| `server_script`, `server_scripts` | Run on the server.                                                               |
| `client_script`, `client_scripts` | Run on every player’s client.                                                    |
| `file`, `files`                   | Other files the resource ships, for example data or UI files.                    |
| `dependency`, `dependencies`      | Resources that must already run. The resource does not start otherwise.          |
| `export`, `exports`               | Names of client exports, for other resources to read.                            |
| `server_export`, `server_exports` | Names of server exports.                                                         |
| `ui_page`                         | HTML page shown over the game. See [Web interfaces (NUI)](/docs/scripting/nui/). |

Scripts load in the order of the manifest: shared scripts first, then the scripts of the side.

## Paths

[Section titled “Paths”](#paths)

* Wildcards: `server/*.lua` matches all Lua files in `server/`, `**/*.lua` matches all Lua files in all folders.
* Files of other resources: `@ox_lib/init.lua` loads `init.lua` from the resource `ox_lib`.

## Ignored directives

[Section titled “Ignored directives”](#ignored-directives)

These FiveM directives are accepted without a warning but have no effect: `fx_version`, `game`, `games`, `lua54`, `author`, `description`, `version`, `name`, `loadscreen`, `loadscreen_manual_shutdown`, `this_is_a_map`, `provide`, `data_file`, `replace_level_meta`, `before_level_meta`, `after_level_meta`, `use_experimental_fxv2_oal`, `use_fxv2_oal`, `repository`, `node_version`.

Unknown directives are ignored with a warning in the log.

# Web interfaces (NUI)

> HTML pages of a resource over the game, with messages and callbacks like FiveM NUI.

Resources can draw menus, HUDs and phones as web pages over the game. GAMPEON uses the same API as FiveM NUI, so most NUI resources work without changes.

Preview

Web interfaces run in the game on test servers that may send client scripts, and in `gampeon-server` for testing.

## A minimal menu

[Section titled “A minimal menu”](#a-minimal-menu)

fxmanifest.lua

```lua
fx_version 'cerulean'
ui_page 'html/index.html'
client_script 'client.lua'
files { 'html/app.js', 'html/style.css', 'html/img/*.png' }
```

client.lua

```lua
RegisterCommand('menu', function()
  SendNUIMessage({ type = 'open', items = { 'bread', 'water' } })
  SetNuiFocus(true, true) -- keyboard and mouse go to the page
end)


RegisterNUICallback('close', function(data, cb)
  SetNuiFocus(false, false)
  cb('ok')
end)
```

html/app.js

```js
window.addEventListener('message', (event) => {
  if (event.data.type === 'open') showMenu(event.data.items);
});


function close() {
  fetch(`https://${GetParentResourceName()}/close`, {
    method: 'POST',
    body: JSON.stringify({ reason: 'button' }),
  });
}
```

## How it works

[Section titled “How it works”](#how-it-works)

* Every resource with `ui_page` gets its own frame, transparent over the game. Pages of different resources do not see each other.
* `ui_page` is sent to players with the other client files. List everything the page loads (scripts, styles, images, fonts) under `files`.
* Pages load from `https://cfx-nui-<resource>/<path>`, the same address as in FiveM. Only `ui_page` and `files` are served; client scripts and other files are not.
* `SendNUIMessage(data)` arrives as `event.data` of a `message` event. The data travels as JSON, at most 1 MB per message.
* `fetch('https://<resource>/<name>')` from the page calls the handler from `RegisterNUICallback(name, ...)`. The body is decoded from JSON and the value passed to `cb` comes back as JSON. `XMLHttpRequest` works the same way, so jQuery `$.post` and axios work too.
* Messages sent before the page has loaded are delivered once it has loaded (up to 256).
* A page may also call callbacks and load files of other resources, as in FiveM, for example item images from `https://cfx-nui-<inventory>/…`.
* Resource names in these addresses are not case-sensitive, because browsers write host names in lower case. Callback addresses only work for resource names without a dot.
* `console.log` and errors of pages appear in the game’s log as `[client/nui]`.

## Images and fonts from your game package

[Section titled “Images and fonts from your game package”](#images-and-fonts-from-your-game-package)

Graphics from store packs, such as UI sprites you bought for your own game, do not belong in a resource: every file under `files` is sent to every player as a plain file. Put them into your [game package](/docs/getting-started/your-own-map/) instead, in a folder `Nui` next to `Content`:

```text
GamCity/
  GamCity.uplugin
  Content/
  Nui/
    menus/panel_wide.png
    icons/coin.png
```

Pages load them from `https://gampeon-pkg-<package>/<path>`, with the package name in lower case:

html/index.html

```html
<img src="https://gampeon-pkg-gamcity/icons/coin.png" alt="">
<div style="background-image: url('https://gampeon-pkg-gamcity/menus/panel_wide.png')"></div>
```

* Only images (`png`, `jpg`, `webp`, `gif`, `avif`), fonts (`woff`, `woff2`, `ttf`, `otf`), sounds (`mp3`, `ogg`, `wav`) and videos (`mp4`, `webm`) are served, at most 32 MB per file. Pages, scripts and styles stay in the resource.
* Only packages the game has mounted are served. In the first stage that is every package given with `-gppackage=`; later only the packages of the project the player joined.
* The game log shows `Web interfaces (NUI): files of game package GamCity at https://gampeon-pkg-gamcity/` when it works.
* Free fonts under an open license (for example from Google Fonts) can stay in the resource.

## Callbacks

[Section titled “Callbacks”](#callbacks)

| Situation                            | The page gets                   |
| ------------------------------------ | ------------------------------- |
| The handler calls `cb(value)`        | Status 200 with `value` as JSON |
| The body is not JSON                 | 400                             |
| No handler with that name            | 404                             |
| The body is larger than 64 KB        | 413                             |
| More than 256 requests are open      | 429                             |
| The handler fails with an error      | 500 with `{ "error": "…" }`     |
| The resource stops before the answer | 503                             |
| No answer within 30 seconds          | 504                             |

Handlers may call `Wait` before they answer.

## Focus

[Section titled “Focus”](#focus)

* `SetNuiFocus(hasFocus, hasCursor)` gives the keyboard and the mouse to the pages. The last call of any resource wins.

* `SetNuiFocusKeepInput(true)` lets the player keep moving while a page has focus.

* When the resource that set the focus stops, the focus goes back to the game.

* Players can always take the focus back by holding **Escape for 2 seconds**, so a page cannot trap the mouse. A short press of Escape still reaches the page, so menus can close on Escape as usual.

* The page stays visible after that. Your client script gets the event [`gampeon:nuiFocusReleased`](/docs/scripting/reference/events-built-in/#gampeonnuifocusreleased) and can close its menu:

  ```lua
  AddEventHandler('gampeon:nuiFocusReleased', function(resourceName)
      if resourceName == GetCurrentResourceName() then
          SendNUIMessage({ type = 'hide' })
      end
  end)
  ```

## Test without the game

[Section titled “Test without the game”](#test-without-the-game)

With [`gampeon-server`](/docs/scripting/test-server/), join a fake player with `gp_fakeplayer client <name>` and then:

| Command                                               | Effect                                                              |
| ----------------------------------------------------- | ------------------------------------------------------------------- |
| `gp_fakeplayer nui <id> <resource> <callback> [json]` | Calls the callback like `fetch` from the page and prints the answer |
| `gp_fakeplayer nuifile <id> <resource> <path>`        | Loads a file like the browser does, or prints 404                   |
| `gp_fakeplayer nuirelease <id>`                       | Takes the focus back like holding Escape in the game                |

Messages, focus changes and answers appear as `[client <id>/nui]` in the output.

## Compared to FiveM

[Section titled “Compared to FiveM”](#compared-to-fivem)

* Same manifest entries, same functions, same `https://<resource>/<name>` callbacks and `GetParentResourceName()`.
* The low-level form `RegisterNuiCallbackType` with `AddEventHandler('__cfx_nui:name', ...)` is not supported. Use `RegisterNUICallback`.
* `ui_page` must be a file of the resource. Remote pages (`ui_page 'https://…'`) are not shown.
* Pages run in a sandbox: no pop-ups, no `alert()` or `confirm()`, and they cannot navigate the game’s browser away. Images, fonts and scripts from `https://` addresses still load, as in FiveM.
* Pages on surfaces in the world (DUI) and loading screens (`loadscreen`) come later.

# Objects

> Place, freeze and delete objects from server scripts with CreateObject, and which models exist.

Server scripts can put objects into the world with the FiveM functions `CreateObject`, `DeleteEntity` and `FreezeEntityPosition`. Every player sees them. The arguments are the same as in FiveM, the models are not: GAMPEON has its own.

server.lua

```lua
RegisterCommand('crate', function(src)
  local ped = GetPlayerPed(src)
  local pos = GetEntityCoords(ped)
  local obj = CreateObject('prop_cube', pos.x + 2.0, pos.y, pos.z + 1.0, true, true, false)
  if obj == 0 then
    return -- unknown model or too many objects, the server log says which
  end
  FreezeEntityPosition(obj, true) -- stays in the air, no physics
end, false)
```

## Models

[Section titled “Models”](#models)

Pass the model name as a string or its hash from `GetHashKey`. Both work everywhere a model is expected.

| Model           | Shape            |
| --------------- | ---------------- |
| `prop_cube`     | Cube, 1 m        |
| `prop_sphere`   | Sphere, 1 m      |
| `prop_cylinder` | Cylinder, 1 m    |
| `prop_cone`     | Cone, 1 m        |
| `prop_plane`    | Flat square, 1 m |

These five exist on every server. A game can add its own models; creators will be able to ship models with their content once the package format is ready.

GTA model names like `prop_atm_01` do not exist. `CreateObject` then returns 0 and writes a hint into the server log, once per resource run. A ported script keeps running and the log shows which models are missing. `IsModelValid(model)` tells you beforehand.

`GetHashKey` computes the same hash as in FiveM. Hashes work signed and unsigned, so `GetHashKey('prop_cube')` and the unsigned value from a FiveM table both match.

## Physics

[Section titled “Physics”](#physics)

Objects are physical but rest until something touches them, like props in GTA. A player who walks into a cube pushes it. `FreezeEntityPosition(obj, true)` turns physics off and holds the object where it is; `false` turns it back on.

The server computes the physics and sends the movement to the players. `SetEntityCoords` and `SetEntityHeading` move objects like characters.

## Who owns an object

[Section titled “Who owns an object”](#who-owns-an-object)

Every object belongs to the resource that created it. When the resource stops, the server deletes its objects after `onResourceStop`. A `restart` therefore never leaves copies behind.

`DeleteEntity` deletes any object a script created, also those of other resources. It never deletes player characters.

## Limits

[Section titled “Limits”](#limits)

| Limit                | Value  |
| -------------------- | ------ |
| Objects per resource | 1000   |
| Objects per server   | 10 000 |

Above the limit `CreateObject` returns 0 and writes a hint into the server log. The values are preliminary and may change after load tests.

## Not yet available

[Section titled “Not yet available”](#not-yet-available)

* **Client scripts cannot create objects.** `CreateObject` only works on the server. Local objects for one player come later.
* **Network IDs.** `NetworkGetNetworkIdFromEntity` and `NetworkGetEntityFromNetworkId` come later, so client scripts cannot address server objects yet.
* **Vehicles.** `CreateVehicle` checks its arguments but returns 0 with a hint, because there are no vehicle models yet.

All functions and their arguments are in [World and entities](/docs/scripting/reference/world/). In [gampeon-server](/docs/scripting/test-server/) objects stand where the script puts them, without physics; `gp_entities` lists them.

# Scripting overview

> How GAMPEON games are built from Lua resources.

GAMPEON games are made of **resources**. A resource is a folder with a [manifest](/docs/scripting/manifest/), Lua scripts and other files. A server runs many resources at once: one for the game mode, one for the shop, one for the chat, and so on.

## Server, client and shared scripts

[Section titled “Server, client and shared scripts”](#server-client-and-shared-scripts)

| Script type   | Runs on                 | Use it for                                                   |
| ------------- | ----------------------- | ------------------------------------------------------------ |
| Server script | The game server         | Rules, money, inventories, anything that must not be cheated |
| Client script | Every player’s computer | Input, UI, effects                                           |
| Shared script | Both                    | Configuration and helpers both sides need                    |

The server is the authority. Never trust a value just because a client sent it: check it on the server. See [Events](/docs/scripting/events/#security-rules-for-network-events).

## Your first resource

[Section titled “Your first resource”](#your-first-resource)

```text
hello/
├── fxmanifest.lua
└── server.lua
```

fxmanifest.lua

```lua
name 'hello'
version '1.0.0'
server_script 'server.lua'
```

server.lua

```lua
AddEventHandler('onResourceStart', function(name)
  if name == GetCurrentResourceName() then
    print('Hello from ' .. name)
  end
end)


CreateThread(function()
  while true do
    Wait(60000)
    print('Another minute passed')
  end
end)
```

## How scripts work together

[Section titled “How scripts work together”](#how-scripts-work-together)

* **Events** pass messages inside one side and between server and client. See [Events](/docs/scripting/events/).
* **Threads** run code over time without blocking the game. See [Threads and timers](/docs/scripting/threads/).
* **Exports** let one resource call functions of another. See [Exports](/docs/scripting/exports/).

## Rules of the sandbox

[Section titled “Rules of the sandbox”](#rules-of-the-sandbox)

Every resource runs in its own protected Lua 5.4 state. There is no file access, no `require` and no `os.execute`, and every resource has limits on memory and run time. Long loops must call `Wait`. See [Sandbox](/docs/scripting/sandbox/).

## Next steps

[Section titled “Next steps”](#next-steps)

* Read the [Lua API reference](/docs/scripting/reference/) for every available function.
* Set up autocomplete in your editor: [Editor setup](/docs/scripting/editor-setup/).
* Let an AI assistant write and check resources for you: [Build with AI](/docs/ai/connect/).

# Players

> Join and leave events, player IDs, identifiers and the player functions on the server.

Players work like in FiveM. Each player gets a numeric ID for the time they are on the server. Server scripts see it as `source` in events and pass it to the player functions.

## Joining and leaving

[Section titled “Joining and leaving”](#joining-and-leaving)

server.lua

```lua
AddEventHandler('playerJoining', function()
  local src = source
  print(('%s joined with %s'):format(GetPlayerName(src), GetPlayerIdentifierByType(src, 'license')))
end)


AddEventHandler('playerDropped', function(reason)
  -- The player still exists here: GetPlayerName and the identifiers work.
  print(('%s left: %s'):format(GetPlayerName(source), reason))
end)
```

`playerJoining` runs once the server has checked the player’s join ticket (see below), before the player spawns. `playerConnecting` with deferrals is not available yet.

## Identifiers

[Section titled “Identifiers”](#identifiers)

| Identifier | Example                             | Meaning                                                                                            |
| ---------- | ----------------------------------- | -------------------------------------------------------------------------------------------------- |
| `gampeon:` | `gampeon:4821`                      | The player’s GAMPEON account. Stable, the same on every server.                                    |
| `license:` | `license:3f0c…` (40 hex characters) | Derived from the account and the server’s salt. Stable on your server, different on other servers. |

`license:` has the same format as in FiveM, so existing tables keyed by `license:` (ESX, QBCore, Qbox) keep working. Servers of one community can share players by setting the same salt in `server.cfg`:

server.cfg

```ini
set sv_licenseSalt "my-community"
```

Without it, the salt is the server ID. Scripts cannot read or change the salt.

## Player functions

[Section titled “Player functions”](#player-functions)

| Function                                                                                | Returns                                                 |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `GetPlayers()`                                                                          | All player IDs as strings                               |
| `GetNumPlayerIndices()`, `GetPlayerFromIndex(i)`                                        | Number of players, player ID by index                   |
| `DoesPlayerExist(id)`                                                                   | `true` while the player is on the server                |
| `GetPlayerName(id)`                                                                     | The player’s GAMPEON display name                       |
| `GetPlayerIdentifiers(id)`, `GetNumPlayerIdentifiers(id)`, `GetPlayerIdentifier(id, i)` | All identifiers or one by index                         |
| `GetPlayerIdentifierByType(id, 'license')`                                              | The first identifier with that prefix                   |
| `GetPlayerEndpoint(id)`                                                                 | IP address                                              |
| `GetPlayerPing(id)`                                                                     | Round trip time in milliseconds                         |
| `GetPlayerLastMsg(id)`                                                                  | Milliseconds since the player last sent a network event |
| `DropPlayer(id, reason)`                                                                | Disconnects the player with that message                |

The full list with types is in the [Lua API reference](/docs/scripting/reference/).

## Join check

[Section titled “Join check”](#join-check)

Players join through the GAMPEON launcher. The launcher gives the game a one-time join ticket, and the server checks it with GAMPEON before scripts see the player. The name and the `gampeon:` identifier come from that check, so players cannot pretend to be someone else.

For the check, the server needs its ID and key from [registering the server](/docs/servers/register/). For local tests without the launcher, turn the check off:

server.cfg

```ini
set sv_requireJoinToken false
```

Players then get identifiers like `gampeon:dev-1` and the name their game sends.

## Network events from players

[Section titled “Network events from players”](#network-events-from-players)

Events from players reach only handlers registered with `RegisterNetEvent`. Before scripts see them, the server checks the size (60 KB in the game), the rate (200 per second, short bursts up to 400) and the format. A player who keeps sending invalid or too many events is disconnected.

# Lua API reference

> Every function, global and event available to GAMPEON Lua scripts.

Version 0.10.0 of the GAMPEON Lua API (Lua 5.4). Everything a script can use is listed here; anything else does not exist.

No GTA natives

GTA natives such as GetEntityCoords or CreateVehicle do not exist in GAMPEON and never will. Player functions (GetPlayers, GetPlayerIdentifiers, DropPlayer …) come from the GAMPEON server. A GAMPEON game API for characters, vehicles and the world comes with the engine plugin.

| Function                                                                                      | Side              | What it does                                                                                                      |
| --------------------------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| [`AddEventHandler`](/docs/scripting/reference/events/#addeventhandler)                        | Server and client | Run a function whenever an event fires.                                                                           |
| [`RemoveEventHandler`](/docs/scripting/reference/events/#removeeventhandler)                  | Server and client | Remove a handler added with AddEventHandler.                                                                      |
| [`RegisterNetEvent`](/docs/scripting/reference/events/#registernetevent)                      | Server and client | Allow an event to arrive from the other side (client to server or server to client).                              |
| [`RegisterServerEvent`](/docs/scripting/reference/events/#registerserverevent)                | Server and client | Old name of RegisterNetEvent, kept for ported FiveM scripts.                                                      |
| [`TriggerEvent`](/docs/scripting/reference/events/#triggerevent)                              | Server and client | Fire an event for all resources on the same side.                                                                 |
| [`CancelEvent`](/docs/scripting/reference/events/#cancelevent)                                | Server and client | Cancel the event whose handler is running.                                                                        |
| [`WasEventCanceled`](/docs/scripting/reference/events/#waseventcanceled)                      | Server and client | Check if a handler canceled the last event fired with TriggerEvent.                                               |
| [`TriggerServerEvent`](/docs/scripting/reference/events/#triggerserverevent)                  | Client only       | Send an event from the client to the server.                                                                      |
| [`TriggerClientEvent`](/docs/scripting/reference/events/#triggerclientevent)                  | Server only       | Send an event from the server to one player or to everyone.                                                       |
| [`CreateThread`](/docs/scripting/reference/threads/#createthread)                             | Server and client | Run a function as its own thread, starting with the next tick.                                                    |
| [`Wait`](/docs/scripting/reference/threads/#wait)                                             | Server and client | Pause the current thread.                                                                                         |
| [`SetTimeout`](/docs/scripting/reference/threads/#settimeout)                                 | Server and client | Run a function once after a delay.                                                                                |
| [`Citizen.CreateThread`](/docs/scripting/reference/threads/#citizencreatethread)              | Server and client | Same as CreateThread. Kept for ported FiveM scripts.                                                              |
| [`Citizen.Wait`](/docs/scripting/reference/threads/#citizenwait)                              | Server and client | Same as Wait. Kept for ported FiveM scripts.                                                                      |
| [`Citizen.SetTimeout`](/docs/scripting/reference/threads/#citizensettimeout)                  | Server and client | Same as SetTimeout. Kept for ported FiveM scripts.                                                                |
| [`exports`](/docs/scripting/reference/exports/#exports)                                       | Server and client | Offer a function to other resources, or call one.                                                                 |
| [`GetCurrentResourceName`](/docs/scripting/reference/resource/#getcurrentresourcename)        | Server and client | Name of the resource this script belongs to.                                                                      |
| [`GetGameTimer`](/docs/scripting/reference/resource/#getgametimer)                            | Server and client | Milliseconds since the runtime started. Use it to measure time.                                                   |
| [`GetHashKey`](/docs/scripting/reference/resource/#gethashkey)                                | Server and client | Hash of a name, for example of a model name. Same numbers as in FiveM.                                            |
| [`IsDuplicityVersion`](/docs/scripting/reference/resource/#isduplicityversion)                | Server and client | True on the server, false on the client.                                                                          |
| [`json.encode`](/docs/scripting/reference/data/#jsonencode)                                   | Server and client | Turn a Lua value into a JSON string.                                                                              |
| [`json.decode`](/docs/scripting/reference/data/#jsondecode)                                   | Server and client | Turn a JSON string into a Lua value.                                                                              |
| [`print`](/docs/scripting/reference/sandbox/#print)                                           | Server and client | Write a line to the server or client log, tagged with the resource name.                                          |
| [`load`](/docs/scripting/reference/sandbox/#load)                                             | Server and client | Compile Lua source text. Precompiled bytecode is refused.                                                         |
| [`RegisterCommand`](/docs/scripting/reference/commands/#registercommand)                      | Server and client | Add a command for the console, the chat (/name) or key bindings.                                                  |
| [`ExecuteCommand`](/docs/scripting/reference/commands/#executecommand)                        | Server and client | Run a console command, as if typed into the server console.                                                       |
| [`GetRegisteredCommands`](/docs/scripting/reference/commands/#getregisteredcommands)          | Server and client | List all commands that resources registered on this side.                                                         |
| [`IsPlayerAceAllowed`](/docs/scripting/reference/commands/#isplayeraceallowed)                | Server only       | Check if a player has a permission (ACE).                                                                         |
| [`GetConvar`](/docs/scripting/reference/convars/#getconvar)                                   | Server and client | Read a convar as text.                                                                                            |
| [`GetConvarInt`](/docs/scripting/reference/convars/#getconvarint)                             | Server and client | Read a convar as a whole number.                                                                                  |
| [`GetConvarFloat`](/docs/scripting/reference/convars/#getconvarfloat)                         | Server and client | Read a convar as a number with decimals.                                                                          |
| [`GetConvarBool`](/docs/scripting/reference/convars/#getconvarbool)                           | Server and client | Read a convar as true or false.                                                                                   |
| [`SetConvar`](/docs/scripting/reference/convars/#setconvar)                                   | Server only       | Set a convar on the server.                                                                                       |
| [`SetConvarReplicated`](/docs/scripting/reference/convars/#setconvarreplicated)               | Server only       | Set a convar that clients can read too.                                                                           |
| [`SetConvarServerInfo`](/docs/scripting/reference/convars/#setconvarserverinfo)               | Server only       | Set a convar that is shown in the server list.                                                                    |
| [`PerformHttpRequest`](/docs/scripting/reference/http/#performhttprequest)                    | Server only       | Send a web request and get the answer in a callback.                                                              |
| [`GetInvokingResource`](/docs/scripting/reference/resource/#getinvokingresource)              | Server and client | Name of the resource that called the current export or triggered the current local event.                         |
| [`LoadResourceFile`](/docs/scripting/reference/resource/#loadresourcefile)                    | Server and client | Read a file from a resource folder.                                                                               |
| [`SaveResourceFile`](/docs/scripting/reference/resource/#saveresourcefile)                    | Server only       | Write a file into the own resource folder.                                                                        |
| [`GetResourceState`](/docs/scripting/reference/resource/#getresourcestate)                    | Server and client | Check if a resource runs.                                                                                         |
| [`GetNumResources`](/docs/scripting/reference/resource/#getnumresources)                      | Server and client | Number of running resources on this side.                                                                         |
| [`GetResourceByFindIndex`](/docs/scripting/reference/resource/#getresourcebyfindindex)        | Server and client | Name of the running resource at an index, for loops over all resources.                                           |
| [`GetResourcePath`](/docs/scripting/reference/resource/#getresourcepath)                      | Server only       | Folder of a resource on the server.                                                                               |
| [`GetResourceMetadata`](/docs/scripting/reference/resource/#getresourcemetadata)              | Server and client | Read a value from the manifest of a running resource.                                                             |
| [`GetNumResourceMetadata`](/docs/scripting/reference/resource/#getnumresourcemetadata)        | Server and client | How many values a manifest directive has.                                                                         |
| [`vector2`](/docs/scripting/reference/vectors/#vector2)                                       | Server and client | Create a vector2 with 2 numbers (x, y).                                                                           |
| [`vec2`](/docs/scripting/reference/vectors/#vec2)                                             | Server and client | Short name for vector2.                                                                                           |
| [`vector3`](/docs/scripting/reference/vectors/#vector3)                                       | Server and client | Create a vector3 with 3 numbers (x, y, z).                                                                        |
| [`vec3`](/docs/scripting/reference/vectors/#vec3)                                             | Server and client | Short name for vector3.                                                                                           |
| [`vector4`](/docs/scripting/reference/vectors/#vector4)                                       | Server and client | Create a vector4 with 4 numbers (x, y, z, w).                                                                     |
| [`vec4`](/docs/scripting/reference/vectors/#vec4)                                             | Server and client | Short name for vector4.                                                                                           |
| [`vec`](/docs/scripting/reference/vectors/#vec)                                               | Server and client | Create a vector with 2, 3 or 4 numbers.                                                                           |
| [`promise.new`](/docs/scripting/reference/promises/#promisenew)                               | Server and client | Create a promise that is resolved later.                                                                          |
| [`promise.resolve`](/docs/scripting/reference/promises/#promiseresolve)                       | Server and client | Create a promise that is already resolved.                                                                        |
| [`promise.reject`](/docs/scripting/reference/promises/#promisereject)                         | Server and client | Create a promise that is already rejected.                                                                        |
| [`promise.all`](/docs/scripting/reference/promises/#promiseall)                               | Server and client | Wait for several promises; resolves with a list of their first values.                                            |
| [`promise.first`](/docs/scripting/reference/promises/#promisefirst)                           | Server and client | Resolve with the first promise that finishes.                                                                     |
| [`promise.race`](/docs/scripting/reference/promises/#promiserace)                             | Server and client | Same as promise.first.                                                                                            |
| [`Citizen.Await`](/docs/scripting/reference/promises/#citizenawait)                           | Server and client | Pause the current thread until a promise is resolved, then return its values.                                     |
| [`Citizen.Trace`](/docs/scripting/reference/sandbox/#citizentrace)                            | Server and client | Write to the server or client log, like print.                                                                    |
| [`MySQL.query`](/docs/scripting/reference/database/#mysqlquery)                               | Server only       | Run a query. SELECT returns the rows; other statements return { affectedRows, insertId }.                         |
| [`MySQL.single`](/docs/scripting/reference/database/#mysqlsingle)                             | Server only       | Run a query and return only the first row.                                                                        |
| [`MySQL.scalar`](/docs/scripting/reference/database/#mysqlscalar)                             | Server only       | Run a query and return the first column of the first row.                                                         |
| [`MySQL.insert`](/docs/scripting/reference/database/#mysqlinsert)                             | Server only       | Run an INSERT and return the new ID.                                                                              |
| [`MySQL.update`](/docs/scripting/reference/database/#mysqlupdate)                             | Server only       | Run an UPDATE or DELETE and return the number of changed rows.                                                    |
| [`MySQL.prepare`](/docs/scripting/reference/database/#mysqlprepare)                           | Server only       | Run a statement with ? placeholders, also many times with a list of parameter lists.                              |
| [`MySQL.rawExecute`](/docs/scripting/reference/database/#mysqlrawexecute)                     | Server only       | Run a query and return the raw result.                                                                            |
| [`MySQL.execute`](/docs/scripting/reference/database/#mysqlexecute)                           | Server only       | Old name of MySQL.query.                                                                                          |
| [`MySQL.transaction`](/docs/scripting/reference/database/#mysqltransaction)                   | Server only       | Run several statements in one transaction. If one fails, none of them is kept.                                    |
| [`MySQL.ready`](/docs/scripting/reference/database/#mysqlready)                               | Server only       | Run a function once the database is ready.                                                                        |
| [`MySQL.Async`](/docs/scripting/reference/database/#mysqlasync)                               | Server only       | Old mysql-async names: fetchAll, fetchScalar, fetchSingle, insert, execute, transaction (callback form).          |
| [`MySQL.Sync`](/docs/scripting/reference/database/#mysqlsync)                                 | Server only       | Old mysql-async names that wait for the result: fetchAll, fetchScalar, fetchSingle, insert, execute, transaction. |
| [`GetPlayers`](/docs/scripting/reference/players/#getplayers)                                 | Server only       | List the IDs of all players on the server.                                                                        |
| [`GetNumPlayerIndices`](/docs/scripting/reference/players/#getnumplayerindices)               | Server only       | Number of players on the server.                                                                                  |
| [`GetPlayerFromIndex`](/docs/scripting/reference/players/#getplayerfromindex)                 | Server only       | Player ID at a position in the player list.                                                                       |
| [`DoesPlayerExist`](/docs/scripting/reference/players/#doesplayerexist)                       | Server only       | Check whether a player ID is on the server.                                                                       |
| [`GetPlayerName`](/docs/scripting/reference/players/#getplayername)                           | Server and client | Display name of a player.                                                                                         |
| [`GetPlayerIdentifiers`](/docs/scripting/reference/players/#getplayeridentifiers)             | Server only       | All identifiers of a player.                                                                                      |
| [`GetNumPlayerIdentifiers`](/docs/scripting/reference/players/#getnumplayeridentifiers)       | Server only       | Number of identifiers of a player.                                                                                |
| [`GetPlayerIdentifier`](/docs/scripting/reference/players/#getplayeridentifier)               | Server only       | One identifier of a player by position.                                                                           |
| [`GetPlayerIdentifierByType`](/docs/scripting/reference/players/#getplayeridentifierbytype)   | Server only       | The identifier of a player with a given prefix.                                                                   |
| [`GetPlayerEndpoint`](/docs/scripting/reference/players/#getplayerendpoint)                   | Server only       | Network address of a player, as far as the server shares it.                                                      |
| [`GetPlayerPing`](/docs/scripting/reference/players/#getplayerping)                           | Server only       | Round-trip time to a player in milliseconds.                                                                      |
| [`GetPlayerLastMsg`](/docs/scripting/reference/players/#getplayerlastmsg)                     | Server only       | Milliseconds since the last network event from a player.                                                          |
| [`PlayerId`](/docs/scripting/reference/players/#playerid)                                     | Client only       | Handle of your own player on the client. Pass it to GetPlayerServerId or GetPlayerName.                           |
| [`GetPlayerServerId`](/docs/scripting/reference/players/#getplayerserverid)                   | Client only       | Server ID (source) of a player, as server scripts see it.                                                         |
| [`DropPlayer`](/docs/scripting/reference/players/#dropplayer)                                 | Server only       | Disconnect a player with a reason.                                                                                |
| [`GetPlayerPed`](/docs/scripting/reference/world/#getplayerped)                               | Server and client | A player’s character (ped).                                                                                       |
| [`PlayerPedId`](/docs/scripting/reference/world/#playerpedid)                                 | Client only       | Your own character (ped) on the client.                                                                           |
| [`DoesEntityExist`](/docs/scripting/reference/world/#doesentityexist)                         | Server and client | Check if an entity handle still points to an entity.                                                              |
| [`GetEntityCoords`](/docs/scripting/reference/world/#getentitycoords)                         | Server and client | Position of an entity in meters.                                                                                  |
| [`GetEntityHeading`](/docs/scripting/reference/world/#getentityheading)                       | Server and client | Direction an entity faces, in degrees.                                                                            |
| [`GetEntityForwardVector`](/docs/scripting/reference/world/#getentityforwardvector)           | Server and client | Unit vector in the direction an entity faces.                                                                     |
| [`GetEntityForwardX`](/docs/scripting/reference/world/#getentityforwardx)                     | Server and client | X part of GetEntityForwardVector.                                                                                 |
| [`GetEntityForwardY`](/docs/scripting/reference/world/#getentityforwardy)                     | Server and client | Y part of GetEntityForwardVector.                                                                                 |
| [`GetEntityVelocity`](/docs/scripting/reference/world/#getentityvelocity)                     | Server and client | Speed and direction of an entity in meters per second.                                                            |
| [`GetEntityType`](/docs/scripting/reference/world/#getentitytype)                             | Server and client | Kind of entity.                                                                                                   |
| [`SetEntityCoords`](/docs/scripting/reference/world/#setentitycoords)                         | Server only       | Teleport an entity to a position in meters.                                                                       |
| [`SetEntityHeading`](/docs/scripting/reference/world/#setentityheading)                       | Server only       | Turn an entity to face a direction in degrees.                                                                    |
| [`GetEntityModel`](/docs/scripting/reference/world/#getentitymodel)                           | Server and client | Model of an entity as a hash.                                                                                     |
| [`IsModelValid`](/docs/scripting/reference/world/#ismodelvalid)                               | Server and client | Check if the game knows a model that CreateObject or CreateVehicle can create.                                    |
| [`IsModelAVehicle`](/docs/scripting/reference/world/#ismodelavehicle)                         | Server and client | Check if a model is a vehicle model.                                                                              |
| [`CreateObject`](/docs/scripting/reference/world/#createobject)                               | Server only       | Create an object in the world for every player.                                                                   |
| [`CreateObjectNoOffset`](/docs/scripting/reference/world/#createobjectnooffset)               | Server only       | Same as CreateObject.                                                                                             |
| [`CreateVehicle`](/docs/scripting/reference/world/#createvehicle)                             | Server only       | Create a vehicle in the world for every player.                                                                   |
| [`DeleteEntity`](/docs/scripting/reference/world/#deleteentity)                               | Server only       | Delete an entity that a script created.                                                                           |
| [`FreezeEntityPosition`](/docs/scripting/reference/world/#freezeentityposition)               | Server only       | Hold an entity in place without physics, or let it move again.                                                    |
| [`Gampeon.ChatAddMessage`](/docs/scripting/reference/chat/#gampeonchataddmessage)             | Client only       | Show a line in the chat window of the game.                                                                       |
| [`Gampeon.ChatClear`](/docs/scripting/reference/chat/#gampeonchatclear)                       | Client only       | Remove all lines from the chat window.                                                                            |
| [`Gampeon.ChatAddSuggestion`](/docs/scripting/reference/chat/#gampeonchataddsuggestion)       | Client only       | Suggest a command while the player types in the chat window.                                                      |
| [`Gampeon.ChatRemoveSuggestion`](/docs/scripting/reference/chat/#gampeonchatremovesuggestion) | Client only       | Remove a command suggestion.                                                                                      |
| [`StartResource`](/docs/scripting/reference/resource/#startresource)                          | Server only       | Start a resource and its dependencies.                                                                            |
| [`StopResource`](/docs/scripting/reference/resource/#stopresource)                            | Server only       | Stop a resource and everything that depends on it.                                                                |
| [`SendNUIMessage`](/docs/scripting/reference/nui/#sendnuimessage)                             | Client only       | Send data to the page of this resource.                                                                           |
| [`SendNuiMessage`](/docs/scripting/reference/nui/#sendnuimessage)                             | Client only       | Send a JSON text to the page of this resource.                                                                    |
| [`RegisterNUICallback`](/docs/scripting/reference/nui/#registernuicallback)                   | Client only       | Answer requests from the page of this resource.                                                                   |
| [`SetNuiFocus`](/docs/scripting/reference/nui/#setnuifocus)                                   | Client only       | Give keyboard and mouse to the pages, or give them back to the game.                                              |
| [`SetNuiFocusKeepInput`](/docs/scripting/reference/nui/#setnuifocuskeepinput)                 | Client only       | Let the game keep getting keyboard input while a page has focus.                                                  |
| [`IsNuiFocused`](/docs/scripting/reference/nui/#isnuifocused)                                 | Client only       | Whether a page has the keyboard focus.                                                                            |
| [`IsNuiFocusKeepingInput`](/docs/scripting/reference/nui/#isnuifocuskeepinginput)             | Client only       | Whether the game keeps keyboard input while a page has focus.                                                     |
| [`EnableBlockWorld`](/docs/scripting/reference/blocks/#enableblockworld)                      | Server only       | Switch on the block world of this server.                                                                         |
| [`IsBlockWorldEnabled`](/docs/scripting/reference/blocks/#isblockworldenabled)                | Server and client | Check whether this server has a block world.                                                                      |
| [`GetBlockWorldSeed`](/docs/scripting/reference/blocks/#getblockworldseed)                    | Server only       | Seed of the block world.                                                                                          |
| [`GetBlock`](/docs/scripting/reference/blocks/#getblock)                                      | Server and client | Block at a position.                                                                                              |
| [`SetBlock`](/docs/scripting/reference/blocks/#setblock)                                      | Server only       | Change a block for every player.                                                                                  |
| [`GetBlockSurfaceZ`](/docs/scripting/reference/blocks/#getblocksurfacez)                      | Server and client | Height of the highest solid block in a column.                                                                    |
| [`IsBlockProtected`](/docs/scripting/reference/blocks/#isblockprotected)                      | Server and client | Check whether a position is inside a zone or outside the world, where nobody can change blocks.                   |
| [`GetBlockTypes`](/docs/scripting/reference/blocks/#getblocktypes)                            | Server and client | All block types.                                                                                                  |
| [`GetBlockTarget`](/docs/scripting/reference/blocks/#getblocktarget)                          | Client only       | Block under the crosshair within reach.                                                                           |
| [`SetBlockHotbar`](/docs/scripting/reference/blocks/#setblockhotbar)                          | Client only       | Blocks the player can place, in the slots of the hotbar.                                                          |
| [`GetBlockHotbarSlot`](/docs/scripting/reference/blocks/#getblockhotbarslot)                  | Client only       | Selected slot of the hotbar.                                                                                      |
| [`SetBlockControlsEnabled`](/docs/scripting/reference/blocks/#setblockcontrolsenabled)        | Client only       | Turn digging and placing with the mouse on or off for this player.                                                |
| [`SetBlockHudVisible`](/docs/scripting/reference/blocks/#setblockhudvisible)                  | Client only       | Show or hide the built-in crosshair, block outline and hotbar.                                                    |

## Globals

[Section titled “Globals”](#globals)

* [`source`](/docs/scripting/reference/globals/#source): ID of the player who sent the network event that is being handled.

## Events

[Section titled “Events”](#events)

* [`onResourceStart`](/docs/scripting/reference/events-built-in/#onresourcestart): A resource has started. Fired for every resource, including your own.
* [`onResourceStop`](/docs/scripting/reference/events-built-in/#onresourcestop): A resource is stopping. Save data here.
* [`playerJoining`](/docs/scripting/reference/events-built-in/#playerjoining): A player joined and was verified. `source` is the new player ID.
* [`playerDropped`](/docs/scripting/reference/events-built-in/#playerdropped): A player left. `source` is the player ID; GetPlayerName and GetPlayerIdentifiers still work inside the handler.
* [`gampeon:chatInput`](/docs/scripting/reference/events-built-in/#gampeonchatinput): The player pressed Enter in the chat window of the game. The built-in chat resource handles it.
* [`gampeon:nuiFocusReleased`](/docs/scripting/reference/events-built-in/#gampeonnuifocusreleased): The player held Escape for 2 seconds and took mouse and keyboard back from a web interface. The page stays visible, so close your menu here.
* [`blockBreak`](/docs/scripting/reference/events-built-in/#blockbreak): A player wants to dig a block. `source` is the player. Call CancelEvent to keep the block, before any Wait.
* [`blockPlace`](/docs/scripting/reference/events-built-in/#blockplace): A player wants to place a block. `source` is the player. Call CancelEvent to refuse, before any Wait.
* [`blockChanged`](/docs/scripting/reference/events-built-in/#blockchanged): A block changed, by a player or by SetBlock. Arrives right after the change, in the next server tick.
* [`blockHotbarSelect`](/docs/scripting/reference/events-built-in/#blockhotbarselect): The player picked another slot of the hotbar.

The same reference is available as JSON at [/reference/lua-api.json](/docs/reference/lua-api.json) and as type definitions for editors (see [Editor setup](/docs/scripting/editor-setup/)).

# Block worlds

> A world made of 1 m blocks that players dig and build in, generated from a seed. A platform feature: switch it on with EnableBlockWorld. Coordinates are whole blocks, which are the same as meters. Provided by the game (or gampeon-server).

A world made of 1 m blocks that players dig and build in, generated from a seed. A platform feature: switch it on with EnableBlockWorld. Coordinates are whole blocks, which are the same as meters. Provided by the game (or gampeon-server).

## EnableBlockWorld

[Section titled “EnableBlockWorld”](#enableblockworld)

```lua
EnableBlockWorld(options) --> boolean
```

Switch on the block world of this server. **Server only.**

Call it once when your resource starts, before players spawn. The world stays on until the server stops, also when your resource restarts; calling it again with the same options does nothing. Every client generates the same terrain from the seed, so only changed blocks travel over the network. With `save`, the server keeps changed blocks in a save file and loads them on the next start. Zones are flat areas without blocks for fixed buildings, for example a city: nobody can dig or build there, scripts neither.

| Parameter | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `options` | `table` | { seed = integer, save = string?, zones = { { minX, minY, maxX, maxY, groundZ, blend?, floorZ? } }? }. seed: 0 to 4294967295. save: 1 to 32 characters a-z, 0-9, \_ and -. Zone values are blocks; groundZ is the height of the fixed floor, blend (default 24) the width of the smooth edge, floorZ (default groundZ - 2) the top block of the hidden foundation inside the zone. Set floorZ lower to keep water or low ground of your own map visible. At most 8 zones. |

**Returns**

* `boolean`: true when the world is on. Errors explain wrong options.

```lua
EnableBlockWorld({
  seed = 1337,
  save = 'main',
  zones = { { minX = -60, minY = -60, maxX = 60, maxY = 60, groundZ = 6 } },
})
```

## IsBlockWorldEnabled

[Section titled “IsBlockWorldEnabled”](#isblockworldenabled)

```lua
IsBlockWorldEnabled() --> boolean
```

Check whether this server has a block world. **Server and client.**

On clients it turns true once the world settings arrived from the server, shortly after joining.

**Returns**

* `boolean`: true when there is a block world.

## GetBlockWorldSeed

[Section titled “GetBlockWorldSeed”](#getblockworldseed)

```lua
GetBlockWorldSeed() --> integer|nil
```

Seed of the block world. **Server only.**

**Returns**

* `integer|nil`: The seed, nil without a block world.

## GetBlock

[Section titled “GetBlock”](#getblock)

```lua
GetBlock(x, y, z) --> string|nil
```

Block at a position. **Server and client.**

Works everywhere in the world, also far from players. GetBlock(GetEntityCoords(ped)) is the block the feet of a character are in.

| Parameter | Type     | Description                                                                   |
| --------- | -------- | ----------------------------------------------------------------------------- |
| `x`       | `number` | Block x (or a vector3 here and leave out y and z). Decimals are rounded down. |
| `y`       | `number` | Block y.                                                                      |
| `z`       | `number` | Block z, up.                                                                  |

**Returns**

* `string|nil`: Block name such as “stone” or “air”, nil without a block world.

```lua
local pos = GetEntityCoords(GetPlayerPed(source))
if GetBlock(pos.x, pos.y, pos.z - 1) == 'sand' then
  print('on the beach')
end
```

## SetBlock

[Section titled “SetBlock”](#setblock)

```lua
SetBlock(x, y, z, block) --> boolean
```

Change a block for every player. **Server only.**

Scripts may set any block, including ones players cannot place. Fires blockChanged. Changes inside zones, outside the world and on the bottom layer are refused.

| Parameter | Type     | Description                                                                   |
| --------- | -------- | ----------------------------------------------------------------------------- |
| `x`       | `number` | Block x (or a vector3 here and leave out y and z). Decimals are rounded down. |
| `y`       | `number` | Block y.                                                                      |
| `z`       | `number` | Block z, up.                                                                  |
| `block`   | `string` | Block name, see GetBlockTypes. “air” removes the block.                       |

**Returns**

* `boolean`: false if the position is protected or outside the world.

```lua
-- a small tower of bricks
for z = 10, 14 do
  SetBlock(20, 30, z, 'brick')
end
```

## GetBlockSurfaceZ

[Section titled “GetBlockSurfaceZ”](#getblocksurfacez)

```lua
GetBlockSurfaceZ(x, y) --> integer|nil
```

Height of the highest solid block in a column. **Server and client.**

| Parameter | Type     | Description                                          |
| --------- | -------- | ---------------------------------------------------- |
| `x`       | `number` | Block x (or a vector2/vector3 here and leave out y). |
| `y`       | `number` | Block y.                                             |

**Returns**

* `integer|nil`: z of the top solid block, nil without a block world. Its top face is at z + 1, so a character stands there with its middle at about z + 2.

```lua
local z = GetBlockSurfaceZ(100, 100)
SetEntityCoords(GetPlayerPed(source), 100.5, 100.5, z + 2.0)
```

## IsBlockProtected

[Section titled “IsBlockProtected”](#isblockprotected)

```lua
IsBlockProtected(x, y, z) --> boolean
```

Check whether a position is inside a zone or outside the world, where nobody can change blocks. **Server and client.**

| Parameter | Type     | Description                                                                   |
| --------- | -------- | ----------------------------------------------------------------------------- |
| `x`       | `number` | Block x (or a vector3 here and leave out y and z). Decimals are rounded down. |
| `y`       | `number` | Block y.                                                                      |
| `z`       | `number` | Block z, up.                                                                  |

**Returns**

* `boolean`: true where blocks cannot change.

## GetBlockTypes

[Section titled “GetBlockTypes”](#getblocktypes)

```lua
GetBlockTypes() --> table
```

All block types. **Server and client.**

The list only grows. Blocks with breakable = false (deepstone) cannot be dug by players; placeable = false means players cannot place them (ores), but scripts can.

**Returns**

* `table`: List of { id = ‘stone’, name = ‘Stone’, solid = true, breakable = true, placeable = true }, without air.

## GetBlockTarget

[Section titled “GetBlockTarget”](#getblocktarget)

```lua
GetBlockTarget() --> integer|nil, integer, integer, integer, integer, integer
```

Block under the crosshair within reach. **Client only.**

**Returns**

* `integer|nil`: x of the block, nil when the crosshair points at nothing within reach.
* `integer`: y
* `integer`: z
* `integer`: nx: side the crosshair points at (-1, 0 or 1). Placing puts the new block at x + nx.
* `integer`: ny
* `integer`: nz

```lua
local x, y, z = GetBlockTarget()
if x then
  print('looking at ' .. GetBlock(x, y, z))
end
```

## SetBlockHotbar

[Section titled “SetBlockHotbar”](#setblockhotbar)

```lua
SetBlockHotbar(slots)
```

Blocks the player can place, in the slots of the hotbar. **Client only.**

The player picks a slot with the mouse wheel or keys 1 to 9 and places it with the right mouse button. An empty list switches placing off. Send the list from your server inventory with an event; the server still asks blockPlace before anything changes.

| Parameter | Type    | Description                                                                          |
| --------- | ------- | ------------------------------------------------------------------------------------ |
| `slots`   | `table` | Up to 9 entries: a block name, or { block = ‘planks’, count = 12 } to show a number. |

```lua
RegisterNetEvent('mygame:inventory', function(items)
  SetBlockHotbar(items) -- { { block = 'stone', count = 32 }, ... }
end)
```

## GetBlockHotbarSlot

[Section titled “GetBlockHotbarSlot”](#getblockhotbarslot)

```lua
GetBlockHotbarSlot() --> integer
```

Selected slot of the hotbar. **Client only.**

**Returns**

* `integer`: Slot from 1, 0 when the hotbar is empty.

## SetBlockControlsEnabled

[Section titled “SetBlockControlsEnabled”](#setblockcontrolsenabled)

```lua
SetBlockControlsEnabled(enabled)
```

Turn digging and placing with the mouse on or off for this player. **Client only.**

On by default. Turn it off while a menu is open or in areas where your game does not allow building.

| Parameter | Type      | Description                   |
| --------- | --------- | ----------------------------- |
| `enabled` | `boolean` | false turns the controls off. |

## SetBlockHudVisible

[Section titled “SetBlockHudVisible”](#setblockhudvisible)

```lua
SetBlockHudVisible(visible)
```

Show or hide the built-in crosshair, block outline and hotbar. **Client only.**

Hide it when your resource draws its own hotbar with a web interface (NUI). The controls keep working.

| Parameter | Type      | Description     |
| --------- | --------- | --------------- |
| `visible` | `boolean` | false hides it. |

# Chat

> The chat window of the game. Use the events of the built-in chat resource (chatMessage, chat:addMessage) in your scripts; these functions are what the chat resource itself uses.

The chat window of the game. Use the events of the built-in chat resource (chatMessage, chat:addMessage) in your scripts; these functions are what the chat resource itself uses.

## Gampeon.ChatAddMessage

[Section titled “Gampeon.ChatAddMessage”](#gampeonchataddmessage)

```lua
Gampeon.ChatAddMessage(author, text, color?)
```

Show a line in the chat window of the game. **Client only.**

Most scripts use the chat:addMessage event instead, which the chat resource turns into this call. Line breaks become spaces, other control characters are removed, the author is cut at 64 bytes and the text at 1024 bytes.

| Parameter          | Type                          | Description                                             |
| ------------------ | ----------------------------- | ------------------------------------------------------- |
| `author`           | `string`                      | Shown before the text. Empty for a line without author. |
| `text`             | `string`                      | The message.                                            |
| `color` (optional) | `{integer, integer, integer}` | Color as {r, g, b} from 0 to 255. Default white.        |

```lua
Gampeon.ChatAddMessage('System', 'Welcome to the server', {0, 200, 255})
```

**Compared to FiveM:** GAMPEON function. FiveM scripts use the chat:addMessage event, which works the same with the built-in chat resource.

## Gampeon.ChatClear

[Section titled “Gampeon.ChatClear”](#gampeonchatclear)

```lua
Gampeon.ChatClear()
```

Remove all lines from the chat window. **Client only.**

**Compared to FiveM:** GAMPEON function. The chat:clear event of the chat resource calls it.

## Gampeon.ChatAddSuggestion

[Section titled “Gampeon.ChatAddSuggestion”](#gampeonchataddsuggestion)

```lua
Gampeon.ChatAddSuggestion(name, help?)
```

Suggest a command while the player types in the chat window. **Client only.**

| Parameter         | Type     | Description                                |
| ----------------- | -------- | ------------------------------------------ |
| `name`            | `string` | The command with slash, for example “/tp”. |
| `help` (optional) | `string` | Short help text.                           |

**Compared to FiveM:** GAMPEON function. The chat:addSuggestion event of the chat resource calls it. Parameter hints are not shown yet.

## Gampeon.ChatRemoveSuggestion

[Section titled “Gampeon.ChatRemoveSuggestion”](#gampeonchatremovesuggestion)

```lua
Gampeon.ChatRemoveSuggestion(name)
```

Remove a command suggestion. **Client only.**

| Parameter | Type     | Description             |
| --------- | -------- | ----------------------- |
| `name`    | `string` | The command with slash. |

**Compared to FiveM:** GAMPEON function. The chat:removeSuggestion event of the chat resource calls it.

# Commands

> Console and chat commands that resources register, and permissions (ACE) for them.

Console and chat commands that resources register, and permissions (ACE) for them.

## RegisterCommand

[Section titled “RegisterCommand”](#registercommand)

```lua
RegisterCommand(commandName, handler, restricted?)
```

Add a command for the console, the chat (/name) or key bindings. **Server and client.**

Commands are shared by all resources on the same side. If two resources register the same name, the later one wins and a warning is logged. Commands of a stopped resource are removed.

| Parameter               | Type                                                       | Description                                                                                           |
| ----------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `commandName`           | `string`                                                   | Name without slash, for example “car”. Not case-sensitive.                                            |
| `handler`               | `fun(source: integer, args: string[], rawCommand: string)` | Called with the player ID (0 for the server console), the words after the command and the whole line. |
| `restricted` (optional) | `boolean`                                                  | If true, only players with the permission command.\<name> may use it (see add_ace in server.cfg).     |

```lua
RegisterCommand('heal', function(source, args, raw)
  local target = tonumber(args[1]) or source
  TriggerClientEvent('myres:heal', target)
end, true)
```

**Compared to FiveM:** Same as in FiveM. The handler runs in its own thread, so it may call Wait.

## ExecuteCommand

[Section titled “ExecuteCommand”](#executecommand)

```lua
ExecuteCommand(commandString)
```

Run a console command, as if typed into the server console. **Server and client.**

| Parameter       | Type     | Description                                               |
| --------------- | -------- | --------------------------------------------------------- |
| `commandString` | `string` | The whole command line, for example “restart myresource”. |

```lua
ExecuteCommand('add_principal identifier.gampeon:42 group.admin')
```

**Compared to FiveM:** Same as in FiveM. On the server it runs with console permissions; built-in commands like start, stop or add_ace work too.

## GetRegisteredCommands

[Section titled “GetRegisteredCommands”](#getregisteredcommands)

```lua
GetRegisteredCommands() --> {name: string, resource: string, arity: integer, restricted: boolean}[]
```

List all commands that resources registered on this side. **Server and client.**

**Returns**

* `{name: string, resource: string, arity: integer, restricted: boolean}[]`: One entry per command. arity is always -1. restricted is true for commands that need an ACE permission.

```lua
for _, cmd in ipairs(GetRegisteredCommands()) do
  print(cmd.name, cmd.resource)
end
```

**Compared to FiveM:** Same as in FiveM.

## IsPlayerAceAllowed

[Section titled “IsPlayerAceAllowed”](#isplayeraceallowed)

```lua
IsPlayerAceAllowed(playerSrc, object) --> boolean
```

Check if a player has a permission (ACE). **Server only.**

| Parameter   | Type              | Description                                              |
| ----------- | ----------------- | -------------------------------------------------------- |
| `playerSrc` | `integer\|string` | Player ID.                                               |
| `object`    | `string`          | Permission, for example “command.heal” or “myres.admin”. |

**Returns**

* `boolean`: true if allowed.

```lua
if IsPlayerAceAllowed(source, 'myres.admin') then
  -- ...
end
```

**Compared to FiveM:** Same as in FiveM. Server operators grant permissions with add_ace and add_principal in server.cfg.

# Convars

> Server settings from server.cfg (set, setr, sets) that scripts can read.

Server settings from server.cfg (set, setr, sets) that scripts can read.

## GetConvar

[Section titled “GetConvar”](#getconvar)

```lua
GetConvar(varName, default) --> string
```

Read a convar as text. **Server and client.**

| Parameter | Type     | Description                        |
| --------- | -------- | ---------------------------------- |
| `varName` | `string` | Name, for example “sv_hostname”.   |
| `default` | `string` | Returned if the convar is not set. |

**Returns**

* `string`: The value or the default.

```lua
local locale = GetConvar('myres_locale', 'en')
```

**Compared to FiveM:** Same as in FiveM. On the client only replicated convars (setr) are visible. Protected convars (for example the server key) always return the default.

## GetConvarInt

[Section titled “GetConvarInt”](#getconvarint)

```lua
GetConvarInt(varName, default) --> integer
```

Read a convar as a whole number. **Server and client.**

| Parameter | Type      | Description                                        |
| --------- | --------- | -------------------------------------------------- |
| `varName` | `string`  | Name.                                              |
| `default` | `integer` | Returned if the convar is not set or not a number. |

**Returns**

* `integer`: The value or the default.

```lua
local slots = GetConvarInt('sv_maxclients', 64)
```

**Compared to FiveM:** Same as in FiveM.

## GetConvarFloat

[Section titled “GetConvarFloat”](#getconvarfloat)

```lua
GetConvarFloat(varName, default) --> number
```

Read a convar as a number with decimals. **Server and client.**

| Parameter | Type     | Description                                        |
| --------- | -------- | -------------------------------------------------- |
| `varName` | `string` | Name.                                              |
| `default` | `number` | Returned if the convar is not set or not a number. |

**Returns**

* `number`: The value or the default.

```lua
local rate = GetConvarFloat('myres_tax', 0.19)
```

**Compared to FiveM:** Same as in FiveM.

## GetConvarBool

[Section titled “GetConvarBool”](#getconvarbool)

```lua
GetConvarBool(varName, default) --> boolean
```

Read a convar as true or false. **Server and client.**

| Parameter | Type      | Description                                              |
| --------- | --------- | -------------------------------------------------------- |
| `varName` | `string`  | Name.                                                    |
| `default` | `boolean` | Returned if the convar is not set or not a yes/no value. |

**Returns**

* `boolean`: true for true, 1, yes, on; false for false, 0, no, off; otherwise the default.

```lua
if GetConvarBool('myres_debug', false) then print('debug on') end
```

**Compared to FiveM:** Same as in FiveM.

## SetConvar

[Section titled “SetConvar”](#setconvar)

```lua
SetConvar(varName, value)
```

Set a convar on the server. **Server only.**

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `varName` | `string` | Name.       |
| `value`   | `string` | New value.  |

```lua
SetConvar('myres_mode', 'event')
```

**Compared to FiveM:** Same as in FiveM. Protected convars cannot be changed.

## SetConvarReplicated

[Section titled “SetConvarReplicated”](#setconvarreplicated)

```lua
SetConvarReplicated(varName, value)
```

Set a convar that clients can read too. **Server only.**

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `varName` | `string` | Name.       |
| `value`   | `string` | New value.  |

```lua
SetConvarReplicated('myres_theme', 'dark')
```

**Compared to FiveM:** Same as in FiveM.

## SetConvarServerInfo

[Section titled “SetConvarServerInfo”](#setconvarserverinfo)

```lua
SetConvarServerInfo(varName, value)
```

Set a convar that is shown in the server list. **Server only.**

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `varName` | `string` | Name.       |
| `value`   | `string` | New value.  |

```lua
SetConvarServerInfo('tags', 'roleplay,economy')
```

**Compared to FiveM:** Same as in FiveM.

# Data

> Encoding and decoding values.

Encoding and decoding values.

## json.encode

[Section titled “json.encode”](#jsonencode)

```lua
json.encode(value) --> string
```

Turn a Lua value into a JSON string. **Server and client.**

| Parameter | Type  | Description                            |
| --------- | ----- | -------------------------------------- |
| `value`   | `any` | Table, string, number, boolean or nil. |

**Returns**

* `string`: JSON text.

```lua
local text = json.encode({ name = 'Max', cash = 100 })
```

**Compared to FiveM:** Same as in FiveM.

## json.decode

[Section titled “json.decode”](#jsondecode)

```lua
json.decode(text) --> any, string?
```

Turn a JSON string into a Lua value. **Server and client.**

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `text`    | `string` | JSON text.  |

**Returns**

* `any`: The value, or nil if the text is not valid JSON.
* `string?`: Error message when decoding failed.

```lua
local data, err = json.decode('{"cash": 100}')
if not data then print(err) end
```

**Compared to FiveM:** FiveM throws on invalid JSON; GAMPEON returns nil and an error message.

# Database

> MySQL/MariaDB (or SQLite for tests) through the MySQL table, compatible with oxmysql. Calls never block the server.

MySQL/MariaDB (or SQLite for tests) through the MySQL table, compatible with oxmysql. Calls never block the server.

## MySQL.query

[Section titled “MySQL.query”](#mysqlquery)

```lua
MySQL.query(query, parameters?, cb?)
```

Run a query. SELECT returns the rows; other statements return { affectedRows, insertId }. **Server only.**

Add .await to wait for the result in the current thread instead of a callback: local rows = MySQL.query.await(sql, params). On an error the callback is not called and the error is logged; .await raises the error in the calling thread.

| Parameter               | Type                 | Description                                                                                                                                       |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`             | SQL with ? or @name placeholders.                                                                                                                 |
| `parameters` (optional) | `table\|any[]`       | Values for ? placeholders (list) or for @name/:name placeholders (table with keys “name” or “@name”). A list as a value for ? expands for IN (?). |
| `cb` (optional)         | `fun(result: table)` | Called with the result. Leave it out and use .await to get the result directly.                                                                   |

```lua
MySQL.query('SELECT name, money FROM users WHERE job = ?', { 'police' }, function(rows)
  for _, row in ipairs(rows) do print(row.name, row.money) end
end)


local rows = MySQL.query.await('SELECT * FROM users WHERE identifier = @id', { id = identifier })
```

**Compared to FiveM:** Same as oxmysql. NULL columns are missing from the row table, TINYINT(1) becomes true/false, DATE/DATETIME/TIMESTAMP become milliseconds since 1970 (UTC).

## MySQL.single

[Section titled “MySQL.single”](#mysqlsingle)

```lua
MySQL.single(query, parameters?, cb?)
```

Run a query and return only the first row. **Server only.**

Add .await to wait for the result in the current thread instead of a callback: local row = MySQL.single.await(sql, params). nil if there is no row.

| Parameter               | Type                  | Description                                                                                                                                       |
| ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`              | SQL.                                                                                                                                              |
| `parameters` (optional) | `table\|any[]`        | Values for ? placeholders (list) or for @name/:name placeholders (table with keys “name” or “@name”). A list as a value for ? expands for IN (?). |
| `cb` (optional)         | `fun(result: table?)` | Called with the result. Leave it out and use .await to get the result directly.                                                                   |

```lua
local user = MySQL.single.await('SELECT * FROM users WHERE identifier = ? LIMIT 1', { identifier })
if user then print(user.money) end
```

**Compared to FiveM:** Same as oxmysql.

## MySQL.scalar

[Section titled “MySQL.scalar”](#mysqlscalar)

```lua
MySQL.scalar(query, parameters?, cb?)
```

Run a query and return the first column of the first row. **Server only.**

Add .await to wait for the result in the current thread instead of a callback: local value = MySQL.scalar.await(sql, params).

| Parameter               | Type               | Description                                                                                                                                       |
| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`           | SQL.                                                                                                                                              |
| `parameters` (optional) | `table\|any[]`     | Values for ? placeholders (list) or for @name/:name placeholders (table with keys “name” or “@name”). A list as a value for ? expands for IN (?). |
| `cb` (optional)         | `fun(result: any)` | Called with the result. Leave it out and use .await to get the result directly.                                                                   |

```lua
local count = MySQL.scalar.await('SELECT COUNT(*) FROM vehicles WHERE owner = ?', { identifier })
```

**Compared to FiveM:** Same as oxmysql.

## MySQL.insert

[Section titled “MySQL.insert”](#mysqlinsert)

```lua
MySQL.insert(query, parameters?, cb?)
```

Run an INSERT and return the new ID. **Server only.**

Add .await to wait for the result in the current thread instead of a callback: local id = MySQL.insert.await(sql, params).

| Parameter               | Type                   | Description                                                                                                                                       |
| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`               | SQL.                                                                                                                                              |
| `parameters` (optional) | `table\|any[]`         | Values for ? placeholders (list) or for @name/:name placeholders (table with keys “name” or “@name”). A list as a value for ? expands for IN (?). |
| `cb` (optional)         | `fun(result: integer)` | Called with the result. Leave it out and use .await to get the result directly.                                                                   |

```lua
local id = MySQL.insert.await('INSERT INTO bills (owner, amount) VALUES (?, ?)', { identifier, 250 })
```

**Compared to FiveM:** Same as oxmysql.

## MySQL.update

[Section titled “MySQL.update”](#mysqlupdate)

```lua
MySQL.update(query, parameters?, cb?)
```

Run an UPDATE or DELETE and return the number of changed rows. **Server only.**

Add .await to wait for the result in the current thread instead of a callback: local count = MySQL.update.await(sql, params).

| Parameter               | Type                   | Description                                                                                                                                       |
| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`               | SQL.                                                                                                                                              |
| `parameters` (optional) | `table\|any[]`         | Values for ? placeholders (list) or for @name/:name placeholders (table with keys “name” or “@name”). A list as a value for ? expands for IN (?). |
| `cb` (optional)         | `fun(result: integer)` | Called with the result. Leave it out and use .await to get the result directly.                                                                   |

```lua
local changed = MySQL.update.await('UPDATE users SET money = money + ? WHERE identifier = ?', { 100, identifier })
```

**Compared to FiveM:** Same as oxmysql.

## MySQL.prepare

[Section titled “MySQL.prepare”](#mysqlprepare)

```lua
MySQL.prepare(query, parameters, cb?)
```

Run a statement with ? placeholders, also many times with a list of parameter lists. **Server only.**

Add .await to wait for the result in the current thread instead of a callback: local result = MySQL.prepare.await(sql, params).

| Parameter       | Type               | Description                                                                     |
| --------------- | ------------------ | ------------------------------------------------------------------------------- |
| `query`         | `string`           | SQL with ? placeholders.                                                        |
| `parameters`    | `any[]\|any[][]`   | One list of values, or a list of lists to run the statement once per entry.     |
| `cb` (optional) | `fun(result: any)` | Called with the result. Leave it out and use .await to get the result directly. |

```lua
MySQL.prepare('INSERT INTO items (owner, name) VALUES (?, ?)', { { 1, 'bread' }, { 1, 'water' } })
local money = MySQL.prepare.await('SELECT money FROM users WHERE id = ?', { 1 })
```

**Compared to FiveM:** Same as oxmysql: one row with one column returns the value, one row returns the row, more rows return the list. INSERT returns the new ID, other statements the number of changed rows. Runs as a normal query on the server.

## MySQL.rawExecute

[Section titled “MySQL.rawExecute”](#mysqlrawexecute)

```lua
MySQL.rawExecute(query, parameters?, cb?)
```

Run a query and return the raw result. **Server only.**

Add .await to wait for the result in the current thread instead of a callback: local result = MySQL.rawExecute.await(sql, params).

| Parameter               | Type                 | Description                                                                                                                                       |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`             | SQL.                                                                                                                                              |
| `parameters` (optional) | `table\|any[]`       | Values for ? placeholders (list) or for @name/:name placeholders (table with keys “name” or “@name”). A list as a value for ? expands for IN (?). |
| `cb` (optional)         | `fun(result: table)` | Called with the result. Leave it out and use .await to get the result directly.                                                                   |

```lua
local rows = MySQL.rawExecute.await('SHOW TABLES')
```

**Compared to FiveM:** Same as MySQL.query in GAMPEON.

## MySQL.execute

[Section titled “MySQL.execute”](#mysqlexecute)

```lua
MySQL.execute(query, parameters?, cb?)
```

Old name of MySQL.query. **Server only.**

| Parameter               | Type                 | Description                                                                                                                                       |
| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`                 | `string`             | SQL.                                                                                                                                              |
| `parameters` (optional) | `table\|any[]`       | Values for ? placeholders (list) or for @name/:name placeholders (table with keys “name” or “@name”). A list as a value for ? expands for IN (?). |
| `cb` (optional)         | `fun(result: table)` | Called with the result. Leave it out and use .await to get the result directly.                                                                   |

```lua
MySQL.execute('DELETE FROM sessions WHERE expires < NOW()')
```

**Compared to FiveM:** Same as oxmysql.

## MySQL.transaction

[Section titled “MySQL.transaction”](#mysqltransaction)

```lua
MySQL.transaction(queries, parameters?, cb?)
```

Run several statements in one transaction. If one fails, none of them is kept. **Server only.**

Add .await to wait for the result in the current thread instead of a callback: local ok = MySQL.transaction.await(queries, params).

| Parameter               | Type                                          | Description                                                                          |
| ----------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------ |
| `queries`               | `(string\|{query: string, values: table?})[]` | Statements as strings (using the shared parameters) or tables with query and values. |
| `parameters` (optional) | `table`                                       | Shared parameters for statements given as strings.                                   |
| `cb` (optional)         | `fun(result: boolean)`                        | Called with the result. Leave it out and use .await to get the result directly.      |

```lua
local ok = MySQL.transaction.await({
  { query = 'UPDATE users SET money = money - ? WHERE id = ?', values = { 100, from } },
  { query = 'UPDATE users SET money = money + ? WHERE id = ?', values = { 100, to } },
})
```

**Compared to FiveM:** Same as oxmysql. The callback gets true, or false after a rollback.

## MySQL.ready

[Section titled “MySQL.ready”](#mysqlready)

```lua
MySQL.ready(cb)
```

Run a function once the database is ready. **Server only.**

| Parameter | Type       | Description             |
| --------- | ---------- | ----------------------- |
| `cb`      | `function` | Called in a new thread. |

```lua
MySQL.ready(function()
  print('database ready')
end)
```

**Compared to FiveM:** Same as oxmysql. The server connects before resources start, so it runs right away.

## MySQL.Async

[Section titled “MySQL.Async”](#mysqlasync)

```lua
MySQL.Async()
```

Old mysql-async names: fetchAll, fetchScalar, fetchSingle, insert, execute, transaction (callback form). **Server only.**

```lua
MySQL.Async.fetchAll('SELECT * FROM users WHERE identifier = @identifier', { ['@identifier'] = id }, function(rows) end)
```

**Compared to FiveM:** Same as the mysql-async names that oxmysql still offers. Prefer MySQL.query and friends in new code.

## MySQL.Sync

[Section titled “MySQL.Sync”](#mysqlsync)

```lua
MySQL.Sync()
```

Old mysql-async names that wait for the result: fetchAll, fetchScalar, fetchSingle, insert, execute, transaction. **Server only.**

```lua
local rows = MySQL.Sync.fetchAll('SELECT * FROM jobs')
```

**Compared to FiveM:** Same as the mysql-async names that oxmysql still offers. Only inside a thread.

# Events

> Resources talk to each other and between server and client through named events.

Resources talk to each other and between server and client through named events.

## AddEventHandler

[Section titled “AddEventHandler”](#addeventhandler)

```lua
AddEventHandler(eventName, handler) --> EventHandle
```

Run a function whenever an event fires. **Server and client.**

Handlers run for local events from TriggerEvent and, once the event is registered with RegisterNetEvent, for events from the other side. Each handler runs in its own thread, so it may call Wait.

| Parameter   | Type            | Description                                                                                      |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `eventName` | `string`        | Name of the event, for example “myshop:buy”. Prefix it with your resource name to avoid clashes. |
| `handler`   | `fun(...: any)` | Called with the arguments of the event.                                                          |

**Returns**

* `EventHandle`: Pass it to RemoveEventHandler to remove the handler again.

```lua
AddEventHandler('myshop:opened', function(shopId)
  print('Shop opened: ' .. shopId)
end)
```

**Compared to FiveM:** Same as in FiveM.

## RemoveEventHandler

[Section titled “RemoveEventHandler”](#removeeventhandler)

```lua
RemoveEventHandler(handle)
```

Remove a handler added with AddEventHandler. **Server and client.**

| Parameter | Type          | Description                                            |
| --------- | ------------- | ------------------------------------------------------ |
| `handle`  | `EventHandle` | Value returned by AddEventHandler or RegisterNetEvent. |

```lua
local h = AddEventHandler('tick', function() end)
RemoveEventHandler(h)
```

**Compared to FiveM:** Same as in FiveM.

## RegisterNetEvent

[Section titled “RegisterNetEvent”](#registernetevent)

```lua
RegisterNetEvent(eventName, handler?) --> EventHandle?
```

Allow an event to arrive from the other side (client to server or server to client). **Server and client.**

Without this call, events from the network never reach your handlers. On the server, treat every network event as untrusted input: check `source` and every argument, because players can send any values.

| Parameter            | Type            | Description                                                   |
| -------------------- | --------------- | ------------------------------------------------------------- |
| `eventName`          | `string`        | Name of the event.                                            |
| `handler` (optional) | `fun(...: any)` | Optional handler, same as calling AddEventHandler afterwards. |

**Returns**

* `EventHandle?`: The handle when a handler was given, otherwise nothing.

```lua
RegisterNetEvent('myshop:buy', function(itemId)
  local player = source
  if type(itemId) ~= 'string' then return end
  -- check that the player may buy the item, then give it
end)
```

**Compared to FiveM:** Same as in FiveM.

## RegisterServerEvent

[Section titled “RegisterServerEvent”](#registerserverevent)

Deprecated

Use RegisterNetEvent.

```lua
RegisterServerEvent(eventName, handler?) --> EventHandle?
```

Old name of RegisterNetEvent, kept for ported FiveM scripts. **Server and client.**

| Parameter            | Type            | Description        |
| -------------------- | --------------- | ------------------ |
| `eventName`          | `string`        | Name of the event. |
| `handler` (optional) | `fun(...: any)` | Optional handler.  |

**Returns**

* `EventHandle?`: The handle when a handler was given.

**Compared to FiveM:** Same as in FiveM.

## TriggerEvent

[Section titled “TriggerEvent”](#triggerevent)

```lua
TriggerEvent(eventName, ...)
```

Fire an event for all resources on the same side. **Server and client.**

Handlers of every running resource on this side receive the event. It never leaves the machine.

| Parameter   | Type     | Description                                                                                                                                                 |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventName` | `string` | Name of the event.                                                                                                                                          |
| `...`       | `any`    | Arguments. Values are copied: tables, strings, numbers, booleans and nil. Functions arrive as callable functions that run in the resource that passed them. |

```lua
TriggerEvent('myshop:opened', 'downtown')


-- callback pattern from ESX
TriggerEvent('myframework:getSharedObject', function(obj) Framework = obj end)
```

**Compared to FiveM:** Same as in FiveM, including functions as arguments.

## CancelEvent

[Section titled “CancelEvent”](#cancelevent)

```lua
CancelEvent()
```

Cancel the event whose handler is running. **Server and client.**

Other handlers still run. The code that fired the event checks WasEventCanceled right after TriggerEvent and can skip its default action. Only works before the handler calls Wait.

```lua
AddEventHandler('chatMessage', function(source, name, message)
  if message:find('badword') then
    CancelEvent()
  end
end)
```

**Compared to FiveM:** Same as in FiveM.

## WasEventCanceled

[Section titled “WasEventCanceled”](#waseventcanceled)

```lua
WasEventCanceled() --> boolean
```

Check if a handler canceled the last event fired with TriggerEvent. **Server and client.**

**Returns**

* `boolean`: true if a handler called CancelEvent.

```lua
TriggerEvent('myshop:beforeBuy', source, item)
if WasEventCanceled() then
  return
end
```

**Compared to FiveM:** Same as in FiveM.

## TriggerServerEvent

[Section titled “TriggerServerEvent”](#triggerserverevent)

```lua
TriggerServerEvent(eventName, ...)
```

Send an event from the client to the server. **Client only.**

The server only receives it if a resource registered it with RegisterNetEvent. The server sees the sending player in `source`.

| Parameter   | Type     | Description                                                                                         |
| ----------- | -------- | --------------------------------------------------------------------------------------------------- |
| `eventName` | `string` | Name of the event.                                                                                  |
| `...`       | `any`    | Arguments, copied like in TriggerEvent. Functions do not travel over the network and arrive as nil. |

```lua
TriggerServerEvent('myshop:buy', 'water')
```

**Compared to FiveM:** Same as in FiveM.

## TriggerClientEvent

[Section titled “TriggerClientEvent”](#triggerclientevent)

```lua
TriggerClientEvent(eventName, target, ...)
```

Send an event from the server to one player or to everyone. **Server only.**

| Parameter   | Type      | Description                                                                                         |
| ----------- | --------- | --------------------------------------------------------------------------------------------------- |
| `eventName` | `string`  | Name of the event.                                                                                  |
| `target`    | `integer` | Player ID, or -1 for all players.                                                                   |
| `...`       | `any`     | Arguments, copied like in TriggerEvent. Functions do not travel over the network and arrive as nil. |

```lua
TriggerClientEvent('myshop:bought', source, 'water')
TriggerClientEvent('chat:announce', -1, 'Server restart in 5 minutes')
```

**Compared to FiveM:** Same as in FiveM.

# Built-in events

> Events the runtime fires by itself.

## onResourceStart

[Section titled “onResourceStart”](#onresourcestart)

A resource has started. Fired for every resource, including your own. Server and client.

| Argument       | Type     | Description                        |
| -------------- | -------- | ---------------------------------- |
| `resourceName` | `string` | Name of the resource that started. |

```lua
AddEventHandler('onResourceStart', function(name)
  if name == GetCurrentResourceName() then
    print('ready')
  end
end)
```

## onResourceStop

[Section titled “onResourceStop”](#onresourcestop)

A resource is stopping. Save data here. Server and client.

| Argument       | Type     | Description                      |
| -------------- | -------- | -------------------------------- |
| `resourceName` | `string` | Name of the resource that stops. |

```lua
AddEventHandler('onResourceStop', function(name)
  if name == GetCurrentResourceName() then
    -- save state
  end
end)
```

## playerJoining

[Section titled “playerJoining”](#playerjoining)

A player joined and was verified. `source` is the new player ID. Server only.

| Argument | Type     | Description                           |
| -------- | -------- | ------------------------------------- |
| `oldId`  | `string` | Player ID as string (same as source). |

```lua
AddEventHandler('playerJoining', function()
  print(GetPlayerName(source) .. ' joined')
end)
```

## playerDropped

[Section titled “playerDropped”](#playerdropped)

A player left. `source` is the player ID; GetPlayerName and GetPlayerIdentifiers still work inside the handler. Server only.

| Argument | Type     | Description          |
| -------- | -------- | -------------------- |
| `reason` | `string` | Why the player left. |

```lua
AddEventHandler('playerDropped', function(reason)
  print(GetPlayerName(source) .. ' left: ' .. reason)
end)
```

## gampeon:chatInput

[Section titled “gampeon:chatInput”](#gampeonchatinput)

The player pressed Enter in the chat window of the game. The built-in chat resource handles it. Client only.

| Argument | Type     | Description                                                                                       |
| -------- | -------- | ------------------------------------------------------------------------------------------------- |
| `text`   | `string` | What the player typed, at most 512 bytes, without control characters. Starts with / for commands. |

```lua
AddEventHandler('gampeon:chatInput', function(text)
  print('typed: ' .. text)
end)
```

## gampeon:nuiFocusReleased

[Section titled “gampeon:nuiFocusReleased”](#gampeonnuifocusreleased)

The player held Escape for 2 seconds and took mouse and keyboard back from a web interface. The page stays visible, so close your menu here. Client only.

| Argument       | Type     | Description                        |
| -------------- | -------- | ---------------------------------- |
| `resourceName` | `string` | Resource whose page had the focus. |

```lua
AddEventHandler('gampeon:nuiFocusReleased', function(name)
  if name == GetCurrentResourceName() then
    SendNUIMessage({ action = 'close' })
  end
end)
```

## blockBreak

[Section titled “blockBreak”](#blockbreak)

A player wants to dig a block. `source` is the player. Call CancelEvent to keep the block, before any Wait. Server only.

| Argument | Type      | Description                      |
| -------- | --------- | -------------------------------- |
| `x`      | `integer` | Block x.                         |
| `y`      | `integer` | Block y.                         |
| `z`      | `integer` | Block z.                         |
| `block`  | `string`  | The block that would be removed. |

```lua
AddEventHandler('blockBreak', function(x, y, z, block)
  if block == 'crystal' and not HasPickaxe(source) then
    CancelEvent()
    return
  end
  AddItem(source, block, 1)
end)
```

## blockPlace

[Section titled “blockPlace”](#blockplace)

A player wants to place a block. `source` is the player. Call CancelEvent to refuse, before any Wait. Server only.

| Argument | Type      | Description                              |
| -------- | --------- | ---------------------------------------- |
| `x`      | `integer` | Block x.                                 |
| `y`      | `integer` | Block y.                                 |
| `z`      | `integer` | Block z.                                 |
| `block`  | `string`  | The block from the selected hotbar slot. |

```lua
AddEventHandler('blockPlace', function(x, y, z, block)
  if not TakeItem(source, block, 1) then
    CancelEvent()
  end
end)
```

## blockChanged

[Section titled “blockChanged”](#blockchanged)

A block changed, by a player or by SetBlock. Arrives right after the change, in the next server tick. Server only.

| Argument   | Type      | Description               |
| ---------- | --------- | ------------------------- |
| `x`        | `integer` | Block x.                  |
| `y`        | `integer` | Block y.                  |
| `z`        | `integer` | Block z.                  |
| `oldBlock` | `string`  | Block before.             |
| `newBlock` | `string`  | Block now.                |
| `player`   | `integer` | Player ID, 0 for scripts. |

```lua
AddEventHandler('blockChanged', function(x, y, z, old, new, player)
  print(('%s: %s -> %s at %d %d %d'):format(player, old, new, x, y, z))
end)
```

## blockHotbarSelect

[Section titled “blockHotbarSelect”](#blockhotbarselect)

The player picked another slot of the hotbar. Client only.

| Argument | Type      | Description                              |
| -------- | --------- | ---------------------------------------- |
| `slot`   | `integer` | Slot from 1, 0 when the hotbar is empty. |
| `block`  | \`string  | nil\`                                    |

```lua
AddEventHandler('blockHotbarSelect', function(slot, block)
  SendNUIMessage({ type = 'slot', slot = slot })
end)
```

# Exports

> Functions one resource offers to other resources on the same side.

Functions one resource offers to other resources on the same side.

## exports

[Section titled “exports”](#exports)

```lua
exports(name, fn)
```

Offer a function to other resources, or call one. **Server and client.**

Call `exports('name', fn)` to offer a function. Other resources call it with `exports.yourresource:name(...)` or `exports['your-resource']:name(...)`. Arguments and return values are copied. Functions in them, also inside tables, stay callable and run in the resource they come from, so an export can return an object with methods. Such a function stops working when its resource stops or restarts. Exports only work between resources on the same side.

| Parameter | Type       | Description            |
| --------- | ---------- | ---------------------- |
| `name`    | `string`   | Name of the export.    |
| `fn`      | `function` | The function to offer. |

```lua
-- in resource 'bank'
exports('GetBalance', function(playerId)
  return balances[playerId] or 0
end)


-- in another resource
local money = exports.bank:GetBalance(source)
```

**Compared to FiveM:** Same as in FiveM, including function references. If the export calls Wait, a caller in a thread or event handler waits for the result; elsewhere the result is lost and the log says so.

# Globals

> Global values set by the runtime.

## source

[Section titled “source”](#source)

Type: `integer?`. Server and client.

ID of the player who sent the network event that is being handled.

Only set while a network event handler runs; nil otherwise. Copy it into a local variable before calling Wait, because another event can change it.

```lua
RegisterNetEvent('myshop:buy', function(itemId)
  local player = source
  Wait(100)
  TriggerClientEvent('myshop:bought', player, itemId)
end)
```

# HTTP

> Web requests from server scripts, for example webhooks or external APIs.

Web requests from server scripts, for example webhooks or external APIs.

## PerformHttpRequest

[Section titled “PerformHttpRequest”](#performhttprequest)

```lua
PerformHttpRequest(url, callback?, method?, data?, headers?, options?) --> integer
```

Send a web request and get the answer in a callback. **Server only.**

| Parameter             | Type                                                                                          | Description                                                                                                                    |
| --------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `url`                 | `string`                                                                                      | http\:// or https\:// address. Addresses in private networks and localhost are blocked unless the server operator allows them. |
| `callback` (optional) | `fun(statusCode: integer, body: string?, headers: table<string, string>, errorData: string?)` | Called with the result. body is nil for errors; then errorData has the reason or the error body.                               |
| `method` (optional)   | `string`                                                                                      | GET (default), POST, PUT, PATCH, DELETE, HEAD or OPTIONS.                                                                      |
| `data` (optional)     | `string`                                                                                      | Request body, at most 1 MB by default.                                                                                         |
| `headers` (optional)  | `table<string, string>`                                                                       | Request headers.                                                                                                               |
| `options` (optional)  | `{timeout: integer?}`                                                                         | timeout in milliseconds (at most the server limit, 30 s by default).                                                           |

**Returns**

* `integer`: ID of the request.

```lua
PerformHttpRequest('https://example.com/api/status', function(status, body, headers, err)
  if status == 200 then
    local data = json.decode(body)
  else
    print('request failed', status, err)
  end
end, 'GET', '', { ['Accept'] = 'application/json' })
```

**Compared to FiveM:** Same as in FiveM. At most 32 requests per resource at the same time, responses up to 16 MB.

# Web interfaces (NUI)

> HTML pages of a resource (ui_page) drawn over the game, with messages and callbacks like FiveM NUI.

HTML pages of a resource (ui_page) drawn over the game, with messages and callbacks like FiveM NUI.

## SendNUIMessage

[Section titled “SendNUIMessage”](#sendnuimessage)

```lua
SendNUIMessage(data) --> boolean
```

Send data to the page of this resource. **Client only.**

The page receives it as the data of a message event: window\.addEventListener(‘message’, (e) => { … e.data … }). The data is sent as JSON, at most 1 MB.

| Parameter | Type    | Description                                                         |
| --------- | ------- | ------------------------------------------------------------------- |
| `data`    | `table` | Any value that converts to JSON, usually a table with a type field. |

**Returns**

* `boolean`: Always true.

```lua
SendNUIMessage({ type = 'open', items = { 'bread', 'water' } })
```

**Compared to FiveM:** Same as in FiveM.

## SendNuiMessage

[Section titled “SendNuiMessage”](#sendnuimessage-1)

```lua
SendNuiMessage(jsonString) --> boolean
```

Send a JSON text to the page of this resource. **Client only.**

| Parameter    | Type     | Description                                |
| ------------ | -------- | ------------------------------------------ |
| `jsonString` | `string` | A JSON text, for example from json.encode. |

**Returns**

* `boolean`: false if the text is not valid JSON.

**Compared to FiveM:** Same as in FiveM.

## RegisterNUICallback

[Section titled “RegisterNUICallback”](#registernuicallback)

```lua
RegisterNUICallback(callbackType, callback) --> EventHandle
```

Answer requests from the page of this resource. **Client only.**

The page calls fetch(`https://${GetParentResourceName()}/name`, { method: ‘POST’, body: JSON.stringify(data) }). The handler gets the decoded body and a function cb to answer; the page gets the answer as JSON. If the handler fails or does not answer within 30 seconds, the page gets an error.

| Parameter      | Type                                   | Description                                                 |
| -------------- | -------------------------------------- | ----------------------------------------------------------- |
| `callbackType` | `string`                               | Name in the URL, for example “close”.                       |
| `callback`     | `fun(data: any, cb: fun(result: any))` | Called with the request body; call cb once with the answer. |

**Returns**

* `EventHandle`: Handle for RemoveEventHandler.

```lua
RegisterNUICallback('close', function(data, cb)
  SetNuiFocus(false, false)
  cb('ok')
end)
```

**Compared to FiveM:** Same as in FiveM. The low-level form with RegisterNuiCallbackType and AddEventHandler(‘\_\_cfx_nui:name’) is not supported.

## SetNuiFocus

[Section titled “SetNuiFocus”](#setnuifocus)

```lua
SetNuiFocus(hasFocus, hasCursor)
```

Give keyboard and mouse to the pages, or give them back to the game. **Client only.**

Focus is shared by all resources; the last call wins. When the resource that set the focus stops, the focus goes back to the game. Players can always take the focus back with a fixed key of the game.

| Parameter   | Type      | Description                                  |
| ----------- | --------- | -------------------------------------------- |
| `hasFocus`  | `boolean` | Pages get the keyboard.                      |
| `hasCursor` | `boolean` | Pages get the mouse and the cursor is shown. |

```lua
RegisterCommand('inventory', function()
  SendNUIMessage({ type = 'open' })
  SetNuiFocus(true, true)
end)
```

**Compared to FiveM:** Same as in FiveM.

## SetNuiFocusKeepInput

[Section titled “SetNuiFocusKeepInput”](#setnuifocuskeepinput)

```lua
SetNuiFocusKeepInput(keepInput)
```

Let the game keep getting keyboard input while a page has focus. **Client only.**

| Parameter   | Type      | Description                                           |
| ----------- | --------- | ----------------------------------------------------- |
| `keepInput` | `boolean` | true: player can still move while the page has focus. |

**Compared to FiveM:** Same as in FiveM.

## IsNuiFocused

[Section titled “IsNuiFocused”](#isnuifocused)

```lua
IsNuiFocused() --> boolean
```

Whether a page has the keyboard focus. **Client only.**

**Returns**

* `boolean`: true while a page has focus.

**Compared to FiveM:** Same as in FiveM.

## IsNuiFocusKeepingInput

[Section titled “IsNuiFocusKeepingInput”](#isnuifocuskeepinginput)

```lua
IsNuiFocusKeepingInput() --> boolean
```

Whether the game keeps keyboard input while a page has focus. **Client only.**

**Returns**

* `boolean`: The value set with SetNuiFocusKeepInput.

**Compared to FiveM:** Same as in FiveM.

# Players

> Players on the server: IDs, names, identifiers and kicking. Provided by the GAMPEON server (game plugin or gampeon-server), not by the bare runtime.

Players on the server: IDs, names, identifiers and kicking. Provided by the GAMPEON server (game plugin or gampeon-server), not by the bare runtime.

## GetPlayers

[Section titled “GetPlayers”](#getplayers)

```lua
GetPlayers() --> string[]
```

List the IDs of all players on the server. **Server only.**

**Returns**

* `string[]`: Player IDs as strings, like in FiveM.

```lua
for _, id in ipairs(GetPlayers()) do
  print(id, GetPlayerName(id))
end
```

**Compared to FiveM:** Same as in FiveM.

## GetNumPlayerIndices

[Section titled “GetNumPlayerIndices”](#getnumplayerindices)

```lua
GetNumPlayerIndices() --> integer
```

Number of players on the server. **Server only.**

**Returns**

* `integer`: Player count.

**Compared to FiveM:** Same as in FiveM.

## GetPlayerFromIndex

[Section titled “GetPlayerFromIndex”](#getplayerfromindex)

```lua
GetPlayerFromIndex(index) --> string?
```

Player ID at a position in the player list. **Server only.**

| Parameter | Type      | Description                     |
| --------- | --------- | ------------------------------- |
| `index`   | `integer` | 0 to GetNumPlayerIndices() - 1. |

**Returns**

* `string?`: Player ID, or nil if the index is out of range.

**Compared to FiveM:** Same as in FiveM.

## DoesPlayerExist

[Section titled “DoesPlayerExist”](#doesplayerexist)

```lua
DoesPlayerExist(playerSrc) --> boolean
```

Check whether a player ID is on the server. **Server only.**

| Parameter   | Type              | Description         |
| ----------- | ----------------- | ------------------- |
| `playerSrc` | `string\|integer` | Player ID (source). |

**Returns**

* `boolean`: true if the player is connected.

**Compared to FiveM:** Same as in FiveM.

## GetPlayerName

[Section titled “GetPlayerName”](#getplayername)

```lua
GetPlayerName(playerSrc) --> string?
```

Display name of a player. **Server and client.**

| Parameter   | Type              | Description                                                                                |
| ----------- | ----------------- | ------------------------------------------------------------------------------------------ |
| `playerSrc` | `string\|integer` | Player ID (source) on the server. On the client only your own player (PlayerId()) for now. |

**Returns**

* `string?`: The name, or nil for unknown IDs on the server. On the client “**Invalid**” for other players.

**Compared to FiveM:** Same as in FiveM. The name is the player’s GAMPEON display name. Client scripts can only read their own name for now.

## GetPlayerIdentifiers

[Section titled “GetPlayerIdentifiers”](#getplayeridentifiers)

```lua
GetPlayerIdentifiers(playerSrc) --> string[]
```

All identifiers of a player. **Server only.**

The first is always `gampeon:<account id>`. `license:<40 hex>` is derived from the account and the convar sv_licenseSalt, so databases from ESX and Qbox that key players by license keep working.

| Parameter   | Type              | Description         |
| ----------- | ----------------- | ------------------- |
| `playerSrc` | `string\|integer` | Player ID (source). |

**Returns**

* `string[]`: Identifiers like “gampeon:42” and “license:…”.

```lua
for _, id in ipairs(GetPlayerIdentifiers(source)) do print(id) end
```

**Compared to FiveM:** Same as in FiveM. There are no steam:, discord:, xbl: or ip: identifiers yet.

## GetNumPlayerIdentifiers

[Section titled “GetNumPlayerIdentifiers”](#getnumplayeridentifiers)

```lua
GetNumPlayerIdentifiers(playerSrc) --> integer
```

Number of identifiers of a player. **Server only.**

| Parameter   | Type              | Description         |
| ----------- | ----------------- | ------------------- |
| `playerSrc` | `string\|integer` | Player ID (source). |

**Returns**

* `integer`: Count, 0 for unknown IDs.

**Compared to FiveM:** Same as in FiveM.

## GetPlayerIdentifier

[Section titled “GetPlayerIdentifier”](#getplayeridentifier)

```lua
GetPlayerIdentifier(playerSrc, index) --> string?
```

One identifier of a player by position. **Server only.**

| Parameter   | Type              | Description         |
| ----------- | ----------------- | ------------------- |
| `playerSrc` | `string\|integer` | Player ID (source). |
| `index`     | `integer`         | 0-based position.   |

**Returns**

* `string?`: The identifier, or nil.

**Compared to FiveM:** Same as in FiveM.

## GetPlayerIdentifierByType

[Section titled “GetPlayerIdentifierByType”](#getplayeridentifierbytype)

```lua
GetPlayerIdentifierByType(playerSrc, identifierType) --> string?
```

The identifier of a player with a given prefix. **Server only.**

| Parameter        | Type              | Description                                               |
| ---------------- | ----------------- | --------------------------------------------------------- |
| `playerSrc`      | `string\|integer` | Player ID (source).                                       |
| `identifierType` | `string`          | Prefix without colon, for example “license” or “gampeon”. |

**Returns**

* `string?`: For example “license:3f2a…”, or nil.

```lua
local license = GetPlayerIdentifierByType(source, 'license')
```

**Compared to FiveM:** Same as in FiveM.

## GetPlayerEndpoint

[Section titled “GetPlayerEndpoint”](#getplayerendpoint)

```lua
GetPlayerEndpoint(playerSrc) --> string?
```

Network address of a player, as far as the server shares it. **Server only.**

| Parameter   | Type              | Description         |
| ----------- | ----------------- | ------------------- |
| `playerSrc` | `string\|integer` | Player ID (source). |

**Returns**

* `string?`: Address text, may be empty.

**Compared to FiveM:** Like FiveM. Servers may hide addresses for privacy, then it is empty.

## GetPlayerPing

[Section titled “GetPlayerPing”](#getplayerping)

```lua
GetPlayerPing(playerSrc) --> integer
```

Round-trip time to a player in milliseconds. **Server only.**

| Parameter   | Type              | Description         |
| ----------- | ----------------- | ------------------- |
| `playerSrc` | `string\|integer` | Player ID (source). |

**Returns**

* `integer`: Ping in ms, 0 for unknown IDs.

**Compared to FiveM:** Same as in FiveM.

## GetPlayerLastMsg

[Section titled “GetPlayerLastMsg”](#getplayerlastmsg)

```lua
GetPlayerLastMsg(playerSrc) --> integer
```

Milliseconds since the last network event from a player. **Server only.**

| Parameter   | Type              | Description         |
| ----------- | ----------------- | ------------------- |
| `playerSrc` | `string\|integer` | Player ID (source). |

**Returns**

* `integer`: Time in ms.

**Compared to FiveM:** Counts script events, not every network packet.

## PlayerId

[Section titled “PlayerId”](#playerid)

```lua
PlayerId() --> integer
```

Handle of your own player on the client. Pass it to GetPlayerServerId or GetPlayerName. **Client only.**

**Returns**

* `integer`: Always 0 for now (the local player).

```lua
local myId = GetPlayerServerId(PlayerId())
print('my server id is ' .. myId)
```

**Compared to FiveM:** Same use as in FiveM. Other players’ handles come with the game natives in a later step.

## GetPlayerServerId

[Section titled “GetPlayerServerId”](#getplayerserverid)

```lua
GetPlayerServerId(player) --> integer
```

Server ID (source) of a player, as server scripts see it. **Client only.**

| Parameter | Type      | Description                             |
| --------- | --------- | --------------------------------------- |
| `player`  | `integer` | Player handle, for now only PlayerId(). |

**Returns**

* `integer`: The server ID, 0 for unknown players.

```lua
TriggerServerEvent('myres:ready', GetPlayerServerId(PlayerId()))
```

**Compared to FiveM:** Same as in FiveM for your own player.

## DropPlayer

[Section titled “DropPlayer”](#dropplayer)

```lua
DropPlayer(playerSrc, reason?)
```

Disconnect a player with a reason. **Server only.**

| Parameter           | Type              | Description          |
| ------------------- | ----------------- | -------------------- |
| `playerSrc`         | `string\|integer` | Player ID (source).  |
| `reason` (optional) | `string`          | Shown to the player. |

```lua
DropPlayer(source, 'You were kicked for spamming.')
```

**Compared to FiveM:** Same as in FiveM. playerDropped fires with the reason.

# Promises

> Wait for a result that arrives later, for example from a callback.

Wait for a result that arrives later, for example from a callback.

## promise.new

[Section titled “promise.new”](#promisenew)

```lua
promise.new(executor?) --> promise
```

Create a promise that is resolved later. **Server and client.**

Call p:resolve(value) or p:reject(err) once. p:next(onResolved, onRejected) chains a follow-up and returns a new promise.

| Parameter             | Type                                       | Description                                          |
| --------------------- | ------------------------------------------ | ---------------------------------------------------- |
| `executor` (optional) | `fun(resolve: function, reject: function)` | Optional: called right away with resolve and reject. |

**Returns**

* `promise`: The promise.

```lua
local p = promise.new()
PerformHttpRequest(url, function(status, body)
  p:resolve(body)
end)
local body = Citizen.Await(p)
```

**Compared to FiveM:** Same as in FiveM.

## promise.resolve

[Section titled “promise.resolve”](#promiseresolve)

```lua
promise.resolve(...) --> promise
```

Create a promise that is already resolved. **Server and client.**

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `...`     | `any` | Values.     |

**Returns**

* `promise`: The promise.

```lua
local p = promise.resolve(42)
```

**Compared to FiveM:** Same as in FiveM.

## promise.reject

[Section titled “promise.reject”](#promisereject)

```lua
promise.reject(err) --> promise
```

Create a promise that is already rejected. **Server and client.**

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `err`     | `any` | Error.      |

**Returns**

* `promise`: The promise.

```lua
local p = promise.reject('no money')
```

**Compared to FiveM:** Same as in FiveM.

## promise.all

[Section titled “promise.all”](#promiseall)

```lua
promise.all(promises) --> promise
```

Wait for several promises; resolves with a list of their first values. **Server and client.**

| Parameter  | Type        | Description |
| ---------- | ----------- | ----------- |
| `promises` | `promise[]` | Promises.   |

**Returns**

* `promise`: Resolves when all are resolved, rejects on the first error.

```lua
local results = Citizen.Await(promise.all({ p1, p2 }))
```

**Compared to FiveM:** Same as in FiveM.

## promise.first

[Section titled “promise.first”](#promisefirst)

```lua
promise.first(promises) --> promise
```

Resolve with the first promise that finishes. **Server and client.**

| Parameter  | Type        | Description |
| ---------- | ----------- | ----------- |
| `promises` | `promise[]` | Promises.   |

**Returns**

* `promise`: The new promise.

```lua
local winner = Citizen.Await(promise.first({ p1, p2 }))
```

**Compared to FiveM:** Same as in FiveM.

## promise.race

[Section titled “promise.race”](#promiserace)

```lua
promise.race(promises) --> promise
```

Same as promise.first. **Server and client.**

| Parameter  | Type        | Description |
| ---------- | ----------- | ----------- |
| `promises` | `promise[]` | Promises.   |

**Returns**

* `promise`: The new promise.

```lua
local winner = Citizen.Await(promise.race({ p1, p2 }))
```

**Compared to FiveM:** Same as in FiveM.

## Citizen.Await

[Section titled “Citizen.Await”](#citizenawait)

```lua
Citizen.Await(p) --> any
```

Pause the current thread until a promise is resolved, then return its values. **Server and client.**

| Parameter | Type      | Description  |
| --------- | --------- | ------------ |
| `p`       | `promise` | The promise. |

**Returns**

* `any`: Values from resolve. A rejected promise raises the error here.

```lua
local data = Citizen.Await(p)
```

**Compared to FiveM:** Same as in FiveM. Only inside a thread, event handler or command.

# Resource and runtime

> Information about the running resource and the side it runs on.

Information about the running resource and the side it runs on.

## GetCurrentResourceName

[Section titled “GetCurrentResourceName”](#getcurrentresourcename)

```lua
GetCurrentResourceName() --> string
```

Name of the resource this script belongs to. **Server and client.**

**Returns**

* `string`: Folder name of the resource.

```lua
print('Started ' .. GetCurrentResourceName())
```

**Compared to FiveM:** Same as in FiveM.

## GetGameTimer

[Section titled “GetGameTimer”](#getgametimer)

```lua
GetGameTimer() --> integer
```

Milliseconds since the runtime started. Use it to measure time. **Server and client.**

**Returns**

* `integer`: Milliseconds.

```lua
local started = GetGameTimer()
Wait(250)
print(GetGameTimer() - started)
```

**Compared to FiveM:** Same as in FiveM.

## GetHashKey

[Section titled “GetHashKey”](#gethashkey)

```lua
GetHashKey(name) --> integer
```

Hash of a name, for example of a model name. Same numbers as in FiveM. **Server and client.**

Jenkins one-at-a-time hash of the lower-case text as a signed 32-bit number. Functions that take a model accept the hash or the name itself.

| Parameter | Type     | Description                                                                     |
| --------- | -------- | ------------------------------------------------------------------------------- |
| `name`    | `string` | Text to hash, for example “prop_cube”. Upper and lower case give the same hash. |

**Returns**

* `integer`: Hash between -2147483648 and 2147483647.

```lua
local model = GetHashKey('prop_cube')
print(IsModelValid(model))
```

**Compared to FiveM:** Same as in FiveM. Backtick hashes (`prop_cube`) are not supported, use GetHashKey.

## IsDuplicityVersion

[Section titled “IsDuplicityVersion”](#isduplicityversion)

```lua
IsDuplicityVersion() --> boolean
```

True on the server, false on the client. **Server and client.**

Useful in shared scripts that run on both sides.

**Returns**

* `boolean`: true on the server.

```lua
if IsDuplicityVersion() then
  print('running on the server')
end
```

**Compared to FiveM:** Same as in FiveM.

## GetInvokingResource

[Section titled “GetInvokingResource”](#getinvokingresource)

```lua
GetInvokingResource() --> string?
```

Name of the resource that called the current export or triggered the current local event. **Server and client.**

**Returns**

* `string?`: Resource name, or nil inside network events, threads and timers.

```lua
exports('Pay', function(amount)
  print(GetInvokingResource() .. ' wants to pay ' .. amount)
end)
```

**Compared to FiveM:** Same as in FiveM.

## LoadResourceFile

[Section titled “LoadResourceFile”](#loadresourcefile)

```lua
LoadResourceFile(resourceName, fileName) --> string?
```

Read a file from a resource folder. **Server and client.**

| Parameter      | Type     | Description                                              |
| -------------- | -------- | -------------------------------------------------------- |
| `resourceName` | `string` | Resource, for example GetCurrentResourceName().          |
| `fileName`     | `string` | Path inside the resource, for example “data/items.json”. |

**Returns**

* `string?`: File content, or nil if the file does not exist.

```lua
local items = json.decode(LoadResourceFile(GetCurrentResourceName(), 'data/items.json'))
```

**Compared to FiveM:** Same as in FiveM. Paths cannot leave the resource folder. Files up to 16 MB.

## SaveResourceFile

[Section titled “SaveResourceFile”](#saveresourcefile)

```lua
SaveResourceFile(resourceName, fileName, data, dataLength?) --> boolean
```

Write a file into the own resource folder. **Server only.**

| Parameter               | Type      | Description                                      |
| ----------------------- | --------- | ------------------------------------------------ |
| `resourceName`          | `string`  | Must be the own resource.                        |
| `fileName`              | `string`  | Path inside the resource. The folder must exist. |
| `data`                  | `string`  | Content.                                         |
| `dataLength` (optional) | `integer` | Number of bytes to write, or -1 for all.         |

**Returns**

* `boolean`: true if written.

```lua
SaveResourceFile(GetCurrentResourceName(), 'data/state.json', json.encode(state), -1)
```

**Compared to FiveM:** FiveM allows writing into any resource; GAMPEON only into the own one.

## GetResourceState

[Section titled “GetResourceState”](#getresourcestate)

```lua
GetResourceState(resourceName) --> string
```

Check if a resource runs. **Server and client.**

| Parameter      | Type     | Description    |
| -------------- | -------- | -------------- |
| `resourceName` | `string` | Resource name. |

**Returns**

* `string`: “started”, “stopped” (known but not running) or “missing”.

```lua
if GetResourceState('gp_inventory') ~= 'started' then
  print('inventory missing')
end
```

**Compared to FiveM:** Same as in FiveM, without the states starting and stopping.

## GetNumResources

[Section titled “GetNumResources”](#getnumresources)

```lua
GetNumResources() --> integer
```

Number of running resources on this side. **Server and client.**

**Returns**

* `integer`: Count.

```lua
print(GetNumResources())
```

**Compared to FiveM:** FiveM also counts stopped resources.

## GetResourceByFindIndex

[Section titled “GetResourceByFindIndex”](#getresourcebyfindindex)

```lua
GetResourceByFindIndex(findIndex) --> string?
```

Name of the running resource at an index, for loops over all resources. **Server and client.**

| Parameter   | Type      | Description                 |
| ----------- | --------- | --------------------------- |
| `findIndex` | `integer` | 0 to GetNumResources() - 1. |

**Returns**

* `string?`: Resource name.

```lua
for i = 0, GetNumResources() - 1 do
  print(GetResourceByFindIndex(i))
end
```

**Compared to FiveM:** Same as in FiveM.

## GetResourcePath

[Section titled “GetResourcePath”](#getresourcepath)

```lua
GetResourcePath(resourceName) --> string?
```

Folder of a resource on the server. **Server only.**

| Parameter      | Type     | Description    |
| -------------- | -------- | -------------- |
| `resourceName` | `string` | Resource name. |

**Returns**

* `string?`: Path, or nil if unknown.

```lua
print(GetResourcePath(GetCurrentResourceName()))
```

**Compared to FiveM:** Same as in FiveM.

## GetResourceMetadata

[Section titled “GetResourceMetadata”](#getresourcemetadata)

```lua
GetResourceMetadata(resourceName, metadataKey, index?) --> string?
```

Read a value from the manifest of a running resource. **Server and client.**

| Parameter          | Type      | Description                                              |
| ------------------ | --------- | -------------------------------------------------------- |
| `resourceName`     | `string`  | Resource name.                                           |
| `metadataKey`      | `string`  | Directive, for example “version”, “author” or “ui_page”. |
| `index` (optional) | `integer` | 0 for the first value.                                   |

**Returns**

* `string?`: The value, or nil.

```lua
local version = GetResourceMetadata(GetCurrentResourceName(), 'version', 0)
```

**Compared to FiveM:** Same as in FiveM.

## GetNumResourceMetadata

[Section titled “GetNumResourceMetadata”](#getnumresourcemetadata)

```lua
GetNumResourceMetadata(resourceName, metadataKey) --> integer
```

How many values a manifest directive has. **Server and client.**

| Parameter      | Type     | Description    |
| -------------- | -------- | -------------- |
| `resourceName` | `string` | Resource name. |
| `metadataKey`  | `string` | Directive.     |

**Returns**

* `integer`: Count.

```lua
print(GetNumResourceMetadata('myres', 'dependency'))
```

**Compared to FiveM:** Same as in FiveM.

## StartResource

[Section titled “StartResource”](#startresource)

```lua
StartResource(resourceName) --> boolean
```

Start a resource and its dependencies. **Server only.**

Needs the permission command.start for the calling resource: `add_ace resource.<name> command.start allow`.

| Parameter      | Type     | Description    |
| -------------- | -------- | -------------- |
| `resourceName` | `string` | Resource name. |

**Returns**

* `boolean`: true if it runs afterwards.

**Compared to FiveM:** Same as in FiveM.

## StopResource

[Section titled “StopResource”](#stopresource)

```lua
StopResource(resourceName) --> boolean
```

Stop a resource and everything that depends on it. **Server only.**

Needs the permission command.stop for the calling resource.

| Parameter      | Type     | Description    |
| -------------- | -------- | -------------- |
| `resourceName` | `string` | Resource name. |

**Returns**

* `boolean`: true if it was running.

**Compared to FiveM:** Same as in FiveM.

# Sandbox

> Standard Lua functions that behave differently in GAMPEON.

Standard Lua functions that behave differently in GAMPEON.

## print

[Section titled “print”](#print)

```lua
print(...)
```

Write a line to the server or client log, tagged with the resource name. **Server and client.**

| Parameter | Type  | Description                |
| --------- | ----- | -------------------------- |
| `...`     | `any` | Values, separated by tabs. |

```lua
print('player joined', source)
```

**Compared to FiveM:** Same as in FiveM.

## load

[Section titled “load”](#load)

```lua
load(chunk, chunkname?, mode?, env?) --> function?, string?
```

Compile Lua source text. Precompiled bytecode is refused. **Server and client.**

| Parameter              | Type     | Description                     |
| ---------------------- | -------- | ------------------------------- |
| `chunk`                | `string` | Lua source text.                |
| `chunkname` (optional) | `string` | Name used in error messages.    |
| `mode` (optional)      | `string` | Ignored; only text is accepted. |
| `env` (optional)       | `table`  | Environment of the chunk.       |

**Returns**

* `function?`: The compiled function, or nil on error.
* `string?`: Error message.

**Compared to FiveM:** FiveM allows bytecode; GAMPEON does not, for security.

## Citizen.Trace

[Section titled “Citizen.Trace”](#citizentrace)

```lua
Citizen.Trace(...)
```

Write to the server or client log, like print. **Server and client.**

| Parameter | Type  | Description |
| --------- | ----- | ----------- |
| `...`     | `any` | Values.     |

```lua
Citizen.Trace('loaded')
```

**Compared to FiveM:** FiveM prints without a line break; GAMPEON writes one log line.

# Threads and timers

> Threads are coroutines that the host resumes every tick. Wait pauses only the current thread.

Threads are coroutines that the host resumes every tick. Wait pauses only the current thread.

## CreateThread

[Section titled “CreateThread”](#createthread)

```lua
CreateThread(fn)
```

Run a function as its own thread, starting with the next tick. **Server and client.**

Use threads for loops that run over time. Always call Wait inside a loop, otherwise the script exceeds its instruction budget and is stopped.

| Parameter | Type    | Description         |
| --------- | ------- | ------------------- |
| `fn`      | `fun()` | Body of the thread. |

```lua
CreateThread(function()
  while true do
    Wait(1000)
    print('one second passed')
  end
end)
```

**Compared to FiveM:** Same as Citizen.CreateThread in FiveM.

## Wait

[Section titled “Wait”](#wait)

```lua
Wait(ms?)
```

Pause the current thread. **Server and client.**

Only works inside a thread, event handler or timeout. The rest of the game keeps running.

| Parameter       | Type      | Description                                                   |
| --------------- | --------- | ------------------------------------------------------------- |
| `ms` (optional) | `integer` | Milliseconds to wait. 0 or nothing waits until the next tick. |

```lua
Wait(500)
```

**Compared to FiveM:** Same as in FiveM. Not allowed inside an export called from another resource.

## SetTimeout

[Section titled “SetTimeout”](#settimeout)

```lua
SetTimeout(ms, fn)
```

Run a function once after a delay. **Server and client.**

| Parameter | Type      | Description                                             |
| --------- | --------- | ------------------------------------------------------- |
| `ms`      | `integer` | Delay in milliseconds.                                  |
| `fn`      | `fun()`   | Function to run. It runs as a thread and may call Wait. |

```lua
SetTimeout(5000, function()
  print('five seconds later')
end)
```

**Compared to FiveM:** Same as in FiveM.

## Citizen.CreateThread

[Section titled “Citizen.CreateThread”](#citizencreatethread)

```lua
Citizen.CreateThread(fn)
```

Same as CreateThread. Kept for ported FiveM scripts. **Server and client.**

| Parameter | Type    | Description         |
| --------- | ------- | ------------------- |
| `fn`      | `fun()` | Body of the thread. |

**Compared to FiveM:** Same as in FiveM.

## Citizen.Wait

[Section titled “Citizen.Wait”](#citizenwait)

```lua
Citizen.Wait(ms?)
```

Same as Wait. Kept for ported FiveM scripts. **Server and client.**

| Parameter       | Type      | Description           |
| --------------- | --------- | --------------------- |
| `ms` (optional) | `integer` | Milliseconds to wait. |

**Compared to FiveM:** Same as in FiveM.

## Citizen.SetTimeout

[Section titled “Citizen.SetTimeout”](#citizensettimeout)

```lua
Citizen.SetTimeout(ms, fn)
```

Same as SetTimeout. Kept for ported FiveM scripts. **Server and client.**

| Parameter | Type      | Description            |
| --------- | --------- | ---------------------- |
| `ms`      | `integer` | Delay in milliseconds. |
| `fn`      | `fun()`   | Function to run.       |

**Compared to FiveM:** Same as in FiveM.

# Types

> Types returned by the API.

## EventHandle

[Section titled “EventHandle”](#eventhandle)

Returned by AddEventHandler and RegisterNetEvent.

| Field  | Type      | Description                 |
| ------ | --------- | --------------------------- |
| `key`  | `integer` | Internal ID of the handler. |
| `name` | `string`  | Name of the event.          |

## vector2

[Section titled “vector2”](#vector2)

Read-only vector with 2 components. Supports + - \* /, # (length) and swizzles like v.xy.

| Field | Type     | Description  |
| ----- | -------- | ------------ |
| `x`   | `number` | x component. |
| `y`   | `number` | y component. |

## vector3

[Section titled “vector3”](#vector3)

Read-only vector with 3 components. Supports + - \* /, # (length) and swizzles like v.xy.

| Field | Type     | Description  |
| ----- | -------- | ------------ |
| `x`   | `number` | x component. |
| `y`   | `number` | y component. |
| `z`   | `number` | z component. |

## vector4

[Section titled “vector4”](#vector4)

Read-only vector with 4 components. Supports + - \* /, # (length) and swizzles like v.xy.

| Field | Type     | Description  |
| ----- | -------- | ------------ |
| `x`   | `number` | x component. |
| `y`   | `number` | y component. |
| `z`   | `number` | z component. |
| `w`   | `number` | w component. |

## promise

[Section titled “promise”](#promise)

Result that arrives later. Use p:resolve(…), p:reject(err), p:next(onResolved, onRejected) and Citizen.Await(p).

| Field     | Type                                                                        | Description                     |
| --------- | --------------------------------------------------------------------------- | ------------------------------- |
| `resolve` | `fun(self: promise, ...: any)`                                              | Fulfil the promise with values. |
| `reject`  | `fun(self: promise, err: any)`                                              | Fail the promise.               |
| `next`    | `fun(self: promise, onResolved?: function, onRejected?: function): promise` | Run a function when it is done. |

# Vectors

> vector2, vector3 and vector4 values for positions, directions and rotations.

vector2, vector3 and vector4 values for positions, directions and rotations.

## vector2

[Section titled “vector2”](#vector2)

```lua
vector2(x?, y?) --> vector2
```

Create a vector2 with 2 numbers (x, y). **Server and client.**

| Parameter      | Type     | Description                                               |
| -------------- | -------- | --------------------------------------------------------- |
| `x` (optional) | `number` | x component. With only one number, all components get it. |
| `y` (optional) | `number` | y component. With only one number, all components get it. |

**Returns**

* `vector2`: Read-only vector.

```lua
local size = vector2(1920, 1080)
print(size.x, size.y)
```

**Compared to FiveM:** Same as in FiveM: + - \* / with vectors and numbers, #v is the length, v.xy and other swizzles, type(v) returns “vector2”. GAMPEON uses double precision.

## vec2

[Section titled “vec2”](#vec2)

```lua
vec2(x?, y?) --> vector2
```

Short name for vector2. **Server and client.**

| Parameter      | Type     | Description  |
| -------------- | -------- | ------------ |
| `x` (optional) | `number` | x component. |
| `y` (optional) | `number` | y component. |

**Returns**

* `vector2`: Read-only vector.

```lua
local v = vec2(1, 2)
```

**Compared to FiveM:** Same as in FiveM.

## vector3

[Section titled “vector3”](#vector3)

```lua
vector3(x?, y?, z?) --> vector3
```

Create a vector3 with 3 numbers (x, y, z). **Server and client.**

Vectors are values: components cannot be changed, create a new vector instead. They keep their type in events between server and client and in exports.

| Parameter      | Type     | Description                                               |
| -------------- | -------- | --------------------------------------------------------- |
| `x` (optional) | `number` | x component. With only one number, all components get it. |
| `y` (optional) | `number` | y component. With only one number, all components get it. |
| `z` (optional) | `number` | z component. With only one number, all components get it. |

**Returns**

* `vector3`: Read-only vector.

```lua
local spawn = vector3(120.0, -45.5, 30.0)
local dist = #(GetEntityCoords(ped) - spawn)
```

**Compared to FiveM:** Same as in FiveM: + - \* / with vectors and numbers, #v is the length, v.xy and other swizzles, type(v) returns “vector3”. GAMPEON uses double precision.

## vec3

[Section titled “vec3”](#vec3)

```lua
vec3(x?, y?, z?) --> vector3
```

Short name for vector3. **Server and client.**

| Parameter      | Type     | Description  |
| -------------- | -------- | ------------ |
| `x` (optional) | `number` | x component. |
| `y` (optional) | `number` | y component. |
| `z` (optional) | `number` | z component. |

**Returns**

* `vector3`: Read-only vector.

```lua
local v = vec3(1, 2, 3)
```

**Compared to FiveM:** Same as in FiveM.

## vector4

[Section titled “vector4”](#vector4)

```lua
vector4(x?, y?, z?, w?) --> vector4
```

Create a vector4 with 4 numbers (x, y, z, w). **Server and client.**

| Parameter      | Type     | Description                                               |
| -------------- | -------- | --------------------------------------------------------- |
| `x` (optional) | `number` | x component. With only one number, all components get it. |
| `y` (optional) | `number` | y component. With only one number, all components get it. |
| `z` (optional) | `number` | z component. With only one number, all components get it. |
| `w` (optional) | `number` | w component. With only one number, all components get it. |

**Returns**

* `vector4`: Read-only vector.

```lua
local spawnWithHeading = vector4(120.0, -45.5, 30.0, 90.0)
print(spawnWithHeading.w)
```

**Compared to FiveM:** Same as in FiveM: + - \* / with vectors and numbers, #v is the length, v.xy and other swizzles, type(v) returns “vector4”. GAMPEON uses double precision.

## vec4

[Section titled “vec4”](#vec4)

```lua
vec4(x?, y?, z?, w?) --> vector4
```

Short name for vector4. **Server and client.**

| Parameter      | Type     | Description  |
| -------------- | -------- | ------------ |
| `x` (optional) | `number` | x component. |
| `y` (optional) | `number` | y component. |
| `z` (optional) | `number` | z component. |
| `w` (optional) | `number` | w component. |

**Returns**

* `vector4`: Read-only vector.

```lua
local v = vec4(1, 2, 3, 4)
```

**Compared to FiveM:** Same as in FiveM.

## vec

[Section titled “vec”](#vec)

```lua
vec(x, y, z?, w?) --> vector2|vector3|vector4
```

Create a vector with 2, 3 or 4 numbers. **Server and client.**

| Parameter      | Type     | Description |
| -------------- | -------- | ----------- |
| `x`            | `number` | x           |
| `y`            | `number` | y           |
| `z` (optional) | `number` | z           |
| `w` (optional) | `number` | w           |

**Returns**

* `vector2|vector3|vector4`: Vector with as many components as arguments.

```lua
local v = vec(1, 2, 3) -- vector3
```

**Compared to FiveM:** Same as in FiveM.

# World and entities

> Player characters (peds), objects and vehicles in the game world: create, move and delete them. Positions are in meters, headings in degrees. Provided by the game (or gampeon-server with its placeholder world).

Player characters (peds), objects and vehicles in the game world: create, move and delete them. Positions are in meters, headings in degrees. Provided by the game (or gampeon-server with its placeholder world).

## GetPlayerPed

[Section titled “GetPlayerPed”](#getplayerped)

```lua
GetPlayerPed(playerSrc) --> integer
```

A player’s character (ped). **Server and client.**

On the server, pass the player ID (source). On the client, pass -1 or PlayerId() for your own character; other players follow later. Returns 0 while the player has no character, for example right after joining.

| Parameter   | Type              | Description                                           |
| ----------- | ----------------- | ----------------------------------------------------- |
| `playerSrc` | `string\|integer` | Server: player ID (source). Client: -1 or PlayerId(). |

**Returns**

* `integer`: Entity handle of the ped, or 0.

```lua
RegisterCommand('pos', function(source)
  local ped = GetPlayerPed(source)
  print(GetPlayerName(source) .. ' is at ' .. GetEntityCoords(ped))
end)
```

**Compared to FiveM:** Same as in FiveM. Server and client have their own handles for the same entity, so do not send handles in events.

## PlayerPedId

[Section titled “PlayerPedId”](#playerpedid)

```lua
PlayerPedId() --> integer
```

Your own character (ped) on the client. **Client only.**

**Returns**

* `integer`: Entity handle of your ped, or 0 before it spawned.

```lua
local coords = GetEntityCoords(PlayerPedId())
print(('I am at %.1f, %.1f, %.1f'):format(coords.x, coords.y, coords.z))
```

**Compared to FiveM:** Same as in FiveM.

## DoesEntityExist

[Section titled “DoesEntityExist”](#doesentityexist)

```lua
DoesEntityExist(entity) --> boolean
```

Check if an entity handle still points to an entity. **Server and client.**

| Parameter | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity. |

**Returns**

* `boolean`: true if the entity exists.

```lua
local ped = GetPlayerPed(source)
if DoesEntityExist(ped) then
  print('ped exists')
end
```

**Compared to FiveM:** Same as in FiveM.

## GetEntityCoords

[Section titled “GetEntityCoords”](#getentitycoords)

```lua
GetEntityCoords(entity) --> vector3
```

Position of an entity in meters. **Server and client.**

| Parameter | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity. |

**Returns**

* `vector3`: Position in meters. vector3(0, 0, 0) for unknown entities.

```lua
local a = GetEntityCoords(GetPlayerPed(source))
local b = vector3(100.0, 20.0, 1.0)
if #(a - b) < 5.0 then
  print('near the shop')
end
```

**Compared to FiveM:** Same as in FiveM: meters, z is up. The axes follow the GAMPEON map, so coordinates from GTA maps do not carry over. Extra arguments (alive) are ignored.

## GetEntityHeading

[Section titled “GetEntityHeading”](#getentityheading)

```lua
GetEntityHeading(entity) --> number
```

Direction an entity faces, in degrees. **Server and client.**

| Parameter | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity. |

**Returns**

* `number`: 0 up to 360. 0 faces +x, 90 faces +y. 0 for unknown entities.

**Compared to FiveM:** Degrees from 0 to 360 like in FiveM, but measured like the Unreal yaw (Rotation Z in the editor): 0 faces +x and the angle grows towards +y. For directions use GetEntityForwardVector instead of GTA heading math.

## GetEntityForwardVector

[Section titled “GetEntityForwardVector”](#getentityforwardvector)

```lua
GetEntityForwardVector(entity) --> vector3
```

Unit vector in the direction an entity faces. **Server and client.**

| Parameter | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity. |

**Returns**

* `vector3`: Length 1, z is 0. Follows GetEntityHeading: heading 0 gives (1, 0, 0), 90 gives (0, 1, 0). (0, 0, 0) for unknown entities.

```lua
local ped = GetPlayerPed(source)
local inFront = GetEntityCoords(ped) + GetEntityForwardVector(ped) * 2.0
```

**Compared to FiveM:** Same as in FiveM. Use it instead of sin and cos of the heading: GAMPEON headings are measured like the Unreal yaw, so GTA heading math gives other directions.

## GetEntityForwardX

[Section titled “GetEntityForwardX”](#getentityforwardx)

```lua
GetEntityForwardX(entity) --> number
```

X part of GetEntityForwardVector. **Server and client.**

| Parameter | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity. |

**Returns**

* `number`: -1 up to 1. 0 for unknown entities.

**Compared to FiveM:** Same as in FiveM.

## GetEntityForwardY

[Section titled “GetEntityForwardY”](#getentityforwardy)

```lua
GetEntityForwardY(entity) --> number
```

Y part of GetEntityForwardVector. **Server and client.**

| Parameter | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity. |

**Returns**

* `number`: -1 up to 1. 0 for unknown entities.

**Compared to FiveM:** Same as in FiveM.

## GetEntityVelocity

[Section titled “GetEntityVelocity”](#getentityvelocity)

```lua
GetEntityVelocity(entity) --> vector3
```

Speed and direction of an entity in meters per second. **Server and client.**

| Parameter | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity. |

**Returns**

* `vector3`: Velocity in meters per second. #velocity is the speed.

```lua
local speed = #GetEntityVelocity(GetPlayerPed(source))
print(('%.1f m/s'):format(speed))
```

**Compared to FiveM:** Same as in FiveM.

## GetEntityType

[Section titled “GetEntityType”](#getentitytype)

```lua
GetEntityType(entity) --> integer
```

Kind of entity. **Server and client.**

| Parameter | Type      | Description                                                      |
| --------- | --------- | ---------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity. |

**Returns**

* `integer`: 0 = no entity, 1 = ped, 2 = vehicle, 3 = object.

**Compared to FiveM:** Same numbers as in FiveM. Peds come from players; objects come from CreateObject. Vehicles need vehicle models, which the game does not have yet.

## SetEntityCoords

[Section titled “SetEntityCoords”](#setentitycoords)

```lua
SetEntityCoords(entity, x, y?, z?)
```

Teleport an entity to a position in meters. **Server only.**

The server owns the world, so only server scripts move entities. Players see the new position through the normal replication. Coordinates must be finite and within 1,000,000 meters. For a character the position is the middle of its body, about 0.9 meters above its feet, so add that to the ground height (GetEntityCoords returns the same point).

| Parameter      | Type              | Description                                                      |
| -------------- | ----------------- | ---------------------------------------------------------------- |
| `entity`       | `integer`         | Entity handle, for example from GetPlayerPed. 0 means no entity. |
| `x`            | `number\|vector3` | x in meters, or a vector3 with x, y and z.                       |
| `y` (optional) | `number`          | y in meters (not needed with a vector3).                         |
| `z` (optional) | `number`          | z in meters (not needed with a vector3).                         |

```lua
RegisterCommand('tpspawn', function(source)
  SetEntityCoords(GetPlayerPed(source), vector3(0.0, 0.0, 2.0))
end, true)
```

**Compared to FiveM:** Like in FiveM, but server only for now. The flags after z (alive, deadFlag, ragdollFlag, clearArea) are ignored. Unknown handles do nothing.

## SetEntityHeading

[Section titled “SetEntityHeading”](#setentityheading)

```lua
SetEntityHeading(entity, heading)
```

Turn an entity to face a direction in degrees. **Server only.**

| Parameter | Type      | Description                                                                      |
| --------- | --------- | -------------------------------------------------------------------------------- |
| `entity`  | `integer` | Entity handle, for example from GetPlayerPed. 0 means no entity.                 |
| `heading` | `number`  | Degrees. Any value works, it is wrapped to 0 up to 360. 0 faces +x, 90 faces +y. |

```lua
SetEntityHeading(GetPlayerPed(source), 90.0)
```

**Compared to FiveM:** Like in FiveM, but server only for now and measured like the Unreal yaw (see GetEntityHeading).

## GetEntityModel

[Section titled “GetEntityModel”](#getentitymodel)

```lua
GetEntityModel(entity) --> integer
```

Model of an entity as a hash. **Server and client.**

| Parameter | Type      | Description                       |
| --------- | --------- | --------------------------------- |
| `entity`  | `integer` | Entity handle. 0 means no entity. |

**Returns**

* `integer`: GetHashKey of the model name, 0 for player characters and missing entities.

```lua
if GetEntityModel(obj) == GetHashKey('prop_cube') then
  print('a cube')
end
```

**Compared to FiveM:** Same as in FiveM, but player characters have no model hash yet (0).

## IsModelValid

[Section titled “IsModelValid”](#ismodelvalid)

```lua
IsModelValid(model) --> boolean
```

Check if the game knows a model that CreateObject or CreateVehicle can create. **Server and client.**

| Parameter | Type              | Description                                                 |
| --------- | ----------------- | ----------------------------------------------------------- |
| `model`   | `string\|integer` | Model name such as “prop_cube” or its hash from GetHashKey. |

**Returns**

* `boolean`: true if the model exists.

```lua
print(IsModelValid('prop_cube'))
```

**Compared to FiveM:** Same idea as in FiveM, but GAMPEON has its own models instead of the GTA ones. Built in: prop_cube, prop_sphere, prop_cylinder, prop_cone and prop_plane.

## IsModelAVehicle

[Section titled “IsModelAVehicle”](#ismodelavehicle)

```lua
IsModelAVehicle(model) --> boolean
```

Check if a model is a vehicle model. **Server and client.**

| Parameter | Type              | Description                                                 |
| --------- | ----------------- | ----------------------------------------------------------- |
| `model`   | `string\|integer` | Model name such as “prop_cube” or its hash from GetHashKey. |

**Returns**

* `boolean`: true for vehicle models, false for objects and unknown models.

**Compared to FiveM:** Same as in FiveM.

## CreateObject

[Section titled “CreateObject”](#createobject)

```lua
CreateObject(model, x, y, z, isNetwork?, netMissionEntity?, doorFlag?) --> integer
```

Create an object in the world for every player. **Server only.**

The object belongs to your resource and is deleted when the resource stops. It has physics but sleeps until something hits it, like props in FiveM; FreezeEntityPosition holds it in place. A resource may have 1000 entities at once. Unknown models return 0 and write a warning to the log.

| Parameter                     | Type              | Description                                                     |
| ----------------------------- | ----------------- | --------------------------------------------------------------- |
| `model`                       | `string\|integer` | Model name such as “prop_cube” or its hash from GetHashKey.     |
| `x`                           | `number`          | Position in meters (or a vector3 here and leave out y and z).   |
| `y`                           | `number`          | Meters.                                                         |
| `z`                           | `number`          | Meters, up.                                                     |
| `isNetwork` (optional)        | `boolean`         | Ignored: objects from the server always exist for every player. |
| `netMissionEntity` (optional) | `boolean`         | Ignored.                                                        |
| `doorFlag` (optional)         | `boolean`         | Ignored.                                                        |

**Returns**

* `integer`: Entity handle, 0 if it could not be created.

```lua
local c = GetEntityCoords(GetPlayerPed(source))
local box = CreateObject('prop_cube', c.x + 2.0, c.y, c.z, true, true, false)
FreezeEntityPosition(box, true)
```

**Compared to FiveM:** Same arguments as in FiveM, but server only for now and with GAMPEON models. The object is not pushed to the ground; it is placed at the position you give.

## CreateObjectNoOffset

[Section titled “CreateObjectNoOffset”](#createobjectnooffset)

```lua
CreateObjectNoOffset(model, x, y, z, isNetwork?, netMissionEntity?, doorFlag?) --> integer
```

Same as CreateObject. **Server only.**

| Parameter                     | Type              | Description                                                   |
| ----------------------------- | ----------------- | ------------------------------------------------------------- |
| `model`                       | `string\|integer` | Model name such as “prop_cube” or its hash from GetHashKey.   |
| `x`                           | `number`          | Position in meters (or a vector3 here and leave out y and z). |
| `y`                           | `number`          | Meters.                                                       |
| `z`                           | `number`          | Meters, up.                                                   |
| `isNetwork` (optional)        | `boolean`         | Ignored.                                                      |
| `netMissionEntity` (optional) | `boolean`         | Ignored.                                                      |
| `doorFlag` (optional)         | `boolean`         | Ignored.                                                      |

**Returns**

* `integer`: Entity handle, 0 if it could not be created.

**Compared to FiveM:** In FiveM the two differ in how the position is offset; GAMPEON places both at the exact position.

## CreateVehicle

[Section titled “CreateVehicle”](#createvehicle)

```lua
CreateVehicle(model, x, y, z, heading?, isNetwork?, netMissionEntity?) --> integer
```

Create a vehicle in the world for every player. **Server only.**

Belongs to your resource and is deleted when it stops. The game has no vehicle models yet, so for now this returns 0 and writes a warning to the log.

| Parameter                     | Type              | Description                                                      |
| ----------------------------- | ----------------- | ---------------------------------------------------------------- |
| `model`                       | `string\|integer` | Model name such as “prop_cube” or its hash from GetHashKey.      |
| `x`                           | `number`          | Position in meters (or a vector3 here and leave out y and z).    |
| `y`                           | `number`          | Meters.                                                          |
| `z`                           | `number`          | Meters, up.                                                      |
| `heading` (optional)          | `number`          | Degrees, 0 faces +x, 90 faces +y.                                |
| `isNetwork` (optional)        | `boolean`         | Ignored: vehicles from the server always exist for every player. |
| `netMissionEntity` (optional) | `boolean`         | Ignored.                                                         |

**Returns**

* `integer`: Entity handle, 0 if it could not be created.

**Compared to FiveM:** Same arguments as in FiveM, but server only for now and with GAMPEON models.

## DeleteEntity

[Section titled “DeleteEntity”](#deleteentity)

```lua
DeleteEntity(entity)
```

Delete an entity that a script created. **Server only.**

Works for objects and vehicles from CreateObject and CreateVehicle of any resource. Player characters cannot be deleted.

| Parameter | Type      | Description                    |
| --------- | --------- | ------------------------------ |
| `entity`  | `integer` | Entity handle. 0 does nothing. |

```lua
DeleteEntity(box)
```

**Compared to FiveM:** Same as in FiveM, but server only for now.

## FreezeEntityPosition

[Section titled “FreezeEntityPosition”](#freezeentityposition)

```lua
FreezeEntityPosition(entity, toggle)
```

Hold an entity in place without physics, or let it move again. **Server only.**

| Parameter | Type      | Description                                          |
| --------- | --------- | ---------------------------------------------------- |
| `entity`  | `integer` | Entity handle.                                       |
| `toggle`  | `boolean` | true holds it in place, false turns physics back on. |

```lua
FreezeEntityPosition(box, true)
```

**Compared to FiveM:** Same as in FiveM, but server only for now and only for entities that scripts created.

# Sandbox

> What scripts can and cannot do, and the limits that apply.

Every resource runs in its own Lua 5.4 state. A resource that crashes, hangs or uses too much memory is stopped; the others keep running.

## Available

[Section titled “Available”](#available)

* Lua 5.4 language features: integers, `//`, `<const>`, `<close>`, `goto`.
* Libraries: `string`, `table`, `math`, `utf8`, `coroutine`, and from `os` only `time`, `clock`, `date` and `difftime`.
* The [GAMPEON Lua API](/docs/scripting/reference/).

## Not available

[Section titled “Not available”](#not-available)

| Missing                                        | Why                                 |
| ---------------------------------------------- | ----------------------------------- |
| `io`, `os.execute`, `os.getenv`, `os.remove` … | No access to files or the machine   |
| `require`, `package`, `dofile`, `loadfile`     | Scripts come from the manifest only |
| `debug`                                        | Could break out of the sandbox      |
| `string.dump`, bytecode in `load`              | Bytecode can break the Lua VM       |

## Limits

[Section titled “Limits”](#limits)

| Limit        | Default                                                     |
| ------------ | ----------------------------------------------------------- |
| Memory       | 64 MB per resource                                          |
| Instructions | 50 million per run of a handler, thread step or export call |

When a limit is hit, the current run stops with an error in the log, for example `script exceeded instruction budget`.

## Client scripts

[Section titled “Client scripts”](#client-scripts)

Client scripts come from the server and run on players’ computers. They have no `PerformHttpRequest`, no `MySQL`, no `SaveResourceFile`, and convars are read-only.

The client sandbox has not had its security review yet. Until it has, the game only runs client scripts from trusted servers. See [Client scripts](/docs/scripting/client-scripts/#which-servers-may-send-client-scripts).

# Test without the game

> Run server resources with gampeon-server, a console-only server with fake players.

`gampeon-server` runs your server resources without Unreal Engine. Instead of the game world it has a simple placeholder world. It reads the same `server.cfg`, runs the same Lua runtime with database and HTTP, and has a console. Use it to port and test resources quickly, or in CI.

```sh
gampeon-server --data ./server-data
```

| Option            | Meaning                                                                         |
| ----------------- | ------------------------------------------------------------------------------- |
| `--data <folder>` | Folder with `server.cfg` and `resources/` (default: current folder)             |
| `--hz <n>`        | Ticks per second (default 30)                                                   |
| `--no-stdin`      | Do not read console commands from the terminal                                  |
| `+<command>`      | Run a console command at start, for example `+exec test.cfg` or `+ensure myres` |

Without `+` commands it runs `exec server.cfg`. All console commands from [Commands and convars](/docs/scripting/commands-and-convars/) work, plus `quit`.

## Fake players

[Section titled “Fake players”](#fake-players)

| Command                                         | Effect                                                                                                                                                                                                |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gp_fakeplayer join <name>`                     | Adds a player with `gampeon:dev-<n>` and `license:` identifiers. Runs `playerJoining`.                                                                                                                |
| `gp_fakeplayer connect <name> [ticket]`         | Joins like the game does. With `sv_requireJoinToken` on, GAMPEON checks the ticket.                                                                                                                   |
| `gp_fakeplayer client <name> [ticket]`          | Like `connect`, with a client in the same process that downloads the packages and runs the client scripts.                                                                                            |
| `gp_fakeplayer waitclient <id> [resource …]`    | Waits until the client scripts of a `client` player are running and the named resources have started there, for at most 30 seconds. Prints `fake client <id> ready`, or `not ready` when it gives up. |
| `gp_fakeplayer clientcmd <id> <command …>`      | Runs a command that client scripts registered with `RegisterCommand`, like `gpc` in the game.                                                                                                         |
| `gp_fakeplayer event <id> <event> [json list]`  | The player sends a network event, like `TriggerServerEvent`.                                                                                                                                          |
| `gp_fakeplayer command <id> <command …>`        | The player types `/command` in chat, with permission checks.                                                                                                                                          |
| `gp_fakeplayer say <id> <text …>`               | A `client` player types into the chat window: text or `/command`. Needs `ensure chat`. Lines in the player’s chat are printed as `[client <id>/chatbox]`. See [Text chat](/docs/scripting/chat/).     |
| `gp_fakeplayer drop <id> [reason]`              | The player leaves. Runs `playerDropped`.                                                                                                                                                              |
| `gp_fakeplayer move <id> <x> <y> <z> [heading]` | Moves the player’s character in the placeholder world (meters, degrees).                                                                                                                              |
| `gp_fakeplayer where <id>`                      | Prints the position and heading of the player’s character.                                                                                                                                            |
| `gp_fakeplayer break <id> [x y z]`              | Digs a block like the left mouse button in a [block world](/docs/scripting/blocks/). Without coordinates, the block below the player’s eyes.                                                          |
| `gp_fakeplayer place <id> [x y z [block]]`      | Places a block like the right mouse button, by default the selected hotbar block.                                                                                                                     |
| `gp_fakeplayer slot <id> <n>`                   | Picks hotbar slot `n`, like the keys 1 to 9.                                                                                                                                                          |
| `gp_block <x> <y> <z>`                          | Prints the block there and the surface height.                                                                                                                                                        |
| `gp_wait <ms>`                                  | Lets time pass, for test scripts.                                                                                                                                                                     |

Events the server sends to players are printed as `[net] -> <id> <event> <arguments as JSON>`.

## Placeholder world

[Section titled “Placeholder world”](#placeholder-world)

Every player gets a character that stands still at the spawn point until `gp_fakeplayer move` or `SetEntityCoords` moves it. Objects from `CreateObject` stand exactly where the script put them; `gp_entities` lists them. There is no physics and no map. That is enough to test scripts that check where players are or place objects, for example shops or zones. See [World and entities](/docs/scripting/reference/world/).

zone-test.cfg

```ini
set sv_requireJoinToken false
ensure my_zones
gp_fakeplayer client Tester
gp_fakeplayer waitclient 1 my_zones
gp_fakeplayer move 1 120 -45.5 30 90
gp_wait 1000
quit
```

## Example

[Section titled “Example”](#example)

test.cfg

```ini
set sv_requireJoinToken false
ensure my_shop
gp_fakeplayer join Tester
gp_wait 100
gp_fakeplayer event 1 my_shop:buy ["bread", 2]
gp_wait 500
quit
```

```sh
gampeon-server --data ./server-data --no-stdin +exec test.cfg
```

The exit happens after `quit`, so the output can be checked in CI.

## Client scripts

[Section titled “Client scripts”](#client-scripts)

Players added with `gp_fakeplayer client` download the client packages through the same channel as in the game and run the client scripts. Their output starts with `[client <id>/<resource>]`, and the server log shows `client scripts running` once they started. Use `gp_fakeplayer waitclient` before the first `clientcmd`: loading takes longer on slow machines, so a fixed `gp_wait` can be too short.

test-client.cfg

```ini
set sv_requireJoinToken false
ensure my_hud
gp_fakeplayer client Tester
gp_fakeplayer waitclient 1 my_hud
gp_fakeplayer clientcmd 1 hud toggle
gp_wait 200
quit
```

The fake client stores its files in the system temp folder under `gampeon-server-fakeclients`.

# Threads and timers

> Run code over time with CreateThread, Wait and SetTimeout.

Scripts must never block the game. Long-running work happens in **threads**: functions that pause with `Wait` and continue on a later tick.

```lua
CreateThread(function()
  while true do
    Wait(1000) -- pause one second; the game keeps running
    print('tick')
  end
end)
```

* `CreateThread(fn)` starts `fn` on the next tick.
* `Wait(ms)` pauses the current thread. `Wait(0)` waits until the next tick.
* `SetTimeout(ms, fn)` runs `fn` once after a delay.
* Event handlers run as threads too, so they may call `Wait`.

## Always call Wait in loops

[Section titled “Always call Wait in loops”](#always-call-wait-in-loops)

Every time a thread runs, it gets a budget of instructions (50 million by default). A loop without `Wait` runs out of budget and the runtime stops that run with an error. Other resources keep running.

```lua
-- Wrong: never yields
CreateThread(function()
  while true do end
end)


-- Right
CreateThread(function()
  while true do
    Wait(0)
  end
end)
```

## Wait outside a thread

[Section titled “Wait outside a thread”](#wait-outside-a-thread)

`Wait` at the top level of a script fails: `Wait can only be called inside a thread or event handler`. Wrap the code in `CreateThread`.

## Measuring time

[Section titled “Measuring time”](#measuring-time)

`GetGameTimer()` returns milliseconds since the runtime started:

```lua
local started = GetGameTimer()
Wait(250)
print(GetGameTimer() - started) -- about 250
```

The FiveM names `Citizen.CreateThread`, `Citizen.Wait` and `Citizen.SetTimeout` work as well.

# Authentication

> Session tokens, access tokens and server keys.

The API knows three kinds of credentials. Every operation in the [reference](/docs/api/reference/) says which one it needs (`x-gampeon-auth`).

| Kind          | Header                           | Used by                             | Status  |
| ------------- | -------------------------------- | ----------------------------------- | ------- |
| Session token | `Authorization: Bearer <token>`  | The portal, your own scripts        | Preview |
| Access token  | `Authorization: Bearer gpat_...` | AI assistants, MCP clients, scripts | Preview |
| Server key    | `X-Server-Key: <key>`            | Game servers sending heartbeats     | Preview |

## Session tokens

[Section titled “Session tokens”](#session-tokens)

```http
POST https://api.gampeon.com/v1/sessions
Content-Type: application/json


{ "email": "you@example.com", "password": "..." }
```

```json
{ "token": "...", "expiresAt": 1767225600000 }
```

A session is valid for 30 days. `DELETE /v1/sessions/current` ends it. A session token has every right of your account: keep it out of chats, logs and repositories.

Login is limited to 5 failed attempts per email and 30 attempts per IP address in 15 minutes.

## Access tokens

[Section titled “Access tokens”](#access-tokens)

Access tokens are for programs that act for you, above all AI assistants. Unlike a session, an access token:

* has **scopes**: it can only do what you allowed, for example read projects or edit marketplace items;
* **expires** after 30 days by default (at most one year);
* shows up in **AI activity** with every action it took;
* can be revoked at any time.

### Scopes

[Section titled “Scopes”](#scopes)

| Scope               | Allows                                                                |
| ------------------- | --------------------------------------------------------------------- |
| `profile:read`      | Read your profile (without email address) and your studios            |
| `projects:read`     | Read your projects and the studios you belong to                      |
| `projects:write`    | Create projects and edit their pages (no deleting)                    |
| `marketplace:read`  | Read your marketplace items, including blocked versions               |
| `marketplace:write` | Create marketplace items and edit their texts (no uploads, no prices) |
| `servers:read`      | Read your registered servers (never their keys)                       |

`GET /v1/tokens/scopes` returns the same list with the templates and limits. `GET /v1/token` works with every valid token, whatever its scopes, and returns the token’s own name, scopes and expiry; MCP clients use it to check a token. Each operation in the [reference](/docs/api/reference/) that a token may use names its scope in `x-gampeon-token-scope`.

### Everything else is closed

[Section titled “Everything else is closed”](#everything-else-is-closed)

A token works **only** on the operations that list a scope. On every other operation, public ones included, the API answers `403 token_not_allowed`. If the token lacks the scope, it answers `403 insufficient_scope`. That is how the API makes sure that no token can ever:

* change your password, email or profile settings, or log you out,
* create, list or revoke tokens,
* moderate, administer or see other people’s private data,
* buy, sell, pay or move GAMPEONS, or set prices,
* upload versions or confirm the [rights statement](/docs/marketplace/rights-statement/),
* delete anything.

With a token, `GET /v1/me` does not include your email address.

### Creating tokens

[Section titled “Creating tokens”](#creating-tokens)

In the portal under **Account → Access tokens**, or with your session:

```http
POST https://api.gampeon.com/v1/me/tokens
Authorization: Bearer <session token>
Content-Type: application/json


{ "name": "Claude Desktop", "scopes": ["profile:read", "projects:read", "projects:write"], "expiresInDays": 30 }
```

The answer contains `token` once. `DELETE /v1/me/tokens/<id>` revokes it immediately. You can have up to 20 active tokens. Every new token adds a notification to your account, so you notice if someone else created one.

### Activity log

[Section titled “Activity log”](#activity-log)

`GET /v1/me/token-events` lists what your tokens did in the last 90 days: route, result (`allowed` or `denied` with the reason), client, MCP tool, IP address and time. Request and response contents are never stored. Clients can name themselves with the headers `X-Gampeon-Client` and `X-Gampeon-Tool`; the GAMPEON MCP server does this.

### Limits

[Section titled “Limits”](#limits)

120 requests per minute and 2000 per hour per token, on top of the limits of each operation.

## Server keys

[Section titled “Server keys”](#server-keys)

You get a server key once, when you [register a server](/docs/servers/register/). It is only valid for the heartbeat of that one server.

## Roles

[Section titled “Roles”](#roles)

Some operations need a role: `moderator` for reports and appeals, `admin` for platform administration. They are not available to normal accounts and never to access tokens.

# Errors and limits

> Error format, status codes and rate limits of the web API.

## Error format

[Section titled “Error format”](#error-format)

Every error has the same shape:

```json
{ "error": "invalid_field", "message": "name too short" }
```

`error` is a stable code you can program against. `message` is optional and meant for people; its wording can change.

## Status codes

[Section titled “Status codes”](#status-codes)

| Status | Typical codes                                                                                             | Meaning                                                                                                    |
| ------ | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_field`, `invalid_json`, `body_must_be_object`                                                    | The request is malformed. `message` names the field.                                                       |
| 401    | `unauthorized`, `invalid_credentials`, `invalid_server_key`                                               | Login missing, expired or wrong.                                                                           |
| 403    | `forbidden`, `email_unverified`, `signup_closed`, `token_not_allowed`, `insufficient_scope`               | Logged in, but not allowed. The last two are for [access tokens](/docs/api/authentication/#access-tokens). |
| 404    | `not_found`                                                                                               | Does not exist, or you may not see it.                                                                     |
| 409    | `name_taken`, `slug_taken`, `version_exists`, `offset_mismatch`, `package_unavailable`, `*_limit_reached` | Conflicts with existing data or a limit. For an upload in pieces, `message` says where to continue.        |
| 413    | `body_too_large`, `file_too_large`, `quota_exceeded`                                                      | Too big.                                                                                                   |
| 415    | `unsupported_media_type`                                                                                  | Wrong `Content-Type`.                                                                                      |
| 416    | `range_not_satisfiable`                                                                                   | The `Range` of a download lies outside the file.                                                           |
| 422    | `rights_confirmation_required`, `checksum_mismatch`, `good_faith_confirmation_required`                   | Understood, but a required confirmation or check failed.                                                   |
| 429    | `rate_limited`, `too_many_attempts`                                                                       | Too many requests. Wait and try again.                                                                     |
| 451    | `unavailable_for_legal_reasons`                                                                           | The version was blocked after a report.                                                                    |
| 500    | `internal_error`                                                                                          | Our fault. Try again later.                                                                                |
| 503    | `packages_unavailable`, `storage_disabled`                                                                | A feature is switched off on this server.                                                                  |
| 507    | `storage_full`                                                                                            | GAMPEON has no room for uploads right now. Try again later.                                                |

## Rate limits

[Section titled “Rate limits”](#rate-limits)

Limits protect the platform and other creators. Each operation lists its limit in the [reference](/docs/api/reference/) (`x-gampeon-rate-limit`). The most important ones:

| Operation                              | Limit                                                                  |
| -------------------------------------- | ---------------------------------------------------------------------- |
| Sign-up                                | 5 per hour per IP address                                              |
| Login                                  | 5 failed attempts per email, 30 attempts per IP address, in 15 minutes |
| Create project                         | 10 per hour                                                            |
| Create studio                          | 5 per hour                                                             |
| Register server                        | 10 per hour                                                            |
| Heartbeat                              | 20 per minute per server                                               |
| Create marketplace item                | 20 per hour                                                            |
| New version, file upload, image upload | 30 per hour each                                                       |
| Edits (`PATCH`)                        | 120 per hour per account                                               |
| Download                               | 120 per hour per IP address                                            |
| Report                                 | 10 per hour per IP address                                             |
| Appeal                                 | 10 per day                                                             |
| Requests with one access token         | 120 per minute, 2000 per hour                                          |
| New access tokens                      | 10 per hour                                                            |

## Account limits

[Section titled “Account limits”](#account-limits)

| What                 | Limit  |
| -------------------- | ------ |
| Projects you create  | 20     |
| Studios you found    | 5      |
| Members per studio   | 50     |
| Projects per studio  | 50     |
| Servers              | 10     |
| Active access tokens | 20     |
| File per version     | 256 MB |
| Storage              | 2 GB   |
| Preview image        | 2 MB   |

## Good practice

[Section titled “Good practice”](#good-practice)

* On `429`, wait for the number of seconds in the `Retry-After` header (currently 60) before retrying. Do not retry in a tight loop.
* Treat `404` and `403` as final; retrying does not help.
* Never log tokens or server keys, also not in error reports.

# Web API overview

> Base URL, formats and conventions of the GAMPEON web API.

The GAMPEON web API is what the portal, game servers and the MCP server use. You can use it too, for example to show your servers on your own website or to automate releases.

|              |                                                                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL     | `https://api.gampeon.com`                                                                                                                     |
| Version      | `/v1/` in every path. Breaking changes get a new version. During the preview, `/v1/` can still change; see the [changelog](/docs/changelog/). |
| Format       | JSON in and out (`Content-Type: application/json`). File uploads use `application/octet-stream`.                                              |
| Request body | At most 64 KB of JSON. Files have their own limits.                                                                                           |
| Times        | Milliseconds since 1970-01-01 UTC, as numbers.                                                                                                |
| Description  | OpenAPI 3.1: [`/v1/openapi.json`](https://api.gampeon.com/v1/openapi.json), also at [/reference/openapi.json](/docs/reference/openapi.json)   |

## Reference

[Section titled “Reference”](#reference)

The [API reference](/docs/api/reference/) lists every operation with its parameters, answers, required login and rate limit. It is generated from the same description the API server serves, and a test in the platform makes sure every route is described.

## Quick examples

[Section titled “Quick examples”](#quick-examples)

Public, no login:

```sh
curl https://api.gampeon.com/v1/servers
curl "https://api.gampeon.com/v1/resources?q=garage&kind=vehicle"
curl https://api.gampeon.com/v1/projects/neon-racers
```

With login:

```sh
curl https://api.gampeon.com/v1/me -H "Authorization: Bearer $GAMPEON_TOKEN"
```

See [Authentication](/docs/api/authentication/) for how to get a token and [Errors and limits](/docs/api/errors-and-limits/) for what can go wrong.

## Browsers

[Section titled “Browsers”](#browsers)

The API allows cross-origin requests (CORS) only from the GAMPEON portal. Call it from your own server or scripts, not directly from a browser page on another domain.

## For AI assistants

[Section titled “For AI assistants”](#for-ai-assistants)

AI assistants should use the [MCP server](/docs/mcp/overview/) instead of calling the API directly: it adds checks, clear tool descriptions and an activity log.

# Coming from FiveM

> What carries over from FiveM, what is different and what does not exist.

If you have written FiveM resources, most of what you know still applies. GAMPEON uses Lua 5.4, the same resource format and the same event, thread and export model. What it does not have is GTA V: there are no GTA natives, no GTA assets and no GTA map.

## What carries over

[Section titled “What carries over”](#what-carries-over)

| FiveM                                                                                                      | GAMPEON                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fxmanifest.lua`, `__resource.lua`                                                                         | Read directly. See [Manifest](/docs/scripting/manifest/).                                                                                                                                                                                                                                                                   |
| `AddEventHandler`, `RegisterNetEvent`, `TriggerEvent`, `TriggerServerEvent`, `TriggerClientEvent`          | Same names, same behaviour. `source` is set in network events.                                                                                                                                                                                                                                                              |
| `CreateThread`, `Wait`, `SetTimeout`, `Citizen.*`                                                          | Same.                                                                                                                                                                                                                                                                                                                       |
| `exports('name', fn)`, `exports.res:fn()`                                                                  | Same. Values are copied, functions are passed as references and may `Wait`. See [Exports](/docs/scripting/exports/).                                                                                                                                                                                                        |
| `json.encode`, `json.decode`, `GetGameTimer`, `GetCurrentResourceName`, `IsDuplicityVersion`               | Same.                                                                                                                                                                                                                                                                                                                       |
| `onResourceStart`, `onResourceStop`                                                                        | Same.                                                                                                                                                                                                                                                                                                                       |
| `RegisterCommand`, `ExecuteCommand`, `GetConvar*`, `SetConvar*`, ACE permissions                           | Same. See [Commands and convars](/docs/scripting/commands-and-convars/).                                                                                                                                                                                                                                                    |
| `PerformHttpRequest`                                                                                       | Same, private addresses are blocked. See [HTTP requests](/docs/scripting/http/).                                                                                                                                                                                                                                            |
| `vector2`, `vector3`, `vector4`, `promise`, `Citizen.Await`                                                | Same.                                                                                                                                                                                                                                                                                                                       |
| `LoadResourceFile`, `SaveResourceFile`, `GetResourceMetadata`, `GetInvokingResource`                       | Same.                                                                                                                                                                                                                                                                                                                       |
| oxmysql, mysql-async (`MySQL.*`)                                                                           | Built in. See [Database](/docs/scripting/database/).                                                                                                                                                                                                                                                                        |
| `server.cfg` with `ensure`, `exec`, `set`/`setr`/`sets`, `add_ace`, `add_principal`                        | Same. See [Commands and convars](/docs/scripting/commands-and-convars/).                                                                                                                                                                                                                                                    |
| `clientkick`, bans from txAdmin                                                                            | `clientkick` is the same. `ban`, `unban` and `banlist` are built into the server. See [Kick and ban](/docs/scripting/commands-and-convars/#kick-and-ban).                                                                                                                                                                   |
| `playerJoining`, `playerDropped`, `GetPlayers`, `GetPlayerName`, `GetPlayerIdentifiers`, `DropPlayer`      | Same. Identifiers are `gampeon:` and `license:`. See [Players](/docs/scripting/players/).                                                                                                                                                                                                                                   |
| `client_script`, `files`, download on join, `PlayerId`, `GetPlayerServerId`                                | Same. Only from trusted servers for now. See [Client scripts](/docs/scripting/client-scripts/).                                                                                                                                                                                                                             |
| `chat` resource: `chat:addMessage`, `chatMessage`, `chat:addSuggestion`, `CancelEvent`                     | Same events, built in. Plain text only, no HTML or colour codes. See [Text chat](/docs/scripting/chat/).                                                                                                                                                                                                                    |
| `ui_page`, `SendNUIMessage`, `RegisterNUICallback`, `SetNuiFocus`, `fetch('https://<resource>/…')`         | Same. Shown over the game on test servers and in `gampeon-server`. See [Web interfaces](/docs/scripting/nui/).                                                                                                                                                                                                              |
| `GetPlayerPed`, `PlayerPedId`, `GetEntityCoords`, `GetEntityHeading`, `SetEntityCoords`, `DoesEntityExist` | Same names, meters like in FiveM. Heading follows the Unreal editor (0 faces +x, 90 faces +y), so values copy 1:1 from a map’s rotation. For “in front of the player” math use `GetEntityForwardVector` instead of GTA heading formulas. Moving is server only. See [World and entities](/docs/scripting/reference/world/). |
| `CreateObject`, `DeleteEntity`, `FreezeEntityPosition`, `GetHashKey`, `GetEntityModel`, `IsModelValid`     | Same arguments, server only for now. GAMPEON has its own models (`prop_cube` and more), GTA model names return 0 with a hint in the log. Objects disappear when their resource stops. See [Objects](/docs/scripting/objects/).                                                                                              |

## What is different

[Section titled “What is different”](#what-is-different)

* **No GTA natives.** GAMPEON has its own game API. Where it does the same as FiveM, it uses the FiveM name: the player functions and [World and entities](/docs/scripting/reference/world/) (`GetPlayerPed`, `GetEntityCoords`, `SetEntityCoords`, `CreateObject` and a few more). `DrawMarker` and most other natives do not exist, and GTA models are not there: `CreateObject` takes GAMPEON models, `CreateVehicle` has none yet. Only the functions in the [Lua API reference](/docs/scripting/reference/) exist.
* **Positions are in meters, headings follow Unreal.** `GetEntityCoords` returns meters like in FiveM, but GAMPEON maps are not GTA maps, so coordinates do not carry over. A heading of 0 faces +x and 90 faces +y.
* **Stricter sandbox.** No `io`, `os.execute`, `debug`, `package`, `require`, `dofile` or bytecode. Every resource has its own memory and CPU limit. See [Sandbox](/docs/scripting/sandbox/).
* **Network events must be registered.** A handler only receives an event from the other side if its resource called `RegisterNetEvent` for that name. This is FiveM’s recommended practice; GAMPEON enforces it.
* **Functions do not cross the network.** Between resources on the same side they work like in FiveM. A received function is a normal Lua function (`type(cb) == 'function'`), not a table.
* **Your own assets.** GTA models, maps, sounds and textures cannot be used. Neither can assets ripped from other games. See [Third-party assets](/docs/policies/third-party-assets/).

## Frameworks

[Section titled “Frameworks”](#frameworks)

ESX, QBCore, Qbox and ox_lib depend heavily on GTA natives, so they do not run unchanged. Instead, the [RP Starter](/docs/fivem/rp-starter/) gives your resources what they expect from ESX and QBCore: `getSharedObject`, `GetCoreObject`, `xPlayer`, `Player.Functions`, callbacks, usable items and the usual events, on top of its own characters, money, jobs and inventory. Database calls work anyway, because `MySQL.*` is built in like oxmysql. Code that uses GTA natives still needs porting.

## Test without the game

[Section titled “Test without the game”](#test-without-the-game)

[`gampeon-server`](/docs/scripting/test-server/) runs your server resources from the console, with fake players that join, send events and type commands.

## Check your server

[Section titled “Check your server”](#check-your-server)

The [porting check](/docs/fivem/porting-check/) reads your server’s resources and tells you, per resource, what works already and what needs replacing.

## With an AI assistant

[Section titled “With an AI assistant”](#with-an-ai-assistant)

Ask your assistant to *“port this FiveM resource to GAMPEON”*. With the MCP server connected, it uses the `port_fivem_resource` prompt, knows which functions exist and marks everything it cannot port. See [Example prompts](/docs/ai/prompts/#port-from-fivem).

# Porting check

> Estimate how much work it is to bring a FiveM server's resources to GAMPEON.

The porting check is a small script that reads a folder of FiveM resources and writes a report. It never runs your code and does not send anything anywhere.

## Run it

[Section titled “Run it”](#run-it)

You need Python 3.10 or newer. No packages.

```sh
python3 scan.py /path/to/server/resources --out report.md
python3 scan.py /path/to/server/resources --json
```

The script is part of the GAMPEON SDK (`porting-kit/scan.py`). Ask the GAMPEON team for access while the SDK is not public yet.

## What the report shows

[Section titled “What the report shows”](#what-the-report-shows)

For every resource:

* **Runtime calls** that GAMPEON already supports (events, exports, threads).
* **Platform calls** such as `GetPlayerName`, `RegisterCommand` or NUI that GAMPEON will provide in its own API.
* **GTA natives** that must be replaced, with how often each is used.
* **Frameworks** in use: ESX, QBCore, Qbox, ox_lib, MySQL, ox_inventory, target systems.
* **ESX and QBCore calls** (`ESX.*`, `xPlayer.*`, `QBCore.Functions.*`, `Player.Functions.*`) and which of them the [RP Starter](/docs/fivem/rp-starter/) bridges do not cover yet. Functions that exist in a bridge but do nothing yet, such as weapons, count as missing.
* **NUI pages and streamed assets.** Streamed models and maps are flagged: check the rights and rebuild them, never copy them.
* An **estimated difficulty** from low to high.

## Limits

[Section titled “Limits”](#limits)

The check uses patterns, not a full Lua parser. Global functions from other resources that start with a capital letter can be counted as natives. The result is an estimate for planning, not a guarantee.

## What happens with the results

[Section titled “What happens with the results”](#what-happens-with-the-results)

If you share reports with the GAMPEON team, the most used natives across many servers decide the order in which GAMPEON builds its game API.

# RP Starter

> A ready roleplay base with characters, money, jobs and inventory, and bridges for ESX and QBCore resources.

The RP Starter is GAMPEON’s own roleplay base. It gives a server characters, money, jobs, an inventory, a HUD and admin commands. Two bridges let resources written for ESX or QBCore run on it without changes, as long as they do not use GTA natives.

It is part of the GAMPEON SDK under `starter/rp` and licensed under MIT, so you can change it and ship it with your server. Ask the GAMPEON team for access while the SDK is not public yet. The design is in ADR 0028.

## What it has

[Section titled “What it has”](#what-it-has)

* **Characters:** up to 4 per player account, chosen or created in a web page when the player joins, saved with their position.
* **Money:** the accounts `cash`, `bank` and `black_money`. ESX calls cash `money`; the bridges translate.
* **Jobs** with grades, salary and a boss flag. Each grade pays its salary to `bank` every 10 minutes.
* **Inventory** by weight (30 kg by default) with usable items.
* **Callbacks** from client to server, notifications and a HUD with cash, bank and job.
* **Admin commands** `setjob`, `givemoney`, `giveitem` and `charinfo` for `group.admin`. Everyone has `/use <item>`, `/logout` and `/inventory`.
* **Saving** with `MySQL.*`, to SQLite or MariaDB: when a player leaves, every 60 seconds after changes and when the resource stops.

Jobs, items, start money and limits are Lua files in `gampeon_rp/shared/`. The server decides everything: clients get a copy of their character, and no client event can change money, jobs or items.

## Start it

[Section titled “Start it”](#start-it)

```plaintext
gampeon-server --data starter/rp
```

The included `server.cfg` uses SQLite in `data/rp.db` and starts the core with both bridges:

server.cfg

```cfg
set mysql_connection_string "sqlite:data/rp.db"
add_ace group.admin command allow
ensure chat
ensure gampeon_rp
ensure es_extended
ensure qb-core
```

Start only the bridges your resources need. On a game server, copy the `[rp]` folder into your `resources` folder.

## ESX resources

[Section titled “ESX resources”](#esx-resources)

The `es_extended` bridge keeps the usual entry points:

fxmanifest.lua

```lua
shared_script '@es_extended/imports.lua'
```

server.lua

```lua
ESX.RegisterUsableItem('water', function(source)
  local xPlayer = ESX.GetPlayerFromId(source)
  if xPlayer.removeInventoryItem('water', 1) then
    xPlayer.showNotification('You drank some water.', 'success')
  end
end)


ESX.RegisterServerCallback('myshop:wallet', function(source, cb)
  local xPlayer = ESX.GetPlayerFromId(source)
  cb(xPlayer.getMoney(), xPlayer.getAccount('bank').money)
end)
```

Covered: `getSharedObject` and `esx:getSharedObject`, `@es_extended/imports.lua` (keeps `ESX.PlayerData` current, calls `OnPlayerData`), `@es_extended/locale.lua`, `GetPlayerFromId`, `GetPlayerFromIdentifier`, `GetExtendedPlayers`, `RegisterServerCallback`, `TriggerServerCallback`, `RegisterUsableItem`, `RegisterCommand` with typed arguments, `GetJobs`, `ShowNotification`, and `xPlayer` with money, accounts, inventory, weight, job, metadata, `set`/`get` and coordinates. Events: `esx:playerLoaded`, `esx:playerDropped`, `esx:setJob`, `esx:onAddInventoryItem`, `esx:onRemoveInventoryItem`, and on the client `esx:setAccountMoney`, `esx:addInventoryItem`, `esx:removeInventoryItem`, `esx:setPlayerData`, `esx:onPlayerLogout`.

The identifier of an `xPlayer` is the character’s citizen ID.

## QBCore resources

[Section titled “QBCore resources”](#qbcore-resources)

server.lua

```lua
local QBCore = exports['qb-core']:GetCoreObject()


QBCore.Functions.CreateUseableItem('bread', function(source, item)
  local Player = QBCore.Functions.GetPlayer(source)
  if Player.Functions.RemoveItem(item.name, 1) then
    Player.Functions.SetMetaData('hunger', Player.PlayerData.metadata.hunger + 25)
  end
end)
```

Covered: `GetCoreObject`, `QBCore.Functions` (`GetPlayer`, `GetPlayerByCitizenId`, `GetPlayers`, `GetQBPlayers`, `CreateCallback`, `TriggerCallback`, `CreateUseableItem`, `HasItem`, `Notify`, `HasPermission`, `GetPlayersOnDuty` and more), `Player.Functions` for money, items, job, duty and metadata, `PlayerData` with `charinfo`, `money`, `job`, `gang`, `metadata` and `items`, `QBCore.Commands.Add`, `QBCore.Shared.Items` and `Jobs`, `@qb-core/shared/locale.lua` with `Lang:t`. Events: `QBCore:Server:PlayerLoaded`, `QBCore:Server:OnPlayerUnload`, `QBCore:Server:OnJobUpdate`, `QBCore:Server:OnMoneyChange`, and on the client `QBCore:Client:OnPlayerLoaded`, `QBCore:Client:OnPlayerUnload`, `QBCore:Player:SetPlayerData`, `QBCore:Client:OnJobUpdate`, `QBCore:Client:SetDuty`, `QBCore:Notify`.

From clients, the bridge accepts only using items, toggling duty, saving and setting hunger or thirst between 0 and 100.

## Its own API

[Section titled “Its own API”](#its-own-api)

New resources can use the core directly, without a bridge:

server.lua

```lua
local RP = exports.gampeon_rp:GetCoreObject()


RP.RegisterCallback('garage:fee', function(source, respond)
  return RP.RemoveMoney(source, 'bank', 50, 'garage')
end)


AddEventHandler('gampeon_rp:playerLoaded', function(source, player, isNew)
  print(player.name, player.job.label, player.getMoney('cash'))
end)
```

The full list of functions and events is in the README of `starter/rp`.

## Not yet

[Section titled “Not yet”](#not-yet)

Gangs, weapons and loadouts, vehicles, slot inventories (QBCore items get slots in list order), `ESX.UI` menus, `ESX.Game`, Qbox exports (`qbx_core`), ox_lib and ox_inventory. The [porting check](/docs/fivem/porting-check/) lists every ESX and QBCore call in your resources that the bridges do not cover yet.

# Create an account

> Sign up for GAMPEON, verify your email and pick your handle.

You need a GAMPEON account to create projects, publish to the marketplace, register servers and connect an AI assistant with write access. Reading these docs and searching the marketplace works without one.

Closed test

Sign-up is by invitation while GAMPEON is in its closed test. If your email is not on the list, the sign-up form answers `signup_closed`. Ask the GAMPEON team to join the test.

## Sign up

[Section titled “Sign up”](#sign-up)

1. Open [gampeon.com](https://gampeon.com/) and choose **Sign up**.
2. Enter your email, a display name, a password, your month and year of birth and, if you like, a **handle**.
3. Accept the [Terms of Use](https://gampeon.com/legal/terms/) and the [Community Guidelines](https://gampeon.com/legal/community-guidelines/). The [Privacy Policy](https://gampeon.com/legal/privacy/) explains what happens with your data.
4. Open the link in the confirmation email. You can log in once your email is verified.

GAMPEON is for people aged 13 and older. Under 16, stricter privacy defaults apply. If you are under 18, read the [short version for teens](https://gampeon.com/legal/teen-safety/).

If you build your own sign-up flow on the API, send `acceptTerms` with the version from `GET /v1/legal/terms`, and only after the person has agreed. Accounts that have not accepted the version in force see a notice in the portal (`terms.current` is `false` in `GET /v1/me`).

Your handle is your public name in URLs, for example `gampeon.com/u/your_handle`. It has 3 to 24 characters: lowercase letters, digits and underscores. If you leave it empty, GAMPEON derives one from your display name. You can change it later.

## Profile

[Section titled “Profile”](#profile)

Your profile shows your display name, bio, the projects and studios you work on, your marketplace items and your achievements. You can change display name, bio and handle in the settings.

## Sessions

[Section titled “Sessions”](#sessions)

Logging in creates a session that lasts 30 days. Logging out ends it on this device. If you forget your password, use **Forgot password** on the login page: the reset link in the email is valid for a short time only.

## Your account and AI assistants

[Section titled “Your account and AI assistants”](#your-account-and-ai-assistants)

Never give your password to an AI assistant or paste it into a chat. To let an assistant work for you, create an **access token** with only the permissions it needs. See [Connect your AI assistant](/docs/ai/connect/) and [Working safely with AI](/docs/ai/safety/).

# Your first resource

> Write a small Lua resource, check it in your editor and get it ready for a server.

This walkthrough builds a resource that greets every player who joins. It takes about ten minutes. If you prefer to describe what you want and let an AI write the code, follow [Your first game with AI](/docs/ai/first-game/) instead. Both paths end with the same files.

## 1. Create the folder

[Section titled “1. Create the folder”](#1-create-the-folder)

```plaintext
resources/
  greeter/
    fxmanifest.lua
    server.lua
    client.lua
```

The folder name is the resource name. Use lowercase letters, digits, `_` and `-`.

## 2. Write the manifest

[Section titled “2. Write the manifest”](#2-write-the-manifest)

fxmanifest.lua

```lua
name 'greeter'
version '0.1.0'
description 'Greets players'


server_script 'server.lua'
client_script 'client.lua'
```

See [Manifest](/docs/scripting/manifest/) for all directives.

## 3. Server script

[Section titled “3. Server script”](#3-server-script)

server.lua

```lua
RegisterNetEvent('greeter:hello')


AddEventHandler('greeter:hello', function(name)
  -- source is the player who sent the event. Never trust the name blindly.
  if type(name) ~= 'string' or #name > 32 then return end
  print(('Player %d says hello as %s'):format(source, name))
  TriggerClientEvent('greeter:welcome', source, ('Welcome, %s!'):format(name))
end)
```

## 4. Client script

[Section titled “4. Client script”](#4-client-script)

client.lua

```lua
RegisterNetEvent('greeter:welcome')


AddEventHandler('greeter:welcome', function(text)
  print(text)
end)


CreateThread(function()
  Wait(1000)
  TriggerServerEvent('greeter:hello', 'Alex')
end)
```

## 5. Check it in your editor

[Section titled “5. Check it in your editor”](#5-check-it-in-your-editor)

Install the [editor setup](/docs/scripting/editor-setup/) once. Your editor then knows every GAMPEON function, warns about typos and shows the documentation on hover. Functions that do not exist in GAMPEON, such as GTA natives, are marked as unknown.

## 6. Run it

[Section titled “6. Run it”](#6-run-it)

Put the folder into the `resources/` folder of a server folder, add `ensure greeter` to `server.cfg` and start [`gampeon-server`](/docs/scripting/test-server/). It runs your resource without the game, with fake players:

test.cfg

```ini
set sv_requireJoinToken false
ensure greeter
gp_fakeplayer client Alex
gp_fakeplayer waitclient 1 greeter
gp_wait 1500
quit
```

```sh
gampeon-server --data ./server-data --no-stdin +exec test.cfg
```

The output shows `[greeter] Player 1 says hello as Alex` from the server and `[client 1/greeter] Welcome, Alex!` from the fake player’s client script.

Game servers

In the game, Lua runs on internal test servers during the closed test. Game servers for creators are [planned](/docs/start/status/). Your resource runs there unchanged.

## Next steps

[Section titled “Next steps”](#next-steps)

* [Events](/docs/scripting/events/): talk between server and client safely.
* [Threads](/docs/scripting/threads/): loops and timers.
* [Make your game, step by step](/docs/getting-started/make-your-game/): from project to players.
* [Publish to the marketplace](/docs/getting-started/publish/).

# Upload your game package

> Cook your content plugin for GAMPEON, upload it to your project, run your server with it, and players get it when they press Play.

A **game package** holds your own Unreal content: maps, meshes, materials, textures, animations and sounds. It belongs to one project. Only servers linked to that project load it, and only their players get it. It never appears on the marketplace and nobody can download it in the portal.

This page takes a package from your Unreal project to players. How to build the plugin and prepare a map is on [Bring your own map](/docs/getting-started/your-own-map/).

Closed test

This is the second stage of [private game packages](/docs/getting-started/make-your-game/#10-your-own-models-maps-and-characters). During the closed test, game servers run only on GAMPEON’s internal test machines, the creator kit comes from the GAMPEON team, and the launcher is not available for download yet. The upload does not check Blueprint logic yet, and packages are not encrypted yet.

## How it works

[Section titled “How it works”](#how-it-works)

1. You **cook** your content plugin with the GAMPEON cook command. Cooking turns your assets into the format the game loads, for exactly one GAMPEON version.
2. You **upload** the cooked package in the portal, in your project’s **Game packages** tab. You confirm that your license allows this content in your game.
3. Your **server** loads the same package and tells GAMPEON which package and version it runs.
4. A player presses **Play** in the launcher. The launcher downloads the package once, checks every file and starts the game with it. Next time only a new version downloads.

## 1. Cook the package

[Section titled “1. Cook the package”](#1-cook-the-package)

The cook command is `CookPackage.ps1` in the **creator kit**: a copy of the GAMPEON Unreal project for one GAMPEON version, together with that version’s release data. Cook against the same version your server and the players run; the game refuses a package cooked for another version.

```powershell
.\Scripts\CookPackage.ps1 -Engine C:\UnrealEngine\UE_5.8 `
  -Plugin C:\MyGame\Plugins\GamCity\GamCity.uplugin `
  -BasedOn C:\GAMPEON\releases\0.1.0-125aa18 `
  -Version 1.0.0 -Out C:\MyGame\Packages
```

| Option     | Meaning                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------- |
| `-Plugin`  | Your content plugin’s `.uplugin`. It stays where it is; the kit only links it while cooking.             |
| `-BasedOn` | The GAMPEON release folder from the kit. Only what GAMPEON does not have already goes into your package. |
| `-Version` | Your package version, such as `1.0.0`. Every upload needs a new version.                                 |
| `-Out`     | Where the cooked package goes.                                                                           |

Before cooking, the command checks the name, that the plugin has no C++ modules, and the file types in `Nui`. The result is a folder `Packages\GamCity` with:

* `GamCity.uplugin`
* `Content\Paks\WindowsClient\…` for players
* `Content\Paks\WindowsServer\…` for your server; this part is not uploaded
* `Nui\…`, the images and fonts for your [web interfaces](/docs/scripting/nui/#images-and-fonts-from-your-game-package)
* `gampeon-package.json`: name, version, GAMPEON version and every file for players with its size and SHA-256

## 2. Upload it

[Section titled “2. Upload it”](#2-upload-it)

1. Open your project in the portal, then **Manage → Game packages**.
2. Choose the package folder, for example `Packages\GamCity`. The portal reads `gampeon-package.json` and shows the name, version and size.
3. Read the license statement and confirm it.
4. Select **Upload**. Large files go up in pieces. If the upload stops, choose the same folder again: it continues where it stopped.

When the upload is done, the version is **ready**. GAMPEON checks every file against its SHA-256 and checks that the `.uplugin` has no code modules. Only cooked paks and the allowed `Nui` file types are accepted.

| Limit               | Value                                                            |
| ------------------- | ---------------------------------------------------------------- |
| Size per version    | 4 GB                                                             |
| Storage per project | 12 GB (files shared by several versions count once)              |
| Ready versions kept | the newest 3 per package; uploading a new one deletes older ones |

Deleting a version in the same tab removes it. Servers that still run it can no longer be joined until they load another ready version.

## 3. Run your server with it

[Section titled “3. Run your server with it”](#3-run-your-server-with-it)

1. Start the server with the cooked folder, the same version you uploaded:

   ```plaintext
   GampeonProtoServer -port=7777 -gppackage="C:/MyGame/Packages/GamCity/GamCity.uplugin"
   ```

2. Choose the map in `server.cfg`, see [Bring your own map](/docs/getting-started/your-own-map/#4-choose-the-map-in-servercfg).

3. Register the server in the portal and put its ID and key into `server.cfg`, then link the server to your project under **Manage → Servers and content**.

The server reports its package name and version with every heartbeat. In the log you see `Game package GamCity 1.0.0 mounted … (cooked)`.

## 4. Players press Play

[Section titled “4. Players press Play”](#4-players-press-play)

Players see your game and its servers in the launcher. When they press **Play**, GAMPEON looks up the packages the server runs and gives the launcher a download permission for 60 minutes. The launcher downloads the files into its own folder, continues interrupted downloads, checks every file and starts the game with your package. A player who joins again with the same version downloads nothing.

If the server runs a version that is not uploaded or not ready yet, Play shows: *This server needs the game package GamCity 1.0.0, which is not available on GAMPEON.* Upload and finish that version, or start the server with a ready one.

## When GAMPEON updates

[Section titled “When GAMPEON updates”](#when-gampeon-updates)

Cooked content fits only the GAMPEON version it was cooked for. After an update of GAMPEON, cook your package again with the new creator kit, give it a new version and upload it, then restart your server with it.

## Not there yet

[Section titled “Not there yet”](#not-there-yet)

* The check for Blueprint logic in packages. Game rules belong in Lua; keep Blueprints to visuals.
* Encryption of packages on the players’ computers.
* Your server downloading its package from GAMPEON by itself.
* Your own models for `CreateObject` from a package (`<package>/<name>`).
* The creator kit as a download in the portal.

# Make your game, step by step

> The whole way from an idea to a game other people play, with GamCity as the example. Project, resource, tests, server, players, and what is not there yet.

This guide follows **GamCity**, the first creator game on GAMPEON: a fixed city in the middle, block land around it where players dig and build, a market that buys ore and sells building blocks. GamCity is built only with the tools every creator has. It has no special access and no code of its own inside the game. Where a step is not possible yet, this page says so.

| Step                                                                                             | Where            | Status                         |
| ------------------------------------------------------------------------------------------------ | ---------------- | ------------------------------ |
| [1. Decide what GAMPEON does and what you write](#1-decide-what-gampeon-does-and-what-you-write) |                  |                                |
| [2. Create your project](#2-create-your-project)                                                 | Portal           | Preview                        |
| [3. Lay out the server folder](#3-lay-out-the-server-folder)                                     | Your computer    | Preview                        |
| [4. Write the resource](#4-write-the-resource)                                                   | Your editor      | Preview                        |
| [5. Test without the game](#5-test-without-the-game)                                             | `gampeon-server` | Preview                        |
| [6. Run a game server](#6-run-a-game-server)                                                     | Test servers     | Preview internal only          |
| [7. Register the server and link it](#7-register-the-server-and-link-it)                         | Portal           | Preview                        |
| [8. Publish the project page](#8-publish-the-project-page)                                       | Portal           | Preview                        |
| [9. Players join](#9-players-join)                                                               | Launcher         | Planned                        |
| [10. Your own models, maps and characters](#10-your-own-models-maps-and-characters)              | Game packages    | Preview maps, local tests only |

## 1. Decide what GAMPEON does and what you write

[Section titled “1. Decide what GAMPEON does and what you write”](#1-decide-what-gampeon-does-and-what-you-write)

GAMPEON runs the world. Your scripts decide the game.

| GAMPEON does                                                                                                             | You write                                     |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
| Characters, movement, camera, network                                                                                    | What players own: inventory, money, levels    |
| The [block world](/docs/scripting/blocks/): terrain from a seed, dig and build controls, hotbar, saving changed blocks   | What digging gives and what players may place |
| Checks against cheating: reach, speed, protected zones                                                                   | Prices, recipes, rules, rewards               |
| [Chat](/docs/scripting/chat/), [web interfaces](/docs/scripting/nui/), [join check](/docs/scripting/players/#join-check) | Your windows, menus and messages              |

Rules belong in **server scripts**. Client scripts show things and send what the player wants; the server checks it again. See [Scripting overview](/docs/scripting/overview/).

Your game does not ship C++ code. If you need something GAMPEON does not have yet, [tell us](/docs/start/feedback/). Missing features are built into GAMPEON for every creator, not as an exception for one game. The block world started that way, for GamCity.

## 2. Create your project

[Section titled “2. Create your project”](#2-create-your-project)

1. Open [GAMPEON Create](https://create.gampeon.com), the creator site, and sign in with your GAMPEON account (the closed test needs an [invitation](/docs/getting-started/account/)).
2. Choose **New project**.
3. Pick the slug (GamCity uses `gamcity`; it cannot be changed later), a title, the genre (`sandbox`) and the status (`development`).

The project stays a **draft** that only you see until you publish it in step 8. See [Studios and projects](/docs/getting-started/studios-and-projects/).

## 3. Lay out the server folder

[Section titled “3. Lay out the server folder”](#3-lay-out-the-server-folder)

A game server reads one folder: `server.cfg` and `resources/`. The same folder works in `gampeon-server` and on the game server.

```plaintext
server-data/
  server.cfg
  resources/
    [gamcity]/              a folder in [brackets] only groups resources
      gamcity/
        fxmanifest.lua
        shared/config.lua   prices, recipes, the city zone
        server/main.lua     block world, inventory, market, saving
        client/main.lua     hotbar and window
        html/index.html     market and workshop window
        data/               the server saves players here
```

server.cfg

```ini
sv_hostname "GamCity"
sv_maxclients 32
sets tags "sandbox, building, city"
sets locale "en-US"


# Local tests: no join check. Remove this line once the server is registered (step 7).
set sv_requireJoinToken false


ensure chat
ensure gamcity
```

Keep the folder in Git if you like, but never commit a server key. Step 7 explains where the key goes.

## 4. Write the resource

[Section titled “4. Write the resource”](#4-write-the-resource)

Install the [editor setup](/docs/scripting/editor-setup/) first. Your editor then knows every GAMPEON function and marks typos.

### Manifest

[Section titled “Manifest”](#manifest)

fxmanifest.lua

```lua
fx_version 'cerulean'
game 'gampeon'


name 'gamcity'
version '0.1.0'


shared_script 'shared/config.lua'
server_script 'server/main.lua'
client_script 'client/main.lua'


ui_page 'html/index.html'
```

### One config for server and client

[Section titled “One config for server and client”](#one-config-for-server-and-client)

Prices and recipes live in a shared script. The server uses them to decide, the window uses them to show, and there is only one copy.

shared/config.lua

```lua
Config = {}
Config.world = { seed = 20261106, save = 'gamcity' }
Config.city = { minX = -48, minY = -48, maxX = 48, maxY = 48, groundZ = 8 }
Config.drops = { turf = 'soil', copper_vein = 'copper_ore', iron_vein = 'iron_ore' }
Config.items = {
  stone      = { label = 'Stone',      block = 'stone', sell = 1,  buy = 2 },
  copper_ore = { label = 'Copper ore',                  sell = 12, buy = 0 },
  -- …
}
```

### Server: the world and what digging gives

[Section titled “Server: the world and what digging gives”](#server-the-world-and-what-digging-gives)

server/main.lua

```lua
EnableBlockWorld({
  seed = Config.world.seed,
  save = Config.world.save,   -- changed blocks survive restarts
  zones = { Config.city },    -- the city: flat, nobody digs or builds there
})


AddEventHandler('blockBreak', function(x, y, z, block)
  local p = getPlayer(source)
  local item = Config.drops[block] or block
  if not Config.items[item] then return end
  if count(p, item) >= Config.maxStack then
    CancelEvent() -- the block stays, the bag is full
    return
  end
  add(p, item, 1)
  send(source) -- TriggerClientEvent('gamcity:state', …)
end)


AddEventHandler('blockPlace', function(x, y, z, block)
  local p = getPlayer(source)
  if count(p, block) < 1 then
    CancelEvent() -- placing needs the block in the bag
    return
  end
  add(p, block, -1)
  send(source)
end)
```

GAMPEON has already checked reach, speed, zones and free space before these events arrive. You only decide the game.

### Server: a market that cannot be cheated

[Section titled “Server: a market that cannot be cheated”](#server-a-market-that-cannot-be-cheated)

The window sends what the player clicked. The server checks everything again: where the player stands, the amount, the money.

server/main.lua

```lua
RegisterNetEvent('gamcity:action', function(action, item, amount)
  local src = source
  if type(item) ~= 'string' then return end
  local c = GetEntityCoords(GetPlayerPed(src))
  if not Config.InCity(c.x, c.y) then
    return notify(src, 'The market is in the city.')
  end
  if action == 'sell' then sell(src, item, amount)
  elseif action == 'buy' then buy(src, item, amount) end
end)
```

### Client: hotbar and window

[Section titled “Client: hotbar and window”](#client-hotbar-and-window)

client/main.lua

```lua
RegisterNetEvent('gamcity:state', function(state)
  local slots = {}
  for _, item in ipairs(Config.hotbar) do
    local n = state.inv[item] or 0
    if n > 0 and #slots < 9 then slots[#slots + 1] = { block = Config.items[item].block, count = n } end
  end
  SetBlockHotbar(slots)
  SendNUIMessage({ type = 'state', inv = state.inv, cash = state.cash })
end)


RegisterCommand('shop', function()
  open = not open
  SendNUIMessage({ type = open and 'open' or 'close' })
  SetNuiFocus(open, open)
  SetBlockControlsEnabled(not open) -- no digging while the window is open
end, false)
```

The window itself is a normal web page that calls back with `fetch`. See [Web interfaces](/docs/scripting/nui/).

### Save what players own

[Section titled “Save what players own”](#save-what-players-own)

The block world saves blocks. Inventories and money are yours to save. GamCity writes one JSON file with [SaveResourceFile](/docs/scripting/reference/resource/) every 30 seconds and when the resource stops. For more players, use the [database](/docs/scripting/database/).

## 5. Test without the game

[Section titled “5. Test without the game”](#5-test-without-the-game)

[`gampeon-server`](/docs/scripting/test-server/) runs your server folder without Unreal, with fake players that dig, build, click in your window and type commands. Write a test file next to `server.cfg`:

test.cfg

```ini
exec server.cfg
gp_fakeplayer client Tester
gp_fakeplayer waitclient 1 gamcity chat
gp_fakeplayer move 1 0.5 0.5 9 0
gp_fakeplayer break 1 0 0 8
gp_fakeplayer move 1 100.5 100.5 20 0
gp_fakeplayer break 1
gp_wait 200
gp_fakeplayer command 1 inv
gp_fakeplayer nui 1 gamcity ready {}
gp_fakeplayer command 1 city
gp_fakeplayer event 1 gamcity:action ["buy", "planks", 3]
gp_wait 500
quit
```

`gp_block 100 100 0` prints the surface height there, so you know where to put the fake player. Without coordinates, `break` digs the block below the player’s eyes.

```sh
gampeon-server --data ./server-data --no-stdin +exec test.cfg
```

The output, shortened:

```plaintext
[blocks] player 1 break at 0 0 8 refused: protected zone
[blocks] player 1 broke turf at 100 100 19
[client 1/blocks] hotbar: soil x1
[client 1/chatbox] GamCity: $50 | Soil 1
[client 1/chatbox] GamCity: Taxi to the city: $15.
[client 1/chatbox] GamCity: Bought 3 Planks for $12.
```

* Digging in the city is refused before your script is even asked.
* Digging turf in the block land puts soil into the bag, and the hotbar shows it.
* The window gets prices and recipes from `ready`, the taxi costs money, and buying works in the city.
* Start the server again: the bag is still there, because the script saved it. `gampeon-server` keeps changed blocks only while it runs; the game server saves them with `save`.

Run the file after every change. It takes a few seconds and needs no graphics card.

## 6. Run a game server

[Section titled “6. Run a game server”](#6-run-a-game-server)

Closed test

During the closed test, game servers run only on GAMPEON’s internal test machines. A server download for your own machine and [test servers on demand](/docs/start/status/) are planned. Until then, [ask us](/docs/start/feedback/) to run your server folder on a test server.

The game server uses the same `server-data` folder as `gampeon-server`. Players connect over UDP, so the game port (for example `7790`) must be open in the firewall. Client scripts and your web interface download to every player automatically when they join; see [Client scripts](/docs/scripting/client-scripts/).

## 7. Register the server and link it

[Section titled “7. Register the server and link it”](#7-register-the-server-and-link-it)

1. In [GAMPEON Create](https://create.gampeon.com/servers), open **Servers**, fill in **Register a server** and name it (`GamCity EU #1`).

2. Copy the server ID and the key. **The key is shown only once.**

3. On the machine that runs the server, put both into `server.cfg` and remove `set sv_requireJoinToken false`:

   server.cfg

   ```ini
   set gampeon_server_id "<id>"
   set gampeon_server_key "<key>"
   ```

   Only that copy of `server.cfg` contains the key. Never put it into Git, a marketplace upload or a chat.

4. Link the server to your project. Its players then count on the project page.

Details in [Register a server](/docs/servers/register/).

## 8. Publish the project page

[Section titled “8. Publish the project page”](#8-publish-the-project-page)

Add a tagline, an about text with at least 100 characters, screenshots and tags, then publish under **Manage**. You can turn it back into a draft at any time. See [Draft and published](/docs/getting-started/studios-and-projects/#draft-and-published).

## 9. Players join

[Section titled “9. Players join”](#9-players-join)

Players will find your server in the server browser of the GAMPEON launcher and on your project page. The launcher signs them in and gives the game a join ticket; your server checks it, so nobody can pretend to be someone else.

Planned

The launcher is in development and not available for download yet. See [Platform status](/docs/start/status/).

## 10. Your own models, maps and characters

[Section titled “10. Your own models, maps and characters”](#10-your-own-models-maps-and-characters)

Today, a game has the built-in block world, five simple [object models](/docs/scripting/objects/) and simple player figures. Your own Unreal content, for example a city, characters, weapons or cars, needs **private game packages**.

Game packages are in preview. GamCity uses one for its city:

* You build your content in your own Unreal project as a content-only plugin and cook it with the creator kit. No code: rules stay in Lua. See [Bring your own map](/docs/getting-started/your-own-map/).
* You upload the cooked package to your project. Only servers linked to that project load it, and only their players get it: the launcher downloads it when they press Play. It is never on the marketplace, cannot be downloaded in the portal, and other creators’ resources cannot use it. See [Upload your game package](/docs/getting-started/game-packages/).
* Later, your scripts use models from the package by name, for example `CreateObject('gamcity/palm_tree_01', …)`.

This is the place for assets you bought for your own game, such as store packs licensed for use in your product but not for passing on to others. Those assets never go on the marketplace or into a public repository. Read [Third-party assets](/docs/policies/third-party-assets/), and check that your license allows a game on GAMPEON: some store licenses have extra rules for platforms with user-generated content. If you are not sure, ask the seller in writing before you publish.

## What is not there yet

[Section titled “What is not there yet”](#what-is-not-there-yet)

* Your own block types with your own colors or textures.
* Vehicles and weapons in the game API.
* Models from game packages for `CreateObject`, and the check for Blueprint logic in uploaded packages.
* The launcher download, game servers on your own machine and test servers on demand.
* Payments for creators.

## Your checklist

[Section titled “Your checklist”](#your-checklist)

1. Project created as a draft.
2. Server folder with `server.cfg` and your resource.
3. Rules in server scripts, client scripts only show and ask.
4. A `test.cfg` that `gampeon-server` runs without errors.
5. Server registered, key only in the server’s `server.cfg`, join check on.
6. Server linked to the project, project page published.

# Publish to the marketplace

> Turn your resource into a marketplace item other creators can download.

Publishing makes your resource, vehicle, map or other content available to every GAMPEON creator. Everything on the marketplace is free during the preview.

## Before you start

[Section titled “Before you start”](#before-you-start)

* Everything in the upload must be yours or licensed for redistribution. Read [Allowed content](/docs/marketplace/allowed-content/) and [Third-party assets](/docs/policies/third-party-assets/).
* Pack your resource folder into a single file, for example `greeter-0.1.0.zip`.

## Steps

[Section titled “Steps”](#steps)

1. **Create the item.** In [GAMPEON Create](https://create.gampeon.com/store), open **Store items → Share an item**. Choose a unique name (`greeter`), a title, a description, the kind (`script`, `vehicle`, `map`, `prop`, `clothing`, `gamemode` or `tool`) and up to 10 tags.
2. **Add a version.** Enter the version number (`0.1.0`), select your file and read the [rights statement](/docs/marketplace/rights-statement/). Tick the box to confirm it. Without that confirmation, no upload is possible.
3. **Upload.** The portal computes a SHA-256 checksum, registers the version and uploads the file. The server checks size and checksum.
4. **Add a preview image** (PNG, JPEG or WebP). Items with an image are found more often.
5. **Link it to your project** if it belongs to one. It then appears on the project page.

The item is public as soon as one version is uploaded. Each version number can be used once; publish fixes as a new version (`0.1.1`).

## With an AI assistant

[Section titled “With an AI assistant”](#with-an-ai-assistant)

An assistant can do steps 1, 4 and 5 for you and prepare step 2 with `prepare_publish`: it checks the files, fills in the description and shows you a summary. **The rights statement is always confirmed by you in the portal.** No AI and no access token can confirm it. See [Working safely with AI](/docs/ai/safety/).

## Limits

[Section titled “Limits”](#limits)

| What                  | Limit       |
| --------------------- | ----------- |
| File size per version | 256 MB      |
| Storage per account   | 2 GB        |
| Preview image         | 2 MB        |
| New items             | 20 per hour |
| New versions          | 30 per hour |

## After publishing

[Section titled “After publishing”](#after-publishing)

Anyone can report an item that breaks the rules. If an item is blocked, you get a message with the reasons and can appeal. See [Reports and appeals](/docs/marketplace/reports/).

# Studios and projects

> How teams (studios) and games (projects) are organised on GAMPEON.

A **project** is a game or game mode you build: it has its own page with a title, tagline, genre, development stage, a gallery, links, linked servers and marketplace items. A **studio** is a team that owns projects together.

You can create projects on your own or inside a studio. Start alone; you can found a studio when other people join.

## Projects

[Section titled “Projects”](#projects)

| Field                       | Values                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Slug                        | The address of the page, for example `neon-racers`. Lowercase letters, digits and hyphens. Cannot be changed. |
| Title, tagline, description | Free text shown on the project page.                                                                          |
| Genre                       | `roleplay`, `racing`, `shooter`, `survival`, `parkour`, `sandbox`, `minigames`, `simulation` or `other`.      |
| Status                      | The development stage: `concept`, `development`, `alpha`, `beta` or `released`.                               |
| Tags                        | Up to 10 short tags, for example `drift` or `zombies`.                                                        |
| Languages                   | Up to 10 languages of the game, as ISO 639-1 codes like `en` or `de`.                                         |
| Links                       | Your website, plus a Discord invite, YouTube channel, X, Twitch, TikTok or Steam store page.                  |

What a project page shows:

* **Gallery**: up to 20 screenshots and YouTube videos, in the order you choose. Screenshots lose all metadata when you upload them.
* **Servers** you link to it, with live player counts. See [Register a server](/docs/servers/register/).
* **Marketplace items** you link to it, for example the vehicles or scripts the game uses.
* **Favorites and views**: players can add the project to their favorites; views are counted once per visitor and day.

### Draft and published

[Section titled “Draft and published”](#draft-and-published)

A new project is a **draft**: only your team sees it. Publish it in the portal under *Manage* or with `published: true`. To publish, the project needs a tagline and an about text with at least 100 characters. The checklist in *Manage* also suggests key art, three screenshots or videos, tags, languages and links. You can turn a published project back into a draft at any time.

The team (owner, or all members of the studio) sees views and new favorites per day in *Manage*.

You can create up to 20 projects of your own.

## Studios

[Section titled “Studios”](#studios)

A studio has members with one of three roles:

| Role   | Can                                                                                              |
| ------ | ------------------------------------------------------------------------------------------------ |
| Owner  | Everything, including deleting the studio and making members admins. There is exactly one owner. |
| Admin  | Edit the studio and its projects, invite and remove members.                                     |
| Member | Appear on the studio page and link their servers and items to studio projects.                   |

Limits: up to 5 studios you found, 50 members per studio, 25 open invitations, 50 projects per studio. Invitations expire if they are not accepted.

## With an AI assistant

[Section titled “With an AI assistant”](#with-an-ai-assistant)

An assistant with an access token can create and edit projects for you (`create_project`, `update_project`). It cannot delete projects or studios, change members or accept invitations. See [MCP tools](/docs/mcp/tools/).

# Bring your own map

> Build a map in your own Unreal project, keep it in a game package outside any repository, and let the GAMPEON server load it.

Your game can run on your own map: a city, an island, a race track. You build it in your own Unreal Engine project and put it into a **game package**, a content-only plugin. The GAMPEON server and the players load the map from that package. Your rules stay in Lua.

Two ways to load it

In your own editor build you can load the plugin as it is, for quick tests on your computer (steps 1 to 5 below). Players get it only as a **cooked** package that you upload to your project; see [Upload your game package](/docs/getting-started/game-packages/). During the closed test, game servers run only on GAMPEON’s internal test machines.

## What a game package is

[Section titled “What a game package is”](#what-a-game-package-is)

* A **content-only plugin** from your Unreal project: maps, meshes, materials, textures, animations, sounds. No C++ modules. GAMPEON refuses a package with code.
* Its name is its mount point. A package `GamCity` puts everything under `/GamCity/`, for example the map `/GamCity/Maps/PalmCity`.
* Images and fonts for your [web interfaces](/docs/scripting/nui/#images-and-fonts-from-your-game-package) can go into a folder `Nui` of the package, so store graphics never sit in a resource.
* It belongs to your game. Store packs you bought for your own game go here and **never** into a Git repository, the marketplace or a resource. See [Third-party assets](/docs/policies/third-party-assets/).

## 1. Make the plugin in your project

[Section titled “1. Make the plugin in your project”](#1-make-the-plugin-in-your-project)

1. Create a project with the same Unreal Engine version as GAMPEON (5.8).
2. Open **Edit → Plugins → Add**, choose **Content Only** and name it, for example `GamCity`. Names use letters, digits and `_`, start with a letter and must not be a built-in name such as `Game` or `Engine`.
3. Leave **Explicitly Loaded** off, so your own editor loads the plugin as usual.

## 2. Move your map into the plugin

[Section titled “2. Move your map into the plugin”](#2-move-your-map-into-the-plugin)

1. Move the map and everything it uses into the plugin’s content folder in the Content Browser, for example from `/Game/PalmCity` to `/GamCity/PalmCity`.
2. Right-click the old folder and choose **Fix Up Redirectors**.
3. Open the map from its new place and check the log: nothing may still point to `/Game/`. GAMPEON does not have your project’s `/Game` folder.
4. Check the materials for references to editor plugins, for example Quixel **Bridge** (`/Bridge/...`). Copy such textures into your plugin and point the material to the copy, because the game has no editor plugins.

Some content needs engine plugins, for example **Water** for an ocean. List them in your plugin under **Plugins**. If GAMPEON does not have one of them, the server log says so and those assets are missing.

## 3. Prepare the map for GAMPEON

[Section titled “3. Prepare the map for GAMPEON”](#3-prepare-the-map-for-gampeon)

* Place **Player Start** actors where players should appear. With several, players are spread over them. Without one, players appear on the ground at the point 0, 0 of the map, and your scripts can move them with [`SetEntityCoords`](/docs/scripting/reference/world/).
* The **GameMode Override** in the World Settings does not matter: GAMPEON always uses its own game mode, so joining, characters and the network work the same on every map. Clear it anyway (set it to **None**). Otherwise the server still loads the template character and its animations and writes warnings about missing input axes.
* Remove backdrop meshes far outside the playable area that you do not need, such as skylines and mountain ranges. Each one costs loading time for every player.
* Gameplay belongs in Lua. Blueprint logic in packages is not checked yet in this stage and will not pass the upload check later.

## 4. Choose the map in server.cfg

[Section titled “4. Choose the map in server.cfg”](#4-choose-the-map-in-servercfg)

server.cfg

```ini
set gp_map "/GamCity/Maps/PalmCity"
```

The server starts as usual and then switches to your map. If the map cannot be found, the server log says so and the server stays on the built-in test map.

## 5. Test it on your computer

[Section titled “5. Test it on your computer”](#5-test-it-on-your-computer)

In an editor build of GAMPEON, server and client load the plugin itself. Add the path to the plugin’s `.uplugin` file:

```plaintext
-gppackage="C:/MyGame/Plugins/GamCity/GamCity.uplugin"
```

Several packages are separated with `;`. In the log you then see `Game package GamCity … mounted at /GamCity/`. A player without the package cannot load the map; their log says to start with `-gppackage=`.

The packaged GAMPEON client and server load only cooked packages. To play with others, cook and upload the package: [Upload your game package](/docs/getting-started/game-packages/). Players then get it from the launcher when they press Play.

The first start with a new map takes longer, because the game prepares the shaders of your materials. Until then some surfaces can show a checkerboard for a moment.

## Your map and a block world

[Section titled “Your map and a block world”](#your-map-and-a-block-world)

A [block world](/docs/scripting/blocks/) also works on your own map. Put your map into a **zone**, so no blocks grow inside it, and set `groundZ` to the street level in meters. If the map has a sea or low ground inside the zone, set `floorZ` below it, so the hidden foundation of the zone does not cover the water. GamCity does this for Palm City, whose streets lie at 0 m and whose sea floor lies at about -11 m:

server.lua

```lua
EnableBlockWorld({
  seed = 20261106,
  zones = { { minX = -340, minY = -350, maxX = 280, maxY = 330, groundZ = 0, floorZ = -14, blend = 32 } },
})
```

Outside the zone the block land starts with a shore at street level. Where the block land is lower than the map’s water, the water shows as lakes. Remove backdrop meshes far outside the city, such as skylines or mountains, from your map, because the block land takes their place. Player Starts of the map still win over the spawn spots of the block world, also when a player falls out of the world.

## Not there yet

[Section titled “Not there yet”](#not-there-yet)

* The check for Blueprint logic in the upload and the encryption of the package. See [Upload your game package](/docs/getting-started/game-packages/#not-there-yet).
* Your own models for `CreateObject` from a package (`<package>/<name>`).

# Allowed content

> What you may and may not publish on the GAMPEON marketplace.

Short version: publish only what you made yourself or are clearly allowed to share, and nothing that harms others.

## Allowed

[Section titled “Allowed”](#allowed)

* Content you created yourself: code, models, textures, sounds, maps.
* Content under a license that allows redistribution, for example CC0 or CC BY (with the credits the license requires in the description).
* Content you bought or commissioned **with** the right to redistribute it to other creators.
* Code that you ported yourself from your own FiveM resources, without GTA assets.

## Not allowed

[Section titled “Not allowed”](#not-allowed)

| Content                                                                                           | Why                                                            |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Assets, maps or sounds from GTA V or any other game, including “converted” or “ripped” ones       | Copyright of the game’s publisher                              |
| Brand names, logos and car makes you have no license for                                          | Trademark rights                                               |
| Assets from stores whose license forbids sharing them, for example the Fab Standard License       | The license allows use in your own product, not redistribution |
| Other people’s resources, also leaked or “reuploaded” ones                                        | Copyright of the author                                        |
| Malware, backdoors, hidden admin commands, crypto miners, code that collects data without telling | Harms servers and players                                      |
| Code that tries to escape the sandbox or attack the platform                                      | See [Security reports](/docs/policies/security/) instead       |
| Illegal content and content that breaks the [content policy](/docs/policies/content/)             |                                                                |

If you are unsure about a license, do not upload. Ask the rights holder first. See [Third-party assets](/docs/policies/third-party-assets/).

## What happens if something is not allowed

[Section titled “What happens if something is not allowed”](#what-happens-if-something-is-not-allowed)

Anyone can [report](/docs/marketplace/reports/) an item. Moderators can block a version. Blocked versions cannot be downloaded (`451 unavailable_for_legal_reasons`). Repeated violations can lead to the account being closed.

# How the marketplace works

> Items, versions, kinds and what players and creators see.

The GAMPEON marketplace is where creators share scripts, vehicles, maps, props, clothing, game modes and tools. Everything is free during the preview. Paid items and payouts in GAMPEONS are [planned](/docs/start/status/).

## Items and versions

[Section titled “Items and versions”](#items-and-versions)

An **item** has a unique name (for example `neon-garage`), a title, a description, a kind, tags, an optional preview image and an optional link to a [project](/docs/getting-started/studios-and-projects/).

Each item has one or more **versions** (`1.0.0`, `1.0.1`, `2.0.0-beta.1`). A version is one file with a fixed SHA-256 checksum. Versions cannot be replaced: to fix something, publish a new version.

An item is listed as soon as it has at least one version that is not blocked.

| Kind       | Typical content                                       |
| ---------- | ----------------------------------------------------- |
| `script`   | Lua resources: jobs, shops, HUDs, admin tools         |
| `vehicle`  | Vehicles with their models and handling               |
| `map`      | Maps, interiors, map additions                        |
| `prop`     | Single objects and object packs                       |
| `clothing` | Clothes and accessories                               |
| `gamemode` | Complete game modes made of several resources         |
| `tool`     | Tools for creators, for example editors or generators |

## Names

[Section titled “Names”](#names)

Item names have 2 to 48 characters: lowercase letters, digits, `_` and `-`, starting with a letter or digit. The first creator to use a name owns it.

## Finding items

[Section titled “Finding items”](#finding-items)

The portal and `GET /v1/resources` search by name, title and description, and filter by kind, tag and creator. Sorting: recently updated (default), newest, name or downloads.

## Publishing

[Section titled “Publishing”](#publishing)

See [Publish to the marketplace](/docs/getting-started/publish/) for the steps and limits. Every version requires the [rights statement](/docs/marketplace/rights-statement/), confirmed by a human.

# Reports and appeals

> How to report content, how decisions are made and how to appeal.

GAMPEON follows the notice and action rules of the EU Digital Services Act (DSA).

## Report content

[Section titled “Report content”](#report-content)

Anyone can report a marketplace version, also without an account. In the portal, open **Create → Report content**, or use the API:

```http
POST https://api.gampeon.com/v1/reports
Content-Type: application/json


{
  "resource": "neon-garage",
  "version": "1.0.0",
  "category": "copyright",
  "explanation": "The car model is the ... from the game ..., see ...",
  "reporterName": "Alex Example",
  "reporterEmail": "alex@example.com",
  "goodFaith": true
}
```

| Field         | Meaning                                                                |
| ------------- | ---------------------------------------------------------------------- |
| `category`    | `copyright`, `trademark`, `illegal_content`, `malware` or `other`      |
| `explanation` | 20 to 5000 characters: what is wrong and where, as exactly as possible |
| `goodFaith`   | You confirm that your report is accurate and made in good faith        |

You get a confirmation by email. A report is not public.

## Decisions

[Section titled “Decisions”](#decisions)

A moderator reviews each report and either **blocks** the version or **rejects** the report, always with a statement of reasons. The person who reported is told the outcome. If a version is blocked, the creator gets a notification with the reasons. A blocked version is no longer listed or downloadable.

## Appeal

[Section titled “Appeal”](#appeal)

If your version was blocked, you can appeal once per decision from your dashboard (or `POST /v1/appeals`), within 20 to 5000 characters. A moderator reviews the appeal and upholds or reverses the decision, again with reasons. You are notified of the outcome.

If you still disagree, you can turn to a certified out-of-court dispute settlement body (Art. 21 DSA) or go to court.

## Copyright and trademark

[Section titled “Copyright and trademark”](#copyright-and-trademark)

Copyright and trademark claims are separate procedures. Choose the category that fits. US DMCA counter-notices only apply to copyright claims under US law, never to trademark claims. GAMPEON has not registered a DMCA agent yet. The full procedure, including what a notice should contain, is in the [Copyright, Trademark & Notice-and-Action Policy](https://gampeon.com/legal/copyright/).

## Contact

[Section titled “Contact”](#contact)

Rights holders who want to send a notice by email write to **<abuse@gampeon.com>**, the contact for reports, intellectual property and illegal content in the [Legal Notice](https://gampeon.com/legal/notice/).

# Rights statement

> The statement every creator confirms before uploading a version.

Before any version can be uploaded, the creator confirms this statement:

> I confirm that I own all rights to the content of this version or am permitted to use it, and that it contains no assets, maps or trademarks from other games. It also contains no assets from marketplaces whose license does not allow redistribution to third parties (for example, content under the Fab Standard License).

The confirmation is stored with the version, together with the exact wording and the time.

## Why

[Section titled “Why”](#why)

Marketplace content is downloaded and used by other creators. If it contains something you are not allowed to share, everyone who uses it is at risk, and so is GAMPEON. The statement makes clear who is responsible: the person who uploads.

## Only a human can confirm it

[Section titled “Only a human can confirm it”](#only-a-human-can-confirm-it)

The statement is a legal declaration. An AI assistant can prepare a release, but it cannot confirm the statement for you, and no access token has a permission for it. You confirm it yourself in the portal, after you have checked the content.

## The exact text

[Section titled “The exact text”](#the-exact-text)

The current text is always available at:

```http
GET https://api.gampeon.com/v1/legal/rights-statement
```

The API only accepts a version if `rightsConfirmed` is `true` and `rightsStatement` is exactly the current text. If the text changes, uploads with the old text are rejected (`422 rights_confirmation_required`) until the creator has read and confirmed the new one.

Note

The wording may change before GAMPEON launches publicly.

# MCP server

> The GAMPEON MCP server for AI assistants, its endpoints and how it works.

The GAMPEON MCP server lets AI assistants work with GAMPEON through the [Model Context Protocol](https://modelcontextprotocol.io). It is the tool layer behind [Build with AI](/docs/ai/connect/).

## Endpoints

[Section titled “Endpoints”](#endpoints)

| URL                                | Authentication          | Tools                                                                         |
| ---------------------------------- | ----------------------- | ----------------------------------------------------------------------------- |
| `https://api.gampeon.com/mcp/docs` | none                    | Docs, Lua API, resource templates and checks, public marketplace and projects |
| `https://api.gampeon.com/mcp`      | Bearer token (`gpat_…`) | All of the above plus account tools                                           |

Transport: Streamable HTTP. The server is stateless and supports the MCP revisions 2026-07-28, 2025-11-25 and 2025-06-18.

### Plain JSON docs search

[Section titled “Plain JSON docs search”](#plain-json-docs-search)

The GAMPEON portal searches these docs through two plain JSON endpoints on the same server. They need no sign-in and no MCP client.

| URL                                                            | Returns                                                                       |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `GET https://api.gampeon.com/mcp/search?q=<text>&limit=<1-20>` | The best matching pages, ranked like the `search_docs` tool                   |
| `GET https://api.gampeon.com/mcp/pages`                        | Every page with title, description, status and section, without the page text |

Both allow 120 requests per minute per IP. Browsers can call them only from the GAMPEON portal (CORS). For anything else, use the MCP tools or [`/llms.txt`](/docs/llms.txt).

## How it works

[Section titled “How it works”](#how-it-works)

The MCP server is a thin client of the [GAMPEON web API](/docs/api/overview/). It has no database access and no rights of its own: every call goes to the API with **your** token, and the API checks the token’s scopes. The assistant can never do more than you, and never more than the token allows.

```text
AI assistant ──MCP──▶ GAMPEON MCP server ──HTTPS + your token──▶ GAMPEON API
```

## Authentication

[Section titled “Authentication”](#authentication)

* **Access tokens** (now): create one in the portal and send it as `Authorization: Bearer gpat_…`.
* **OAuth 2.1** (planned): sign in from Claude or ChatGPT with your GAMPEON account. Uses authorization code with PKCE, Client ID Metadata Documents and protected resource metadata (RFC 9728), as the MCP specification requires.

See [Tools](/docs/mcp/tools/) for the tool list and [Security](/docs/mcp/security/) for the security model.

# Security

> How the GAMPEON MCP server protects accounts against mistakes, stolen tokens and prompt injection.

## Principles

[Section titled “Principles”](#principles)

1. **Least privilege.** Tokens carry scopes. The API enforces them on every route; routes without a scope are closed to tokens by default. The MCP server only lists the tools your token’s scopes allow.
2. **No ambient authority.** The MCP server has no database access and no rights of its own. It forwards your token to the API.
3. **Humans confirm what is final or legal.** Publishing, the rights statement, deleting, server keys and money stay in the portal.
4. **No secrets in the conversation.** Tool results never contain tokens, server keys or email addresses. Conversations are stored by AI providers, so anything in them counts as shared.
5. **Untrusted content stays data.** Text written by other users arrives inside an `<untrusted-data>` block with a fixed warning, stripped of control, invisible and direction-changing characters, and shortened. The content cannot close the block. Tool descriptions are fixed in code.
6. **No fetching of arbitrary URLs.** No tool loads a URL you or someone else provides.

## Limits

[Section titled “Limits”](#limits)

| Limit                           | Value                          |
| ------------------------------- | ------------------------------ |
| API calls per token             | 120 per minute, 2,000 per hour |
| MCP messages per token          | 300 per minute                 |
| Requests per IP without login   | 60 per minute                  |
| Request size                    | 2 MB                           |
| Files per `check_resource` call | 200 files, 1 MB in total       |

## Audit log

[Section titled “Audit log”](#audit-log)

Every API call a tool makes with your token is logged: time, token, action, result, client (`MCP` plus the name your client sends), tool and IP address. When an assistant connects, a **Connected** entry appears (at most every 10 minutes). Arguments and contents are not stored. You see the log in the portal under **Account → AI activity**. Entries are kept for 90 days.

## Tokens

[Section titled “Tokens”](#tokens)

* Format `gpat_` followed by 43 random characters. Stored only as a SHA-256 hash.
* Expire after 30 days by default, at most one year.
* At most 20 active tokens per account.
* Revoke instantly in the portal.

## Reporting a vulnerability

[Section titled “Reporting a vulnerability”](#reporting-a-vulnerability)

Email **<security@gampeon.com>**. See [Security reports](/docs/policies/security/).

# Tools

> Every tool, prompt and resource the GAMPEON MCP server offers.

## Without login

[Section titled “Without login”](#without-login)

Available on both addresses.

| Tool                   | What it does                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `search_docs`          | Full-text search in these docs. Returns titles, paths and snippets.                                                                                                                                                                                                                              |
| `read_doc`             | One docs page as Markdown.                                                                                                                                                                                                                                                                       |
| `lookup_lua_api`       | A function, event or topic from the Lua API, with an example.                                                                                                                                                                                                                                    |
| `scaffold_resource`    | New resource files from a template: `empty`, `events` (server and client talking), `gamemode` (rounds), `shop`, `job`. Every template passes `check_resource`.                                                                                                                                   |
| `check_resource`       | Checks resource files without running them: manifest and missing files, Lua block structure (a missing or extra `end`, unclosed strings), functions that do not exist in GAMPEON (GTA natives, FiveM-only functions), blocked sandbox libraries, endless loops without `Wait`, FiveM frameworks. |
| `search_marketplace`   | Search public marketplace items.                                                                                                                                                                                                                                                                 |
| `get_marketplace_item` | One marketplace item with versions.                                                                                                                                                                                                                                                              |
| `search_projects`      | Search public projects.                                                                                                                                                                                                                                                                          |
| `get_project`          | One public project with servers, items and team.                                                                                                                                                                                                                                                 |

## With login

[Section titled “With login”](#with-login)

Only on `/mcp`, and only the tools your token’s scopes allow. A token with the template **Read only** sees no tools that change anything.

| Tool                        | Scope               | What it does                                                                                                      |
| --------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `whoami`                    | `profile:read`      | Your handle, display name and studios. Never your email.                                                          |
| `list_my_projects`          | `projects:read`     | Projects you work on, with edit rights.                                                                           |
| `create_project`            | `projects:write`    | Create a project page.                                                                                            |
| `update_project`            | `projects:write`    | Change title, tagline, description, genre, status, tags.                                                          |
| `list_my_marketplace_items` | `marketplace:read`  | Your marketplace items, including blocked versions.                                                               |
| `create_marketplace_item`   | `marketplace:write` | Create a marketplace entry (not yet visible until a version is published).                                        |
| `update_marketplace_item`   | `marketplace:write` | Change title, description, kind, tags, linked project.                                                            |
| `prepare_publish`           | `marketplace:read`  | Returns a checklist, the exact rights statement and the portal link where **you** upload and confirm. Only reads. |
| `list_my_servers`           | `servers:read`      | Your registered game servers with status and players. Never their keys.                                           |

## Prompts

[Section titled “Prompts”](#prompts)

Prompts appear as commands in many clients.

| Prompt                | Use it to                                           |
| --------------------- | --------------------------------------------------- |
| `start_new_game`      | Turn an idea into a plan and a first resource.      |
| `add_feature`         | Add a feature to an existing resource, safely.      |
| `port_fivem_resource` | Check a FiveM resource and plan the port.           |
| `prepare_release`     | Check everything and prepare a marketplace release. |

## Not offered on purpose

[Section titled “Not offered on purpose”](#not-offered-on-purpose)

Deleting anything, registering servers, server keys, confirming rights, publishing versions, account and security settings, tokens, GAMPEONS and payments, moderation. See [What the AI can and cannot do](/docs/ai/safety/).

# Content policy

> What is not allowed in games, profiles, projects and marketplace items on GAMPEON.

These rules apply to everything creators publish on GAMPEON: marketplace items, project pages, studio pages, server listings and profiles. Games may have their own, stricter rules on top.

This page is a practical summary. The binding texts are the [Creator Platform Terms of Use](https://gampeon.com/legal/terms/) and the [UGC & Community Guidelines](https://gampeon.com/legal/community-guidelines/); see [Terms and legal texts](/docs/policies/legal/).

## Not allowed

[Section titled “Not allowed”](#not-allowed)

* **Illegal content**, including content that sexualises minors, promotes terrorism, or incites hatred or violence against people because of who they are.
* **Harassment**: content that targets, threatens or exposes real people, including their private data.
* **Sexual content**: pornographic content is not allowed.
* **Fraud and scams**: fake giveaways, phishing, impersonating GAMPEON or other creators, selling things you do not deliver.
* **Malicious code**: malware, backdoors, hidden commands, data collection players were not told about.
* **Content you have no rights to**: see [Allowed content](/docs/marketplace/allowed-content/) and [Third-party assets](/docs/policies/third-party-assets/).
* **Gambling with real money** or with items that can be exchanged for real money.

## Mature themes

[Section titled “Mature themes”](#mature-themes)

Violence, crime and mature themes are part of many games, including roleplay. They are allowed in games as long as they stay fiction and do not break the rules above. Describe them honestly on the project page.

## Reporting

[Section titled “Reporting”](#reporting)

Use [Reports and appeals](/docs/marketplace/reports/) for marketplace content. For anything else, write to **<abuse@gampeon.com>**.

Note

This summary and the legal texts are closed beta versions. They will be legally reviewed before GAMPEON launches publicly.

# Terms and legal texts

> The rules every GAMPEON creator agrees to, what they mean for your content, and where the full texts are.

GAMPEON’s legal texts are on [gampeon.com/legal](https://gampeon.com/legal/). English is the main version, a German version sits next to each text. This page sums up what matters most when you build on GAMPEON. If this summary and a legal text differ, the legal text applies.

| Text                                                                                    | What it covers                                                                                              | Status                                    |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| [Creator Platform Terms of Use](https://gampeon.com/legal/terms/)                       | Accounts, who is responsible for which content, your rights in your content, reports, moderation, liability | Closed beta version, accepted at sign-up  |
| [UGC & Community Guidelines](https://gampeon.com/legal/community-guidelines/)           | What you may publish, safety, age rules, scripts and downloads                                              | Closed beta version, accepted at sign-up  |
| [Copyright, Trademark & Notice-and-Action Policy](https://gampeon.com/legal/copyright/) | How to report infringing or illegal content, counter-notices, appeals                                       | Closed beta version                       |
| [Creator Monetization & Payout Terms](https://gampeon.com/legal/creator-monetization/)  | Selling for GAMPEONS and payouts                                                                            | Not in effect yet, payments are test-only |
| [Privacy Policy](https://gampeon.com/legal/privacy/)                                    | Which data GAMPEON processes and why                                                                        | Preliminary                               |
| [Legal Notice](https://gampeon.com/legal/notice/)                                       | Who runs GAMPEON, contacts                                                                                  | Preliminary                               |
| [Safety & Privacy for Users Aged 13–17](https://gampeon.com/legal/teen-safety/)         | The short version for teens                                                                                 | Closed beta version                       |

## Your content stays yours

[Section titled “Your content stays yours”](#your-content-stays-yours)

You keep the rights you own in your work. By publishing, you give GAMPEON a limited license to host, process, stream, show and promote your content **inside GAMPEON**. GAMPEON does not train generative AI models on your content without separate permission. Other players only get the rights they need to play; they may not extract, reupload or resell your assets.

## Three levels of responsibility

[Section titled “Three levels of responsibility”](#three-levels-of-responsibility)

* **Uploader:** the person who uploads an item is responsible for having all rights to it: models, textures, sounds, music, logos, scripts. See [Third-party assets](/docs/policies/third-party-assets/) and [Allowed content](/docs/marketplace/allowed-content/).
* **Project owner:** responsible for their own content and rules. Content that players upload into your game does not automatically become yours, but when you get a specific report about content you control, you must help remove or restrict it.
* **GAMPEON:** hosts content and runs the notice-and-action process. Forwarding a report to you does not end GAMPEON’s own duties.

Business creators (companies, or anyone publishing commercially) must indemnify GAMPEON for claims they caused by publishing infringing content. Players and minors acting as consumers do not.

## Age rules

[Section titled “Age rules”](#age-rules)

* GAMPEON is for people aged 13 and older.
* Under 16: stricter privacy defaults (friend requests, lists, suggestions).
* Jobs: applying from 16 (unpaid roles only), posting jobs and paid roles from 18.
* Buying GAMPEONS and payouts: 18 and older.

## GAMPEONS in short

[Section titled “GAMPEONS in short”](#gampeons-in-short)

GAMPEON is the seller of every item offered for GAMPEONS. Creators license their items to GAMPEON and receive a license fee as earned GAMPEONS. Only earned GAMPEONS can be paid out; GAMPEONS bought with money never can, and GAMPEONS cannot be transferred between users. None of this is live yet: payments run in test mode only.

## Building on the API

[Section titled “Building on the API”](#building-on-the-api)

* Your own sign-up flow must show the Terms of Use and the Community Guidelines and send `acceptTerms` with the version from `GET /v1/legal/terms`. See [Create an account](/docs/getting-started/account/).
* Access tokens can never accept terms for a person (`POST /v1/me/terms` needs a portal session).
* If your game or tool collects player data for your own purposes, you are responsible for your own privacy notice. GAMPEON’s Privacy Policy does not cover it.

# Security reports

> How to report a security problem in GAMPEON.

If you find a security problem in GAMPEON, please tell us before you tell anyone else. Write to **<security@gampeon.com>**. The same address is in [gampeon.com/.well-known/security.txt](https://gampeon.com/.well-known/security.txt).

## What helps us

[Section titled “What helps us”](#what-helps-us)

* What is affected: the API, the portal, the MCP server, the Lua sandbox, a game server or something else.
* Steps to reproduce, and what an attacker could do with it.
* Your name or handle, if you want to be credited.

## What we ask

[Section titled “What we ask”](#what-we-ask)

* Only test with your own accounts and data. Do not access, change or delete other people’s data.
* Do not run load tests or denial-of-service attacks against our servers.
* Give us reasonable time to fix the problem before you publish it.

## Especially interesting

[Section titled “Especially interesting”](#especially-interesting)

* Ways to escape the Lua sandbox or break the memory and CPU limits.
* Ways for content (marketplace items, project pages, profiles) to make an AI assistant do things the user did not ask for. See [MCP security](/docs/mcp/security/).
* Access to data or actions beyond what a token’s scopes allow.

We answer every report. There is no paid bug bounty yet.

# Third-party assets

> Using models, textures, sounds and code you did not make yourself.

Most games use some assets made by others. That is fine, as long as the license allows what you do with them. The key question is: **are you allowed to give this asset to other people?**

## Two different situations

[Section titled “Two different situations”](#two-different-situations)

| Situation                                               | Example                             | What you need                            |
| ------------------------------------------------------- | ----------------------------------- | ---------------------------------------- |
| The asset is part of your own game, players only see it | A building model in your game’s map | A license for use in your product        |
| You share the asset with other creators                 | A vehicle pack on the marketplace   | A license that allows **redistribution** |

Many store licenses allow the first but not the second. The **Fab Standard License** is the most common example: you may use Fab content in your own game, but you may not upload it to the GAMPEON marketplace, neither alone nor inside a pack.

## Always forbidden

[Section titled “Always forbidden”](#always-forbidden)

* Assets taken from GTA V or any other game, also “converted”, “ripped” or “ported” ones.
* Models of real cars, weapons or brands with their names and logos, unless you have a license from the brand owner.
* Leaked, cracked or “nulled” assets and scripts.

## Licenses that usually work for the marketplace

[Section titled “Licenses that usually work for the marketplace”](#licenses-that-usually-work-for-the-marketplace)

* **CC0** (public domain): no conditions.
* **CC BY**: allowed; name the author and the license in the item description.
* **MIT, Apache 2.0, BSD** for code: allowed; keep the license file in the upload.

Licenses with “NC” (non-commercial) or “ND” (no derivatives) can cause trouble once paid items arrive. Prefer assets without those terms.

## With AI-generated content

[Section titled “With AI-generated content”](#with-ai-generated-content)

You are responsible for AI-generated code, models, textures and sounds just like for your own work. Check the terms of the AI service you used, and do not ask an AI to recreate a protected asset from another game.

## When in doubt

[Section titled “When in doubt”](#when-in-doubt)

Do not upload. Ask the rights holder for written permission, and keep it.

# Server browser

> How players find servers, and how to read the list through the API.

The server browser in the portal lists every server that sent a heartbeat in the last 90 seconds, sorted by players online.

## Filters

[Section titled “Filters”](#filters)

* **Search** by server name.
* **Tags**, for example the genre (`roleplay`, `racing`, `shooter`, `survival`, `parkour`, `sandbox`, `minigames`, `simulation`).

## Through the API

[Section titled “Through the API”](#through-the-api)

```http
GET https://api.gampeon.com/v1/servers?q=neon&tag=racing
```

No login needed. Each entry has the name, description, owner, address and port, players, maximum players, tags, language, peak players and the linked project. `GET /v1/servers/<id>` returns a single server, also when it is offline.

The full description is in the [API reference](/docs/api/reference/).

## Getting more players

[Section titled “Getting more players”](#getting-more-players)

* Link the server to a project with a good description and image: players find games first, then servers.
* Use accurate tags and the right language.
* Keep the server online. Achievements on your profile count online time and peak players.

# Register a server

> Get a server key and send heartbeats so your server appears in the server browser.

A registered server appears in the GAMPEON server browser while it sends heartbeats. Registration only lists your server; it does not host it.

## 1. Create the server entry

[Section titled “1. Create the server entry”](#1-create-the-server-entry)

In [GAMPEON Create](https://create.gampeon.com/servers), open **Servers**, fill in **Register a server** and enter a name (3 to 64 characters). Or use the API:

```http
POST https://api.gampeon.com/v1/servers
Authorization: Bearer <session token>
Content-Type: application/json


{ "name": "Neon Racers EU #1" }
```

The answer contains the server `id` and a `serverKey`. **The key is shown only once.** Store it in your server’s configuration, never in a Git repository or a marketplace upload.

You can register up to 10 servers per account.

## 2. Send heartbeats

[Section titled “2. Send heartbeats”](#2-send-heartbeats)

Every 30 seconds, your server sends its state:

```http
POST https://api.gampeon.com/v1/servers/<id>/heartbeat
X-Server-Key: <serverKey>
Content-Type: application/json


{
  "port": 7790,
  "players": 12,
  "maxPlayers": 64,
  "tags": ["racing", "drift"],
  "language": "en"
}
```

| Field        | Required | Meaning                                                                                               |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `port`       | yes      | Game port, 1 to 65535.                                                                                |
| `players`    | yes      | Players online now, at most `maxPlayers`.                                                             |
| `maxPlayers` | yes      | 1 to 2048.                                                                                            |
| `address`    | no       | Host name or IP. Defaults to the address the heartbeat came from.                                     |
| `tags`       | no       | Up to 10 tags, used as filters in the browser. Use genres such as `roleplay`, `racing` or `survival`. |
| `language`   | no       | Language code such as `en` or `de-DE`.                                                                |

The answer says when to send the next heartbeat (`nextHeartbeatInMs`). A server without a heartbeat for 90 seconds is shown as offline and disappears from the list.

## With the GAMPEON game server

[Section titled “With the GAMPEON game server”](#with-the-gampeon-game-server)

The GAMPEON game server (and `gampeon-server`) sends heartbeats and checks players’ join tickets by itself. Put the ID and key into `server.cfg`:

server.cfg

```ini
set gampeon_server_id "<id>"
set gampeon_server_key "<serverKey>"
sets tags "roleplay, economy"
sets locale "en-US"
sv_maxclients 64
```

* The game server sends `port` and `maxPlayers` itself. `sv_maxclients` lowers `maxPlayers` if it is smaller than the game’s limit.
* `tags` and `locale` become the tags and the language in the server browser.
* Set `sv_publicAddress` if players should connect to another host name than the one the heartbeat comes from.
* Scripts can neither read nor change `gampeon_server_id`, `gampeon_server_key` or `gampeon_api`. The key is only sent over HTTPS.

Players who join get checked with `POST /v1/servers/<id>/join/verify`, see [Players](/docs/scripting/players/#join-check).

## 3. Describe and link it

[Section titled “3. Describe and link it”](#3-describe-and-link-it)

In the portal or with `PATCH /v1/servers/<id>` you can add a description, a website (`https://` only) and link the server to one of your [projects](/docs/getting-started/studios-and-projects/). Linked servers add their players to the project page.

## Lost key

[Section titled “Lost key”](#lost-key)

Delete the server entry and create a new one. Keys cannot be shown again, because GAMPEON only stores a hash of them.

# Changelog

> Recent changes to the platform, the SDK, the engine and these docs.

The newest changes for creators and developers. The full changelog for all of GAMPEON, with an Atom feed, is at [gampeon.com/changelog](https://gampeon.com/changelog/).

## 2026-11-07

* **Improved** · Docs: The developer docs now look like the rest of gampeon.com, with the same menu, footer, fonts and colours.

## 2026-11-06

* **New** · Docs: Guide for creators to cook, upload and play their own game package.
* **New** · Platform: Creators can upload private game packages (cooked maps, models and UI art) to their project. Only players of the project's servers get them, through the launcher.
* **New** · Docs: Web interfaces can load images and fonts from your game package, so licensed UI art stays in your private package instead of your resources.
* **New** · Engine: Web interfaces can load images and fonts from your game package (\`https\://gampeon-pkg-\<package>/\<path>\`), so licensed UI art stays in your private package instead of your resources.
* **Fixed** · Engine: Clients started with \`-RenderOffscreen\` no longer show a black web page over the game.
* **New** · Engine: Your first quest, "Supply Run": search three supply crates, then bring the supplies back to the plaza center. Your objectives show at the top right, and the compass points you back.
* **New** · Docs: Guide "Bring your own map": load a map from your own content-only plugin on a local test server.
* **New** · SDK & scripting: Block world zones take an optional floorZ, so a city on your own map keeps its water and low ground visible.
* **Fixed** · Docs: The block world reference now shows how to place a character on top of a block instead of half inside it.
* **Fixed** · SDK & scripting: The GetBlockSurfaceZ example now places characters on top of the block instead of half inside it.
* **New** · Engine: Block worlds for creators: one EnableBlockWorld call in a server script gives your game terrain made of blocks that players dig and build in, with mouse controls and a hotbar.
* **New** · Engine: Lua functions for block worlds: GetBlock, SetBlock, GetBlockSurfaceZ, SetBlockHotbar and more, plus the events blockBreak, blockPlace, blockChanged and blockHotbarSelect.
* **New** · Docs: Block worlds for creators: switch on terrain that players dig and build in with one Lua call, and decide in your scripts what they get and may place (preview).
* **New** · Docs: Guide "Make your game, step by step", covering the whole way from project to players.
* **New** · SDK & scripting: Block worlds for creators: switch them on with EnableBlockWorld, read and change blocks with GetBlock and SetBlock, and decide in blockBreak and blockPlace what players may dig and build.
* **New** · SDK & scripting: gampeon-server runs block worlds too, with gp_fakeplayer break, place and slot for tests.
* **New** · Engine: A compass at the top of the screen shows the cardinal directions and nearby supply crates that still hold loot.
* **New** · Engine: Supply crates now hold loot. Search a crate with E to put its items into your inventory, and press Tab to see what you carry.
* **New** · Engine: Hold E to use objects. The sandbox test now has supply crates you can open and close, and everyone nearby sees it.
* **Fixed** · Engine: Other players no longer appear in the wrong place in the game client.
* **Improved** · Engine: The test world is easier to read: shadowed sides are no longer black, boxes and walls have colors, and other players have a light body with a red visor that shows where they look.
* **New** · Platform: Voice channels in communities: join with one click, talk and share your screen or a window with sound (launcher, 16 and older during the test)
* **New** · Platform: Moderators can mute members in voice and disconnect them, and anyone can report a person in a voice channel to GAMPEON.
* **Improved** · Engine: Mouse look is calmer by default. The sensitivity can still be changed with \`gp.MouseSensitivity\` in the console.
* **Improved** · Docs: The RP Starter docs now say it is MIT licensed.
* **Improved** · SDK & scripting: The GAMPEON RP Starter is now MIT licensed, so server owners can change it and ship it with their servers.
* **New** · Engine: In the game, scripts can use \`GetEntityForwardVector\`, \`GetEntityForwardX\` and \`GetEntityForwardY\` on server and client.
* **Improved** · Docs: The Lua reference documents \`GetEntityForwardVector\`, \`GetEntityForwardX\` and \`GetEntityForwardY\`, and explains that headings match the rotation in the Unreal editor.
* **New** · SDK & scripting: \`GetEntityForwardVector\`, \`GetEntityForwardX\` and \`GetEntityForwardY\` on server and client. Use them for "in front of the player" math; GAMPEON headings stay measured like the rotation in the Unreal editor (0 faces +x, 90 faces +y).
* **Improved** · Docs: The porting check docs explain the new list of framework calls that the RP Starter bridges do not cover yet.
* **Improved** · Docs: The platform status page lists the playable game client as a preview.
* **Improved** · SDK & scripting: The porting check now lists which framework calls in your resources the RP Starter bridges already cover, and which ones are still missing.
* **Fixed** · SDK & scripting: The RP Starter HUD no longer repeats the job name when the rank has the same name.
* **New** · Engine: The game client is now playable: walk with WASD, look around with the mouse and jump with Space.
* **New** · Engine: Maps without their own lighting get a sun and sky, so the test world is no longer black.
* **New** · Engine: Players see each other as simple figures until real character models arrive.
* **New** · Docs: New developer docs page RP Starter: a ready roleplay base with characters, money, jobs and inventory, plus bridges for existing roleplay resources.
* **Improved** · Docs: The Exports page explains objects with methods, callbacks and waiting inside exports.
* **Improved** · Docs: The test server page documents \`gp_fakeplayer waitclient\`, which waits for a test client's scripts instead of a fixed time.