YMAP Builder

The YMAP Builder turns a list of props and positions into a .ymap placement file without opening a map editor. You paste coordinates from the game (or place props in the 3D world), set heading or full rotation, and the tool writes CodeWalker XML with the quaternions, entity extents, streaming extents and map flags already calculated. It is for server owners and devs who want a few benches, barriers or decorations streamed with the map instead of spawned by a script.

What it is for

Props spawned with CreateObject live in a script: they need a thread, they need cleanup, and every client creates them again. A ymap is part of the map itself. The game streams it in when you get close and drops it when you leave, with no script at all. The catch is the file format: rotations are stored as an inverted quaternion, extents have to cover every entity plus its draw distance, and the map flags depend on the LOD levels you use. Get one of those wrong and props face the wrong way, pop out early or never load. This tool handles those parts so you only think about model, position and heading.

Typical jobs:

• Decorating a spot (benches, bins, barriers, plants) around an MLO or a job location.
• Turning a list of vector4 spawn points from your config into static props.
• Editing an existing ymap XML: fix a rotation, move a group of props, change lodDist on everything.

Quick start

1. Add the helper from Grab positions in game (bottom of the page) to a client script on your dev server. Stand where a prop should go and run /ymappos, or look at an existing prop and run /ymapprop. Finish with /ymapdump.
2. In Import, keep the Coordinates tab, paste the lines, pick a Default model and press Add.
3. Fine tune rows in Entities, or select several and use the bulk edit bar. Open 3D world (desktop) to move them with a gizmo inside the GTA V map.
4. Set Name in the Ymap panel. It becomes the file name.
5. Check the warnings under the preview, then press Download on the XML tab of Export. You get <name>.ymap.xml.
6. Convert it to a binary .ymap with CodeWalker (see the Convert tab), put it in stream/ of a resource and ensure it.

The page starts with three sample props at Vespucci Beach so you can see the output before adding your own. Your work is saved in the browser (local storage) and comes back when you reopen the page.

Panels

Ymap

Undo reverts the last structural change (add, delete, duplicate, reorder, import, bulk edit, 3D edits), up to 40 steps. Typing in a field is not recorded, to keep the history useful. Clear removes every entity, and Undo brings them back.

Entities

Each row has a model field (with autocomplete from the vanilla objects list), x, y, z and heading. A model name that is not in the objects list is marked, and the row number turns amber when the row has a warning.

• Add appends a row 2 m east of the last one, with the same z and heading, using the model, flags and lodDist from the import defaults.
• Paste a whole vector3(...), vector4(...) or a /ymapprop line into the x field and it fills x, y, z, heading (and pitch, roll and model when the line has them).
• The row buttons duplicate (the copy sits 1 m east) or delete that row. The chevron opens More fields.
• The checkbox bar on top selects rows. With a selection you get move up, move down, duplicate and delete for all of them, plus the bulk edit bar.
• Long lists show 60 rows at a time with a Show more button.

More fields per entity:

Flag presets:

If an entity is tilted (pitch or roll not zero), flag 1 (allow full rotation) is added on export, and the flags editor says so. Without it the game ignores pitch and roll.

For entities loaded from an XML, guid, parentIndex, numChildren and any extensions block are kept and written back unchanged.

Bulk edit

With rows selected, the bar under the toolbar edits all of them at once. Empty fields stay unchanged, offsets are added.

• model, flags (presets), lodDist, priority, lodLevel: replace the value.
• offset x, offset y, offset z: add to the position (move a whole group).
• rotate heading by: adds degrees to each heading. set heading: sets one heading for all (wins over rotate).
• Apply to N runs it, Reset empties the bar.

Import: Coordinates

Paste one entity per line. It accepts vector3, vector4, vec3/vec4, {x = , y = , z = , w = }, JSON objects or arrays and plain numbers. A model name, model=<hash> or rot=vector3(pitch, roll, yaw) on the same line is picked up too. Model hashes are turned back into names when they are vanilla props, otherwise into hash_XXXXXXXX.

vector4(-1386.72, -1004.23, 3.86, 125.0)
{x = -1383.35, y = -1008.94, z = 3.86, w = 125.0}
prop_bin_07a vector3(-1385.1, -1006.62, 3.86)
model=prop_bench_01a pos=vector3(-1374.0, -1018.5, 3.86) rot=vector3(0.0, 0.0, 125.0)

Add N appends, Replace all replaces the list. Lines it cannot read are counted and the first five are listed.

Import: Ymap XML

Open .ymap.xml or paste XML and press Load pasted XML. It replaces the current entities (Undo brings them back). Get the XML from CodeWalker: RPF Explorer, right click the ymap, Export XML. Rotations are read the way CodeWalker stores them and shown as in-game heading or pitch/roll/yaw. Sections the builder does not edit (car generators, occluders, LOD lights, time cycle modifiers and so on) are kept and written back as they were.

Top-down preview

An SVG plan of every entity. The line on each dot shows its heading. Click a dot to jump to its row, Shift or Ctrl click to add it to the selection. The solid box is the entity extents; tick Streaming extents to also draw the dashed streaming box (the area in which the ymap is loaded).

Warnings

The list under the preview checks your ymap as you edit. Click a warning to select the rows it is about.

• Missing or invalid name, empty model, invalid numbers.
• Models not in the vanilla objects list (fine for custom props, otherwise a typo).
• Two entities within 1 cm of each other, entities outside the playable map, entities at 0, 0.
• A ymap spanning a very large area, or more than 1000 entities (split it by area).
• lodDist under 20 m.
• HD levels without a LOD parent (use ORPHANHD for standalone props).
• Tilted entities that get flag 1 on export (info).

3D world

The 3D world button in the preview panel (desktop only) opens the ymap inside the GTA V world at the top of the page, starting next to the active entity. Props that have a model in the Objects List show as the real mesh, others as a box of their real size (or a 1 m box). Everything you do there updates the entity list and the export right away, and Undo works for moves, rotations and placed props.

The camera, quality setting and full screen work the same as in the 3D world docs. Close 3D hides the panel again.

Output

Export tabs

• XML: a stats line (entities, map flags, contentFlags, entity extent size) and the full CMapData XML. Download saves it as <name>.ymap.xml.
• Resource: the folder layout, a ready fxmanifest.lua, and a client.lua with RequestIpl when Scripted is on.
• Convert: the CodeWalker steps below.

Each entity is written like this (a prop_bench_01a at heading 125):

  <Item type="CEntityDef">
   <archetypeName>prop_bench_01a</archetypeName>
   <flags value="1572896" />
   <guid value="0" />
   <position x="-1386.72" y="-1004.23" z="3.86" />
   <rotation x="0" y="0" z="-0.8870108" w="0.4617486" />
   <scaleXY value="1" />
   <scaleZ value="1" />
   <parentIndex value="-1" />
   <lodDist value="100" />
   <childLodDist value="0" />
   <lodLevel>LODTYPES_DEPTH_ORPHANHD</lodLevel>
   <numChildren value="0" />
   <priorityLevel>PRI_REQUIRED</priorityLevel>
   <extensions />
   <ambientOcclusionMultiplier value="255" />
   <artificialAmbientOcclusion value="255" />
   <tintValue value="0" />
  </Item>

Converting with CodeWalker

Browsers cannot write the binary ymap format, so CodeWalker does the last step:

1. Put <name>.ymap.xml in your resource’s stream folder. Keep the double extension, CodeWalker uses it to know the file type.
2. Open CodeWalker’s RPF Explorer, then File, Open Folder and pick that stream folder.
3. Turn on Edit mode, then Edit, Import XML (or drag the file into the window) and choose the XML.
4. CodeWalker writes <name>.ymap next to it. Delete the .xml from stream.
5. ensure the resource and reconnect.

To check it first, open CodeWalker’s world view, use the Project window, File, Open Files to load the ymap and fly to it.

The resource

my_props/
├── fxmanifest.lua
└── stream/
    └── my_props.ymap        <- binary, converted with CodeWalker

fx_version 'cerulean'
game 'gta5'

name 'my_props'
description 'Props streamed with my_props.ymap'

-- A .ymap inside stream/ is picked up on its own, nothing else is required.
-- this_is_a_map 'yes' reloads the map store when the resource starts. Only add it
-- if you replace vanilla map files or ship map data files.
-- this_is_a_map 'yes'

ensure my_props

With Scripted on, the manifest adds client_script 'client.lua' and the tool gives you:

-- The ymap has the "scripted" flag, so the game only loads it on request.
CreateThread(function()
    RequestIpl('my_props')
end)

-- Later, to remove the props again:
-- RemoveIpl('my_props')

Grabbing positions in game

The Grab positions in game panel gives you ymap_helper.lua, a client script for your dev server:

Each line is printed to the F8 console and chat. Tick Copy to clipboard (ox_lib) to also copy it with lib.setClipboard (needs ox_lib). Every line it prints is a format the importer reads. Remove the helper before going live.

Rotation

Enter rotations the way you read them in game: heading from GetEntityHeading, or pitch, roll and yaw from GetEntityRotation(entity, 2). Heading 0 faces north and 90 faces west. The tool writes the quaternion a ymap expects, so you never type one yourself. The expanded row shows the value that will be written, if you want to compare it with another file.

When you open the result in CodeWalker, its entity panel shows the stored rotation as is, so its Euler Z reads minus your in-game heading. That is normal, the prop still faces the heading you entered.

Common mistakes

• Props float 1 m in the air. GetEntityCoords(PlayerPedId()) is at the pelvis. Use /ymappos (ground snapped) or set Z offset to -1 when importing.
• Props face the wrong way. Someone wrote the heading straight into the quaternion without inverting it. Import the XML here and headings are read correctly.
• Props vanish when you walk away. lodDist too low, or the streaming extents were not recalculated after moving things. The builder recalculates them on every change.
• Nothing shows up. The file in stream/ is still the .xml, the name clashes with another ymap, or Scripted is on and nothing calls RequestIpl.
• Custom props are invisible. The ymap only places them. Their .ydr, .ytd and .ytyp must be streamed too.
• One huge ymap. The whole file streams in as soon as you enter its extents. Keep one ymap per area.
• Changes do not show. Reconnect. Map files load when you join, a resource restart is not always enough.

Limitations

• Output is CodeWalker XML. You still need CodeWalker to make the binary .ymap.
• The tool does not know model sizes, so extents use the Assumed entity radius. Raise it for big props.
• No LOD chain authoring (parents, LOD models), occluders, car generators or MLO interiors. Those sections are only passed through from an imported XML.
• The 3D world needs a desktop browser with WebGL 2, and it does not include Cayo Perico or North Yankton.
• Everything runs in your browser and is saved locally. Nothing is uploaded.

Related tools

• Objects / Props List: find model names, sizes and 3D previews.
• 3D world: camera modes, keys and performance tips for the 3D view.
• Interactive Map: grab coordinates without starting the game.
• YTYP Creator: archetypes for custom props you place with a ymap.
• fxmanifest Generator