# 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).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://squirrel-bracket.gitbook.io/squirrel-bracket-documentation/map-editor/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.