Decentraland Editor ReadMe
==========================

by METATIGER, August 31 2025


This document has some useful information how to run or compile the DecentralandEditor Source for Windows from scratch
by using MSYS2 and the sources from Github, the Export and the Import process into Blender. The Editor is just a
customized variant of the "Netradiant" map editor which is a fork of the famous Quake 3 Map Editor "GTK Radiant".

It is a help tool to establish a simple workflow to build and export 3D Objects like buildings or also single objects
to Blender, and to use it further in Decentraland Creator Hub from there. Without any knowledge about UV unwrapping!
You can also reuse textures instead of baking which can increase the scene details a lot in Decentraland, and also
can reduce the file size of a final GLB.

Workflow:
Decentraland Editor > Export as OBJ > Import OBJ into Blender > Export as GLB > Import GLB to DCL Creator Hub

======================================================================================================================

Prerequisites:
- this tools uses Python to rescale an exported OBJ model to match the DCL dimensions
- Download Python Version 3 or higher from https://www.python.org
- Install Python

Installation:
- simply extract the "DCL.zip" which runs out of the box to C:\ root folder
- make sure that python.exe is accessible from any location (try to call it from C:\DCL in a Commandline Window)
- Run with "DecentralandEditor.exe"

Notice:
- you may see a "Windows protected your PC" message running the executable
- if yes, you must click "More info" and "Run anyway" to let Windows start the app
- if you are unsure you can upload the ZIP or the executables/DLLs inside to a Virus scan page first
- it does not contain a virus, it is just the compiled source and we're no "official" publisher
- you can always compile the source by yourself, which is a little more complex and descibed below
- you can then exchange your own compiled executables/DLLs with the provided ones, but they should be the same

======================================================================================================================

Compilation:
- Download MSYS2 from https://www.msys2.org
- Download Netradiant Source from https://github.com/Garux/netradiant-custom
- Install MSYS2 to C:\msys64
- copy source to c:\msys64\src
- run from Windows Startmenu "MSYS2 MINGW64"
- type "cd /c/msys64/src"
- type "make MAKEFILE_CONF=msys2-Makefile.conf BUILD=release -j$(nproc)"

How to turn Netradiant into a Editor for Decentraland or OBJ in general:
- bitmaps/splash.png has been altered to match the DCL style
- folders dcl.game and gamepacks/dcl.game and gamepacks/games/dcl.game must be copied to Netradiant root folder
- custom "scale.py" Python script to scale and rotate and exported OBJ must be copied to Netradiant root folder
- Editor Settings are located at AppData\Roaming\NetRadiantSettings

======================================================================================================================

How to export a Map to OBJ format:
- make sure there is a worldspawn entity in the map
- make sure there is a info_player_start entity in the map
- click "Build > Export to OBJ" or "Build > Export to OBJ with Lightmap"
- the Map will be converted into a Quake 3 BSP file using q3map2, optional with a external Lightmap
- the BSP will be converted into a Wavefront OBJ format 3D file
- an additional Python script will scale and rotate the OBJ file that it matches the Decentraland standards
- you can find the final OBJ at C:\DCL\dcl.game\maps\[mapname]_scaled.obj - including the previous steps

How to import exported Maps into Blender:
- exported Maps can be imported into Blender (current version: 4.2) using Blender's Wavefront (OBJ) importer
- OBJ files include the UVs of the whole Map and the Texture associations
- Textures are automatically loaded by Blender from the Netradiant source path (ex. C:\DCL\dcl.game\textures
- it can be exported to a single GLB file direct from Blender without any further actions

Lightmaps:
- an additional external Lightmap can be created, but is currently not supported in Decentraland atm

======================================================================================================================

Additional Information:

- if something goes wrong, there is a compilation log at AppData\Roaming\NetRadiantSettings\1.6.0\radiant.log
- you can also find a Batch file there with the last compilation/export steps
- the syntax of the "scale.py" script is: scale.py [source objfile] [target objfile] scalefactor rotationangle
- of course Python needs to be installed on your system to make it work (tested with version 3.12.8)
- many features of the Quake3 Engine are NOT supported, it's just about to create 3D architectural geometry very simple
- you can still use custom shader files to manipulate the level geometry on compile process
- most of these shader options are designed to work ingame using a Quake III Engine, but some also work on compile
- see q3map2 documentation: https://q3map2.robotrenegade.com/
- compilation is a 3-stage-process: BSP, VIS and Light
  - BSP creates the level geometry, we usually don't need more than this for Decentraland
  - VIS calculates the visibility of BSP nodes, this is for performance optimization in the Quake III Engine needed only
  - Light creates a Lightmap based on BSP and VIS stages usign skylights and custom lights on a map
- there is an Blender Addon to import BSP files direct into Blender (needs some work after import but supports lightmaps)
  - https://github.com/SomaZ/Blender_BSP_Importer
  
======================================================================================================================

Basic Usage of the Editor GUI:

General:
- Top Left is the 3D Preview Window
- click once with the right Mouse Button and use WASD to move the camere there
- in the other three Windows click and hold the right Mouse Button to drag the map
- use the Mousewheel to Zoom
- use Key 0-9 to change the grid resolution, entities get snapped according to this grid size
- if you click an Entity you can use these Keyboard Shortcuts:
  - "W" shows the XYZ Axis to drag and move an Entity around
  - "R" shows the rotation Angles to rotate an Entity (hold SHIFT to use fixed steps)
- press "S" to open the surface inspector, here you can manipulate the UVs and the assigned texture
- textures can also be assigned pressing "T" to enter the Texture window
- it is crucial to understand the difference between Brushes and Patches (Curves)
- Brushes are like LEGO bricks, always cuboid, solid and can also be cutted into smaller pieces
- Patches are irregular shapes like Planes, Cylinders or Spheres and can be subdivided
- both get converted into level geometry on export, where Patches will get subdivided by a given factor
- it is a good idea to organize subobjects into "func_groups"
  - select more than one object by holding SHIFT and left click the Brushes, Patches, Entities
  - right click and select "func_group"
  - the new object will turn into a blue color
  - you can still select single objects or create new func_groups from these
  - to select ALL objects of a func_group click one of it and press "SHIFT E" or "CTRL E"
- you can hide select objects with "H" and show all objects again with "SHIFT H"

======================================================================================================================

Useful tips:

- you can import external models to add more detail to the level geometry
- these models will also be rendered into the final map on export as regular level geometry
- important: Faces or Patches painted with the "CAULK" texture are NEVER exported into level geometry
- always paint ALL faces who are NOT visible with the CAULK texture to save draw calls on the object!
- it is also a good idea to create new Brushes with the CAULK texture only
- and then paint only the faces with different textures you want to see
  
======================================================================================================================

Brushes Manipulation: 

- a new brush can be created by just click and drag the left Mouse Button, in all 4 windows
- clicking a brush always select the whole brush
- to select a single Face hold CTRL and click the face with the right Mouse Button
- only a single face can be select at once
- to manipulate the Edges or Vertices of a Brush select it and press "E" or "V"
- the edges/vertices can then be dragged with the mouse or even with the "W" XYZ axis tool
- you can cut/split brushes selecting and pressing "X"
  - first you left click somewhere as a cutting start point (shown as "1")
  - second you left click somewhere as a cutting end point (shown as "2")
  - a line will be shown across the brush to show the cut
  - then either press Enter to cut out the part from the brush or SHIFT+Enter to split the Brush into two parts
  - or you can always leave the cut mode again by pressing "X" again
  
======================================================================================================================

Patches Manipulation:

- a new patch can be created from the "Curve" Menu
- with Patches you can create rounded objects like arches, gates and so on very easy
- a Patch consists of Rows and Columns
- select a Patch and press "V" to see the Vertices and Control Points between these
- for example of you create a simple 3x3 Patch and drag the center vertex upwards it will create a soft bulge
- Patches are always one-sided
- to make them solid use the additional "Cap Selection" features or the Thicken tool
- to "flip the normals" you can use "Curve > Matrix > Invert"

=====================================================================================================================