FiveMPublished on February 6, 20265 min read

How to add a mapping to your FiveM server: the complete guide

A FiveM mapping adds buildings, interiors, props or whole areas to the GTA V map. This guide explains what a mapping is, how it is structured and how to install it on your FiveM server with OuiPanel, the OuiHeberg game panel. It also covers MLO interiors and the most common errors, so your FiveM mapping loads the first time.


What exactly is a mapping?

A mapping (or map) changes the GTA V environment to add things to the game world. It can be several things.

  • Buildings and outdoor structures.

  • Enterable interiors, called MLOs.

  • Furniture and decoration props.

  • Terrain changes.

  • Entirely new areas.

A mapping works like any other FiveM resource. You put it in the resources folder, declare it in server.cfg, and the server loads it on startup.


Structure of a mapping

A well-organized mapping always follows the same folder tree.

mapping-name/
├── fxmanifest.lua
├── stream/
│   ├── file1.ymap
│   ├── file2.ytyp
│   └── file3.ybn
└── data/ (optional)
    └── file.meta

The main files

The fxmanifest.lua file is required. It tells FiveM how to load the resource.

The stream/ folder holds the mapping files themselves.

  • .ymap sets the position and placement of objects.

  • .ytyp defines the object types.

  • .ybn handles collisions, so players do not walk through objects.

  • .ytd holds textures, if the mapping uses custom ones.

The optional data/ folder holds .meta files for extra settings.


Create a fxmanifest.lua if the mapping does not have one

Some downloaded mappings come without a manifest. Without it, FiveM cannot load the resource. Here is how to create one.

Basic manifest

If the mapping only has a stream/ folder with .ymap, .ytyp and .ybn files, use this manifest.

fx_version 'cerulean'
game 'gta5'

author 'YourName'
description 'Mapping description'
version '1.0.0'

this_is_a_map 'yes'

The this_is_a_map 'yes' line is essential. It tells FiveM that the resource is a mapping, and that it must load the files in the stream/ folder on its own.

Manifest with data files

If the mapping also has a data/ folder with .meta or .ytyp files, add the matching declarations.

fx_version 'cerulean'
game 'gta5'

author 'YourName'
description 'Mapping description'
version '1.0.0'

this_is_a_map 'yes'

files {
    'data/*.meta'
}

data_file 'DLC_ITYP_REQUEST' 'data/*.ytyp'

Manifest for an MLO (interior)

MLOs are more complex interior mappings. Their structure looks like this.

mlo-interior/
├── fxmanifest.lua
└── stream/
    ├── interior.ymap
    ├── interior.ytyp
    ├── interior_shell.ybn
    └── textures.ytd

And here is the matching manifest.

fx_version 'cerulean'
game 'gta5'

this_is_a_map 'yes'

files {
    'stream/*.ytyp'
}

data_file 'DLC_ITYP_REQUEST' 'stream/*.ytyp'

Some MLOs need extra scripts to set entry and exit points. Read the documentation of the mapping you install.


Installing the mapping on your server

Upload the mapping folder

  1. In OuiPanel, open your FiveM server, then click File Manager in the side menu.

  2. Open the resources folder.

  3. If you have several mappings, click Create folder and name it [mappings]. Open it.

  4. On your computer, compress the mapping folder into a .zip. Drag the file onto the page. When the "Drop your files here" overlay shows up, release it.

  5. Click the three dots on the file's row, then Decompress. Then delete the .zip.

Check that the extracted folder directly contains fxmanifest.lua and stream/, with no extra folder in between. Uploads are limited to 100 MB per file. Above that, use SFTP as shown in the guide How to connect via SFTP with FileZilla.

resources folder in the File Manager with the Create folder button

Declare the mapping in server.cfg

Open server.cfg in the server root, add an ensure line for the mapping, then click Save.

ensure mapping-name

With several mappings, add one line per mapping.

# Mappings
ensure mapping-police-station
ensure mapping-hospital
ensure mapping-garage

Editing server.cfg window with the ensure lines of the resources

For mappings, always use ensure rather than start. It is the most reliable command for this kind of resource.

Respect the load order

The order of resources in server.cfg can matter. As a rule, load mappings after the framework and before the job scripts that use them.

# Framework
ensure es_extended
ensure esx_skin

# Mappings
ensure mapping-police-station
ensure mapping-hospital

# Job scripts
ensure esx_policejob
ensure esx_ambulancejob

Restart the server

In the Console, click Restart to load the mappings. Then read the startup lines. If all goes well, no error mentions your mappings.


Check that the mapping works

Join the game and go to the mapping coordinates. Most creators give them in the description or in a readme file.

If you do not have the coordinates, look for them in the mapping's .ymap files, or use a teleport command if you have an admin menu.


Troubleshooting common issues

The mapping does not show

  • Check that fxmanifest.lua exists and contains this_is_a_map 'yes'.

  • Check that the ensure line is in server.cfg.

  • Look for loading errors in the Console.

  • Make sure you are at the right coordinates in game.

Collisions do not work

If players walk through objects, the .ybn file is probably missing or misnamed. Check that it matches the mapping.

Error on server startup

  • Read the error message in the Console.

  • Check the syntax of fxmanifest.lua.

  • Make sure every referenced file exists.

An updated mapping keeps its old version

The server caches the files it sends to players. In FiveM Configuration, click Delete cache, confirm, then restart the server.

The mapping causes lag

Very detailed mappings can weigh on performance. A few ideas.

  • Lower the draw distance in the mapping settings, if it has one.

  • Do not stack too many mappings in the same area.

  • Prefer optimized mappings tested by the community.


Best practices

Organize your mappings

Group your mappings in a [mappings] folder inside resources. It makes management and upkeep easier.

resources/
├── [mappings]/
│   ├── mapping-police-station/
│   ├── mapping-hospital/
│   └── mapping-garage/
├── [esx]/
└── ...

Test before going live

Test each new mapping on a test server before adding it to your main server. It saves you bad surprises in front of your players.

Back up before each addition

Before you add or change a mapping, create a backup. In the side menu, click Backups, then Create backup.

Backups page with the Create backup button and a successful backup


Need help?

Open a ticket from Tickets › Open a Ticket, or from the Contact support tile at the bottom of your server's page in the client area. You can also ask your question on the OuiHeberg Discord.

Was this article helpful?

2,289 views
Share this article
FiveM
Need a GTA/FiveM server?

Discover our GTA V / FiveM hosting plans starting from $3.46/month, with your server ready in 60 seconds.

View plans →
FiveM
Need a GTA/FiveM server?

Discover our GTA V / FiveM hosting plans starting from $3.46/month, with your server ready in 60 seconds.

View plans →

Related Articles