root.hpp

Go to the documentation of this file.

#pragma once

 
#include <array>
#include <cstdint>
#include <cstring>
#include <format>
#include <span>
#include <string_view>
#include <vector>
 
#include <wowlib/core/client_builds.hpp>
#include <wowlib/core/client_version.hpp>
#include <wowlib/core/lang.hpp>
#include <wowlib/formats/common/chunked_file.hpp>
#include <wowlib/formats/common/fourcc.hpp>
#include <wowlib/formats/common/string_block.hpp>
#include <wowlib/formats/common/types.hpp>
#include <wowlib/formats/common/version_slot.hpp>
#include <wowlib/formats/wmo/boundaries.hpp>
#include <wowlib/formats/wmo/root/chunks/doodad.hpp>
#include <wowlib/formats/wmo/root/chunks/environment.hpp>
#include <wowlib/formats/wmo/root/chunks/header.hpp>
#include <wowlib/formats/wmo/root/chunks/light.hpp>
#include <wowlib/formats/wmo/root/chunks/material.hpp>
#include <wowlib/formats/wmo/root/chunks/structure.hpp>
 
namespace wowlib::formats::wmo::root {
  using namespace wowlib::formats::wmo::root::chunks;

  struct [[
      =welder::weld,
      =welder::weld_as("WMORoot"),
      WOWLIB_CS_FAMILY_SURFACE
      =welder::doc(R"(
        A WMO root file, abstract over the client version. The root file lists the
        object's shared data (materials, doodads, portals, lights, fog and the
        group table); the geometry lives in the separate group files. Construct a
        concrete version with WMORoot.for_version(expansion); the per-version
        WMORoot* classes are subclasses. See https://wowdev.wiki/WMO.)")
    ]] WMORootBase {};
 
  namespace detail {
    // --- version-range trait bases (unwelded) ---------------------------------
    // One struct per availability range; members keep their chunk/since/until/doc/
    // marks (read off the declaring class, so flattening preserves them). Member
    // order within a trait is for readability; the serialization order is the
    // entity's ChunkOrder table, not the flatten order.

    struct RootLegion {
      [[
        =chunk("GFID"),
        =since(builds::Legion_Alpha),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(R"(Group file FileDataIDs (GFID, Legion+), in group order;
                        repeated per LOD level for LOD WMOs.)")]]
      std::vector<std::uint32_t> groupFdids;
    };

    struct Root73 {
      [[
        =chunk("MOUV"),
        =since(builds::Legion_ShadowsOfArgus_24473),
        =formats::Optional,
        =formats::countMatches("materials"),
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Texture-coordinate translation animations (MOUV, 7.3+), one
                        per material.)")]]
      std::vector<UVAnimation> uvAnimations;
    };

    struct RootPre83 {
      [[
        =chunk("MOTX"),
        =until(builds::BfA_VisionsOfNzoth_32044),
        =formats::Optional,
        =welder::doc(
          R"(Texture filenames (MOTX); the material texture fields index
                        into this block. Pre-8.1 it is the primary reference; in
                        8.1/8.2 its presence marks the fallback mode (MOMT texture
                        fields are MOTX offsets, not FileDataIDs). Removed at 8.3,
                        when the client dropped name-based texture loading.)")]]
      StringBlock textures;
 
      [[
        =chunk("MODN"),
        =until(builds::BfA_VisionsOfNzoth_32044),
        =formats::Optional,
        =welder::doc(
          R"(Doodad (M2) filenames (MODN); MODD entries index into this
                        block. Pre-8.1 primary, 8.1/8.2 fallback (see textures).
                        Removed at 8.3 alongside MOTX; MODI (doodad FileDataIDs)
                        replaces it.)")]]
      StringBlock doodadNames;
    };

    struct Root81 {
      [[
        =chunk("MOSI"),
        =since(builds::BfA_TidesOfVengeance),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Skybox FileDataID (MOSI, 8.1+).")]]
      std::vector<std::uint32_t> skyboxFdid;
 
      [[
        =chunk("MODI"),
        =since(builds::BfA_TidesOfVengeance),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          "Doodad FileDataIDs (MODI, 8.1+; replaces doodad_names).")]]
      std::vector<std::uint32_t> doodadFdids;
    };

    struct Root83 {
      [[
        =chunk("MDDI"),
        =since(builds::BfA_VisionsOfNzoth_32044),
        =formats::Optional,
        =formats::countMatches("doodadDefs"),
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Per-doodad color multipliers (MDDI, 8.3+), applied to the
                        MODD color.)")]]
      std::vector<float> doodadColorMults;
 
      [[
        =chunk("MPVD"),
        =since(builds::BfA_VisionsOfNzoth_32044),
        =formats::Optional,
        =welder::doc(
          R"(Particulate volume data (MPVD, 8.3+); undocumented layout,
                        kept opaque.)")]]
      ChunkBlob particulateVolumes;
 
      [[
        =chunk("MAVG"),
        =since(builds::BfA_VisionsOfNzoth_32044),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Global ambient volumes (MAVG, 8.3+); position and radii are
                        zero, selected by doodad set.)")]]
      std::vector<AmbientVolume> globalAmbientVolumes;
 
      [[
        =chunk("MAVD"),
        =since(builds::BfA_VisionsOfNzoth_32044),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Ambient volumes (MAVD, 8.3+), overriding the header ambient
                        color inside their radius.)")]]
      std::vector<AmbientVolume> ambientVolumes;
 
      [[
        =chunk("MBVD"),
        =since(builds::BfA_VisionsOfNzoth_32044),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Box ambient volumes (MBVD, 8.3+); read only when MAVG/MAVD is
                        present.)")]]
      std::vector<AmbientBoxVolume> ambientBoxVolumes;
    };

    struct Root90 {
      [[
        =chunk("MFED"),
        =since(builds::SL_Alpha_33978),
        =formats::Optional,
        =formats::countMatches("fogs"),
        =welder::mark::no_reassign,
        =welder::doc("Fog extra data (MFED, 9.0+); same count as MFOG.")]]
      std::vector<FogExtra> fogExtras;
 
      [[
        =chunk("MGI2"),
        =since(builds::SL_Alpha_33978),
        =formats::Optional,
        =formats::countMatches("groupInfos"),
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Group info v2 (MGI2, 9.0+); same count as MOGI, overrides LOD
                        selection.)")]]
      std::vector<GroupInfo2> groupInfos2;
 
      [[
        =chunk("MNLD"),
        =since(builds::SL_Alpha_33978),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(R"(Dynamic lights (MNLD, 9.0+): torch fires, window light
                        projection and the like.)")]]
      std::vector<NewLight> newLights;
 
      [[
        =chunk("MDDL"),
        =since(builds::SL_Alpha_33978),
        =formats::Optional,
        =welder::doc(R"(Detail (ground-effect) doodad layers (MDDL, 9.0+);
                        variable-length RLE layout, kept opaque.)")]]
      ChunkBlob detailDoodads;
    };

    struct Root91 {
      [[
        =chunk("MOLV"),
        =since(builds::SL_ChainsOfDomination),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Directional-gradient light extensions (MOLV, 9.1+); entries
                        reference lights by index.)")]]
      std::vector<LightExtension> lightExtensions;
    };

    struct Root110 {
      [[
        =chunk("MOM3"),
        =since(builds::TWW_Alpha),
        =formats::Optional,
        =welder::doc(
          R"(M3 materials (MOM3, 11.0+); when present, MOMT is ignored. An
                        m3SI blob, kept opaque.)")]]
      ChunkBlob materialsM3;
    };

    struct Root111 {
      [[
        =chunk("MOPE"),
        =since(builds::TWW_Undermined),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Portal extra data (MOPE, 11.1+).")]]
      std::vector<PortalExtra> portalExtras;
    };
  }
 
  namespace detail {
    // The annotated entity; instantiate through the canonicalizing alias
    // below, never directly. The trait bases share this namespace, so they
    // need no qualifier (a bare detail:: would be ambiguous against
    // chunks::detail via the using-directive).
    template <ClientVersion V>
    struct [[
        =welder::weld,
        =welder::doc(R"(
          A WMO root file for one client version. The root lists the object's shared
          data — materials and textures, doodad (M2) sets and placements, portals,
          lights, fog, culling volumes and the per-group table — while the 3D
          geometry lives in the separate group files (see WMOGroup). An instance read
          from a client file rewrites byte-for-byte until modified. See
          https://wowdev.wiki/WMO.)")
      ]] WMORoot
      : ChunkedFile<WMORoot<V>>,
        WMORootBase,
        Slot<V, builds::Legion_Alpha, RootLegion>,
        Slot<V, builds::Legion_ShadowsOfArgus_24473, Root73>,
        Slot<V, ClientVersion{0, 0, 0, 0}, RootPre83, builds::BfA_VisionsOfNzoth_32044>,
        Slot<V, builds::BfA_TidesOfVengeance, Root81>,
        Slot<V, builds::BfA_VisionsOfNzoth_32044, Root83>,
        Slot<V, builds::SL_Alpha_33978, Root90>,
        Slot<V, builds::SL_ChainsOfDomination, Root91>,
        Slot<V, builds::TWW_Alpha, Root110>,
        Slot<V, builds::TWW_Undermined, Root111> {
      static constexpr ClientVersion Version = V;
 
      [[
        =chunk("MVER"),
        =formats::expectedValue(WmoVersionV17),
        =welder::doc("The WMO format version; 17 for every supported client.")]]
      std::uint32_t mver = WmoVersionV17;
 
      [[
        =chunk("MOHD"),
        =welder::doc("The root header (MOHD).")]]
      SMOHeader header{};
 
      [[
        =chunk("MOMT"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Materials (MOMT).")]]
      std::vector<SMOMaterial> materials;
 
      [[
        =chunk("MOGN"),
        =formats::Optional,
        =welder::doc("Group names (MOGN), referenced by byte offset.")]]
      StringBlock groupNames;
 
      [[
        =chunk("MOGI"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Per-group info (MOGI).")]]
      std::vector<SMOGroupInfo> groupInfos;
 
      [[
        =chunk("MOSB"),
        =formats::Optional,
        =welder::doc(
          R"(Skybox filename (MOSB); raw bytes — files pad it to 4-byte
                        alignment. skybox_fdid (MOSI, 8.1+) functionally replaces
                        it, but the chunk never left the corpus: a 9.2.7 client
                        survey (2026-08-08) found MOSB in 5404 of 8148 roots —
                        always empty, never alongside MOSI — so it stays on every
                        version as the no-skybox marker exporters still emit.)")
      ]]
      ChunkBlob skyboxName;
 
      [[
        =chunk("MOPV"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Portal vertices (MOPV).")]]
      std::vector<C3Vector> portalVertices;
 
      [[
        =chunk("MOPT"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Portals (MOPT).")]]
      std::vector<SMOPortal> portals;
 
      [[
        =chunk("MOPR"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Portal references from groups (MOPR).")]]
      std::vector<SMOPortalRef> portalRefs;
 
      [[
        =chunk("MOVV"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Visible block vertices (MOVV).")]]
      std::vector<C3Vector> visibleBlockVertices;
 
      [[
        =chunk("MOVB"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Visible blocks (MOVB).")]]
      std::vector<SMOVisibleBlock> visibleBlocks;
 
      [[
        =chunk("MOLT"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Lights (MOLT).")]]
      std::vector<SMOLight> lights;
 
      [[
        =chunk("MODS"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Doodad sets (MODS).")]]
      std::vector<SMODoodadSet> doodadSets;
 
      [[
        =chunk("MODD"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Doodad placements (MODD).")]]
      std::vector<SMODoodadDef> doodadDefs;
 
      [[
        =chunk("MFOG"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Fog volumes (MFOG).")]]
      std::vector<SMOFog> fogs;
 
      [[
        =chunk("MCVP"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Convex volume planes (MCVP); transports mostly.")]]
      std::vector<C4Plane> convexVolumePlanes;
 
      [[
        =chunk("MOMX"),
        =formats::Optional,
        =welder::doc("MOMX (11.x, undocumented purpose); preserved opaque.")]]
      ChunkBlob momx;

      static constexpr std::array ChunkOrder = {
        fourcc("MVER"),
        fourcc("MOHD"),
        fourcc("MOTX"),
        fourcc("MOMT"),
        fourcc("MOM3"),
        fourcc("MOUV"),
        fourcc("MOGN"),
        fourcc("MOGI"),
        fourcc("MOSB"),
        fourcc("MOSI"),
        fourcc("MOPV"),
        fourcc("MOPT"),
        fourcc("MOPR"),
        fourcc("MOPE"),
        fourcc("MOVV"),
        fourcc("MOVB"),
        fourcc("MOLT"),
        fourcc("MOLV"),
        fourcc("MODS"),
        fourcc("MODN"),
        fourcc("MODI"),
        fourcc("MODD"),
        fourcc("MFOG"),
        fourcc("MCVP"),
        fourcc("GFID"),
        fourcc("MDDI"),
        fourcc("MPVD"),
        fourcc("MAVG"),
        fourcc("MAVD"),
        fourcc("MBVD"),
        fourcc("MFED"),
        fourcc("MGI2"),
        fourcc("MNLD"),
        fourcc("MDDL"),
        fourcc("MOMX"),
      };

      [[=welder::mark::exclude]]
      void patchChunk(std::uint32_t fourccMagic, std::span<std::byte> payload) const {
        if (fourccMagic != fourcc("MOHD") || payload.size() < sizeof(SMOHeader)) return;
        SMOHeader h;
        std::memcpy(&h, payload.data(), sizeof h);
        h.nGroups = static_cast<std::uint32_t>(groupInfos.size());
        h.nPortals = static_cast<std::uint32_t>(portals.size());
        h.nDoodadSets = static_cast<std::uint32_t>(doodadSets.size());
        std::memcpy(payload.data(), &h, sizeof h);
      }

      [[=welder::mark::exclude]]
      void validateExtra(ValidationReport& report) const {
        // MODS: (startIndex, count) ranges into MODD
        for (std::size_t i = 0; i < doodadSets.size(); ++i)
          if (doodadSets[i].startIndex + doodadSets[i].count > doodadDefs.size())
            report.addError(std::format("doodad_sets[{}]", i),
                            std::format("range [{}, {}) overruns the {} doodad placements", doodadSets[i].startIndex,
                                        doodadSets[i].startIndex + doodadSets[i].count, doodadDefs.size()));
 
        // MODD name references: MODN byte offsets pre-8.3, MODI indices once
        // the names block is gone (8.1/8.2 carry both - an engaged MODN marks
        // the by-name fallback mode, so it stays authoritative)
        constexpr std::size_t maxReported = 8;
        std::size_t badNames = 0;
        for (std::size_t i = 0; i < doodadDefs.size(); ++i) {
          const std::uint32_t name = doodadDefs[i].nameIndex();
          bool resolvable = false;
          std::string_view space;
          std::size_t bound = 0;
          if constexpr (requires { this->doodadNames; })
            if (!this->doodadNames.empty()) {
              resolvable = name < this->doodadNames.size();
              space = "doodad_names blob byte";
              bound = this->doodadNames.size();
            }
          if constexpr (requires { this->doodadFdids; })
            if (space.empty()) {
              resolvable = name < this->doodadFdids.size();
              space = "doodad FileDataID";
              bound = this->doodadFdids.size();
            }
          if (space.empty()) {
            resolvable = false;
            space = "doodad name source (none engaged)";
          }
          if (!resolvable && ++badNames <= maxReported)
            report.addError(std::format("doodadDefs[{}]", i),
                            std::format("name reference {} does not resolve: {} count {}", name, space, bound));
        }
        if (badNames > maxReported)
          report.addError("doodadDefs", std::format(
                            "... and {} more unresolvable name " "references", badNames - maxReported));
 
        // MOPT: vertex ranges into MOPV
        for (std::size_t i = 0; i < portals.size(); ++i)
          if (portals[i].startVertex + portals[i].count > portalVertices.size())
            report.addError(std::format("portals[{}]", i),
                            std::format("vertex range [{}, {}) overruns the {} portal vertices",
                                        portals[i].startVertex, portals[i].startVertex + portals[i].count,
                                        portalVertices.size()));
 
        // MOPR: indices into MOPT and MOGI
        for (std::size_t i = 0; i < portalRefs.size(); ++i) {
          if (portalRefs[i].portalIndex >= portals.size())
            report.addError(std::format("portal_refs[{}]", i),
                            std::format("portal_index {} out of range: {} portals", portalRefs[i].portalIndex,
                                        portals.size()));
          if (portalRefs[i].groupIndex >= groupInfos.size())
            report.addError(std::format("portal_refs[{}]", i),
                            std::format("group_index {} out of range: {} groups", portalRefs[i].groupIndex,
                                        groupInfos.size()));
        }
 
        // MOVB: vertex ranges into MOVV
        for (std::size_t i = 0; i < visibleBlocks.size(); ++i)
          if (visibleBlocks[i].firstVertex + visibleBlocks[i].count > visibleBlockVertices.size())
            report.addError(std::format("visible_blocks[{}]", i), std::format(
                              "vertex range [{}, {}) overruns the {} visible block " "vertices",
                              visibleBlocks[i].firstVertex, visibleBlocks[i].firstVertex + visibleBlocks[i].count,
                              visibleBlockVertices.size()));
 
        // MOGI: group-name offsets into MOGN (-1 marks the unnamed group)
        for (std::size_t i = 0; i < groupInfos.size(); ++i)
          if (groupInfos[i].nameOffset >= 0 && static_cast<std::size_t>(groupInfos[i].nameOffset) >= groupNames.
            size())
            report.addError(std::format("groupInfos[{}]", i),
                            std::format("name offset {} out of range: {} blob bytes", groupInfos[i].nameOffset,
                                        groupNames.size()));
 
        // MOMT texture references are MOTX byte offsets while the names block
        // is engaged (pre-8.1 always; 8.1/8.2 fallback mode). Only texture1
        // is validated: real vanilla/TBC-era files ship raw float garbage in
        // the texture2/texture3 slots (corpus: Stormwind.wmo, Subway.wmo),
        // which the client evidently never dereferences.
        if constexpr (requires { this->textures; })
          if (!this->textures.empty())
            for (std::size_t i = 0; i < materials.size(); ++i)
              if (materials[i].texture1 >= this->textures.size())
                report.addError(std::format("materials[{}]", i),
                                std::format("texture_1 offset {} out of range: {} blob bytes", materials[i].texture1,
                                            this->textures.size()));
 
        // MOLV (9.1+): entries reference lights by index
        if constexpr (requires { this->lightExtensions; })
          for (std::size_t i = 0; i < this->lightExtensions.size(); ++i)
            if (const auto index = this->lightExtensions[i].lightIndex; index < 0 || static_cast<std::size_t>(index)
              >= lights.size())
              report.addError(std::format("light_extensions[{}]", i),
                              std::format("light_index {} out of range: {} lights", index, lights.size()));
      }
    };
  }

  template <ClientVersion V>
  using WMORoot = detail::WMORoot<canonicalVersion(V, WmoRootPivots, WmoVersions)>;
}