> For the complete documentation index, see [llms.txt](https://squirrel-bracket.gitbook.io/squirrel-bracket-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://squirrel-bracket.gitbook.io/squirrel-bracket-documentation/map-editor/readme.md).

# Introduction

## Description

`sb-map-editor` is a FiveM map editing resource built for fast in-game placement and management of world objects.

It combines a freecam editing workflow, a React-based NUI, zone-restricted placement, and project persistence so you can build maps directly in-game instead of constantly exporting coordinates by hand.

The resource is designed to work on standalone, ESX, or QBCore servers, with automatic framework and database detection where possible.

## Features

* In-game freecam editor opened with `/mapeditor` by default.
* Project-based workflow for grouping entities into reusable maps.
* Zone system with polygon points, `minZ` / `maxZ`, allow lists, and blacklist zones.
* Auto-spawn support for map projects on resource start.
* Optional database persistence with automatic fallback to JSON files.
* Permission-aware editing limits for camera distance, object distance, and zone/project actions.
* React + Vite NUI with live locale loading and a full object placement interface.
* Config hook API for extending notifications, permission checks, project events, zone events, and client-side editor actions without editing core logic.

## How to use

### Opening the editor

Use the configured editor command, `/mapeditor` by default, in-game to toggle the editor UI.

When the editor is open you can:

* Create a new project.
* Add objects from the model list defined in `configs/config.lua`.
* Move, rotate, and ground-place selected entities.
* Save a project for later use.
* Spawn or despawn saved map projects.

### Projects

Projects are the main container for placed entities.

* A project stores entity transforms, folders, description metadata, timestamps, creator information, and optional zone assignment.
* `autoSpawn` projects are loaded automatically when the resource starts.
* Saving includes conflict protection so an outdated client is warned before overwriting newer project data.

### Zones

Zones let you control where editing is allowed and who can use a zone.

* Zones are built from polygon points.
* `minZ` and `maxZ` define the vertical bounds.
* Access entries can target everyone, individual player identifiers, or configured groups.
* Blacklist zones prevent object placement or movement inside them.
* Projects can be linked to zones so entities must stay inside the assigned area.

### Extending the resource

Customization is intended to happen through the handler functions in `configs/server_config.lua` and `configs/client_config.lua`.

These handlers are:

* Empty by default.
* Optional to implement.
* Safe to leave unchanged.
* Type-annotated for easier editing in IDEs.

For the full list, see [⚙️ API](/squirrel-bracket-documentation/map-editor/api.md).