group.hpp

Go to the documentation of this file.

#pragma once

 
#include <array>
#include <cstdint>
#include <format>
#include <utility>
#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/types.hpp>
#include <wowlib/formats/common/version_slot.hpp>
#include <wowlib/formats/wmo/boundaries.hpp>
#include <wowlib/formats/wmo/group/chunks/geometry.hpp>
#include <wowlib/formats/wmo/group/chunks/header.hpp>
#include <wowlib/formats/wmo/group/chunks/light.hpp>
#include <wowlib/formats/wmo/group/chunks/liquid.hpp>
 
namespace wowlib::formats::wmo::group {
  using namespace wowlib::formats::wmo::group::chunks;

  struct [[
      =welder::weld,
      =welder::weld_as("WMOGroupBody"),
  WOWLIB_CS_FAMILY_SURFACE
      =welder::doc(R"(
        The MOGP container payload, abstract over the client version. Construct a
        concrete version with WMOGroupBody.for_version(expansion).)")
    ]] WMOGroupBodyBase {};

      `x: WMOGroup` annotation, `WMOGroup.for_version(expansion)`). It has no role
      in the C++ API, where you use the concrete WMOGroup<V> directly.
 
      @see https://wowdev.wiki/WMO */
  struct [[
      =welder::weld,
      =welder::weld_as("WMOGroup"),
  WOWLIB_CS_FAMILY_SURFACE
      =welder::doc(R"(
        One WMO group file, abstract over the client version. A group file holds
        the 3D model data (geometry, render batches, collision, liquid) for one
        unit of a world map object. Construct a concrete version with
        WMOGroup.for_version(expansion); the per-version WMOGroup* classes are
        subclasses. See https://wowdev.wiki/WMO.)")
    ]] WMOGroupBase {};
 
  namespace detail {
    // --- version-range trait bases (unwelded) ---------------------------------
    // One struct per availability range; members keep their chunk/since/doc/marks
    // (read off the declaring class, so flattening preserves them). Members are in
    // canonical order within a trait for readability; the serialization order is
    // the entity's ChunkOrder table, not the flatten order.

    struct GroupBodyCata {
      [[
        =chunk("MORB"),
        =since(builds::Cata),
        =formats::Optional,
        =formats::countMatches("batches"),
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Triangle-strip batch overrides (MORB, Cata+); same count as
                        MOBA.)")]]
      std::vector<RenderBatchOverride> batchOverrides;
 
      [[
        =chunk("MOTA"),
        =since(builds::Cata),
        =formats::Optional,
        =welder::doc(R"(Tangent arrays (MOTA, Cata+); offset-based layout, kept
                        opaque.)")]]
      ChunkBlob tangents;
 
      [[
        =chunk("MOBS"),
        =since(builds::Cata),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Shadow batches (MOBS, Cata+).")]]
      std::vector<ShadowBatch> shadowBatches;
    };

    struct GroupBodyMop {
      [[
        =chunk("MDAL"),
        =since(builds::MoP),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(R"(Ambient color override (MDAL, MoP+); a single color in
                        practice, replacing the header ambient. wowdev dates it
                        to WoD but flags that unverified — a 5.4.8 corpus sweep
                        found 421 of these, while sampled Cata and WotLK groups
                        carry none.)")]]
      std::vector<CArgb> ambientColorOverride;
    };


    struct GroupBodyWod {
      [[
        =chunk("MOPL"),
        =since(builds::WoD),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(R"(Terrain-cutting planes (MOPL, WoD+); requires the
                        can_cut_terrain flag, at most 32.)")]]
      std::vector<C4Plane> terrainCutPlanes;
    };

    struct GroupBodyLegion {
      [[
        =chunk("MOPB"),
        =since(builds::Legion_Alpha),
        =formats::Optional,
        =welder::doc(R"(Prepass batches (MOPB, Legion+); undocumented 24-byte
                        records, kept opaque.)")]]
      ChunkBlob prepassBatches;
 
      [[
        =chunk("MOLS"),
        =since(builds::Legion_Alpha),
        =formats::Optional,
        =welder::doc(
          R"(Spot lights (MOLS, Legion+); undocumented 56-byte records,
                        kept opaque.)")]]
      ChunkBlob spotLights;
 
      [[
        =chunk("MOLP"),
        =since(builds::Legion_Alpha),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Point lights (MOLP, Legion+).")]]
      std::vector<PointLight> pointLights;
    };

    struct GroupBody81 {
      [[
        =chunk("MLSS"),
        =since(builds::BfA_TidesOfVengeance),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Spot-light sets (MLSS, 8.1+): (first, count) ranges into MOLS
                        per doodad set.)")]]
      std::vector<LightSet> spotLightSets;
 
      [[
        =chunk("MLSP"),
        =since(builds::BfA_TidesOfVengeance),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Point-light sets (MLSP, 8.1+): (first, count) ranges into
                        MOLP per doodad set.)")]]
      std::vector<LightSet> pointLightSets;
 
      [[
        =chunk("MLSK"),
        =since(builds::BfA_TidesOfVengeance),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(R"(Point-light animation sets (MLSK, 8.1+): (first, count)
                        ranges into MOP2.)")]]
      std::vector<LightSet> pointLightAnimSets;
 
      [[
        =chunk("MOP2"),
        =since(builds::BfA_TidesOfVengeance),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Animated point lights (MOP2, 8.1+).")]]
      std::vector<PointLightAnim> pointLightAnims;
    };

    struct GroupBody83 {
      [[
        =chunk("MPVR"),
        =since(builds::BfA_VisionsOfNzoth_33775),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          "Particulate volume references (MPVR, 8.3+) into the root's MPVD.")]]
      std::vector<std::uint16_t> particulateRefs;
    };

    struct GroupBody90 {
      [[
        =chunk("MOVX"),
        =since(builds::SL_Alpha_33978),
        =formats::Optional,
        =formats::countMultipleOf(3),
        =formats::indexes("vertices"),
        =welder::mark::no_reassign,
        =welder::doc(
          R"(32-bit triangle vertex indices (MOVX, ~9.0+; the large-mesh
                        MOVI replacement).)")]]
      std::vector<std::uint32_t> largeIndices;
 
      [[
        =chunk("MAVR"),
        =since(builds::SL_Alpha_33978),
        =formats::Optional,
        =formats::indexesInRoot("ambientVolumes"),
        =welder::mark::no_reassign,
        =welder::doc(
          "Ambient volume references (MAVR, 9.0+) into the root's MAVD.")]]
      std::vector<std::uint16_t> ambientVolumeRefs;
 
      [[
        =chunk("MBVR"),
        =since(builds::SL_Alpha_33978),
        =formats::Optional,
        =formats::indexesInRoot("ambientBoxVolumes"),
        =welder::mark::no_reassign,
        =welder::doc("Box volume references (MBVR, 9.0+) into the root's MBVD.")
      ]]
      std::vector<std::uint16_t> boxVolumeRefs;
 
      [[
        =chunk("MFVR"),
        =since(builds::SL_Alpha_33978),
        =formats::Optional,
        =formats::indexesInRoot("fogs"),
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Fog volume references (MFVR, 9.0+) into the root's MFOG and
                        MFED.)")]]
      std::vector<std::uint16_t> fogVolumeRefs;
 
      [[
          =chunk("MNLR"),
          =since(builds::SL_Alpha_33978),
          =formats::Optional,
          =formats::indexesInRoot("newLights"),
          =welder::mark::no_reassign,
          =welder::doc(
            "New-light references (MNLR, 9.0+) into the root's MNLD.")]
      ]
      std::vector<std::uint16_t> newLightRefs;
    };

    struct GroupBody100 {
      [[
          =chunk("MOGX"),
          =since(builds::DF_Alpha),
          =formats::Optional,
          =welder::mark::no_reassign,
          =welder::doc(
            R"(Query face start (MOGX, 10.0+): the base subtracted from a
                        polygon index into MOQG. A single value in practice.)")]
      ]
      std::vector<std::uint32_t> queryFaceStart;
 
      [[
        =chunk("MPY2"),
        =since(builds::DF_Alpha),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          "Per-triangle material info v2 (MPY2, 10.0+; replaces MOPY).")]]
      std::vector<Poly2> polys2;
 
      [[
        =chunk("MOQG"),
        =since(builds::DF_Alpha),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Per-polygon ground types (MOQG, 10.0+), indexed by polygon
                        index minus the MOGX base.)")]]
      std::vector<std::uint32_t> queryFaces;
 
      // wowdev lists MOC2 without a version marker, but its consumers are the
      // Parallax and DF-shader-23 materials and the wiki section only appeared
      // 2022-10 (the Dragonflight beta window); corpus sweeps found ZERO MOC2
      // across 9,346 3.3.5a and 27,191 9.2.7 group files, so it is gated 10.0+.
      [[
        =chunk("MOC2"),
        =since(builds::DF_Alpha),
        =formats::Optional,
        =formats::countMatches("vertices"),
        =welder::mark::no_reassign,
        =welder::doc(
          R"(Second vertex-color-like weights (MOC2, 10.0+), used by the
                        parallax and shader-23 materials.)")]]
      std::vector<CImVector> vertexColors2;
    };
  }
 
  namespace detail {
    // The annotated entities; instantiate through the canonicalizing
    // aliases 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"(
          The MOGP payload for one client version: the group header and the geometry
          subchunks (triangles, vertices, normals, batches, BSP, liquid, lights).
          See https://wowdev.wiki/WMO.)")
      ]] WMOGroupBody
      : ChunkedFile<WMOGroupBody<V>>,
        WMOGroupBodyBase,
        Slot<V, builds::Cata, GroupBodyCata>,
        Slot<V, builds::MoP, GroupBodyMop>,
        Slot<V, builds::WoD, GroupBodyWod>,
        Slot<V, builds::Legion_Alpha, GroupBodyLegion>,
        Slot<V, builds::BfA_TidesOfVengeance, GroupBody81>,
        Slot<V, builds::BfA_VisionsOfNzoth_33775, GroupBody83>,
        Slot<V, builds::SL_Alpha_33978, GroupBody90>,
        Slot<V, builds::DF_Alpha, GroupBody100> {
      static constexpr ClientVersion Version = V;
 
      [[
        =formats::Header,
        =welder::doc("The group header leading the MOGP payload.")]]
      SMOGroupHeader<V> header{};
 
      // NOT countMatches("indices", 3): a 9.0+ large-mesh group carries its
      // indices in MOVX instead, leaving MOVI empty — the poly/face
      // relationship is checked against whichever list is active, in
      // validateExtra.
      [[
        =chunk("MOPY"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Per-triangle material info (MOPY).")]]
      std::vector<SMOPoly> polys;
 
      [[
        =chunk("MOVI"),
        =formats::Optional,
        =formats::countMultipleOf(3),
        =formats::indexes("vertices"),
        =welder::mark::no_reassign,
        =welder::doc("Triangle vertex indices (MOVI), three per triangle.")]]
      std::vector<std::uint16_t> indices;
 
      [[
        =chunk("MOVT"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Vertices (MOVT).")]]
      std::vector<C3Vector> vertices;
 
      [[
        =chunk("MONR"),
        =formats::Optional,
        =formats::countMatches("vertices"),
        =welder::mark::no_reassign,
        =welder::doc("Normals (MONR).")]]
      std::vector<C3Vector> normals;
 
      [[
        =chunk("MOTV"),
        =formats::Optional,
        =repeats(4),
        =formats::countMatches("vertices"),
        =welder::mark::only(welder::lang::py),
        =welder::doc(
          R"(Texture-coordinate sets (MOTV), up to four; the active count
                        is driven by the group flags (has_two_motv, has_three_motv).
                        Dragonflight groups ship a fourth set with no known flag
                        (983 roots' groups in the 10.2.7 fleet client — e.g.
                        Stormwind 8sw_portalroom01 group 2); it engages the
                        fourth slot here. Binds as a list of the filled sets,
                        by value.)")]]
      Repeated<std::vector<C2Vector>, 4> texcoords;
 
      [[
        =chunk("MOBA"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Render batches (MOBA).")]]
      std::vector<SMOBatch<V>> batches;
 
      [[
        =chunk("MOLR"),
        =formats::Optional,
        =formats::indexesInRoot("lights"),
        =welder::mark::no_reassign,
        =welder::doc("Light references into the root's MOLT (MOLR).")]]
      std::vector<std::uint16_t> lightRefs;
 
      [[
        =chunk("MODR"),
        =formats::Optional,
        =formats::indexesInRoot("doodadDefs"),
        =welder::mark::no_reassign,
        =welder::doc("Doodad references into the root's MODD (MODR).")]]
      std::vector<std::uint16_t> doodadRefs;
 
      [[
        =chunk("MOBN"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Collision BSP nodes (MOBN).")]]
      std::vector<CAaBspNode> bspNodes;
 
      [[
        =chunk("MOBR"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("BSP face indices (MOBR).")]]
      std::vector<std::uint16_t> bspFaceIndices;
 
      [[
        =chunk("MOCV"),
        =formats::Optional,
        =repeats(2),
        =formats::countMatches("vertices"),
        =welder::mark::only(welder::lang::py),
        =welder::doc(
          R"(Vertex-color layers (MOCV), up to two; the active count is
                        driven by the group flags (has_vertex_colors, has_two_mocv).
                        Binds as a list of the filled layers, by value.)")]]
      Repeated<std::vector<CImVector>, 2> vertexColors;
 
      [[
        =chunk("MLIQ"),
        =formats::Optional,
        =welder::doc(
          R"(Liquid data (MLIQ): a vertex grid and tile-flag grid with a
                        base position and material id.)")]]
      MLIQData liquid;
 
      [[
        =chunk("MORI"),
        =formats::Optional,
        =welder::mark::no_reassign,
        =welder::doc("Triangle-strip indices (MORI).")]]
      std::vector<std::uint16_t> transBatchIndices;
 
      // --- the repeated-chunk slot surface (MOTV, MOCV) ----------------------
      // The Repeated<> members above bind to Python only (a bespoke nanobind
      // caster lists the filled slots by value; no other rod can marshal the
      // wrapper). These accessors are the same surface for every language.
      // The getters are ZERO-COPY live views — a slot's std::vector object
      // has a stable address inside the Repeated's array storage, so a
      // reference_internal view is as safe as any vector member's; out of
      // range returns null/None instead of a Result (an expected cannot
      // carry a reference). Only set/append copy, where handing data in is
      // inherently a copy.
 
      [[=welder::doc("The number of filled texture-coordinate sets (MOTV), "
                     "0 to 4.")]]
      std::size_t texcoordSetCount() const { return texcoords.size(); }
 
      [[nodiscard]]
      [[=welder::return_policy(welder::rv::reference_internal),
        =welder::doc("One filled texture-coordinate set (MOTV), as a live "
                     "zero-copy view."),
        =welder::returns(
          "the set's coordinates, live; None/null when set is out of range")]]
      std::vector<C2Vector>* texcoordSet(
        std::size_t set [[=welder::doc("the filled-set index")]]) {
        return set < texcoords.size() ? &texcoords[set] : nullptr;
      }
 
      [[nodiscard]]
      [[=welder::doc("Replace one filled texture-coordinate set (MOTV)."),
        =welder::returns("nothing; errors when set is out of range")]]
      Result<void> setTexcoordSet(
        std::size_t set [[=welder::doc("the filled-set index")]],
        std::vector<C2Vector> coords
        [[=welder::doc("the coordinates, one per vertex")]]) {
        if (set >= texcoords.size())
          return makeError(ErrorCode::InvalidEntityState,
                            std::format(
                              "texcoord set {} out of range ({} filled)",
                              set, texcoords.size()));
        texcoords[set] = std::move(coords);
        return {};
      }
 
      [[nodiscard]]
      [[=welder::doc("Fill the next free texture-coordinate slot (MOTV)."),
        =welder::returns("nothing; errors when all four slots are filled")]]
      Result<void> appendTexcoordSet(
        std::vector<C2Vector> coords
        [[=welder::doc("the coordinates, one per vertex")]]) {
        auto* slot = texcoords.push();
        if (slot == nullptr)
          return makeError(ErrorCode::InvalidEntityState,
                            "all 4 texcoord slots are filled");
        *slot = std::move(coords);
        return {};
      }
 
      [[=welder::doc("Empty every texture-coordinate slot (MOTV).")]]
      void clearTexcoordSets() { texcoords.clear(); }
 
      [[=welder::doc("The number of filled vertex-color layers (MOCV), "
                     "0 to 2.")]]
      std::size_t vertexColorLayerCount() const { return vertexColors.size(); }
 
      [[nodiscard]]
      [[=welder::return_policy(welder::rv::reference_internal),
        =welder::doc("One filled vertex-color layer (MOCV), as a live "
                     "zero-copy view."),
        =welder::returns(
          "the layer's colors, live; None/null when layer is out of range")]]
      std::vector<CImVector>* vertexColorLayer(
        std::size_t layer [[=welder::doc("the filled-layer index")]]) {
        return layer < vertexColors.size() ? &vertexColors[layer] : nullptr;
      }
 
      [[nodiscard]]
      [[=welder::doc("Replace one filled vertex-color layer (MOCV)."),
        =welder::returns("nothing; errors when layer is out of range")]]
      Result<void> setVertexColorLayer(
        std::size_t layer [[=welder::doc("the filled-layer index")]],
        std::vector<CImVector> colors
        [[=welder::doc("the colors, one per vertex")]]) {
        if (layer >= vertexColors.size())
          return makeError(ErrorCode::InvalidEntityState,
                            std::format(
                              "vertex-color layer {} out of range ({} filled)",
                              layer, vertexColors.size()));
        vertexColors[layer] = std::move(colors);
        return {};
      }
 
      [[nodiscard]]
      [[=welder::doc("Fill the next free vertex-color layer slot (MOCV)."),
        =welder::returns("nothing; errors when both layers are filled")]]
      Result<void> appendVertexColorLayer(
        std::vector<CImVector> colors
        [[=welder::doc("the colors, one per vertex")]]) {
        auto* slot = vertexColors.push();
        if (slot == nullptr)
          return makeError(ErrorCode::InvalidEntityState,
                            "both vertex-color layers are filled");
        *slot = std::move(colors);
        return {};
      }
 
      [[=welder::doc("Empty every vertex-color layer slot (MOCV).")]]
      void clearVertexColorLayers() { vertexColors.clear(); }

      static constexpr std::array ChunkOrder = {
        fourcc("MOGX"),
        fourcc("MOPY"),
        fourcc("MPY2"),
        fourcc("MOVI"),
        fourcc("MOVX"),
        fourcc("MOVT"),
        fourcc("MONR"),
        fourcc("MOTV"),
        fourcc("MOBA"),
        fourcc("MOQG"),
        fourcc("MOLR"),
        fourcc("MODR"),
        fourcc("MOBN"),
        fourcc("MOBR"),
        fourcc("MOCV"),
        fourcc("MOC2"),
        fourcc("MLIQ"),
        fourcc("MORI"),
        fourcc("MORB"),
        fourcc("MOTA"),
        fourcc("MOBS"),
        fourcc("MDAL"),
        fourcc("MOPL"),
        fourcc("MOPB"),
        fourcc("MOLS"),
        fourcc("MOLP"),
        fourcc("MLSS"),
        fourcc("MLSP"),
        fourcc("MLSK"),
        fourcc("MOP2"),
        fourcc("MPVR"),
        fourcc("MAVR"),
        fourcc("MBVR"),
        fourcc("MFVR"),
        fourcc("MNLR"),
      };

      [[=welder::mark::exclude]]
      std::size_t activeIndexCount() const {
        if constexpr (requires { this->largeIndices; })
          if (!this->largeIndices.empty())
            return this->largeIndices.size();
        return indices.size();
      }

      [[=welder::mark::exclude]]
      void validateExtra(ValidationReport& report) const {
        const std::size_t indexCount = activeIndexCount();
 
        // one per-triangle record per three indices, against whichever index
        // list is active (MOVI, or MOVX on a large mesh)
        const auto perTriangle = [&](const auto& records,
                                      std::string_view what) {
          if (!records.empty() && records.size() * 3 != indexCount)
            report.addError(std::string{what},
                             std::format(
                               "count {} x 3 != the {} active triangle indices",
                               records.size(), indexCount));
        };
        perTriangle(polys, "polys");
        if constexpr (requires { this->polys2; })
          perTriangle(this->polys2, "polys2");
 
        // MOBA ranges: the client draws [startIndex, startIndex + count) and
        // uploads vertices up to maxIndex
        for (std::size_t i = 0; i < batches.size(); ++i) {
          const auto& batch = batches[i];
          if (batch.startIndex + batch.count > indexCount)
            report.addError(std::format("batches[{}]", i),
                             std::format(
                               "index range [{}, {}) overruns the {} indices",
                               batch.startIndex,
                               batch.startIndex + batch.count,
                               indexCount));
          if (batch.minIndex > batch.maxIndex)
            report.addError(std::format("batches[{}]", i),
                             std::format("min_index {} > max_index {}",
                                         batch.minIndex,
                                         batch.maxIndex));
          else if (!vertices.empty() && batch.maxIndex >= vertices.size())
            report.addError(std::format("batches[{}]", i),
                             std::format(
                               "max_index {} out of range: {} vertices",
                               batch.maxIndex, vertices.size()));
        }
 
        // the header's batch partition counts what MOBA holds
        const std::size_t declaredBatches = static_cast<std::size_t>(header.
            transBatchCount)
          + header.intBatchCount + header.extBatchCount;
        if (declaredBatches != batches.size())
          report.addError("header",
                           std::format("batch counts {}+{}+{} != {} batches",
                                       header.transBatchCount,
                                       header.intBatchCount,
                                       header.extBatchCount, batches.size()));
 
        // BSP: leaves reference faces through MOBR; children index MOBN
        const std::size_t faceCount = indexCount / 3;
        formats::detail::validateIndexElements(
          bspFaceIndices, faceCount, "bspFaceIndices",
          "faces", report);
        for (std::size_t i = 0; i < bspNodes.size(); ++i) {
          const auto& node = bspNodes[i];
          for (const std::int16_t child : {node.negChild, node.posChild})
            if (child != -1 && static_cast<std::size_t>(child) >= bspNodes.
              size())
              report.addError(std::format("bsp_nodes[{}]", i),
                               std::format("child {} out of range: {} nodes",
                                           child,
                                           bspNodes.size()));
          if (node.faceStart + node.nFaces > bspFaceIndices.size())
            report.addError(std::format("bsp_nodes[{}]", i),
                             std::format(
                               "face range [{}, {}) overruns the {} face indices",
                               node.faceStart, node.faceStart + node.nFaces,
                               bspFaceIndices.size()));
        }
 
        // header flags vs chunk presence: the base HasVertexColors flag with
        // NO layer at all makes the client consume absent data (error); the
        // multi-layer flags fall short in real files (corpus: a BfA kultiras
        // group ships HasTwoMocv with a single layer), so a shortfall there
        // only warns
        const auto flagWants = [&](GroupFlags flag,
                                    std::size_t have,
                                    std::size_t want,
                                    std::string_view what,
                                    ValidationSeverity severity) {
          if (hasFlag(header.flags, flag) && have < want)
            report.add(severity, std::string{what},
                       std::format(
                         "group flag {:#x} is set but only {} of {} {} present",
                         std::to_underlying(flag), have, want, what));
        };
        flagWants(GroupFlags::HasVertexColors, vertexColors.size(), 1,
                   "vertexColors",
                   ValidationSeverity::Error);
        flagWants(GroupFlags::HasTwoMocv, vertexColors.size(), 2,
                   "vertexColors",
                   ValidationSeverity::Warning);
        flagWants(GroupFlags::HasTwoMotv, texcoords.size(), 2, "texcoords",
                   ValidationSeverity::Warning);
        flagWants(GroupFlags::HasThreeMotv, texcoords.size(), 3, "texcoords",
                   ValidationSeverity::Warning);
        if (!vertexColors.empty() && !hasFlag(
          header.flags, GroupFlags::HasVertexColors))
          report.addWarning("vertexColors",
                             "present but the has_vertex_colors group flag is clear");
 
        // MLIQ: the grids must match their declared dimensions, and the flag
        // decides whether the client reads the chunk at all
        if (!liquid.empty()) {
          const auto expect = [&](const auto& grid,
                                  const C2IVector& dim,
                                  std::string_view what) {
            const std::size_t cells =
              dim.x < 0 || dim.y < 0
                ? 0
                : static_cast<std::size_t>(dim.x) * static_cast<std::size_t>(dim
                  .y);
            if (grid.size() != cells)
              report.addError(std::format("liquid.{}", what),
                               std::format("count {} != {}x{} grid",
                                           grid.size(), dim.x, dim.y));
          };
          expect(liquid.vertices, liquid.vertsDim, "vertices");
          expect(liquid.tiles, liquid.tilesDim, "tiles");
          if (liquid.vertsDim.x != liquid.tilesDim.x + 1
            || liquid.vertsDim.y != liquid.tilesDim.y + 1)
            report.addError("liquid",
                             std::format(
                               "vertex grid {}x{} is not one larger per axis than the "
                               "tile grid {}x{}",
                               liquid.vertsDim.x, liquid.vertsDim.y,
                               liquid.tilesDim.x, liquid.tilesDim.y));
          if (!hasFlag(header.flags, GroupFlags::HasLiquid))
            report.addWarning("liquid",
                               "present but the has_liquid group flag is clear");
        }
 
        // WoD+ terrain-cut planes: the client caps them at 32 and gates on flags2
        if constexpr (requires { this->terrainCutPlanes; }) {
          if (this->terrainCutPlanes.size() > 32)
            report.addError("terrainCutPlanes",
                             std::format(
                               "{} planes exceed the client's cap of 32",
                               this->terrainCutPlanes.size()));
          if (!this->terrainCutPlanes.empty()
            && !hasFlag(header.flags2, GroupFlags2::CanCutTerrain))
            report.addWarning("terrainCutPlanes",
                               "present but the can_cut_terrain flag2 is clear");
        }
 
        // 8.1+ light sets: (offset, count) ranges into their referenced chunks
        if constexpr (requires { this->pointLightSets; }) {
          const auto setRanges = [&](const auto& sets,
                                      const auto& target,
                                      std::string_view member,
                                      std::string_view what) {
            for (std::size_t i = 0; i < sets.size(); ++i)
              if (sets[i].offset + sets[i].count > target.size())
                report.addError(std::format("{}[{}]", member, i),
                                 std::format(
                                   "range [{}, {}) overruns the {} {}",
                                   sets[i].offset,
                                   sets[i].offset + sets[i].count,
                                   target.size(), what));
          };
          setRanges(this->pointLightSets, this->pointLights,
                     "pointLightSets",
                     "point lights");
          setRanges(this->pointLightAnimSets, this->pointLightAnims,
                     "pointLightAnimSets", "animated point lights");
        }
      }
    };

    template <ClientVersion V>
    struct [[
        =welder::weld,
        =welder::doc(R"(
          One WMO group file for one client version: the format version and the MOGP
          container holding the group's geometry (see WMOGroupBody). A group holds
          the 3D model data for one unit of a world map object. See
          https://wowdev.wiki/WMO.)")
      ]] WMOGroup : ChunkedFile<WMOGroup<V>>, WMOGroupBase {
      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("MOGP"),
        =formats::Container,
        =welder::doc("The MOGP container: group header and geometry.")]]
      // the raw sibling is intentional: WMOGroup and WMOGroupBody share
      // WmoGroupPivots, so at a canonical V they are the same type the
      // canonicalizing alias would name
      WMOGroupBody<V> body{};
    };
  }

  template <ClientVersion V>
  using WMOGroupBody =
  group::detail::WMOGroupBody<canonicalVersion(V, WmoGroupPivots,
                                                WmoVersions)>;

  template <ClientVersion V>
  using WMOGroup =
  group::detail::WMOGroup<canonicalVersion(V, WmoGroupPivots, WmoVersions)>;
}