FX-3DMAP

A live 3D world map for RedM, with every blip on your server managed from one place.

Version: 1.0 · Game: RedM (RDR3) · Frameworks: VORP, RSG, Standalone · Requires: oxmysql

---

#Table of Contents

1. What Is FX-3DMAP?
2. Requirements
3. Installation
4. Giving Your Staff Permission
5. First Start: The Setup Wizard
6. Using the Map (Players)
7. Blip Manager (Staff)
8. Areas and Glow Circles (Staff)
9. Staff Tools
10. Configuration — config.lua
11. Places, Categories and Colours — config_locations.lua
12. Icon Library — config_icons.lua
13. Languages — locales.lua
14. Frameworks — frameworks.lua
15. Your Own Hooks — c/opensource.lua
16. Exports and Events (Developers)
17. Database
18. Updating
19. Troubleshooting and FAQ
20. Support

---

#1. What Is FX-3DMAP?

FX-3DMAP replaces the flat paper map with the real game world. When a player presses the map key, the camera rises from their character into the sky and the whole map opens up beneath them, live. They can fly over towns, roads and rivers, search for places, set a route and drop their own pins.

For server owners, FX-3DMAP is also the one place every blip on your server comes from. Instead of hunting through dozens of config files to change one icon, you add, move, recolour and remove blips from inside the game. Every player sees the change at once.

In short:

• Players get a 3D map with search, categories, favourites, routes and personal pins.
• Staff get a Blip Manager, an area drawing tool and teleport tools, all inside the map.
• Server owners get a Setup Wizard that brings in all existing blips from other scripts in one click.

---

#2. Requirements

---

#3. Installation

Step 1 — Download. After purchase, open portal.cfx.re → Granted Assets and download fx-3dmap-redm.

Step 2 — Put it in your resources. Place the fx-3dmap-redm folder inside your server's resources folder. Do not rename the folder.

Step 3 — Start order. In server.cfg, start it after oxmysql and your framework:

cfgensure oxmysql
ensure vorp_core        # or rsg-core (leave out on a standalone server)
ensure fx-3dmap-redm

⚠️ If FX-3DMAP starts before your framework, it cannot see it. The server console will tell you so. Just fix the order.

Step 4 — Database. Nothing to do. The two tables are created automatically on the first start.

If your database user is not allowed to create tables, run setup/sql/install.sql once by hand (see Database).

Step 5 — OneSync. Turn OneSync on (txAdmin → Settings → OneSync). This is only needed for "nearby only" areas; everything else works without it.

Step 6 — Permissions. Give your staff the editor permission (see the next section).

Step 7 — Restart the server. In game, press the map key (M) or type /3dmap.

When the server starts you will see the detected framework in the console and in every player's F8:

[fx-3dmap-redm] Framework: VORP

---

#4. Giving Your Staff Permission

Normal players only use the map. The Blip Manager, area drawing and teleport tools are for staff only. Players never see these buttons.

A player is staff if any of these is true:

With fx-adminpanel, permissions are split into three:

To turn this off and use the framework/ACE rules instead, set Config.Editor.adminpanel = false in config.lua.

💡 The ACE list lives in Config.AdminAces in config.lua. By default it includes command, which the default admin group in server.cfg has. If your moderators also have command, remove that line, or they will be able to edit blips too.

---

#5. First Start: The Setup Wizard

FX-3DMAP ships empty. Every server has its own places, so the map does not come with a fixed list. The Setup Wizard finds the blips your other scripts already draw and brings them in for you.

#How to use it

1. Open the map and click Blip manager in the top bar.
2. On an empty map, the Setup wizard opens by itself. (You can open it any time from the Blip Manager.)
3. Press Find my blips. The wizard:
• reads the config files of your running resources,
• finds every blip they define, with its name, icon and position,
• checks which of them are on the map right now,
• lists them by resource.
• Blips that are on the map right now are ticked for you.
• Click a resource's header to tick or untick all of its blips.
• Use Select all or Select none for everything.
• Press Add selected. Every player gets them at once.
• The wizard then shows exactly which file and line each original blip is switched on in. Turn those blips off in their own scripts. From then on, every blip comes from FX-3DMAP and nothing shows twice.

#Labels you may see in the list

#Good to know

• Encrypted (escrowed) files cannot be read. Their blips appear under Other blips with position only.
• Places added by the wizard are normal places. You can edit or delete them like any other.
• The map holds up to 1000 places. If you hit the limit, the wizard tells you how many could not be added.

---

#6. Using the Map (Players)

#Opening and closing

• Press the map key (M), or open Map from the pause menu. The 3D map opens instead of the game map.
• You can also type /3dmap.
• To close, press M again or click Close.
• Game map in the top bar opens the game's own map for one look. The next time you press M, the 3D map is back.

The map cannot open while you are dead, or while riding or driving fast. Your server may also require a map item (see Map item).

#Controls

Mouse and keyboard work at the same time: you can hold W and turn with the mouse.

The buttons on the side do the same: Zoom in, Zoom out, Face north and My location.

#Finding places

• Search places: type a name and pick a result. The camera flies there.
• Categories: browse places by type. The eye button shows or hides a category on both maps.
• Favorites: select a place and press the star.
• Recent: places you selected lately.
• Regions: the list under the map title. Pick a town and the camera flies there.

Each place has a card with its name, distance, note and opening hours.

#Towns

From far away, all the places in a town stand as one town marker with a count. Fly closer, or click it, and it opens up into its shops and services. No more piles of icons on top of each other.

#Your card and your horse

• You: your marker on the map. Your card shows your name, job, town, district and coordinates.
• Your horse: your horse is shown on the map with its live distance.

#Routes

• Double click a place or any spot on the ground, or press Route here on a place's card.
• A red route appears, just like the game's own waypoint.
• A distance bar at the bottom shows how far it is, live. Click it to fly to the destination; click again to fly back.
• When the map is closed, a marker stays in the world at the destination with its distance.
• The route clears itself when you arrive. To remove it earlier, press Clear route, or double click / right click on its end.
• Fly to the waypoint: if you set a waypoint on the game map, this button takes the camera there.

#Personal pins

1. Right click the ground and choose Put a pin.
2. Give it a name, pick an icon and a colour, and press Save.
3. Your pins are under My pins. You can route to them, edit them or delete them.

Pins are saved to your character in the database, so they are still there after a restart. Each character can have up to 30 pins (server owners can change this).

#While the map is open

Your character stays where it stands and the world goes on around it.

• Real damage (being shot, falling, being trampled) closes the map.
• Being moved far on foot closes the map.
• People, horses and wagons far from your character are hidden, so the map cannot be used to spy on others.
• You still hear the voices around your character. Players on your radio or phone call are left to your voice script.
• The sky is shown clear while the map is open (only on your screen).

---

#7. Blip Manager (Staff)

Click Blip manager in the top bar. Everything you change here is saved to the database and reaches every player at once.

#Adding a blip

1. Blip manager → New, then click the spot on the map. (Or right click the ground → Put a blip here, or use Where I stand.)
2. Fill in the form:

1. Press Add.

#Editing, moving and deleting

• Click a place, then Edit.
• Pick on map moves it to a new spot.
• Delete asks once: press again to confirm.
• The Places list shows everything, split into Added by admins, From the config and On the game map.

#Categories

In the Blip Manager you can also create and edit categories: name, icon, colour, and Open by default (shown when a player joins). Players can still hide any category with the eye button.

#Discover (Find game blips)

The Discover layer shows blips that other scripts draw on the game map right now. Click one to take it into FX-3DMAP. This is handy for blips the Setup Wizard could not read.

#If two admins edit at the same time

If another admin changed the catalog while you were editing, you will see:

"Another admin changed the catalog. Look again, then save."

Nothing is lost. Look at the updated list and save again.

---

#8. Areas and Glow Circles (Staff)

#Drawing an area

1. Blip manager → Areas → Draw an area, or right click the ground → Draw an area here.
2. Pick a shape:

While drawing: Z = undo the last point, Enter = finish.

1. Set the details: name, colour, an optional icon in the middle, and Who sees it.
2. Press Save. Use Redraw later to change the shape.

#Who sees it

Areas show on the 3D map, the pause map and the compass. When a player walks into an area, the compass opens wide until they leave (can be turned off, see Areas settings).

#Glow circles

Any blip can have a coloured circle around it. In the blip form, turn on Circle around it, press Draw and click where the circle should end. Circle seen by works the same as for areas: everyone, or only those nearby.

---

#9. Staff Tools

• Go there (teleport): teleport to any spot on the map, or to the end of a route. If there is no ground under the spot, you are left above it safely.
• Discover / Find game blips: shows every blip other scripts draw, so you can take them in.

With fx-adminpanel, teleport needs the tpmarker permission.

---

#10. Configuration — config.lua

All settings are in config.lua. Each setting has a comment next to it. Below is every setting in plain words.

#General

luaConfig.Language = "en"   -- "en" or "tr"

The language of the map. Missing texts fall back to English.

#Commands

luaConfig.Commands = {
  map = "3dmap",
}

The chat command that opens and closes the map.

#Game map

luaConfig.ReplaceGameMap = true

• true: the map key and the pause menu's Map open the 3D map.
• false: the game map stays as it is; the 3D map only opens with the command or an export.

#Camera

luaConfig.Camera = {
  distance      = 220.0,  -- height when the map opens
  minDistance   = 45.0,   -- closest zoom
  maxDistance   = 900.0,  -- furthest zoom
  pitch         = 55.0,   -- tilt when the map opens (90 = straight down)
  minPitch      = 20.0,
  maxPitch      = 85.0,
  fov           = 50.0,
  transition    = 800,    -- ms to fly in and out
  focusDistance = 160.0,  -- height when a place is selected
  focusPitch    = 40.0,   -- tilt when a place is selected
  fadeBeyond    = 350.0,  -- closing further than this from your character fades the screen
}

Heights are in metres above the ground. fadeBeyond: when you close the map far away from your character, the screen fades briefly while the ground loads, instead of flying back over empty land.

The furthest zoom is limited on purpose. RedM cannot load full detail from very high up, so the camera stops where the world still looks whole.

#Markers

luaConfig.Markers = {
  limit  = 120,     -- most markers on screen at once
  town   = 450.0,   -- a town opens into its places closer than this (metres)
  range  = 1500.0,  -- places further than this from the view appear as you fly closer
  labels = 300.0,   -- names show closer than this; further out only icons
}

#Blip Manager

luaConfig.Editor = {
  enabled    = true,       -- false turns the Blip Manager off
  adminpanel = true,       -- use fx-adminpanel ranks when it is running
  scanMax    = 8000,       -- how many game blips "Discover" looks through
  category   = "markers",  -- default category for new places
}

#Areas

luaConfig.Zones = {
  expandRadar = true,                    -- open the compass wide inside an area
  radarConfig = "RADAR_CONFIG_CARAVAN",  -- the game's "wide" radar preset
  radarZoom   = nil,                     -- or a fixed radar zoom number
}

Set expandRadar = false if another script on your server controls the compass.

#Pins

luaConfig.Pins = {
  enabled = true,
  max     = 30,          -- pins per character
  color   = "default",   -- the default pin colour (a Config.Colors key)
  icons   = { "blip_poi", "blip_proc_home", ... },  -- icons players may choose from
}

The first icon in icons is the default. Icon names are the file names in ui/assets/blips.

#Route

luaConfig.Gps = {
  arrive    = 20.0,         -- metres from the target that count as "arrived"
  color     = "COLOR_RED",  -- route line colour (game colour name)
  blipColor = "red",        -- colour of the route's end on the game map
  worldPin  = true,         -- show a marker in the world while the map is closed
}

#Game map blips

luaConfig.GameBlips = true

• true: places are also drawn as blips on the game map and compass.
• false: places only show on the 3D map.

The game's blip font cannot draw some Turkish letters (ı, ş, ğ). On the game map these are written plain; the 3D map shows them correctly.

#While the map is open

luaConfig.Behavior = {
  maxMountSpeed   = 1.5,   -- riding faster than this (m/s) blocks opening
  closeOnDamage   = true,  -- real damage closes the map
  damageThreshold = 10,    -- a health drop this big also counts as damage
  closeOnMovement = 40.0,  -- metres your character may be moved on foot (0 = never)
  visibleDistance = 30.0,  -- people/horses/wagons further than this are hidden
  hearDistance    = 30.0,  -- voices around your character you still hear (0 = game default)
  clearWeather    = true,  -- clear sky on your screen while the map is open
}

#Map item

luaConfig.MapItem = {
  enabled = false,  -- true: the map needs an item
  item    = "map",  -- item name in the inventory
  label   = "Map",  -- name shown in the message
  amount  = 1,      -- how many are needed
}

When enabled, players without the item see "You need Map x1." With ReplaceGameMap = true, they cannot open the game map either. (On a standalone server there is no inventory, so this rule does not apply.)

#Permission

luaConfig.AcePermission = "fx3dmap.editor"
Config.AdminAces = {
  "fx3dmap.editor",
  "txAdmin.login",
  "command",
}

Anyone with any of these ACE permissions is staff. See section 4.

#Server requests

luaConfig.RateLimit = {
  requests = 25,  -- requests allowed per window
  seconds  = 10,  -- window length
}

Protects the server from spam. Past the limit, the player sees "Too many requests. Wait a moment."

#Developer mode

luaConfig.DevMode = false

true prints what the map is doing to the F8 console. Leave it off on a live server.

---

#11. Places, Categories and Colours — config_locations.lua

You can manage everything from the Blip Manager in game. This file is for those who prefer to write places by hand.

#Colours — Config.Colors

Each colour has two values: the hex colour the 3D map uses, and the game's own colour for the game map. Available keys:

default, blue, red, orange, pink, green, teal, navy, maroon, grey, lime, forest, sky, purple, gold, tan, white

#Categories — Config.Categories

lua{ id = "banks", label = { en = "Banks", tr = "Bankalar" },
  sprite = "blip_proc_bank", color = "green", open = true, blips = true },

Built-in categories: markers, general_stores, banks, post_offices, gunsmiths, clothing, barbers, horse_supplies, saloons, doctors, shops, pet_shops, fishing, lumber, mining, crafting, stashes, black_market, guarma_travel, identity, moonshine, water_depots.

#Places — Config.Locations

luaConfig.Locations = {
  { id = "valentine_bank", label = "Valentine Bank", category = "banks",
    coords = vector3(-308.02, 773.82, 116.7), sprite = "blip_proc_bank" },
}

#Regions — Config.Regions

The list under the map title. Pick one and the camera flies there. Add your own towns freely:

lua{ id = "valentine", label = "Valentine", coords = vector3(-281.02, 790.56, 118.71) },

#Town and district names — Config.Towns / Config.Districts

The map title follows the town or district under the camera, and the player's card shows where they stand. These lists turn the game's zone numbers into names. You can rename them freely.

---

#12. Icon Library — config_icons.lua

This file decides how the icon picker in the Blip Manager is grouped. The most useful icons come first, in groups, each with a readable name:

• General (point, objective, home, camp, job…)
• Shops and services (store, doctor, gunsmith, stable, saloon, bank…)
• Law and trouble (sheriff, bounty hunter, gang, hideout…)
• Activities and nature (hunting, fishing, poker, plant, chest…)

Every other game icon is still available under All icons. To add your own to a group:

lua{ sprite = "blip_shop_horse", label = { en = "Horse shop", tr = "At dukkani" } },

Icon names are the file names in ui/assets/blips (without .png).

---

#13. Languages — locales.lua

Every text the player sees is in locales.lua. English and Turkish are included.

• Choose the language with Config.Language in config.lua.
• To add a language, copy the whole en = { ... } block, rename it (for example de = { ... }), translate the texts and set Config.Language = "de".
• A missing text falls back to English, so nothing ever shows a raw key name.
• Keep ${...} parts as they are. They are filled in by the script (for example ${item}, ${amount}, ${n}).

Turkish texts are written without special letters (ı, ş, ğ) because the game's map font cannot draw them.

Server console messages stay in English so the owner can always read them.

---

#14. Frameworks — frameworks.lua

FX-3DMAP detects VORP and RSG automatically. Without either, it runs standalone.

#Adding another framework

A ready template is at the bottom of frameworks.lua:

1. Detection: add your core to the detection part:

lua   elseif GetResourceState('my-core') == 'started' then
       Framework = "MYFX"

1. Server functions: add a block for your framework with FX.IsAdminAllowed, FX.GetCharacterId, FX.GetProfile and FX.GetItemCount, following the VORP and RSG blocks.
2. Restart the resource.

---

#15. Your Own Hooks — c/opensource.lua

This file is open so you can connect the map to the rest of your server.

#Map.CanOpen

Return false to stop the map from opening, for example in a cutscene, in jail or during a job. It runs on top of the map's own checks.

luafunction Map.CanOpen()
    if LocalPlayer.state.inJail then return false end
    return true
end

#Map.OnVisibility

Called when the map opens (true) and closes (false). Use it to hide your HUD. fx-hud is already handled.

luafunction Map.OnVisibility(visible)
    if visible then
        exports["my-hud"]:Hide()
    else
        exports["my-hud"]:Show()
    end
    TriggerEvent("fx-3dmap-redm:visibility", visible)  -- keep this line
end

---

#16. Exports and Events (Developers)

All exports are client-side. The resource name is fx-3dmap-redm.

#Open

Opens the 3D map. The same checks as the map key apply (not while dead, not while riding fast, map item if enabled, Map.CanOpen).

lualocal opened = exports['fx-3dmap-redm']:Open()
-- returns true when the map is open or opening

#Close

Closes the 3D map. The camera flies back to the player.

luaexports['fx-3dmap-redm']:Close()

#IsOpen

lualocal isOpen = exports['fx-3dmap-redm']:IsOpen()
-- returns true or false

#RegisterLocations

Sends your script's places to the map. They appear on the 3D map and as blips on the game map, in the search, and players can set a route to them.

luaexports['fx-3dmap-redm']:RegisterLocations({
    {
        id       = "stable_valentine",            -- required: unique inside your script
        label    = "Valentine Stable",            -- required: or { en = "...", tr = "..." }
        category = "horse_supplies",              -- required: an id from Config.Categories
        coords   = vector3(-365.1, 791.9, 116.2), -- required
        sprite   = "blip_shop_horse",             -- optional: icon from ui/assets/blips
        color    = "orange",                      -- optional: a Config.Colors key
        note     = "Open all night",              -- optional: text on the place's card
        size     = "big",                         -- optional: "big" or "huge"
        hours    = { from = 8, to = 20 },         -- optional: game hours 0-23, shown only then
    },
})

Rules to know:

• Each call replaces your script's whole list. To add one place, send the full list again.
• When your script stops, its places are removed automatically.
• A place without id, category or coords is skipped.
• A category that does not exist shows the places under markers, and F8 says so.
• Up to 1000 places per script.
• hours: whole hours from 0 to 23. from and to cannot be the same. Wrong hours are ignored and the place is always shown.

#RemoveLocations

Removes every place your script registered.

luaexports['fx-3dmap-redm']:RemoveLocations()

#Event: fx-3dmap-redm:visibility

Fired on the client when the map opens (true) and closes (false). Use it to hide your own HUD.

luaAddEventHandler("fx-3dmap-redm:visibility", function(visible)
    if visible then
        -- the map is on screen: hide your HUD
    else
        -- the map is closed: show your HUD
    end
end)

#Examples

A job script that shows its depots on the map:

luaCreateThread(function()
    local list = {}
    for i, depot in ipairs(Config.Depots) do
        list[#list + 1] = {
            id = "depot_" .. i,
            label = depot.name,
            category = "markers",
            coords = depot.coords,
        }
    end
    exports['fx-3dmap-redm']:RegisterLocations(list)
end)

Open the map from an item:

luaRegisterNetEvent("myitems:useMap", function()
    exports['fx-3dmap-redm']:Open()
end)

Close the map when a cutscene starts:

luaif exports['fx-3dmap-redm']:IsOpen() then
    exports['fx-3dmap-redm']:Close()
end

---

#17. Database

FX-3DMAP creates two tables by itself on the first start:

Your data lives in the database, not in the resource files. That means an update can never delete your places, areas or pins.

If your database user is not allowed to create tables, run setup/sql/install.sql once by hand. It is safe to run more than once.

---

#18. Updating

1. Download the new version from portal.cfx.re → Granted Assets.
2. Replace the files. Your places, areas and pins are in the database and are not touched.
3. If you edited config.lua, config_locations.lua, config_icons.lua or locales.lua, compare them with the new ones before replacing, so you keep your changes and get the new settings.
4. Restart the resource.

When a new version is out, the server console tells you on start, with the list of files that changed.

---

#19. Troubleshooting and FAQ

The console says "oxmysql is not running".

Install oxmysql and put ensure oxmysql before ensure fx-3dmap-redm in server.cfg. Until then, the Blip Manager and pins stay off.

The console says "vorp_core / rsg-core is installed but was not running".

The start order is wrong. Put ensure fx-3dmap-redm after your framework.

"Could not set up the database tables".

Your database user may not create tables. Run setup/sql/install.sql by hand.

I don't see the Blip Manager button.

You are not staff yet. See section 4. With fx-adminpanel running, check your rank has the blips permission.

Blips show twice on the game map.

The original script still draws its own blip. Open the Setup Wizard; it lists the file and line where each one is switched on. Turn those off.

The map won't open.

You may be dead, riding too fast, missing the map item, or Map.CanOpen returned false. The player sees "The map cannot be opened right now."

The map key opens the normal game map.

Check Config.ReplaceGameMap = true. If another script (for example a pause menu script) also uses the map key, it may take it first.

"Nearby only" areas don't show.

Turn OneSync on.

The compass behaves strangely inside areas.

Another script may control the radar. Set Config.Zones.expandRadar = false.

Some Turkish letters look plain on the game map.

The game's blip font cannot draw ı, ş and ğ. The 3D map shows them correctly.

Can I use it without a framework?

Yes. On a standalone server, pins are saved per player license and staff are decided by ACE permissions.

Will an update delete my blips?

No. Everything is in the database.

Can I add my blips by hand instead of in game?

Yes, in config_locations.lua (see section 11), or from your own scripts with RegisterLocations (see section 16).

---

#20. Support

• 💬 Discord & Support: discord.gg/PjEu6tgAkU — open a ticket and we will help you.
• 📖 Documentation: fixitfy.com.tr/docs/fx-3dmap-redm

Built by Fixitfy Development.