YMAP Builder

Build a map placement file without opening a map editor: paste coordinates from the game or add props one by one, set heading or full rotation, and get CodeWalker-ready .ymap XML with quaternions, entity and streaming extents calculated for you. Import an existing ymap XML to edit it.

Config & CodeMaps, Props, DownloadRead the docs

Ymap

NameFile name too: stream/<name>.ymap. Must be unique on your server.ParentLeave empty for standalone props.Assumed entity radius (m)The browser does not know model sizes. Used for the extents.lodDist when set to -1 (m)Streaming extents need a distance for entities that use the model's own lodDist.

Scripted (flags 1)The game only loads it after RequestIpl('name'). Leave off for props that should always be there.

Entities (3)

Select all

1
xyzheading
2
xyzheading
3
xyzheading

Import

Coordinates, one entity per linevector3, vector4, vec3/vec4, {x=, y=, z=, w=}, JSON objects or arrays, plain numbers. A model name, model=<hash> or rot=vector3(pitch, roll, yaw) on the same line is picked up too.

Default modelHeading if missingZ offset (m)Flags for new rowslodDist for new rows

Coordinates from GetEntityCoords(PlayerPedId()) are about 1 m above the ground. Set Z offset to for those, or use /ymappos from the helper below, which already snaps to the ground.

Top-down preview

Streaming extents

Click a dot to jump to its row, Shift or Ctrl click to select. The line shows the heading. Solid box: entity extents, dashed: streaming extents (the ymap loads while you are inside it).

No problems found.

Export

entities: 3
flags: 0
contentFlags: 1
extent: 23 x 25 m

my_props.ymap.xml

<?xml version="1.0" encoding="UTF-8"?>
<CMapData>
 <name>my_props</name>
 <parent />
 <flags value="0" />
 <contentFlags value="1" />
 <streamingExtentsMin x="-1496.72" y="-1118.94" z="-106.14" />
 <streamingExtentsMax x="-1273.35" y="-894.23" z="113.86" />
 <entitiesExtentsMin x="-1396.72" y="-1018.94" z="-6.14" />
 <entitiesExtentsMax x="-1373.35" y="-994.23" z="13.86" />
 <entities>
  <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>
  <Item type="CEntityDef">
   <archetypeName>prop_bench_01a</archetypeName>
   <flags value="1572896" />
   <guid value="0" />
   <position x="-1383.35" y="-1008.94" 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>
  <Item type="CEntityDef">
   <archetypeName>prop_bin_07a</archetypeName>
   <flags value="1572896" />
   <guid value="0" />
   <position x="-1385.1" y="-1006.62" 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>
 </entities>
 <containerLods itemType="rage__fwContainerLodDef" />
 <boxOccluders itemType="BoxOccluder" />
 <occludeModels itemType="OccludeModel" />
 <physicsDictionaries />
 <instancedData>
  <ImapLink />
  <PropInstanceList itemType="rage__fwPropInstanceListDef" />
  <GrassInstanceList itemType="rage__fwGrassInstanceListDef" />
 </instancedData>
 <timeCycleModifiers itemType="CTimeCycleModifier" />
 <carGenerators itemType="CCarGen" />
 <LODLightsSOA>
  <direction itemType="FloatXYZ" />
  <falloff />
  <falloffExponent />
  <timeAndStateFlags />
  <hash />
  <coneInnerAngle />
  <coneOuterAngleOrCapExt />
  <coronaIntensity />
 </LODLightsSOA>
 <DistantLODLightsSOA>
  <position itemType="FloatXYZ" />
  <RGBI />
  <numStreetLights value="0" />
  <category value="0" />
 </DistantLODLightsSOA>
 <block>
  <version value="0" />
  <flags value="0" />
  <name>my_props</name>
  <exportedBy>fivemad.com</exportedBy>
  <owner />
  <time />
 </block>
</CMapData>

This is CodeWalker XML. The game needs the binary .ymap: see the Convert tab.

Grab positions in game

Copy to clipboard (ox_lib)

Drop this into any client script on your dev server. Stand where a prop should go and run /ymappos, or look at an existing prop and run /ymapprop to copy its exact model, position and rotation. Then /ymapdump and paste the lines into Import. Every output line is a format the importer reads.

ymap_helper.lua

-- fivemad.com YMAP Builder helper (client side). Dev only, remove before going live.
-- /ymappos   your position on the ground + heading, as vector4
-- /ymapprop  model, position and rotation of the prop in front of the camera
-- /ymapdump  print every line collected so far (paste them all into the builder)
-- /ymapclear forget the collected lines
local lines = {}

local function out(line)
    lines[#lines + 1] = line
    print(line) -- F8 console, also saved in CitizenFX.log
    TriggerEvent('chat:addMessage', { args = { 'ymap', line } })
    -- lib.setClipboard(line) -- needs ox_lib
end

RegisterCommand('ymappos', function()
    local ped = PlayerPedId()
    local c = GetEntityCoords(ped)
    -- GetEntityCoords(ped) is about 1 m above the ground (pelvis), so snap to the ground
    local found, gz = GetGroundZFor_3dCoord(c.x, c.y, c.z + 0.5, false)
    local z = found and gz or (c.z - 1.0)
    out(('vector4(%.3f, %.3f, %.3f, %.2f)'):format(c.x, c.y, z, GetEntityHeading(ped)))
end, false)

local function camForward()
    local r = GetGameplayCamRot(2)
    local p, y = math.rad(r.x), math.rad(r.z)
    return vector3(-math.sin(y) * math.abs(math.cos(p)), math.cos(y) * math.abs(math.cos(p)), math.sin(p))
end

RegisterCommand('ymapprop', function()
    local from = GetGameplayCamCoord()
    local to = from + camForward() * 30.0
    -- 16 = objects. Map props only show up here if the game spawned them as objects.
    local ray = StartExpensiveSynchronousShapeTestLosProbe(from.x, from.y, from.z, to.x, to.y, to.z, 16, PlayerPedId(), 7)
    local _, hit, _, _, ent = GetShapeTestResult(ray)
    if hit ~= 1 or ent == 0 or GetEntityType(ent) ~= 3 then
        return print('ymap: no object in front of the camera')
    end
    local c, r = GetEntityCoords(ent), GetEntityRotation(ent, 2)
    -- the builder turns the model hash back into a name when it is a vanilla prop
    out(('model=%d pos=vector3(%.3f, %.3f, %.3f) rot=vector3(%.2f, %.2f, %.2f)'):format(GetEntityModel(ent), c.x, c.y, c.z, r.x, r.y, r.z))
end, false)

RegisterCommand('ymapdump', function()
    local all = table.concat(lines, '\n')
    print(all)
    -- lib.setClipboard(all) -- needs ox_lib
end, false)

RegisterCommand('ymapclear', function()
    lines = {}
    print('ymap: cleared')
end, false)

From in-game coords to a streamed ymap

Add the helper from Grab positions in game to a client script on your dev server. Walk to each spot and run/ymappos, or look at an existing prop and run /ymapprop. Finish with /ymapdump.
Paste the lines into Import, Coordinates, pick a default model and add them. Fine tune rows, or select several and bulk edit.
Check the warnings, then download <name>.ymap.xml from Export.
Convert it with CodeWalker: RPF Explorer, File, Open Folder on your stream folder, enable Edit mode, Edit, Import XML. You get <name>.ymap.
Put it in stream/ of a resource with a plain fxmanifest.lua, ensure it and reconnect.

Everything runs in your browser and is saved locally, so you can come back to the same map later.

How rotation is stored

In game you think in heading (GetEntityHeading) or pitch, roll and yaw (GetEntityRotation(entity, 2)). Heading 0 faces north and 90 faces west. A ymap stores a quaternion instead, and it is the inverse of the in-game rotation. CodeWalker inverts it when it loads an entity and inverts it again when it saves. For a plain heading h:

rotation x = 0
rotation y = 0
rotation z = -sin(h / 2)
rotation w =  cos(h / 2)

heading 90  ->  z = -0.7071068, w = 0.7071068
heading 180 ->  z = -1,         w = 0

With pitch and roll the in-game rotation is Rz(yaw) * Rx(pitch) * Ry(roll) (rotation order 2, the default forGetEntityRotation), and the stored quaternion is its conjugate. Tilted entities also need flag 1 (allow full rotation), which this tool adds on export.

Heads up: CodeWalker's entity panel shows the stored quaternion as is, so its Euler Z reads minus your in-game heading. That is normal. Interior placements (CMloInstanceDef) are the one exception and store the rotation without inverting it.

Fields that matter

Field	What to use
`flags`	`32` freezes the prop (no physics). `1572864` are the two shadow bits almost every vanilla entity has. `1572896` is both. `0` leaves physics on for props that have it.
`lodDist`	How far away the prop is drawn, in metres. `-1` uses the model's own value. 100 to 200 is fine for most props, go higher for big landmarks.
`lodLevel`	`LODTYPES_DEPTH_ORPHANHD` for standalone props. HD, LOD and SLOD levels are for map LOD chains with parents.
`priorityLevel`	`PRI_REQUIRED` always loads. The optional levels can be skipped by the game, so do not use them for anything gameplay related.
`tintValue`	Texture variation of the prop (same as `SetObjectTextureVariation`).
extents	Entities extents box the props, streaming extents add the lodDist. The ymap is only loaded while you are inside the streaming extents. Both are filled in on export.

Common pitfalls

Props float 1 m in the air. Player coords are 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 the headings are read correctly.
Props vanish when you walk away. lodDist too low, or streaming extents too small because they were not recalculated after moving things.
Nothing shows up. Check the ymap is binary (not the .xml), the file name is unique across all resources, and the scripted flag is off (or you call RequestIpl).
Custom props are invisible. The ymap only places them. Their .ydr, .ytd and .ytyp have to be streamed as well.
Huge ymap covering half the map. The whole file streams in as soon as you enter its extents. Keep one ymap per area.
Changes do not show. Reconnect. Map files are loaded when you join, a resource restart is not always enough.

Do I need this_is_a_map?

No. A .ymap in stream/ is registered on its own. this_is_a_map 'yes' tells FiveM to reload the map store when the resource starts, which matters when you replace vanilla map files, not when you only add props.