m2_bindings.cpp

// SPDX-License-Identifier: BSD-3-Clause
// Copyright (c) 2026 Fernando Sahmkow
//
// AUTOGENERATED by tools/codegen — do not edit by hand.
// Regenerate via:  python -m tools.codegen.codegen m2 --backend pybind11
//
// Source headers and `@bind` annotations live under include/whiteout/.
//
// Include order matters here:
//   1. pybind11/pybind11.h   sets up the base library
//   2. project headers       define whiteout::u32 et al used inside MAKE_OPAQUE
//   3. PYBIND11_MAKE_OPAQUE  opts out of stl.h's auto-conversion for our vectors
//   4. pybind11/stl.h, stl_bind.h   honor the opaque declarations

#include <pybind11/pybind11.h>

#include <array>
#include <cstdint>
#include <optional>
#include <sstream>
#include <string>
#include <vector>

#include <whiteout/vector_types.h>
#include <whiteout/models/m2/types.h>
#include <whiteout/models/m2/structures/base.h>
#include <whiteout/models/m2/structures/extensions.h>
#include <whiteout/models/m2/structures/phys.h>
#include <whiteout/models/m2/structures/bone_overrides.h>
#include <whiteout/models/m2/structures/skin.h>
#include <whiteout/models/m2/structures.h>
#include <whiteout/models/m2/parser.h>
#include <whiteout/models/m2/phys_file.h>
#include <whiteout/models/m2/bone_file.h>
#include <whiteout/models/m2/writer.h>
#include <whiteout/interfaces.h>

PYBIND11_MAKE_OPAQUE(std::vector<whiteout::i16>);
PYBIND11_MAKE_OPAQUE(std::vector<std::string>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::u32>>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::Quaternion>>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::Vector3f>>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::f32>>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::i16>>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::m2::CameraSpline>>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::m2::CompatQuaternion>>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::u16>>);
PYBIND11_MAKE_OPAQUE(std::vector<std::vector<whiteout::u8>>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::u8>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::u32>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::u16>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::Quaternion>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::Vector2f>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::Vector3f>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::Vector4f>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::f32>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::AnimationTrackBase>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Attachment>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Batch>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Bone>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::BoneOverride>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::BoneOverrideSet>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::BoxShape>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Camera>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::CameraSpline>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::CapsuleShape>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::ColorAnimation>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::CompatQuaternion>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::DebugOcclusionData>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::DetailedLightData>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::DistanceFadeData>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::DistanceJoint>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::EdgeFadeData>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Event>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Extent>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::GlobalSequence>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Light>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Material>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::ParticleEmitter>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::ParticleGeosetData>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::PhysicsBody>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::PhysicsJoint>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::PhysicsShape>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::PhysicsTuning>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::PivotDisplacementData>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::PolytopeHalfEdge>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::PolytopeShape>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::PrismaticJoint>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::RevoluteJoint>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::RibbonEmitter>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Sequence>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::ShadowBatch>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::ShoulderJoint>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::SkinProfile>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::SkinSection>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::SphereShape>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::SphericalJoint>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Texture>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::TextureTransform>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::TextureWeight>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::TexturedLightData>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::Vertex>);
PYBIND11_MAKE_OPAQUE(std::vector<whiteout::m2::WeldJoint>);

#include <pybind11/stl.h>
#include <pybind11/stl_bind.h>
#include <pybind11/operators.h>
#include <pybind11/numpy.h>

namespace py = pybind11;


namespace {

// Buffer-protocol vector wrapper for std::vector<Elem> where Elem is laid
// out as `Components` contiguous Scalars (Vector3f, Quaternion, ColorBGRA…).
//
// pybind11's bind_vector<> wires up py::buffer_protocol() automatically,
// but stl_bind.h's auto-buffer-info path static-asserts on element types
// lacking a format_descriptor — Vector3f/Quaternion don't have one.
// We provide the same Python surface (append, extend, clear, __getitem__,
// __setitem__, __iter__, __len__, __bool__) plus a 2D buffer view.
template <typename Elem, typename Scalar, py::ssize_t Components>
auto bindBufferVector(py::module_& m, const char* name) {
    using Vec = std::vector<Elem>;
    py::class_<Vec> cls(m, name, py::buffer_protocol());
    cls.def(py::init<>());
    cls.def("__len__",  [](const Vec& v) { return v.size(); });
    cls.def("__bool__", [](const Vec& v) { return !v.empty(); });
    cls.def("__getitem__", [](const Vec& v, std::size_t i) -> Elem {
        if (i >= v.size()) throw py::index_error();
        return v[i];
    });
    cls.def("__setitem__", [](Vec& v, std::size_t i, const Elem& val) {
        if (i >= v.size()) throw py::index_error();
        v[i] = val;
    });
    cls.def("__iter__", [](Vec& v) {
        return py::make_iterator(v.begin(), v.end());
    }, py::keep_alive<0, 1>());
    cls.def("append",   [](Vec& v, const Elem& val) { v.push_back(val); });
    cls.def("extend",   [](Vec& v, const Vec& o) {
        v.insert(v.end(), o.begin(), o.end());
    });
    cls.def("clear",    &Vec::clear);
    cls.def_buffer([](Vec& v) -> py::buffer_info {
        if constexpr (Components == 1) {
            return py::buffer_info(
                v.data(),
                static_cast<py::ssize_t>(sizeof(Scalar)),
                py::format_descriptor<Scalar>::format(),
                1,
                { static_cast<py::ssize_t>(v.size()) },
                { static_cast<py::ssize_t>(sizeof(Scalar)) });
        } else {
            return py::buffer_info(
                v.data(),
                static_cast<py::ssize_t>(sizeof(Scalar)),
                py::format_descriptor<Scalar>::format(),
                2,
                { static_cast<py::ssize_t>(v.size()), Components },
                { static_cast<py::ssize_t>(sizeof(Elem)),
                  static_cast<py::ssize_t>(sizeof(Scalar)) });
        }
    });
    return cls;
}

} // namespace
void bind_m2_1(py::module_& m);
void bind_m2_2(py::module_& m);
void bind_m2_3(py::module_& m);

void bind_m2(py::module_& m) {
    py::enum_<whiteout::m2::InterpolationType>(m, "InterpolationType")
        .value("NONE", whiteout::m2::InterpolationType::None)
        .value("LINEAR", whiteout::m2::InterpolationType::Linear)
        .value("BEZIER", whiteout::m2::InterpolationType::Bezier)
        .value("HERMITE", whiteout::m2::InterpolationType::Hermite)
    ;

    py::enum_<whiteout::m2::GlobalFlag>(m, "GlobalFlag", R"doc(The MD20 header's `globalFlags`, named for what WoW 12.1 does with each bit (`WOW_M2_FLAGS.md`, corrected where noted).)doc")
        .value("NONE", whiteout::m2::GlobalFlag::None)
        .value("TILT_X", whiteout::m2::GlobalFlag::TiltX, R"doc(The model leans to follow the ground normal, about X and about Y.)doc")
        .value("TILT_Y", whiteout::m2::GlobalFlag::TiltY, R"doc(The model leans to follow the ground normal, about X and about Y.)doc")
        .value("WORLD_ABSOLUTE_TRANSFORM", whiteout::m2::GlobalFlag::WorldAbsoluteTransform, R"doc(The world transform is taken as is: no attachment parent's scale or translation is composed in, and emitters do not inherit it.)doc")
        .value("USE_TEXTURE_COMBINER_COMBOS", whiteout::m2::GlobalFlag::UseTextureCombinerCombos, R"doc(The header carries `textureCombinerCombos` after its fixed part. Read by the parser; the 12.1 client never tests it.)doc")
        .value("ANIMATED_BOUNDS", whiteout::m2::GlobalFlag::AnimatedBounds, R"doc(Batch bounds and sort distance come from the bone-transformed geometry.)doc")
        .value("LOAD_PHYSICS_DATA", whiteout::m2::GlobalFlag::LoadPhysicsData, R"doc(Load physics when the model attaches to a scene. CM2Shared::FinishLoadingM2Data tests it before LegacyLoadPhysData.)doc")
        .value("VISIBLE_GEOMETRY_OPTIMISE", whiteout::m2::GlobalFlag::VisibleGeometryOptimise, R"doc(Enters the visible-geometry optimiser and the shadow-map gather.)doc")
        .value("PARENT_LINKED_PARTICLES", whiteout::m2::GlobalFlag::ParentLinkedParticles, R"doc(Emitters of record type 4 are relinked when the model attaches to a parent.)doc")
        .value("NEW_PARTICLE_RECORD", whiteout::m2::GlobalFlag::NewParticleRecord, R"doc(Files of version 271 and below: the particle record carries the 16-byte multi-texture scroll tail. 12.1 reads the bit on helmets instead, as "has per-race rows in HelmetAnimScaling" (bone flag HelmetAnimScaled).)doc")
        .value("UNK_0X400", whiteout::m2::GlobalFlag::Unk_0x400, R"doc(Files of version 271 and below: the particle record carries the 16-byte multi-texture scroll tail. 12.1 reads the bit on helmets instead, as "has per-race rows in HelmetAnimScaling" (bone flag HelmetAnimScaled).)doc")
        .value("TEXTURE_TRANSFORMS_USES_BONE_SEQUENCES", whiteout::m2::GlobalFlag::TextureTransformsUsesBoneSequences, R"doc(Texture transforms are driven by bone sequences through textureTransformBoneMap.)doc")
        .value("UNK_0X1000", whiteout::m2::GlobalFlag::Unk_0x1000, R"doc(Texture transforms are driven by bone sequences through textureTransformBoneMap.)doc")
        .value("PER_SKIN_VERTEX_BLOCKS", whiteout::m2::GlobalFlag::PerSkinVertexBlocks, R"doc(Each skin profile owns a slice of the vertex array starting at its SkinProfile::lodVertexBase; clear, every profile indexes from 0.)doc")
        .value("PARENT_SKELETON_BOUND", whiteout::m2::GlobalFlag::ParentSkeletonBound, R"doc(A skinned attachment posed by its parent model: the client rebinds its bones to the parent skeleton by Bone::boneNameCRC.)doc")
        .value("LIGHT_ATTENUATION_TRACKS", whiteout::m2::GlobalFlag::LightAttenuationTracks, R"doc(Point lights take their attenuation start and end from their tracks; clear, the client uses 1.6666 and 5.2666 times the model scale. (WOW_M2_FLAGS.md reads this as a ribbon bit: the 156-byte record it describes is the light.))doc")
        .value("RIBBON_TEXTURE_TRANSFORMS", whiteout::m2::GlobalFlag::RibbonTextureTransforms, R"doc(Ribbons resolve their textureTransformIndex through textureTransformCombos; clear, the index is ignored. (WOW_M2_FLAGS.md reads this as a particle bit: the 176-byte record is the ribbon.))doc")
        .value("BONE_WIND", whiteout::m2::GlobalFlag::BoneWind, R"doc(In the bone-wind system: the palette entries of every bone but the root carry wind amplitude and phase for a wind vertex-shader permutation.)doc")
        .value("EXTERNAL_SKELETON", whiteout::m2::GlobalFlag::ExternalSkeleton, R"doc(Sequences and bones come from the SKID `.skel`, not the header.)doc")
        .value("CHUNKED_ANIM_AFM2", whiteout::m2::GlobalFlag::ChunkedAnimAfm2, R"doc(External `.anim` files are a chunk stream whose AFM2 chunk holds the sequence data; clear, the whole file is sequence data.)doc")
        .value("NAMED_TEXTURE_REQUEST_INERT", whiteout::m2::GlobalFlag::NamedTextureRequestInert, R"doc(Sets a texture-creation flag nothing in the 12.1 client reads.)doc")
        .value("SUPPRESS_PHYSICS_FILE", whiteout::m2::GlobalFlag::SuppressPhysicsFile, R"doc(Ignore the PFID physics file, whatever the model carries.)doc")
        .value("SKIP_OCCLUSION_QUERY", whiteout::m2::GlobalFlag::SkipOcclusionQuery, R"doc(Skip the HiZ occlusion test.)doc")
        .value("FORCE_UNOCCLUDED", whiteout::m2::GlobalFlag::ForceUnoccluded, R"doc(Treat the model as visible without querying occlusion.)doc")
        .value("PIPELINE_STATE_OVERRIDE", whiteout::m2::GlobalFlag::PipelineStateOverride, R"doc(Patches two bytes of the M2 render-state word; the bytes' meaning is not resolved.)doc")
        .value("FAR_LOD_LINK_SUBSTITUTE", whiteout::m2::GlobalFlag::FarLodLinkSubstitute, R"doc(Past a LOD threshold the model swaps its link record and releases its textures.)doc")
        .value("SECONDARY_PASS_RENDER_STATE", whiteout::m2::GlobalFlag::SecondaryPassRenderState, R"doc(Picks which of two render-state words a secondary pass draws the model with.)doc")
    ;

    py::enum_<whiteout::m2::SequenceFlag>(m, "SequenceFlag")
        .value("NONE", whiteout::m2::SequenceFlag::None)
        .value("TILT_IN", whiteout::m2::SequenceFlag::TiltIn)
        .value("TILT_OUT", whiteout::m2::SequenceFlag::TiltOut)
        .value("TILT_FIXED", whiteout::m2::SequenceFlag::TiltFixed)
        .value("LOOPING", whiteout::m2::SequenceFlag::Looping)
        .value("IS_ALIAS", whiteout::m2::SequenceFlag::IsAlias)
        .value("ANIMATED_SETUP", whiteout::m2::SequenceFlag::AnimatedSetup)
        .value("STORED_ANIMATED", whiteout::m2::SequenceFlag::StoredAnimated)
        .value("ENABLE_COMPOSITE", whiteout::m2::SequenceFlag::EnableComposite)
    ;

    py::enum_<whiteout::m2::BoneFlag>(m, "BoneFlag", R"doc(`M2CompBone.flags`, as WoW 12.1 reads it (`WOW_M2_FLAGS.md` §7).

The client ORs the file word with a runtime word, so the bits marked runtime below are never meant to come from a file.)doc")
        .value("NONE", whiteout::m2::BoneFlag::None)
        .value("IGNORE_PARENT_TRANSLATE", whiteout::m2::BoneFlag::IgnoreParentTranslate)
        .value("IGNORE_PARENT_SCALE", whiteout::m2::BoneFlag::IgnoreParentScale)
        .value("IGNORE_PARENT_ROTATION", whiteout::m2::BoneFlag::IgnoreParentRotation)
        .value("SPHERICAL_BILLBOARD", whiteout::m2::BoneFlag::SphericalBillboard, R"doc(@name Billboards One switch over `flags & BillboardMask`: exactly one of these, or none. Two or more set give no billboard at all. @{)doc")
        .value("CYLINDRICAL_BILLBOARD_X", whiteout::m2::BoneFlag::CylindricalBillboardX, R"doc(@name Billboards One switch over `flags & BillboardMask`: exactly one of these, or none. Two or more set give no billboard at all. @{)doc")
        .value("CYLINDRICAL_BILLBOARD_Y", whiteout::m2::BoneFlag::CylindricalBillboardY, R"doc(@name Billboards One switch over `flags & BillboardMask`: exactly one of these, or none. Two or more set give no billboard at all. @{)doc")
        .value("CYLINDRICAL_BILLBOARD_Z", whiteout::m2::BoneFlag::CylindricalBillboardZ, R"doc(@name Billboards One switch over `flags & BillboardMask`: exactly one of these, or none. Two or more set give no billboard at all. @{)doc")
        .value("BILLBOARD_AIM_AT_CAMERA", whiteout::m2::BoneFlag::BillboardAimAtCamera, R"doc(Faces the camera position rather than lying flat against the view.)doc")
        .value("PROCEDURAL_TRANSFORM", whiteout::m2::BoneFlag::ProceduralTransform, R"doc(@} A procedural matrix is multiplied into the local transform.)doc")
        .value("TRANSFORMED", whiteout::m2::BoneFlag::Transformed, R"doc(Has animation; with ProceduralTransform clear too, the bone skips animation.)doc")
        .value("KINEMATIC", whiteout::m2::BoneFlag::Kinematic, R"doc(Eligible for physics: a live dynamic body on the bone replaces its animation.)doc")
        .value("HELMET_ANIM_SCALED", whiteout::m2::BoneFlag::HelmetAnimScaled, R"doc(The helmet-scaling pass writes its per-race scale into this bone.)doc")
        .value("PRIMARY_SEQUENCE_ATTACHED", whiteout::m2::BoneFlag::PrimarySequenceAttached, R"doc(runtime)doc")
        .value("SECONDARY_SEQUENCE_ATTACHED", whiteout::m2::BoneFlag::SecondarySequenceAttached, R"doc(runtime)doc")
        .value("PHYSICS_INTERACTION_OFFSET", whiteout::m2::BoneFlag::PhysicsInteractionOffset, R"doc(runtime)doc")
        .value("PHYSICS_DRIVEN", whiteout::m2::BoneFlag::PhysicsDriven, R"doc(runtime: a dynamic body owns the bone)doc")
        .value("SKIP_SEQUENCE_BLEND_WEIGHT", whiteout::m2::BoneFlag::SkipSequenceBlendWeight, R"doc(With PrimarySequenceAttached, skip the per-sequence blend weight.)doc")
        .value("PROCEDURAL_IN_WORLD_SPACE", whiteout::m2::BoneFlag::ProceduralInWorldSpace, R"doc(With ProceduralTransform, apply the matrix after parenting, in world space.)doc")
    ;

    py::enum_<whiteout::m2::MaterialFlag>(m, "MaterialFlag")
        .value("NONE", whiteout::m2::MaterialFlag::None)
        .value("UNLIT", whiteout::m2::MaterialFlag::Unlit)
        .value("UNFOGGED", whiteout::m2::MaterialFlag::Unfogged)
        .value("TWO_SIDED", whiteout::m2::MaterialFlag::TwoSided)
        .value("DEPTH_TEST", whiteout::m2::MaterialFlag::DepthTest)
        .value("DEPTH_WRITE", whiteout::m2::MaterialFlag::DepthWrite)
        .value("NO_ALPHA_COMPOSITE", whiteout::m2::MaterialFlag::NoAlphaComposite)
    ;

    py::enum_<whiteout::m2::ParticleEmitterType>(m, "ParticleEmitterType")
        .value("PLANE", whiteout::m2::ParticleEmitterType::Plane)
        .value("SPHERE", whiteout::m2::ParticleEmitterType::Sphere)
        .value("SPLINE", whiteout::m2::ParticleEmitterType::Spline)
        .value("BONE", whiteout::m2::ParticleEmitterType::Bone)
    ;

    py::enum_<whiteout::m2::ParticleBlending>(m, "ParticleBlending")
        .value("OPAQUE", whiteout::m2::ParticleBlending::Opaque)
        .value("ALPHA_BLEND", whiteout::m2::ParticleBlending::AlphaBlend)
        .value("ADDITIVE", whiteout::m2::ParticleBlending::Additive)
        .value("ALPHA_TEST", whiteout::m2::ParticleBlending::AlphaTest)
        .value("ADDITIVE_ALPHA_TEST", whiteout::m2::ParticleBlending::AdditiveAlphaTest)
    ;

    py::enum_<whiteout::m2::ParticleFlag>(m, "ParticleFlag")
        .value("NONE", whiteout::m2::ParticleFlag::None)
        .value("UNLIT", whiteout::m2::ParticleFlag::Unlit)
        .value("SORT_PARTICLES", whiteout::m2::ParticleFlag::SortParticles)
        .value("VELOCITY_ORIENT", whiteout::m2::ParticleFlag::VelocityOrient)
        .value("UNFOGGED", whiteout::m2::ParticleFlag::Unfogged)
        .value("WORLD_SPACE", whiteout::m2::ParticleFlag::WorldSpace)
        .value("INHERIT_BONE_SCALE", whiteout::m2::ParticleFlag::InheritBoneScale)
        .value("INHERIT_VELOCITY", whiteout::m2::ParticleFlag::InheritVelocity)
        .value("IMPLOSION_FILTER", whiteout::m2::ParticleFlag::ImplosionFilter)
        .value("HEMISPHERE_UP_DIRECTION", whiteout::m2::ParticleFlag::HemisphereUpDirection)
        .value("NEGATE_SPIN_RANDOM", whiteout::m2::ParticleFlag::NegateSpinRandom)
        .value("CLAMP_TAIL_TO_AGE", whiteout::m2::ParticleFlag::ClampTailToAge)
        .value("INHERIT_POSITION", whiteout::m2::ParticleFlag::InheritPosition)
        .value("XY_QUAD", whiteout::m2::ParticleFlag::XYQuad)
        .value("PROJECT_PARTICLE", whiteout::m2::ParticleFlag::ProjectParticle)
        .value("FOLLOW_POSITION", whiteout::m2::ParticleFlag::FollowPosition)
        .value("SQUIRT", whiteout::m2::ParticleFlag::Squirt)
        .value("CHOOSE_RANDOM_TEXTURE", whiteout::m2::ParticleFlag::ChooseRandomTexture)
        .value("HEAD_STYLE", whiteout::m2::ParticleFlag::HeadStyle)
        .value("TAIL_STYLE", whiteout::m2::ParticleFlag::TailStyle)
        .value("UNSCALED_SIZE_VARIATION", whiteout::m2::ParticleFlag::UnscaledSizeVariation)
        .value("REFRACTION", whiteout::m2::ParticleFlag::Refraction)
        .value("RAND_FLIPBOOK_START", whiteout::m2::ParticleFlag::RandFlipbookStart)
        .value("UNK_0X400000", whiteout::m2::ParticleFlag::Unk_0x400000)
        .value("COMPRESSED_GRAVITY", whiteout::m2::ParticleFlag::CompressedGravity)
        .value("BONE_GENERATOR_BONE", whiteout::m2::ParticleFlag::BoneGeneratorBone)
        .value("NO_GLOBAL_VIEW_SCALE", whiteout::m2::ParticleFlag::NoGlobalViewScale)
        .value("LOD_IGNORE_DISTANCE", whiteout::m2::ParticleFlag::LodIgnoreDistance)
        .value("OFFSET_HEAD_BY_SPIN", whiteout::m2::ParticleFlag::OffsetHeadBySpin)
        .value("MULTI_TEXTURE", whiteout::m2::ParticleFlag::MultiTexture)
        .value("MULTITEX_USE_MODX4", whiteout::m2::ParticleFlag::MultitexUseModx4)
        .value("MULTITEX_USE3_COLORS", whiteout::m2::ParticleFlag::MultitexUse3Colors)
        .value("DYNAMIC_WIND", whiteout::m2::ParticleFlag::DynamicWind)
    ;

    py::enum_<whiteout::m2::PhysicsBodyType>(m, "PhysicsBodyType", R"doc(How the client drives a body — the value stored in BODY is inverted relative to Domino's own `dmBodyType`.)doc")
        .value("KINEMATIC", whiteout::m2::PhysicsBodyType::Kinematic, R"doc(Animation-driven collider. Becomes `dmBodyType` 1; the client keeps it glued to its bone and the simulation only reads it.)doc")
        .value("DYNAMIC", whiteout::m2::PhysicsBodyType::Dynamic, R"doc(Simulated. Becomes `dmBodyType` 0 and gets its bone transform written back every frame. These are the cloth/tassel segments.)doc")
        .value("STATIC", whiteout::m2::PhysicsBodyType::Static, R"doc(Any value from 2 up: `dmBodyType` 2. No shipped body uses it.)doc")
    ;

    py::enum_<whiteout::m2::PhysicsShapeType>(m, "PhysicsShapeType", R"doc(Which shape chunk a PhysicsShape indexes into.)doc")
        .value("BOX", whiteout::m2::PhysicsShapeType::Box, R"doc(BOXS)doc")
        .value("CAPSULE", whiteout::m2::PhysicsShapeType::Capsule, R"doc(CAPS)doc")
        .value("SPHERE", whiteout::m2::PhysicsShapeType::Sphere, R"doc(SPHS)doc")
        .value("POLYTOPE", whiteout::m2::PhysicsShapeType::Polytope, R"doc(PLYT, version 3+)doc")
    ;

    py::enum_<whiteout::m2::PhysicsJointType>(m, "PhysicsJointType", R"doc(Which joint chunk a PhysicsJoint indexes into.)doc")
        .value("SPHERICAL", whiteout::m2::PhysicsJointType::Spherical, R"doc(SPHJ)doc")
        .value("SHOULDER", whiteout::m2::PhysicsJointType::Shoulder, R"doc(SHOJ / SHJ2)doc")
        .value("WELD", whiteout::m2::PhysicsJointType::Weld, R"doc(WELJ / WLJ2 / WLJ3)doc")
        .value("REVOLUTE", whiteout::m2::PhysicsJointType::Revolute, R"doc(REVJ / REV2, version 2+)doc")
        .value("PRISMATIC", whiteout::m2::PhysicsJointType::Prismatic, R"doc(PRSJ / PRS2, version 2+)doc")
        .value("DISTANCE", whiteout::m2::PhysicsJointType::Distance, R"doc(DSTJ, version 2+)doc")
    ;

    py::enum_<whiteout::m2::PhysicsObjectKind>(m, "PhysicsObjectKind", R"doc(What a model's `PHYT` makes of it (`PHYS_FORMAT.md` §3.10).

A file with no PHYT reads as 0.)doc")
        .value("ATTACHED_RAGDOLL", whiteout::m2::PhysicsObjectKind::AttachedRagdoll, R"doc(Ragdoll whose kinematic bodies follow the model, not their bones: items worn on a character. 0 and 1 take the same branch in the client.)doc")
        .value("ATTACHED_RAGDOLL_ALT", whiteout::m2::PhysicsObjectKind::AttachedRagdollAlt, R"doc(Ragdoll whose kinematic bodies follow the model, not their bones: items worn on a character. 0 and 1 take the same branch in the client.)doc")
        .value("VEGETATION_PHANTOM", whiteout::m2::PhysicsObjectKind::VegetationPhantom, R"doc(Vegetation phantom built from the model's bounds and pushed by units. Needs a PHYV, and builds no bodies.)doc")
        .value("RAGDOLL", whiteout::m2::PhysicsObjectKind::Ragdoll, R"doc(Ragdoll in the shared physics world.)doc")
        .value("PRIVATE_WORLD_RAGDOLL", whiteout::m2::PhysicsObjectKind::PrivateWorldRagdoll, R"doc(Ragdoll in a physics world of its own, solved with twelve position iterations rather than two.)doc")
    ;

    py::class_<whiteout::m2::Extent>(m, "Extent")
        .def(py::init<>())
        .def_readwrite("minimum", &whiteout::m2::Extent::minimum)
        .def_readwrite("maximum", &whiteout::m2::Extent::maximum)
        .def_readwrite("sphere_radius", &whiteout::m2::Extent::sphereRadius)
    ;

    py::class_<whiteout::m2::PhysicsFrame>(m, "PhysicsFrame", R"doc(The affine frame the Domino chunks store: three basis columns and an origin, twelve floats in all.

The client reassembles it as `dmMtx{axisX, axisY, axisZ}` -> `dmQuatFromMtx` plus `origin` as the translation, giving a `dmTransform`.)doc")
        .def(py::init<>())
        .def_readwrite("axis_x", &whiteout::m2::PhysicsFrame::axisX)
        .def_readwrite("axis_y", &whiteout::m2::PhysicsFrame::axisY)
        .def_readwrite("axis_z", &whiteout::m2::PhysicsFrame::axisZ)
        .def_readwrite("origin", &whiteout::m2::PhysicsFrame::origin)
    ;

    py::class_<whiteout::m2::CompatQuaternion>(m, "CompatQuaternion")
        .def(py::init<>())
    ;

    py::class_<whiteout::m2::ColorBGRA>(m, "ColorBGRA")
        .def(py::init<>())
    ;

    py::class_<whiteout::m2::KeySpanRef>(m, "KeySpanRef", R"doc(One sequence's slice of a key array, as the file writes it: a count and an offset into whichever file holds that sequence's keys.

Kept only by a lazily parsed model (Parser::setLazyAnimations), which leaves the sub-arrays of externally-stored sequences empty until loadSequence() reads their `.anim` sibling. Nothing else needs it: an eager parse consumes the reference on the spot.)doc")
        .def(py::init<>())
        .def_readwrite("count", &whiteout::m2::KeySpanRef::count)
        .def_readwrite("offset", &whiteout::m2::KeySpanRef::offset)
    ;

    py::class_<whiteout::m2::AnimationTrackBase>(m, "AnimationTrackBase")
        .def(py::init<>())
        .def_readwrite("interpolation_type", &whiteout::m2::AnimationTrackBase::interpolationType)
        .def_readwrite("global_sequence_id", &whiteout::m2::AnimationTrackBase::globalSequenceId)
        .def_readwrite("timestamps", &whiteout::m2::AnimationTrackBase::timestamps)
    ;

    py::class_<whiteout::m2::ParticleEmitterExtension>(m, "ParticleEmitterExtension")
        .def(py::init<>())
        .def_readwrite("z_source", &whiteout::m2::ParticleEmitterExtension::zSource)
        .def_readwrite("color_mult", &whiteout::m2::ParticleEmitterExtension::colorMult)
        .def_readwrite("alpha_mult", &whiteout::m2::ParticleEmitterExtension::alphaMult)
    ;

    py::class_<whiteout::m2::LodProfile>(m, "LodProfile")
        .def(py::init<>())
        .def_readwrite("flags", &whiteout::m2::LodProfile::flags)
        .def_readwrite("num_lod_levels", &whiteout::m2::LodProfile::numLodLevels)
        .def_readwrite("lod_distance", &whiteout::m2::LodProfile::lodDistance)
        .def_readwrite("lod_scale_raw", &whiteout::m2::LodProfile::lodScaleRaw, R"doc(Fixed-point LOD scale, applied as `lodScaleRaw / 2048.0` and only when `flags & 0x08` is set (otherwise the client uses 1.0). This is the pair of bytes previously read as `reserved0` + `lodFlags`; reading it as a u16 explains why the high byte looked like a mirror of flags bit 3, since 0x0800 / 2048 == 1.0.)doc")
        .def_readwrite("lod_batch_count", &whiteout::m2::LodProfile::lodBatchCount)
        .def_readwrite("reserved1", &whiteout::m2::LodProfile::reserved1)
        .def("get_particle_bone_lod",
            [](const whiteout::m2::LodProfile& self) {
                return std::vector<whiteout::u8>(self.particleBoneLod.begin(), self.particleBoneLod.end());
            })
        .def("set_particle_bone_lod",
            [](whiteout::m2::LodProfile& self, const std::vector<whiteout::u8>& v) {
                if (v.size() != self.particleBoneLod.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.particleBoneLod.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.particleBoneLod[i] = v[i];
            })
    ;

    py::class_<whiteout::m2::WaterfallData>(m, "WaterfallData")
        .def(py::init<>())
        .def_readwrite("bump_scale", &whiteout::m2::WaterfallData::bumpScale)
        .def_readwrite("value0_x", &whiteout::m2::WaterfallData::value0_x)
        .def_readwrite("value0_y", &whiteout::m2::WaterfallData::value0_y)
        .def_readwrite("value0_z", &whiteout::m2::WaterfallData::value0_z)
        .def_readwrite("value1_w", &whiteout::m2::WaterfallData::value1_w)
        .def_readwrite("value0_w", &whiteout::m2::WaterfallData::value0_w)
        .def_readwrite("value1_x", &whiteout::m2::WaterfallData::value1_x)
        .def_readwrite("value1_y", &whiteout::m2::WaterfallData::value1_y)
        .def_readwrite("value2_w", &whiteout::m2::WaterfallData::value2_w)
        .def_readwrite("value3_y", &whiteout::m2::WaterfallData::value3_y)
        .def_readwrite("value3_x", &whiteout::m2::WaterfallData::value3_x)
        .def_readwrite("base_color", &whiteout::m2::WaterfallData::baseColor)
        .def_readwrite("flags", &whiteout::m2::WaterfallData::flags)
        .def_readwrite("unknown0", &whiteout::m2::WaterfallData::unknown0)
        .def_readwrite("value3_w", &whiteout::m2::WaterfallData::value3_w)
        .def_readwrite("value3_z", &whiteout::m2::WaterfallData::value3_z)
        .def_readwrite("value4_y", &whiteout::m2::WaterfallData::value4_y)
        .def_readwrite("unknown1", &whiteout::m2::WaterfallData::unknown1)
        .def_readwrite("unknown2", &whiteout::m2::WaterfallData::unknown2)
        .def_readwrite("unknown3", &whiteout::m2::WaterfallData::unknown3)
        .def_readwrite("unknown4", &whiteout::m2::WaterfallData::unknown4)
    ;

    py::class_<whiteout::m2::ParticleGeosetData>(m, "ParticleGeosetData")
        .def(py::init<>())
        .def_readwrite("geoset", &whiteout::m2::ParticleGeosetData::geoset)
    ;

    py::class_<whiteout::m2::EdgeFadeData>(m, "EdgeFadeData")
        .def(py::init<>())
        .def_readwrite("value8", &whiteout::m2::EdgeFadeData::value8)
        .def("get_value0",
            [](const whiteout::m2::EdgeFadeData& self) {
                return std::vector<whiteout::f32>(self.value0.begin(), self.value0.end());
            })
        .def("set_value0",
            [](whiteout::m2::EdgeFadeData& self, const std::vector<whiteout::f32>& v) {
                if (v.size() != self.value0.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.value0.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.value0[i] = v[i];
            })
        .def("get_value_c",
            [](const whiteout::m2::EdgeFadeData& self) {
                return std::vector<whiteout::u8>(self.valueC.begin(), self.valueC.end());
            })
        .def("set_value_c",
            [](whiteout::m2::EdgeFadeData& self, const std::vector<whiteout::u8>& v) {
                if (v.size() != self.valueC.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.valueC.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.valueC[i] = v[i];
            })
    ;

    py::class_<whiteout::m2::DistanceFadeData>(m, "DistanceFadeData")
        .def(py::init<>())
        .def_readwrite("squared_far_dist", &whiteout::m2::DistanceFadeData::squaredFarDist)
        .def_readwrite("squared_near_dist", &whiteout::m2::DistanceFadeData::squaredNearDist)
        .def("get_reserved",
            [](const whiteout::m2::DistanceFadeData& self) {
                return std::vector<whiteout::u32>(self.reserved.begin(), self.reserved.end());
            })
        .def("set_reserved",
            [](whiteout::m2::DistanceFadeData& self, const std::vector<whiteout::u32>& v) {
                if (v.size() != self.reserved.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.reserved.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.reserved[i] = v[i];
            })
    ;

    py::class_<whiteout::m2::DetailedLightData>(m, "DetailedLightData")
        .def(py::init<>())
        .def_readwrite("flags", &whiteout::m2::DetailedLightData::flags)
        .def_readwrite("unknown0", &whiteout::m2::DetailedLightData::unknown0)
        .def_readwrite("unknown1", &whiteout::m2::DetailedLightData::unknown1)
    ;

    py::class_<whiteout::m2::DebugOcclusionData>(m, "DebugOcclusionData")
        .def(py::init<>())
        .def_readwrite("unknown1_1", &whiteout::m2::DebugOcclusionData::unknown1_1)
        .def_readwrite("unknown1_2", &whiteout::m2::DebugOcclusionData::unknown1_2)
        .def_readwrite("unknown1_3", &whiteout::m2::DebugOcclusionData::unknown1_3)
        .def_readwrite("unknown1_4", &whiteout::m2::DebugOcclusionData::unknown1_4)
    ;

    py::class_<whiteout::m2::TexturedLightData>(m, "TexturedLightData")
        .def(py::init<>())
        .def_readwrite("unknown0", &whiteout::m2::TexturedLightData::unknown0)
        .def_readwrite("unknown1", &whiteout::m2::TexturedLightData::unknown1)
        .def_readwrite("texture_lookup", &whiteout::m2::TexturedLightData::textureLookup)
        .def_readwrite("unknown2", &whiteout::m2::TexturedLightData::unknown2)
    ;

    py::class_<whiteout::m2::PivotDisplacementData>(m, "PivotDisplacementData", R"doc(One DPIV (pivot displacement) record, 32 bytes.

The client keeps the payload pointer and a record count of `chunkSize / 32`, so a chunk holds N of these — the corpus has both 1- and 2-record chunks.)doc")
        .def(py::init<>())
        .def_readwrite("offset", &whiteout::m2::PivotDisplacementData::offset, R"doc(small displacement; Z varies most)doc")
        .def_readwrite("flags", &whiteout::m2::PivotDisplacementData::flags, R"doc(0 or 1)doc")
        .def("get_reserved",
            [](const whiteout::m2::PivotDisplacementData& self) {
                return std::vector<whiteout::u32>(self.reserved.begin(), self.reserved.end());
            })
        .def("set_reserved",
            [](whiteout::m2::PivotDisplacementData& self, const std::vector<whiteout::u32>& v) {
                if (v.size() != self.reserved.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.reserved.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.reserved[i] = v[i];
            })
    ;

    py::class_<whiteout::m2::PhysicsCollision>(m, "PhysicsCollision")
        .def(py::init<>())
        .def_readwrite("vertex_positions", &whiteout::m2::PhysicsCollision::vertexPositions)
        .def_readwrite("face_normals", &whiteout::m2::PhysicsCollision::faceNormals)
        .def_readwrite("indices", &whiteout::m2::PhysicsCollision::indices)
        .def_readwrite("flags", &whiteout::m2::PhysicsCollision::flags)
    ;

    py::class_<whiteout::m2::SkinSection>(m, "SkinSection")
        .def(py::init<>())
        .def_readwrite("skin_section_id", &whiteout::m2::SkinSection::skinSectionId)
        .def_readwrite("level", &whiteout::m2::SkinSection::level)
        .def_readwrite("vertex_start", &whiteout::m2::SkinSection::vertexStart)
        .def_readwrite("vertex_count", &whiteout::m2::SkinSection::vertexCount)
        .def_readwrite("index_start", &whiteout::m2::SkinSection::indexStart)
        .def_readwrite("index_count", &whiteout::m2::SkinSection::indexCount)
        .def_readwrite("bone_count", &whiteout::m2::SkinSection::boneCount)
        .def_readwrite("bone_combo_index", &whiteout::m2::SkinSection::boneComboIndex)
        .def_readwrite("bone_influences", &whiteout::m2::SkinSection::boneInfluences)
        .def_readwrite("center_bone_index", &whiteout::m2::SkinSection::centerBoneIndex)
        .def_readwrite("center_position", &whiteout::m2::SkinSection::centerPosition)
        .def_readwrite("sort_center_position", &whiteout::m2::SkinSection::sortCenterPosition)
        .def_readwrite("sort_radius", &whiteout::m2::SkinSection::sortRadius)
    ;

    py::class_<whiteout::m2::Batch>(m, "Batch")
        .def(py::init<>())
        .def_readwrite("flags", &whiteout::m2::Batch::flags)
        .def_readwrite("priority_plane", &whiteout::m2::Batch::priorityPlane)
        .def_readwrite("shader_id", &whiteout::m2::Batch::shaderId)
        .def_readwrite("skin_section_index", &whiteout::m2::Batch::skinSectionIndex)
        .def_readwrite("geoset_index", &whiteout::m2::Batch::geosetIndex)
        .def_readwrite("color_index", &whiteout::m2::Batch::colorIndex)
        .def_readwrite("material_index", &whiteout::m2::Batch::materialIndex)
        .def_readwrite("material_layer", &whiteout::m2::Batch::materialLayer)
        .def_readwrite("texture_count", &whiteout::m2::Batch::textureCount)
        .def_readwrite("texture_combo_index", &whiteout::m2::Batch::textureComboIndex)
        .def_readwrite("texture_coord_combo_index", &whiteout::m2::Batch::textureCoordComboIndex)
        .def_readwrite("texture_weight_combo_index", &whiteout::m2::Batch::textureWeightComboIndex)
        .def_readwrite("texture_transform_combo_index", &whiteout::m2::Batch::textureTransformComboIndex)
    ;

    py::class_<whiteout::m2::ShadowBatch>(m, "ShadowBatch")
        .def(py::init<>())
        .def_readwrite("flags", &whiteout::m2::ShadowBatch::flags)
        .def_readwrite("flags2", &whiteout::m2::ShadowBatch::flags2)
        .def_readwrite("unknown0", &whiteout::m2::ShadowBatch::unknown0)
        .def_readwrite("submesh_id", &whiteout::m2::ShadowBatch::submeshId)
        .def_readwrite("texture_id", &whiteout::m2::ShadowBatch::textureId)
        .def_readwrite("color_id", &whiteout::m2::ShadowBatch::colorId)
        .def_readwrite("transparency_id", &whiteout::m2::ShadowBatch::transparencyId)
    ;

    py::class_<whiteout::m2::SkinProfile>(m, "SkinProfile")
        .def(py::init<>())
        .def_readwrite("vertices", &whiteout::m2::SkinProfile::vertices)
        .def_readwrite("indices", &whiteout::m2::SkinProfile::indices)
        .def_readwrite("submeshes", &whiteout::m2::SkinProfile::submeshes)
        .def_readwrite("batches", &whiteout::m2::SkinProfile::batches)
        .def_readwrite("lod_vertex_base", &whiteout::m2::SkinProfile::lodVertexBase, R"doc(Where this profile's vertex indices start in the model's vertex array. The client applies it only when GlobalFlag::PerSkinVertexBlocks is set.)doc")
        .def_readwrite("shadow_batches", &whiteout::m2::SkinProfile::shadowBatches)
    ;

    py::class_<whiteout::m2::GlobalFlags>(m, "GlobalFlags")
        .def(py::init<>())
        .def_readwrite("value", &whiteout::m2::GlobalFlags::value)
    ;

    py::class_<whiteout::m2::GlobalSequence>(m, "GlobalSequence")
        .def(py::init<>())
        .def_readwrite("timestamp", &whiteout::m2::GlobalSequence::timestamp)
    ;

    py::class_<whiteout::m2::Sequence>(m, "Sequence")
        .def(py::init<>())
        .def_readwrite("id", &whiteout::m2::Sequence::id)
        .def_readwrite("variation_index", &whiteout::m2::Sequence::variationIndex)
        .def_readwrite("duration", &whiteout::m2::Sequence::duration)
        .def_readwrite("movespeed", &whiteout::m2::Sequence::movespeed)
        .def_readwrite("flags", &whiteout::m2::Sequence::flags)
        .def_readwrite("frequency", &whiteout::m2::Sequence::frequency)
        .def_readwrite("padding", &whiteout::m2::Sequence::padding)
        .def_readwrite("replay_min", &whiteout::m2::Sequence::replayMin)
        .def_readwrite("replay_max", &whiteout::m2::Sequence::replayMax)
        .def_readwrite("blend_time_in", &whiteout::m2::Sequence::blendTimeIn)
        .def_readwrite("blend_time_out", &whiteout::m2::Sequence::blendTimeOut)
        .def_readwrite("bounding", &whiteout::m2::Sequence::bounding)
        .def_readwrite("variation_next", &whiteout::m2::Sequence::variationNext)
        .def_readwrite("alias_next", &whiteout::m2::Sequence::aliasNext)
    ;

    py::class_<whiteout::m2::Vertex>(m, "Vertex")
        .def(py::init<>())
        .def_readwrite("position", &whiteout::m2::Vertex::position)
        .def_readwrite("normal", &whiteout::m2::Vertex::normal)
        .def("get_bone_weights",
            [](const whiteout::m2::Vertex& self) {
                return std::vector<whiteout::u8>(self.boneWeights.begin(), self.boneWeights.end());
            })
        .def("set_bone_weights",
            [](whiteout::m2::Vertex& self, const std::vector<whiteout::u8>& v) {
                if (v.size() != self.boneWeights.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.boneWeights.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.boneWeights[i] = v[i];
            })
        .def("get_bone_indices",
            [](const whiteout::m2::Vertex& self) {
                return std::vector<whiteout::u8>(self.boneIndices.begin(), self.boneIndices.end());
            })
        .def("set_bone_indices",
            [](whiteout::m2::Vertex& self, const std::vector<whiteout::u8>& v) {
                if (v.size() != self.boneIndices.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.boneIndices.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.boneIndices[i] = v[i];
            })
        .def("get_tex_coords",
            [](const whiteout::m2::Vertex& self) {
                return std::vector<whiteout::Vector2f>(self.texCoords.begin(), self.texCoords.end());
            })
        .def("set_tex_coords",
            [](whiteout::m2::Vertex& self, const std::vector<whiteout::Vector2f>& v) {
                if (v.size() != self.texCoords.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.texCoords.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.texCoords[i] = v[i];
            })
    ;

    py::class_<whiteout::m2::Bone>(m, "Bone")
        .def(py::init<>())
        .def_readwrite("key_bone_id", &whiteout::m2::Bone::keyBoneId)
        .def_readwrite("flags", &whiteout::m2::Bone::flags)
        .def_readwrite("parent_bone_id", &whiteout::m2::Bone::parentBoneId)
        .def_readwrite("submesh_id", &whiteout::m2::Bone::submeshId)
        .def_readwrite("bone_name_crc", &whiteout::m2::Bone::boneNameCRC)
        .def_readwrite("translation", &whiteout::m2::Bone::translation)
        .def_readwrite("rotation", &whiteout::m2::Bone::rotation)
        .def_readwrite("scale", &whiteout::m2::Bone::scale)
        .def_readwrite("pivot", &whiteout::m2::Bone::pivot)
    ;

    py::class_<whiteout::m2::Texture>(m, "Texture")
        .def(py::init<>())
        .def_readwrite("type", &whiteout::m2::Texture::type)
        .def_readwrite("flags", &whiteout::m2::Texture::flags)
        .def_readwrite("filename", &whiteout::m2::Texture::filename)
    ;

    py::class_<whiteout::m2::Material>(m, "Material")
        .def(py::init<>())
        .def_readwrite("flags", &whiteout::m2::Material::flags)
        .def_readwrite("blending_mode", &whiteout::m2::Material::blendingMode)
    ;

    py::class_<whiteout::m2::TextureWeight>(m, "TextureWeight")
        .def(py::init<>())
        .def_readwrite("weight", &whiteout::m2::TextureWeight::weight)
    ;

    py::class_<whiteout::m2::TextureTransform>(m, "TextureTransform")
        .def(py::init<>())
        .def_readwrite("translation", &whiteout::m2::TextureTransform::translation)
        .def_readwrite("rotation", &whiteout::m2::TextureTransform::rotation)
        .def_readwrite("scaling", &whiteout::m2::TextureTransform::scaling)
    ;

    py::class_<whiteout::m2::ColorAnimation>(m, "ColorAnimation")
        .def(py::init<>())
        .def_readwrite("color", &whiteout::m2::ColorAnimation::color)
        .def_readwrite("alpha", &whiteout::m2::ColorAnimation::alpha)
    ;

    py::class_<whiteout::m2::Light>(m, "Light")
        .def(py::init<>())
        .def_readwrite("type", &whiteout::m2::Light::type)
        .def_readwrite("bone_id", &whiteout::m2::Light::boneId)
        .def_readwrite("position", &whiteout::m2::Light::position)
        .def_readwrite("ambient_color", &whiteout::m2::Light::ambientColor)
        .def_readwrite("ambient_intensity", &whiteout::m2::Light::ambientIntensity)
        .def_readwrite("diffuse_color", &whiteout::m2::Light::diffuseColor)
        .def_readwrite("diffuse_intensity", &whiteout::m2::Light::diffuseIntensity)
        .def_readwrite("attenuation_start", &whiteout::m2::Light::attenuationStart)
        .def_readwrite("attenuation_end", &whiteout::m2::Light::attenuationEnd)
        .def_readwrite("visibility", &whiteout::m2::Light::visibility)
    ;

    py::class_<whiteout::m2::CameraSpline>(m, "CameraSpline")
        .def(py::init<>())
        .def_readwrite("value", &whiteout::m2::CameraSpline::value)
        .def_readwrite("in_tangent", &whiteout::m2::CameraSpline::inTangent)
        .def_readwrite("out_tangent", &whiteout::m2::CameraSpline::outTangent)
    ;

    py::class_<whiteout::m2::Camera>(m, "Camera")
        .def(py::init<>())
        .def_readwrite("type", &whiteout::m2::Camera::type)
        .def_readwrite("field_of_view", &whiteout::m2::Camera::fieldOfView)
        .def_readwrite("far_clip", &whiteout::m2::Camera::farClip)
        .def_readwrite("near_clip", &whiteout::m2::Camera::nearClip)
        .def_readwrite("positions", &whiteout::m2::Camera::positions)
        .def_readwrite("position_base", &whiteout::m2::Camera::positionBase)
        .def_readwrite("target_positions", &whiteout::m2::Camera::targetPositions)
        .def_readwrite("target_position_base", &whiteout::m2::Camera::targetPositionBase)
        .def_readwrite("roll", &whiteout::m2::Camera::roll)
        .def_readwrite("field_of_view_track", &whiteout::m2::Camera::fieldOfViewTrack)
    ;

    py::class_<whiteout::m2::Attachment>(m, "Attachment")
        .def(py::init<>())
        .def_readwrite("id", &whiteout::m2::Attachment::id)
        .def_readwrite("bone_id", &whiteout::m2::Attachment::boneId)
        .def_readwrite("unknown", &whiteout::m2::Attachment::unknown)
        .def_readwrite("position", &whiteout::m2::Attachment::position)
        .def_readwrite("animate", &whiteout::m2::Attachment::animate)
    ;

    py::class_<whiteout::m2::RibbonEmitter>(m, "RibbonEmitter")
        .def(py::init<>())
        .def_readwrite("ribbon_id", &whiteout::m2::RibbonEmitter::ribbonId)
        .def_readwrite("bone_id", &whiteout::m2::RibbonEmitter::boneId)
        .def_readwrite("position", &whiteout::m2::RibbonEmitter::position)
        .def_readwrite("texture_indices", &whiteout::m2::RibbonEmitter::textureIndices)
        .def_readwrite("material_indices", &whiteout::m2::RibbonEmitter::materialIndices)
        .def_readwrite("color_track", &whiteout::m2::RibbonEmitter::colorTrack)
        .def_readwrite("alpha_track", &whiteout::m2::RibbonEmitter::alphaTrack)
        .def_readwrite("height_above", &whiteout::m2::RibbonEmitter::heightAbove)
        .def_readwrite("height_below", &whiteout::m2::RibbonEmitter::heightBelow)
        .def_readwrite("edges_per_second", &whiteout::m2::RibbonEmitter::edgesPerSecond)
        .def_readwrite("edge_lifetime", &whiteout::m2::RibbonEmitter::edgeLifetime)
        .def_readwrite("gravity", &whiteout::m2::RibbonEmitter::gravity)
        .def_readwrite("texture_rows", &whiteout::m2::RibbonEmitter::textureRows)
        .def_readwrite("texture_cols", &whiteout::m2::RibbonEmitter::textureCols)
        .def_readwrite("tex_slot", &whiteout::m2::RibbonEmitter::texSlot)
        .def_readwrite("visibility", &whiteout::m2::RibbonEmitter::visibility)
        .def_readwrite("priority_plane", &whiteout::m2::RibbonEmitter::priorityPlane)
        .def_readwrite("ribbon_color_index", &whiteout::m2::RibbonEmitter::ribbonColorIndex)
        .def_readwrite("texture_transform_index", &whiteout::m2::RibbonEmitter::textureTransformIndex)
    ;

    py::class_<whiteout::m2::M2Box>(m, "Box")
        .def(py::init<>())
        .def_readwrite("minimum", &whiteout::m2::M2Box::minimum)
        .def_readwrite("maximum", &whiteout::m2::M2Box::maximum)
    ;

    py::class_<whiteout::m2::ParticleEmitter>(m, "ParticleEmitter")
        .def(py::init<>())
        .def_readwrite("particle_id", &whiteout::m2::ParticleEmitter::particleId)
        .def_readwrite("flags", &whiteout::m2::ParticleEmitter::flags)
        .def_readwrite("position", &whiteout::m2::ParticleEmitter::position)
        .def_readwrite("bone_id", &whiteout::m2::ParticleEmitter::boneId)
        .def_readwrite("particle_model_filename", &whiteout::m2::ParticleEmitter::particleModelFilename)
        .def_readwrite("child_emitters_model_filename", &whiteout::m2::ParticleEmitter::childEmittersModelFilename)
        .def_readwrite("blending_type", &whiteout::m2::ParticleEmitter::blendingType)
        .def_readwrite("emitter_type", &whiteout::m2::ParticleEmitter::emitterType)
        .def_readwrite("particle_color_index", &whiteout::m2::ParticleEmitter::particleColorIndex)
        .def_readwrite("particle_type", &whiteout::m2::ParticleEmitter::particleType)
        .def_readwrite("head_or_tail", &whiteout::m2::ParticleEmitter::headOrTail)
        .def_readwrite("texture_tilerotation", &whiteout::m2::ParticleEmitter::textureTilerotation)
        .def_readwrite("rows", &whiteout::m2::ParticleEmitter::rows)
        .def_readwrite("columns", &whiteout::m2::ParticleEmitter::columns)
        .def_readwrite("emission_speed", &whiteout::m2::ParticleEmitter::emissionSpeed)
        .def_readwrite("speed_variation", &whiteout::m2::ParticleEmitter::speedVariation)
        .def_readwrite("vertical_range", &whiteout::m2::ParticleEmitter::verticalRange)
        .def_readwrite("horizontal_range", &whiteout::m2::ParticleEmitter::horizontalRange)
        .def_readwrite("gravity", &whiteout::m2::ParticleEmitter::gravity)
        .def_readwrite("lifespan", &whiteout::m2::ParticleEmitter::lifespan)
        .def_readwrite("lifespan_variation", &whiteout::m2::ParticleEmitter::lifespanVariation)
        .def_readwrite("emission_rate", &whiteout::m2::ParticleEmitter::emissionRate)
        .def_readwrite("emission_rate_variation", &whiteout::m2::ParticleEmitter::emissionRateVariation)
        .def_readwrite("emission_area_width", &whiteout::m2::ParticleEmitter::emissionAreaWidth)
        .def_readwrite("emission_area_length", &whiteout::m2::ParticleEmitter::emissionAreaLength)
        .def_readwrite("z_source", &whiteout::m2::ParticleEmitter::zSource)
        .def_readwrite("color_track", &whiteout::m2::ParticleEmitter::colorTrack)
        .def_readwrite("scale_track", &whiteout::m2::ParticleEmitter::scaleTrack)
        .def_readwrite("scale_vary", &whiteout::m2::ParticleEmitter::scaleVary)
        .def_readwrite("tail_length", &whiteout::m2::ParticleEmitter::tailLength)
        .def_readwrite("twinkle_speed", &whiteout::m2::ParticleEmitter::twinkleSpeed)
        .def_readwrite("twinkle_percent", &whiteout::m2::ParticleEmitter::twinklePercent)
        .def_readwrite("twinkle_scale", &whiteout::m2::ParticleEmitter::twinkleScale)
        .def_readwrite("inherit_velocity_scale", &whiteout::m2::ParticleEmitter::inheritVelocityScale)
        .def_readwrite("drag", &whiteout::m2::ParticleEmitter::drag)
        .def_readwrite("base_spin", &whiteout::m2::ParticleEmitter::baseSpin)
        .def_readwrite("base_spin_variation", &whiteout::m2::ParticleEmitter::baseSpinVariation)
        .def_readwrite("spin_speed", &whiteout::m2::ParticleEmitter::spinSpeed)
        .def_readwrite("spin_speed_variation", &whiteout::m2::ParticleEmitter::spinSpeedVariation)
        .def_readwrite("tumble", &whiteout::m2::ParticleEmitter::tumble)
        .def_readwrite("wind_vector", &whiteout::m2::ParticleEmitter::windVector)
        .def_readwrite("wind_time", &whiteout::m2::ParticleEmitter::windTime)
        .def_readwrite("follow_speed1", &whiteout::m2::ParticleEmitter::followSpeed1)
        .def_readwrite("follow_scale1", &whiteout::m2::ParticleEmitter::followScale1)
        .def_readwrite("follow_speed2", &whiteout::m2::ParticleEmitter::followSpeed2)
        .def_readwrite("follow_scale2", &whiteout::m2::ParticleEmitter::followScale2)
        .def_readwrite("spline_points", &whiteout::m2::ParticleEmitter::splinePoints)
        .def_readwrite("enabled_in", &whiteout::m2::ParticleEmitter::enabledIn)
        .def_readwrite("extension", &whiteout::m2::ParticleEmitter::extension)
        .def("get_multi_tex_scale",
            [](const whiteout::m2::ParticleEmitter& self) {
                return std::vector<whiteout::fixed_point<signed char, 5>>(self.multiTexScale.begin(), self.multiTexScale.end());
            })
        .def("set_multi_tex_scale",
            [](whiteout::m2::ParticleEmitter& self, const std::vector<whiteout::fixed_point<signed char, 5>>& v) {
                if (v.size() != self.multiTexScale.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.multiTexScale.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.multiTexScale[i] = v[i];
            })
        .def("get_multi_tex_scroll_mid",
            [](const whiteout::m2::ParticleEmitter& self) {
                return std::vector<std::array<whiteout::fixed_point<unsigned short, 9>, 2>>(self.multiTexScrollMid.begin(), self.multiTexScrollMid.end());
            })
        .def("set_multi_tex_scroll_mid",
            [](whiteout::m2::ParticleEmitter& self, const std::vector<std::array<whiteout::fixed_point<unsigned short, 9>, 2>>& v) {
                if (v.size() != self.multiTexScrollMid.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.multiTexScrollMid.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.multiTexScrollMid[i] = v[i];
            })
        .def("get_multi_tex_scroll_range",
            [](const whiteout::m2::ParticleEmitter& self) {
                return std::vector<std::array<whiteout::fixed_point<unsigned short, 9>, 2>>(self.multiTexScrollRange.begin(), self.multiTexScrollRange.end());
            })
        .def("set_multi_tex_scroll_range",
            [](whiteout::m2::ParticleEmitter& self, const std::vector<std::array<whiteout::fixed_point<unsigned short, 9>, 2>>& v) {
                if (v.size() != self.multiTexScrollRange.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.multiTexScrollRange.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.multiTexScrollRange[i] = v[i];
            })
    ;

    py::class_<whiteout::m2::Event>(m, "Event")
        .def(py::init<>())
        .def_readwrite("identifier", &whiteout::m2::Event::identifier)
        .def_readwrite("data", &whiteout::m2::Event::data)
        .def_readwrite("bone_id", &whiteout::m2::Event::boneId)
        .def_readwrite("position", &whiteout::m2::Event::position)
        .def_readwrite("enabled", &whiteout::m2::Event::enabled)
    ;

    py::class_<whiteout::m2::PhysicsBody>(m, "PhysicsBody", R"doc(One rigid body, bound to a single model bone — BODY/BDY2/BDY3/BDY4.

The four on-disk layouts are the same fields accreting over time, so they share one struct; PhysicsData::version decides which of them is written back, and fields the older layouts lack keep the values the client's upgrader gives them (`PHYS_FORMAT.md` §5).)doc")
        .def(py::init<>())
        .def_readwrite("type", &whiteout::m2::PhysicsBody::type)
        .def_readwrite("bone_index", &whiteout::m2::PhysicsBody::boneIndex, R"doc(BODY/BDY2 store it as a u32 at +16 and the client keeps the low 16 bits; BDY3 moved it into the u16 at +2.)doc")
        .def_readwrite("position", &whiteout::m2::PhysicsBody::position, R"doc(The body's model-space origin, where the client creates it; the first step moves it onto its bone's animated pivot.)doc")
        .def_readwrite("shape_index", &whiteout::m2::PhysicsBody::shapeIndex, R"doc(First entry in PhysicsData::shapes belonging to this body. 32 bits wide in every layout.)doc")
        .def_readwrite("shape_count", &whiteout::m2::PhysicsBody::shapeCount)
        .def_readwrite("gravity_scale", &whiteout::m2::PhysicsBody::gravityScale, R"doc(BDY2+. 1.0 on all but 45 of 1213 kinematic bodies but tuned freely on dynamic ones, negatives included — `dmBodyDef+0x30`.)doc")
        .def_readwrite("inertia_scale", &whiteout::m2::PhysicsBody::inertiaScale, R"doc(BDY3+. 1.0 in 3457 of 3526 bodies, otherwise 1.1-10 — `dmBodyDef+0x2C`.)doc")
        .def_readwrite("linear_damping", &whiteout::m2::PhysicsBody::linearDamping, R"doc(BDY3+. Zero on 1196 of 1213 kinematic bodies and 0-10 on dynamic ones — `dmBodyDef+0x24`.)doc")
        .def_readwrite("angular_damping", &whiteout::m2::PhysicsBody::angularDamping, R"doc(BDY3+. Same kinematic/dynamic split as @ref linearDamping — `dmBodyDef+0x28`.)doc")
        .def_readwrite("follow_factor", &whiteout::m2::PhysicsBody::followFactor, R"doc(BDY4. The fraction of the way a kinematic body is snapped to its animated pose each step, ramping to a full teleport when the motion is fast. Not a Domino parameter. Older layouts get the upgrader's 0.9.)doc")
        .def_readwrite("attachment", &whiteout::m2::PhysicsBody::attachment, R"doc(BDY3+ (+40 in BDY3, +44 in BDY4): see the `kPhysicsAttachment*` constants.)doc")
        .def_readwrite("padding", &whiteout::m2::PhysicsBody::padding, R"doc(BDY3+. Zero in every corpus body.)doc")
    ;

    py::class_<whiteout::m2::PhysicsShape>(m, "PhysicsShape", R"doc(One collision shape reference — SHAP/SHP2. Points at an entry of the box/capsule/sphere/polytope array named by @ref shapeType.)doc")
        .def(py::init<>())
        .def_readwrite("shape_type", &whiteout::m2::PhysicsShape::shapeType)
        .def_readwrite("shape_index", &whiteout::m2::PhysicsShape::shapeIndex)
        .def_readwrite("game_flags", &whiteout::m2::PhysicsShape::gameFlags, R"doc(`dmFixtureDef.gameFlags`. Zero in every corpus shape.)doc")
        .def_readwrite("padding06", &whiteout::m2::PhysicsShape::padding06)
        .def_readwrite("friction", &whiteout::m2::PhysicsShape::friction)
        .def_readwrite("restitution", &whiteout::m2::PhysicsShape::restitution)
        .def_readwrite("density", &whiteout::m2::PhysicsShape::density, R"doc(Rescaled by the client for capsules in files of version 4 and below (`PHYS_FORMAT.md` §4.2).)doc")
        .def_readwrite("unused14", &whiteout::m2::PhysicsShape::unused14, R"doc(@name SHP2+, parsed and never read The client copies these onto its shape def and no `CreateInstance` reads them (`PHYS_FORMAT.md` §4.5). SHAP's upgrade gives 0, 1.0 and 0. @{)doc")
        .def_readwrite("unused18", &whiteout::m2::PhysicsShape::unused18, R"doc(1.0 in 3229 of 3230 shapes, and still not the fixture scale.)doc")
        .def_readwrite("unused1c", &whiteout::m2::PhysicsShape::unused1c)
        .def_readwrite("padding1e", &whiteout::m2::PhysicsShape::padding1e, R"doc(SHP2+. Uninitialised on disk; kept so writes match.)doc")
    ;

    py::class_<whiteout::m2::BoxShape>(m, "BoxShape", R"doc(BOXS — an oriented box. The client turns it straight into a polytope via `CPhysicsBoxShapeDef::SetPolytopeData(frame, halfExtents)`.)doc")
        .def(py::init<>())
        .def_readwrite("frame", &whiteout::m2::BoxShape::frame)
        .def_readwrite("half_extents", &whiteout::m2::BoxShape::halfExtents)
    ;

    py::class_<whiteout::m2::CapsuleShape>(m, "CapsuleShape", R"doc(CAPS — a capsule between two local points.)doc")
        .def(py::init<>())
        .def_readwrite("local_position1", &whiteout::m2::CapsuleShape::localPosition1)
        .def_readwrite("local_position2", &whiteout::m2::CapsuleShape::localPosition2)
        .def_readwrite("radius", &whiteout::m2::CapsuleShape::radius)
    ;

    py::class_<whiteout::m2::SphereShape>(m, "SphereShape", R"doc(SPHS — a sphere at a local point.)doc")
        .def(py::init<>())
        .def_readwrite("local_position", &whiteout::m2::SphereShape::localPosition)
        .def_readwrite("radius", &whiteout::m2::SphereShape::radius)
    ;

    py::class_<whiteout::m2::PolytopeHalfEdge>(m, "PolytopeHalfEdge", R"doc(One half-edge of a polytope — Domino's `dmSubEdge`, four bytes.

Half-edges are stored in twin pairs at adjacent indices, and the ones bounding a face form a cycle through @ref nextEdge.)doc")
        .def(py::init<>())
        .def_readwrite("twin_offset", &whiteout::m2::PolytopeHalfEdge::twinOffset, R"doc(Signed step to the paired half-edge: the twin of edge `i` is `i + twinOffset`. Only +1 and -1 occur, in equal numbers.)doc")
        .def_readwrite("origin_vertex", &whiteout::m2::PolytopeHalfEdge::originVertex, R"doc(Where this half-edge starts, indexing PolytopeShape::vertices.)doc")
        .def_readwrite("face_index", &whiteout::m2::PolytopeHalfEdge::faceIndex, R"doc(The face this half-edge bounds, indexing PolytopeShape::facePlanes.)doc")
        .def_readwrite("next_edge", &whiteout::m2::PolytopeHalfEdge::nextEdge, R"doc(Next half-edge around @ref faceIndex.)doc")
    ;

    py::class_<whiteout::m2::PolytopeShape>(m, "PolytopeShape", R"doc(PLYT — a convex hull, version 3+. Domino's `dmPolytope`.

The chunk stores fixed-size headers and variable-size payloads in two blocks; both halves are folded into this one struct, and the header's counts are recomputed from the vectors on write. The header's four pointer fields are filled in by the client at load time and are zero in every file, so they are not kept.)doc")
        .def(py::init<>())
        .def_readwrite("vertices", &whiteout::m2::PolytopeShape::vertices, R"doc(Hull corners.)doc")
        .def_readwrite("face_planes", &whiteout::m2::PolytopeShape::facePlanes, R"doc(Outward plane of each face, `xyz` normal and `w` offset.)doc")
        .def_readwrite("face_first_edges", &whiteout::m2::PolytopeShape::faceFirstEdges, R"doc(One entry per face: any half-edge bounding it, as the entry point for walking the face through PolytopeHalfEdge::nextEdge.)doc")
        .def_readwrite("edges", &whiteout::m2::PolytopeShape::edges)
        .def_readwrite("centroid", &whiteout::m2::PolytopeShape::centroid, R"doc(Volume-weighted, not the vertex average.)doc")
        .def_readwrite("volume", &whiteout::m2::PolytopeShape::volume, R"doc(Hull volume.)doc")
        .def_readwrite("surface_area", &whiteout::m2::PolytopeShape::surfaceArea, R"doc(Hull surface area.)doc")
        .def_readwrite("padding04", &whiteout::m2::PolytopeShape::padding04, R"doc(The four-byte gaps each count leaves in front of its 64-bit pointer, and the one that trails the header. Uninitialised in the files — some carry fragments of unrelated strings — so they are kept verbatim for writing.)doc")
        .def_readwrite("padding14", &whiteout::m2::PolytopeShape::padding14)
        .def_readwrite("padding2c", &whiteout::m2::PolytopeShape::padding2c)
        .def_readwrite("padding4c", &whiteout::m2::PolytopeShape::padding4c)
    ;

    py::class_<whiteout::m2::PhysicsJoint>(m, "PhysicsJoint", R"doc(JOIN — connects two bodies with the joint named by @ref jointType.)doc")
        .def(py::init<>())
        .def_readwrite("body_a_index", &whiteout::m2::PhysicsJoint::bodyAIndex)
        .def_readwrite("body_b_index", &whiteout::m2::PhysicsJoint::bodyBIndex)
        .def_readwrite("padding08", &whiteout::m2::PhysicsJoint::padding08, R"doc(Zero in every corpus joint.)doc")
        .def_readwrite("joint_type", &whiteout::m2::PhysicsJoint::jointType)
        .def_readwrite("joint_id", &whiteout::m2::PhysicsJoint::jointId, R"doc(Entry index within the joint array @ref jointType selects.)doc")
    ;

    py::class_<whiteout::m2::WeldJoint>(m, "WeldJoint", R"doc(WELJ/WLJ2/WLJ3 — a soft rigid connection. Zero frequency means the axis is solved as a hard constraint.)doc")
        .def(py::init<>())
        .def_readwrite("frame_a", &whiteout::m2::WeldJoint::frameA)
        .def_readwrite("frame_b", &whiteout::m2::WeldJoint::frameB)
        .def_readwrite("angular_frequency_hz", &whiteout::m2::WeldJoint::angularFrequencyHz)
        .def_readwrite("angular_damping_ratio", &whiteout::m2::WeldJoint::angularDampingRatio)
        .def_readwrite("linear_frequency_hz", &whiteout::m2::WeldJoint::linearFrequencyHz, R"doc(WLJ2+)doc")
        .def_readwrite("linear_damping_ratio", &whiteout::m2::WeldJoint::linearDampingRatio, R"doc(WLJ2+)doc")
        .def_readwrite("unused70", &whiteout::m2::WeldJoint::unused70, R"doc(WLJ3+. Copied onto the weld def and never sent to Domino. Zero in 265 of 274 weld joints.)doc")
    ;

    py::class_<whiteout::m2::SphericalJoint>(m, "SphericalJoint", R"doc(SPHJ — a ball joint between two anchor points.)doc")
        .def(py::init<>())
        .def_readwrite("anchor_a", &whiteout::m2::SphericalJoint::anchorA)
        .def_readwrite("anchor_b", &whiteout::m2::SphericalJoint::anchorB)
        .def_readwrite("friction_torque", &whiteout::m2::SphericalJoint::frictionTorque)
    ;

    py::class_<whiteout::m2::ShoulderJoint>(m, "ShoulderJoint", R"doc(SHOJ/SHJ2 — a twist-and-cone joint, the one that chains cloth.)doc")
        .def(py::init<>())
        .def_readwrite("frame_a", &whiteout::m2::ShoulderJoint::frameA)
        .def_readwrite("frame_b", &whiteout::m2::ShoulderJoint::frameB)
        .def_readwrite("lower_twist_angle", &whiteout::m2::ShoulderJoint::lowerTwistAngle, R"doc(Degrees, like the cone; the client converts both to radians and enables the twist limit when `upper > lower`.)doc")
        .def_readwrite("upper_twist_angle", &whiteout::m2::ShoulderJoint::upperTwistAngle)
        .def_readwrite("cone_angle", &whiteout::m2::ShoulderJoint::coneAngle, R"doc(Degrees: the corpus holds 20, 35, 45 and 60. Stored as authored, so the conversion is the consumer's.)doc")
        .def_readwrite("max_motor_torque", &whiteout::m2::ShoulderJoint::maxMotorTorque)
        .def_readwrite("motor_mode", &whiteout::m2::ShoulderJoint::motorMode, R"doc(low byte: 0 off, 1 position, 2 velocity)doc")
        .def_readwrite("motor_frequency_hz", &whiteout::m2::ShoulderJoint::motorFrequencyHz, R"doc(SHJ2)doc")
        .def_readwrite("motor_damping_ratio", &whiteout::m2::ShoulderJoint::motorDampingRatio, R"doc(SHJ2)doc")
    ;

    py::class_<whiteout::m2::PrismaticJoint>(m, "PrismaticJoint", R"doc(PRSJ/PRS2 — a sliding joint, version 2+.)doc")
        .def(py::init<>())
        .def_readwrite("frame_a", &whiteout::m2::PrismaticJoint::frameA)
        .def_readwrite("frame_b", &whiteout::m2::PrismaticJoint::frameB)
        .def_readwrite("lower_limit", &whiteout::m2::PrismaticJoint::lowerLimit, R"doc(Distances, not angles; the limit is enabled when `upper > lower`.)doc")
        .def_readwrite("upper_limit", &whiteout::m2::PrismaticJoint::upperLimit)
        .def_readwrite("reference_translation", &whiteout::m2::PrismaticJoint::referenceTranslation, R"doc(The zero point the limit is measured from. No `dmJointDef` slot: the client writes it into the live joint after creation. Zero in all twelve corpus prismatics.)doc")
        .def_readwrite("max_motor_force", &whiteout::m2::PrismaticJoint::maxMotorForce)
        .def_readwrite("motor_speed", &whiteout::m2::PrismaticJoint::motorSpeed, R"doc(Target velocity, written into the live joint like @ref referenceTranslation.)doc")
        .def_readwrite("motor_mode", &whiteout::m2::PrismaticJoint::motorMode)
        .def_readwrite("motor_frequency_hz", &whiteout::m2::PrismaticJoint::motorFrequencyHz, R"doc(PRS2)doc")
        .def_readwrite("motor_damping_ratio", &whiteout::m2::PrismaticJoint::motorDampingRatio, R"doc(PRS2)doc")
    ;

    py::class_<whiteout::m2::RevoluteJoint>(m, "RevoluteJoint", R"doc(REVJ/REV2 — a hinge, version 2+.)doc")
        .def(py::init<>())
        .def_readwrite("frame_a", &whiteout::m2::RevoluteJoint::frameA)
        .def_readwrite("frame_b", &whiteout::m2::RevoluteJoint::frameB)
        .def_readwrite("lower_angle", &whiteout::m2::RevoluteJoint::lowerAngle, R"doc(Degrees; the limit is enabled when `upper > lower`.)doc")
        .def_readwrite("upper_angle", &whiteout::m2::RevoluteJoint::upperAngle)
        .def_readwrite("max_motor_torque", &whiteout::m2::RevoluteJoint::maxMotorTorque)
        .def_readwrite("motor_mode", &whiteout::m2::RevoluteJoint::motorMode, R"doc(1: position mode (frequency > 0), 2: velocity mode.)doc")
        .def_readwrite("motor_frequency_hz", &whiteout::m2::RevoluteJoint::motorFrequencyHz, R"doc(REV2)doc")
        .def_readwrite("motor_damping_ratio", &whiteout::m2::RevoluteJoint::motorDampingRatio, R"doc(REV2)doc")
    ;

    py::class_<whiteout::m2::DistanceJoint>(m, "DistanceJoint", R"doc(DSTJ — holds two anchors a fixed distance apart, version 2+.)doc")
        .def(py::init<>())
        .def_readwrite("local_anchor_a", &whiteout::m2::DistanceJoint::localAnchorA)
        .def_readwrite("local_anchor_b", &whiteout::m2::DistanceJoint::localAnchorB)
        .def_readwrite("distance", &whiteout::m2::DistanceJoint::distance)
    ;

    py::class_<whiteout::m2::PhysicsTuning>(m, "PhysicsTuning", R"doc(PHYV — the per-model vegetation push: the six `physVeg*` console variables in registration order (`PHYS_FORMAT.md` §3.9).

Read only for a `PHYT` 2 model, which becomes a phantom pushed by units walking through it rather than a ragdoll.)doc")
        .def(py::init<>())
        .def_readwrite("pos_max_push", &whiteout::m2::PhysicsTuning::posMaxPush, R"doc(Yards a bone may be pushed from its base before it is clamped.)doc")
        .def_readwrite("pos_push_amt", &whiteout::m2::PhysicsTuning::posPushAmt, R"doc(Yards per frame a bone is pushed while a unit moves along it, times dt.)doc")
        .def_readwrite("pos_relax_speed", &whiteout::m2::PhysicsTuning::posRelaxSpeed, R"doc(How fast the bone returns to rest once the unit leaves.)doc")
        .def_readwrite("vel_max_push", &whiteout::m2::PhysicsTuning::velMaxPush, R"doc(Extra push along a moving unit's velocity.)doc")
        .def_readwrite("vel_speed", &whiteout::m2::PhysicsTuning::velSpeed, R"doc(How fast the bone sways along that velocity.)doc")
        .def_readwrite("min_push_dist", &whiteout::m2::PhysicsTuning::minPushDist, R"doc(**Squared** distance inside which a unit starts pushing. The client uses 8.0 for a model with no PHYV.)doc")
    ;

    py::class_<whiteout::m2::PhysicsAllowList>(m, "PhysicsAllowList", R"doc(PHAO — the host skeletons this file's follow factors were tuned on.

On a host whose key-bone-4 name CRC is not listed, the client discards every body's @ref PhysicsBody::followFactor for a flat 0.7. No shipped file has one.)doc")
        .def(py::init<>())
        .def_readwrite("header", &whiteout::m2::PhysicsAllowList::header, R"doc(The chunk's leading u32. The client keeps its low byte and never reads it.)doc")
        .def_readwrite("keys", &whiteout::m2::PhysicsAllowList::keys)
    ;

    py::class_<whiteout::m2::PhysicsUnknownChunk>(m, "PhysicsUnknownChunk", R"doc(A `.phys` chunk this library does not know, kept verbatim so a parse/write cycle does not drop it.)doc")
        .def(py::init<>())
        .def_readwrite("data", &whiteout::m2::PhysicsUnknownChunk::data)
        .def("get_tag",
            [](const whiteout::m2::PhysicsUnknownChunk& self) {
                return std::vector<char>(self.tag.begin(), self.tag.end());
            })
        .def("set_tag",
            [](whiteout::m2::PhysicsUnknownChunk& self, const std::vector<char>& v) {
                if (v.size() != self.tag.size())
                    throw std::runtime_error("setter expected exactly "
                        + std::to_string(self.tag.size()) + " elements");
                for (std::size_t i = 0; i < v.size(); ++i) self.tag[i] = v[i];
            })
    ;

    py::class_<whiteout::m2::PhysicsData>(m, "PhysicsData", R"doc(A whole `.phys` file — Blizzard's Domino rigid-body setup for a model, either a `.phys` sibling or an M2's inline PFDC chunk.

Bodies attach to bones and are linked by joints; each body owns a run of @ref shapes, and each shape indexes the array its type names.)doc")
        .def(py::init<>())
        .def_readwrite("version", &whiteout::m2::PhysicsData::version, R"doc(0 (MoP) through 6. Decides which layout each chunk is written in — see the per-field version notes on the structs above.)doc")
        .def_readwrite("phyt", &whiteout::m2::PhysicsData::phyt, R"doc(PHYT, version 1+: a PhysicsObjectKind, kept raw so any value round-trips.)doc")
        .def_readwrite("allow_list", &whiteout::m2::PhysicsData::allowList, R"doc(PHAO. Absent in every shipped file.)doc")
        .def_readwrite("bodies", &whiteout::m2::PhysicsData::bodies)
        .def_readwrite("shapes", &whiteout::m2::PhysicsData::shapes)
        .def_readwrite("box_shapes", &whiteout::m2::PhysicsData::boxShapes)
        .def_readwrite("capsule_shapes", &whiteout::m2::PhysicsData::capsuleShapes)
        .def_readwrite("sphere_shapes", &whiteout::m2::PhysicsData::sphereShapes)
        .def_readwrite("polytope_shapes", &whiteout::m2::PhysicsData::polytopeShapes)
        .def_readwrite("joints", &whiteout::m2::PhysicsData::joints)
        .def_readwrite("weld_joints", &whiteout::m2::PhysicsData::weldJoints)
        .def_readwrite("spherical_joints", &whiteout::m2::PhysicsData::sphericalJoints)
        .def_readwrite("shoulder_joints", &whiteout::m2::PhysicsData::shoulderJoints)
        .def_readwrite("prismatic_joints", &whiteout::m2::PhysicsData::prismaticJoints)
        .def_readwrite("revolute_joints", &whiteout::m2::PhysicsData::revoluteJoints)
        .def_readwrite("distance_joints", &whiteout::m2::PhysicsData::distanceJoints)
        .def_readwrite("tuning", &whiteout::m2::PhysicsData::tuning, R"doc(PHYV. A file that has one carries nothing else.)doc")
    ;

    bind_m2_1(m);
    bind_m2_2(m);
    bind_m2_3(m);
}