Editing Map

Game levels in Weissblatt are commonly called '''Maps''' while the act of creating a map is called '''Mapping'''. Like with many multiplayer PC games, this terminology is inherited from [[wikipedia:Doom_(1993_video_game)|Doom]].

This article describes the technical aspect of Weissblatt's map format. If you're looking to get started building maps, visit [[Guide:Map Design]].

== Map format Basics ==
Weissblatt supports two different map formats:
# ''Legacy maps'' (sometimes called ''binary maps'') - This format is inherited from Sonic Robo Blast 2 and is generally advised against when mapping. Weissblatt will no longer develop it an thus a lot of features will be unavailable when using it.
# ''[https://doomwiki.org/wiki/UDMF UDMF] maps'', upon which Weissblatt is built. UDMF stands for '''U'''niversal '''D'''oom '''M'''ap '''F'''ormat - a text-based map description format developed by the Doom source port community.
To fully understand Weissblatt's map formats, you should understand the concepts of how (modern) Doom engines construct their maps in the abstract:

=== Sectors, Walls and Linedefs ===
In short, Doom maps are essentially two-dimensional top-down vertex structures with added properties for height and other gameplay mechanics.

''Walls'' are lines between two or more vertices on a map. Each wall can either be solid with a single texture assigned to it or it can be a two-sided ''Linedef'' seperating two sectors. Depending on the two sectors' floor and ceiling heights, each Linedef may be assigned a top, middle or bottom texture per-side. Linedefs can also be equipped a ''Type'' which can trigger various effects at runtime. 

Walls can also have multiple ''flags'', which can have effects on movement and rendering such as <code>Peg Midtexture</code> or <code>Impassable</code>. 

''Sectors'' are polygons made up of multiple walls through which the player can move. Sectors can be assigned 

* Top and Bottom [[Flat]] [ceiling/floor texture]
* Floor and ceiling height
* Light level
* Colored lighting (depending on the map format)
* A numeric ''Tag'' (multiple for UDMF maps)
* Various unique effects, such as damage upon touch

==== Tagging ====
''Further Reading: [[:Category:Linedef Type]]''

Walls, sectors, and Things within a map can be ''tagged'' using an integer number. Depending on the sector effect and Linedef type, Sectors and Linedefs with matching tags may trigger one another, given trigger-dependent conditions, such as one or all players entering a sector or (not) having collected all [[Chakra Shards]] when doing so. Matching tags can also be used for triggers relating to Things.

==== Binary Space partitioning ====
Simply put, Doom maps are heavily preprocessed using a so-called ''node builder'' before being included in the game. A modern node builder with UDMF support is [https://doomwiki.org/wiki/ZDBSP ZDBSP] from the ZDoom source port.

Node builders implement an algorithm called ''Binary Space Partitioning'' or BSP. Through BSP, all map sectors are subdivided into convex shapes and assembled into a binary tree. The game engine can then per-frame traverse the leaves of any given branch of that tree to determine all potentially visible walls.

<more TBA>

==== Floor-over-Floor (FOF) ====
''Floor-over-Floor sectors'' or FOFs are an extension upon the original Doom format which allows for multi-floor sectors like hovering bridges. To achieve this, a separate ''control sector'' is created outside of the play area to which other host sectors are tagged. Triggered through an [[FOF Linedef Type]], the engine then uniformly applies a subdivision in between the host sector's space based on the control sector's assigned textures and flats.

==== Polyobjects ====
''Polyobjects'' are an extension to use pieces of predefined map geometry as if they were map objects. This allows for many more gameplay mechanics such as spinning geometry, sideways crushers or swinging doors.

=== Things and MOBJs ===
''Further reading: [[:Category:Thing]] | [[:Category:MOBJ]]''

''Things'' are static spawners for game objects placed within sectors. Upon map load, things are initialized and spawn their respective MOBJs. Things can also be given ''parameters'' and ''flags'', which may modify the Thing's behavior. Since Things are only initialized upon map load, this requires some gameplay design considerations when placing enemies such as [https://doomwiki.org/wiki/Monster_closet monster closets].

MOBJs are only spawned at runtime and represent game objects, such as enemies, gems or decorative sprites. MOBJs contain their own Object flags, which are distinct from Thing flags.

=== Fracunits ===
''A fracunit'' is the smallest possible distance in a map. At default scale it corresponds to one texel [pixel on a texture]. In general, Weissblatt assumes a scale of 64 Fracunits per one meter.  

== UDMF Mapping ==
''[https://doomwiki.org/wiki/UDMF UDMF]'' stands for ''Universal Doom Map Format''. It is a textual map format developed for near-infinite extensibility within modern Doom engine source ports. It is not backwards compatible to older formats.

A UDMF map consists of the following lumps within a WAD or [[PK3]], :

* <code>MAPxx</code> - A simple marker lump denoting the map number. Required.
* <code>TEXTMAP</code> contains information on the map geometry (vertices, linedefs, sectors), SIDEDEFs and Things. Despite UDMF being a text format, it is not intended to be read or edited manually. Instead it should be parsed by dedicated programs such as Ultimate Zone Builder, SLADE or Weissblatt's game engine.
* <code>ZNODES</code> - BSP information generated by  [https://doomwiki.org/wiki/ZDBSP ZDBSP] (as it's the only node builder with UDMF support). If missing, many Doom engines expect it to be generated on-the-fly by a ZDBSP instance built into the engine.

* <code>ENDMAP</code> - a simple marker lump. Required

=== TEXTMAP specification ===
Weissblatt supports UDMF <code>TEXTMAP</code>s of namespace <code>weissblatt</code> and <code>srb2</code>.

== Legacy Mapping ==
The Legacy map format was inherited from Sonic Robo Blast 2 and is now considered deprecated. Weissblatt does not develop it any further and merely maintains it for backwards compatibility. As such the format will be missing many features compared to Weissblatt's UDMF implementation.

Like traditional Doom maps, legacy maps are a ''binary map format'', meaning all data is encoded directly into byte structures. This brings some limitations:

# Each Sector/Linedef/Thing can only be assigned one tag
# Texture/Flat/Thing scaling is not supported
# Flat alignment/rotation is not supported
# Only 65536 tags are allowed.
# The total amount of possible walls, Linedefs, Sectors, etc. within a map may be limited.
# <TBA>

Binary maps are made up of the following lumps:

# <code>THINGS</code>
# <code>VERTEXES</code>
# <code>LINEDEFS</code>
# <code>SIDEDEFS</code>
# <code>SECTORS</code>

=== Reserved specialty tags ===
The Legacy map format does not support multitagging and is generally less flexible when it comes to tagging Things. To get around this, some Tag numbers are given special treatment:
{| class="wikitable"
|+
!Tag
!SOC/Lua Constant
!Effect
|-
|649
|<code>LE_AXE</code>
|Triggered when
|-
|650
|<code>LE_KOOPA</code>
|Triggered when <++> is defeated. Raises matching sectors' ceiling to the highest adjacent ceiling
|-
|680
|<code>LE_CAPSULE0</code>
| rowspan="3" |Triggered when a boss is defeated.
|-
|681
|<code>LE_CAPSULE1</code>
|-
|682
|<code>LE_CAPSULE2</code>
|-
|4200
|<code>LE_BRAKPLATFORM</code>
|Triggered after six hits to the alternate form of [[KOTU]].
|-
|32000
|<code>LE_TURRET</code>
|Triggered when a turret is destroyed.
|-
|65530 (-6)
|<code>LE_BRAKVILEATACK</code>
|Triggered when [[KOTU]] starts casting magic.
|-
|65531 (-5)
|<code>LE_BOSS4DROP</code>
|Triggered when <++> drops <++>
|-
|65532 (-4)
|<code>LE_BOSSDEAD</code>
|Triggered when any Boss is defeated
|-
|65533 (-3)
|<code>LE_ALLBOSSDEAD</code>
|Triggered when all Bosses are defeated
|-
|65534 (-2)
|<code>LE_PINCHPHASE</code>
|Triggered when Bosses switch into their pinch phase
|-
|65535 (-1)
|
|Affect every sector in a map
|-
|
|<code>LE_PARAMWIDTH</code>
|
|}

=== Conversion to UDMF ===
Legacy maps can be converted to UDMF maps: Simply launch the game using <code>-textmap</code> and <code>-warp <MAPNUM></code>. After you quit the game, the engine will save a UDMF conversion of your map to the file <code>TEXTMAP</code> within your game directory. You can use SLADE or Ultimate Zone Builder to recompile the newly-generated <code>TEXTMAP</code> into a proper UDMF map.
[[Category:Technology]]