---
name: creating-gta-maps-sollumz
description: Use when creating, editing, or placing custom GTA V content — maps, interiors/MLOs, static meshes, props, or collisions — with the Sollumz Blender addon and CodeWalker. Covers YDR/YBN/YTYP/YMAP/YTD/YDD file formats, archetypes, rooms and portals, entities, LODs, shaders, and FiveM or singleplayer modding pipelines.
---

# Creating GTA V Maps with Sollumz

## Overview

Sollumz is a Blender addon (Blender 4.0+) that is the primary tool for authoring GTA V ("GTA 5") custom content — interiors (MLOs), map placements, props, static meshes, vehicles, and collisions — as native game file formats. It always works paired with **CodeWalker** (for browsing game files, exporting reference geometry, converting Sollumz's exported XML to game binary formats, and placing final entities in a YMAP). Sollumz cannot do the job alone; CodeWalker is required at both ends of the pipeline.

Source: official docs at https://docs.sollumz.org/ (fetched 2026-08-26; check for updates on breaking changes).

## When to use

- User wants to build a custom **interior** (MLO), building conversion, or map add-on for GTA V (FiveM or singleplayer).
- User wants to convert a 3D model into a game-ready prop, static mesh, or vehicle (`.ydr`/`.yft`).
- User is debugging collision, texture, LOD, shader, archetype, or export problems in a Sollumz/Blender GTA project.
- User asks about YDR/YBN/YTYP/YMAP/YTD/YDD/YCD files, archetypes, rooms/portals, entities, or CodeWalker/Sollumz terminology.

**Not for:** general Blender modeling help unrelated to GTA export, or FiveM Lua/server-side scripting (only the map/asset authoring side).

## Prerequisites

- Blender 4.0 or later, with the Sollumz addon installed (see Installation below).
- Latest CodeWalker build (distributed via the Sollumz Discord `#releases` channel, not the old public CodeWalker releases).
- Basic Blender modeling proficiency.
- For FiveM targets: understanding of how the server streams assets. For singleplayer: understanding of RPF mod loading.

### Installation
Blender 4.2+: Preferences → Get Extensions → Repositories → `+` → Add Remote Repository → URL `https://repo.sollumz.org/` → search "Sollumz" → Install. Older Blender: download `Sollumz.zip` from the GitHub latest release → Edit → Preferences → Add-ons → Install... → enable → restart. Full detail: [reference/static-assets.md](reference/static-assets.md).

## Core file formats

| Ext | Name | Holds |
|---|---|---|
| `.ydr` | Drawable | One mesh + shaders (+skeleton if dynamic). Base format for static props/map pieces. |
| `.ydd` | Drawable Dictionary | Container of multiple drawables (LOD sets, ped components, instanced props). Embedded collision does NOT work inside a `.ydd`. |
| `.yft` | Fragment | Multi-part/breakable objects — vehicles, breakable props. Ped YFTs with ragdoll physics are **not supported**. |
| `.ybn` | Bound (collision) | `BoundComposite → BoundGeometryBVH → BoundPolyMesh/BoundBox/BoundPolyBox`. Variants: plain (general), `hi@` (bullet-only), `ma@` (procedural spawning). |
| `.ytd` | Texture Dictionary | Reusable `.dds`, power-of-2 textures shared across models. HD variants: `+hi`/`+hidr`/`+hifr`/`+hidd`. |
| `.ytyp` | Archetype Definition | Base / Time / MLO archetypes: model+collision+texture+flags+extensions per object. |
| `.ymap` | Map Data | Entities, car generators, timecycle modifiers, grass batches, occluders, LOD lights — organized into Containers under Map Groups. |
| `.ycd` | Clip Dictionary | Animation data. Partial import/export support. |
| `_manifest.ymf` | Manifest | Required for MLOs and HD texture dictionaries to actually load in-game. Generated in CodeWalker: Tools → Generate Manifest. |

Full field-level reference (archetype flags, extensions, map item types, asset libraries): see [reference/file-formats.md](reference/file-formats.md). For vehicle/breakable-prop fragments, LOD editing, rigging, and light flags/flashiness: see [reference/fragments-and-lighting.md](reference/fragments-and-lighting.md).

## Building a custom interior/map — condensed workflow

This is the flagship "create a map" workflow (an MLO interior placed into the world). Steps don't have to be done in this exact order, but this is the recommended sequence. Full step-by-step with exact menu paths and keybinds: **[reference/interior-workflow.md](reference/interior-workflow.md)**.

1. **Pick a building** in CodeWalker. For a first interior, pick something small (1–2 rooms).
2. **Export from CodeWalker**: RPF Explorer → find the building → Export to XML for the drawable, plus textures (folder named after the building); export both `.ybn` variants (`name.ybn` player collision, `hi@name.ybn` bullet collision); find its `.ymap` for placement coordinates.
3. **Plan** (optional, recommended for larger interiors): rough floor plan + mood board, not to scale.
4. **Model in Blender**: import the YBN/YDR then YMAP, build a working plane off the imported shell, detach a copy to world origin, model floor/walls/roof/decals from scratch (the slowest phase), then `Convert to Drawable`.
5. **Texture**: create a shader material (NORMAL shader = base + normal map), assign power-of-2 `.dds` textures, fix UVs, embed textures, and add a `Color 1` vertex-color attribute (Face Corner / Byte Color) — Red=AO, Green=self-emissive, Blue=moonlight. **Skipping this causes props to glow wrong at night.**
6. **Collision**: duplicate the shell, detach, `Convert to Composite`, apply a **Flag Preset** (forgetting this is the #1 cause of "collision doesn't work"), assign per-room floor materials (drives room-specific footstep/gunshot audio).
7. **Create the YTYP**: auto-create a Base archetype from the drawable, auto-create an MLO archetype from the collision, add a Limbo room + one room per interior space (bounds from 4 selected collision vertices), draw portals at each doorway (arrow must point **Room → Limbo**), add the drawable as an Entity in its room.
8. **Export from Blender**: select everything, ensure nothing is hidden (hidden objects are silently skipped), run the Sollumz exporter. Then drag the XML into CodeWalker's RPF Explorer to convert to binary.
9. **Create the YMAP**: new entity referencing your MLO archetype name, paste the Blender transform (Object Location & Rotation Tools → copy) into CodeWalker, auto-calculate flags/extents, generate `_manifest.ymf`, save.

## Other workflows

For a standalone static mesh (`.ydr`), a standalone collision (`.ybn`), or a placeable prop archetype — each is a shorter subset of the interior steps above (convert to drawable, shader + texture, optionally build collision, optionally create an archetype, export, place via YMAP). Full step-by-step: [reference/static-assets.md](reference/static-assets.md).

## Common mistakes (check these first when something doesn't work)

| Symptom | Cause |
|---|---|
| Collision doesn't work at all | No Flag Preset applied to Bound GeometryBVH |
| MLO shows in CodeWalker but not in-game | `_manifest.ymf` not generated |
| "No Sollumz objects" error | "Limit to Selected" enabled, or object's Sollumz Type unset |
| Props glow wrong at night | Missing/wrong vertex color channel (Green=indoor MLO, Red=outdoor) |
| Object missing after export | Object was hidden — hidden objects are silently excluded |
| Textures missing after import | Didn't save textures into a folder named after the model; use `V > Find Missing Files` in Blender |
| `KeyError: 'Principled BSDF'` | Only Principled BSDF is supported for material conversion |
| Portal seems backwards | Portal must point Room → Limbo, not Limbo → Room; use "Flip Direction" |
| Doubled/tripled vertex count on export | Expected — game meshes split vertices per unique normal/UV/color, unlike Blender |

Full FAQ and unsupported-file list: [reference/troubleshooting.md](reference/troubleshooting.md).