BLANCO

5. .ytyp in detail

<CMapTypes>
  <extensions/>
  <archetypes>
    <Item type="CBaseArchetypeDef">
      <lodDist value="500.00000000"/>
      <flags value="32"/>
      <specialAttribute value="0"/>
      <bbMin x="-1.5" y="-0.5" z="0.0"/>
      <bbMax x="1.5" y="0.5" z="1.0"/>
      <bsCentre x="0.0" y="0.0" z="0.5"/>
      <bsRadius value="1.7"/>
      <hdTextureDist value="250.00000000"/>
      <name>my_prop_01</name>
      <textureDictionary>my_props</textureDictionary>
      <clipDictionary/>
      <drawableDictionary/>
      <physicsDictionary>my_props</physicsDictionary>
      <assetType>ASSET_TYPE_DRAWABLE</assetType>
      <assetName>my_prop_01</assetName>
      <extensions/>
    </Item>
  </archetypes>
  <name>my_props</name>
  <dependencies/>
  <compositeEntityTypes/>
</CMapTypes>

Archetype types

assetType (verified enum, rage__fwArchetypeDef__eAssetType)

Archetype flags (bitmask)

Every row in the previous version of this table was wrong except 2 and 32. Corrected against Dekurwinator's research. CodeWalker stores flags as a raw uint with no named enum, so there is no authoritative source better than this.

32 (static prop) is the sane default. Every real ytyp generator ships <flags value="32"/> as its baseline.

🟡 specialAttribute

The SA_* names are GTA IV IDE special attributes, a different system entirely. GTA V's specialAttribute is a small enum, mostly door behaviour. Door values need FLAG_DOOR_PHYSICS (67108864) set.

Enum, not a bitfield — engine-confirmed. RAGE calls these model attributes and tests them for equality, never with a mask: pModel->GetAttributes() == MODEL_ATTRIBUTE_IS_BENDABLE_PLANT. Six of the names below appear verbatim in engine code (IS_LADDER, IS_TRAFFIC_LIGHT, IS_BENDABLE_PLANT, IS_RAIL_CROSSING_DOOR, NOISY_AND_DEFORMABLE_BUSH, IS_RAIL_CROSSING_LIGHT), and there is no attribute name in the engine that this table is missing. The numeric mapping is still community research; the names and the enum shape are not.

1, 18-26 are unused. Ladder is 2, not 1. Street light is 32, not 31.

CTimeArchetypeDef timeFlags

Bits 1-24 map to hours 00:00-23:00 (bit 1 = midnight, bit 24 = 23:00). Bit 25 = ALLOW_VANISH_WHILST_VIEWED. Bit 32 = always on (24/7).

physicsDictionary

Name of the .ybn container (the rpf-internal collision dictionary), not the individual bound. Wrong value → prop with no collision. If collision is embedded in the .ydr, match it to the ytyp name or leave blank depending on setup.

MLO specifics (CMloArchetypeDef)

<Item type="CMloArchetypeDef">
  <name>my_interior</name>
  <assetType>ASSET_TYPE_ASSETLESS</assetType>
  <assetName>my_interior</assetName>
  <mloFlags value="0"/>
  <rooms>
    <Item>
      <name>limbo</name>
      <bbMin x="-100" y="-100" z="-100"/>
      <bbMax x="100" y="100" z="100"/>
      <blend value="1.0"/>
      <timecycleName>int_mall</timecycleName>
      <secondaryTimecycleName/>
      <flags value="0"/>
      <portalCount value="0"/>
      <floorId value="0"/>
      <exteriorVisibiltyDepth value="-1"/>
      <attachedObjects/>
    </Item>
  </rooms>
  <portals>
    <Item>
      <roomFrom value="0"/>
      <roomTo value="1"/>
      <flags value="0"/>
      <mirrorPriority value="0"/>
      <opacity value="0"/>
      <audioOcclusion value="0"/>
      <corners>
        <Item x="0" y="0" z="0"/>
        <Item x="1" y="0" z="0"/>
        <Item x="1" y="0" z="2"/>
        <Item x="0" y="0" z="2"/>
      </corners>
      <attachedObjects/>
    </Item>
  </portals>
  <entities/>
  <entitySets/>
  <timeCycleModifiers/>
</Item>

Portal gotchas:

• Exactly 4 corners, wound consistently, must be coplanar.
• roomFrom/roomTo are indices into <rooms>. Room 0 = limbo = exterior.
• Portals to limbo make the interior visible from outside; set exteriorVisibiltyDepth on rooms that need to see out.
• Portal count per room must be recalculated (CodeWalker does it).

MLO portal flags

MLO room flags

6. .ymap in detail

<CMapData>
  <name>my_map</name>
  <parent/>
  <flags value="0"/>
  <contentFlags value="65"/>
  <streamingExtentsMin x="100" y="-350" z="0"/>
  <streamingExtentsMax x="200" y="-250" z="60"/>
  <entitiesExtentsMin x="140" y="-310" z="18"/>
  <entitiesExtentsMax x="160" y="-290" z="24"/>
  <entities>
    <Item type="CEntityDef">
      <archetypeName>my_prop_01</archetypeName>
      <flags value="32"/>
      <guid value="0"/>
      <position x="150.0" y="-300.0" z="20.0"/>
      <rotation x="0" y="0" z="0" w="1"/>
      <scaleXY value="1"/>
      <scaleZ value="1"/>
      <parentIndex value="-1"/>
      <lodDist value="500"/>
      <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/>
  <boxOccluders/>
  <occludeModels/>
  <physicsDictionaries/>
  <instancedData>
    <ImapLink/>
    <PropInstanceList/>
    <GrassInstanceList/>
  </instancedData>
  <timeCycleModifiers/>
  <carGenerators/>
  <LODLightsSOA/>
  <DistantLODLightsSOA/>
  <block>
    <version value="0"/>
    <flags value="0"/>
    <name>my_map</name>
    <exportedBy>Blanco</exportedBy>
    <owner/>
    <time/>
  </block>
</CMapData>

CMapData <flags>

🟡 gtamods still records CMapData <flags> as "unknown"; the mapping above is community-derived but consistent in practice (Community RE, not untested folklore).

CMapData <contentFlags> (bitmask)

Common values:

• 1: props, no collision
• 65 (1+64): props with embedded collision ← most add-on prop ymaps
• 73 (1+8+64): MLO placement ymap
• 2: LOD only
• 18 (2+16): LOD + SLOD1
• 50 (2+16+32): LOD + SLOD1 + occlusion
• 1088 (64+1024): instanced grass

FiveM auto-patches a missing bit 3 if it finds a CMloInstanceDef without it, and logs a warning. Don't rely on it.

CodeWalker: Tools → Auto-calculate flags/extents. Just use this.

Extents

• entitiesExtentsMin/Max: AABB tightly containing all entities.
• streamingExtentsMin/Max: the box that must be on-screen for the ymap to stream in. Must be ≥ entities extents, usually padded by the largest lodDist.
• Too-small streaming extents = props pop in/out or vanish when you look away. Single most common "my map is flickering" bug.

CEntityDef fields

<Item type="CMloInstanceDef"> adds groupId, floorId, defaultEntitySets, numExitPortals, MLOInstflags.

CEntityDef flags (bitmask)

128-16384 and 1073741824+ are unused.

Known combos:

• 1572864 (524288 + 1048576) = lights cast static and dynamic shadows. Standard for doors, gates, ladders. This is the shadow pair, not a "common for scripted" flag.
• 1572866 (+2) = security gates (up/down).

parentIndex

Which entity list parentIndex indexes depends on entity flag bit 3 (value 8, FLAG_ATTACH_LOD_IS_IN_PARENT_MAPDATA).

• Flag 8 clear (default): parentIndex indexes the entity array of the same ymap. CodeWalker: alldefs[pind].
• Flag 8 set: parentIndex indexes the entity array of the ymap named in <parent>. CodeWalker resolves this in ConnectToParent() via pymap.AllEntities[pind].

CodeWalker exposes exactly this: public bool LodInParentYmap => ((_CEntityDef.flags >> 3) & 1) > 0;. Dekurwinator's independently-derived flag name for bit 3 is FLAG_ATTACH_LOD_IS_IN_PARENT_MAPDATA, two sources, same conclusion.

Resolution is flag-dependent: not always the same ymap, and not always the parent ymap.

Either way it's a zero-based array index, not a name or hash. Insert an entity mid-list and every index after it shifts.

CodeWalker additionally rejects a parent as invalid (treats the entity as a root) when the parent's lodLevel is numerically ≤ the child's, or when an ORPHANHD parent has a non-ORPHANHD child.

lodLevel (verified enum, rage__eLodType)

Note the numbering: ORPHANHD is 5, between SLOD3 and SLOD4. That's why CodeWalker's p.lodLevel <= d.lodLevel root check needs the extra ORPHANHD special case.

🟡 Render mask (drawable visibility)

A drawable's renderMask byte controls which render passes it appears in. It is a bitfield in the low 5 bits, with bits 5 to 7 always set, so the value never drops below 224: renderMask = 224 + (enabled bits). 255 renders in everything; 224 in nothing.

Example: 253 = 224 + 1 + 4 + 8 + 16, so drawable, spec, mirror, and water are on and shadow is off. The 32 possible combinations run 224 to 255. Flag research by kirill_mapper (komarovs_mappers team). Still 🟡 after a 2026-08-15 check: the field is real and CodeWalker names it RenderMaskFlags, a u16 at DrawableModel + 0x2C whose low byte GIMS EVO calls "Mask", but nothing in available RAGE source assigns the bits — the bucket masks in rmcore are a different mechanism. Recorded so the next person does not re-search the same places.

LOD parenting

Chain is HD → LOD → SLOD1 → SLOD2 → SLOD3 (→ SLOD4).

• Each level typically lives in a separate ymap, linked via <parent> in CMapData, and then every child entity needs flag bit 3 set, or the index resolves against the wrong list.
• numChildren on the parent must equal the actual count of children pointing at it.
• Terminal entity: parentIndex = -1.
• lodDist must increase up the chain: HD 100 → LOD 300 → SLOD1 700 → SLOD2 1500 → SLOD3 5000+.
• For LOD models glowing at night: set FLAG_USE_AMBIENT_SCALE (536870912) on the archetype. The old "drop the green vertex-paint channel" advice is a vertex-colour workaround for the same symptom; the flag is the actual mechanism.

If you just want a prop to exist: LODTYPES_DEPTH_ORPHANHD, parentIndex -1, numChildren 0, childLodDist 0. Done.

Other ymap sections

• boxOccluders: cheap box occlusion volumes. Position as int16 (cm), size in cm, iCosZ/iSinZ for rotation.
• occludeModels: mesh-based occluders.
• carGenerators: parked-car spawn points. carModel, popGroup, flags, perpendicularLength, livery.
• timeCycleModifiers: named timecycle region volumes; percentage, range, startHour/endHour.
• LODLightsSOA / DistantLODLightsSOA: structure-of-arrays light data. numStreetLights must match positions count or FiveM patches/warns.
• instancedData.GrassInstanceList: batched grass. Position packed as uint16 relative to a batch AABB, plus normal, colour, scale, pad.
• containerLods: grouping for streamed container LODs.
• physicsDictionaries: list of .ybn dictionary names this ymap needs loaded.

Cargen flags

🟡 Light flags (ydr/ymap lights)

Bit index → meaning: 1 INTERIOR_ONLY, 2 EXTERIOR_ONLY, 3 DISABLE_IN_CUTSCENE, 4 VEHICLE, 5 FX, 6 TEXTURE_PROJECTION, 7 CAST_SHADOWS, 8 CAST_STATIC_SHADOWS, 9 CAST_DYNAMIC_SHADOWS, 10 CALC_FROM_SUNLIGHT, 11 ENABLE_BUZZING, 12 FORCE_BUZZING, 13 VOLUME_DRAWING, 14 NO_SPECULAR, 15 INT_AND_EXT, 16 ONLY_CORONA, 17 DONT_RENDER_IN_REFLECTION, 18 ONLY_RENDER_IN_REFLECTION, 19 USE_CULLPLANE, 20 USE_VOL_OUTER_COLOUR, 21 CAST_HIGHER_RES_SHADOW, 22 CAST_ONLY_LOWRES_SHADOWS, 23 ADD_TO_VIP_LOD_LIGHTS, 24 DONT_LIGHT_ALPHA, 25 SHADOWS_IF_POSSIBLE, 26 CUTSCENE, 27 MOVING_LIGHT_SOURCE, 28 USE_VEHICLE_TWIN, 29 FORCE_MEDIUM_LOD_LIGHT, 30 CORONA_ONLY_LOD_LIGHT.

Checked against engine source (2026-08-15). RAGE's own LIGHTFLAG_* set has 28 names, and 21 of the 30 above match one exactly once renames are allowed (CAST_STATIC_SHADOWS → CAST_STATIC_GEOM_SHADOWS, VOLUME_DRAWING → DRAW_VOLUME, INT_AND_EXT → BOTH_INTERIOR_AND_EXTERIOR, ONLY_CORONA → CORONA_ONLY, DONT_RENDER_IN_REFLECTION → NOT_IN_REFLECTION, CALC_FROM_SUNLIGHT → CALC_FROM_SUN, DISABLE_IN_CUTSCENE → DONT_USE_IN_CUTSCENE). Nine have no counterpart in the engine code available: VEHICLE, ENABLE_BUZZING, FORCE_BUZZING, ONLY_RENDER_IN_REFLECTION, USE_CULLPLANE, ADD_TO_VIP_LOD_LIGHTS, SHADOWS_IF_POSSIBLE, FORCE_MEDIUM_LOD_LIGHT, CORONA_ONLY_LOD_LIGHT — treat those nine as the least certain. Seven engine flags are missing from this list (CAUSTIC, DELAY_RENDER, SOFT_SHADOWS, USE_FADEDIST_AS_FADEVAL, ALREADY_TESTED_FOR_OCCLUSION, HIGH_PRIORITY, USE_AS_PED_ONLY), but at least three of those are runtime-only rather than asset bits — HIGH_PRIORITY and USE_AS_PED_ONLY are stashed in CLightAttr's padding fields on PC, not in m_flags.

The header that assigns the bit numbers is not available, so the ordering above is still community research. One behavioural note that is engine-confirmed: the deferred lighting path switches on exact flag combinations to choose a render pass, so some pairs select a whole pass rather than composing independently.

7. _manifest.ymf

Tells the streamer which ytyps an ymap depends on. Without it: random missing-archetype behaviour, especially in MP/FiveM.

<CPackFileMetaData>
  <MapDataGroups/>
  <HDTxdBindingArray/>
  <imapDependencies>
    <Item>
      <imapName>my_map</imapName>
      <itypName>my_props</itypName>
      <packFileName/>
    </Item>
  </imapDependencies>
  <imapDependencies_2>
    <Item>
      <imapName>my_map</imapName>
      <manifestFlags/>
      <itypDepArray>
        <Item>my_props</Item>
      </itypDepArray>
    </Item>
  </imapDependencies_2>
  <itypDependencies_2/>
  <Interiors/>
</CPackFileMetaData>

✅ Fill both forms: imapDependencies (one pair per imap→ityp) and imapDependencies_2 (array form). Template1 and the working pack ship both forms.

CodeWalker: Tools → Generate Manifest. Always regenerate after adding ymaps/ytyps.

8. Collision (.ybn)

Per-poly material (materials.dat / materialfx.dat) drives footsteps, tyre marks, bullet decals, destructibility. CONCRETE, TARMAC, GRASS_LONG, METAL, WATER, STAIR_*.

Per-poly flags: NONE, STAIRS, NOT_CLIMBABLE, SEE_THROUGH, SHOOT_THROUGH, NOT_COVER, WALKABLE_PATH, NO_CAM_COLLISION, SHOOT_THROUGH_FX, NO_DECAL, NO_NAVMESH, NO_RAGDOLL, VEHICLE_WHEEL, NO_PTFX, TOO_STEEP_FOR_PLAYER, NO_NETWORK_SPAWN, NO_CAM_COLLISION_ALLOW_CLIPPING.

Collision include-flags

General objects/terrain: Flags 1: Map Animal, Map Cover, Map Dynamic, Map Vehicle, Map Weapon. Flags 2: Animal, Animal Ragdoll, Forklift Forks, Glass, Object, Ped, Plant, Projectile, Ragdoll, Test AI, Test Camera, Test Script, Test Vehicle Wheel, Test Weapon, Vehicle BVH, Vehicle Not BVH.

Water: Flags 1: Map River. Flags 2: Test AI, Test Camera, Test Script, Test Vehicle Wheel, Test Weapon.

For stairs, add the stairs flag to Flags 1, but not to ground, or it changes the player's movement animation.

Unk VertOffset is the collision margin, and it is a parameter rather than two magic numbers. RAGE sets it on every geometry bound with SetMarginAndShrink(DEFAULT_GEOM_MARGIN) where DEFAULT_GEOM_MARGIN = 0.04f: the margin is how far collision detection expands beyond the surface, and the stored vertices are shrunk inward by it, hence "vertex offset". The shrink cannot exceed the bound's own half-extent, so it is clamped — margin = min(margin, sizeX, sizeY, sizeZ), which CodeWalker mirrors. That is why thin or simple bounds carry a smaller value. The commonly quoted 0.002 and 0.02 are observations of that clamp, not rules; copy the value from a comparable stock bound rather than picking one.

Embedded vs standalone

Neither respects scaleXY/scaleZ from the ymap. Entity scale applies to the drawable only, never to collision. Scale a tree in the ymap and its collision stays original size either way. Standalone .ybn just gives you a bound you can pre-scale at export.