WARNING! THIS IS NOT FINISHED! ACTUALLY, IT'S NOT EVEN STARTED YET!
the information here may be wrong or outdated.


file: "models/models.xml"

<?xml version="1.0" encoding="UTF-8" ?>
<vavoom_models_list>
  <!-- the only possible node here -->
  <include file="models/ammo/clip.xml" />
</vavoom_models_list>


"transform" tag contains set of transformations, like this:
<transform>
  <offset z="-10" />
  <scale value="2" />
</transform>

allowed simple transformations: "offset", "scale", "rotate". those
transformations can have either "value" attr, or "x", "y", "z".
the transformations are stacked. for "rotate" you can use "yaw",
"pitch", and "roll" attribute names.

you can also specify transformation matrix with:
  <matrix>
    1 0 0 0
    0 1 0 0
    0 0 1 0
    0 0 0 1
  </matrix>

it's just a raw 4x4 matrix values. you can use `absolute="true"` attribute to
replace the current matrix, otherwise matrix multiplication will be used.

identity matrix can be written as: <matrix>identity</matrix>

WARNING! the matrix must describe a valid affine transformation, but cannot include
shearing. this is because frame interpolator doesn't know what to do with shearing yet.

each frame can have a local transform tag too.


"vavoom_model_definition" can be used to set global parameters (with attrs).
currently supported:
  noselfshadow
  noshadow
  fullbright
  usedepth
  iwadonly
  thiswadonly
  rotation
  bobbing


<?xml version="1.0" encoding="UTF-8" ?>
<vavoom_model_definition>
  <!--
    this defines one 3d model. you can have several of them, and refer to models by their names.
    one model can contain several submodels in various formats; they can be used to build a complex
    compound models from simplier parts.
    note that names are local for "vavoom_model_definition".
  -->
  <model name="base">
    <md2 file="models/ammo/ammo.md2">
      <!--
        this defines source model file. you can use 'md2', 'md3', or 'kvx' tag here.
        'kvx' is common tag for KVX and KV6 voxel models.
        voxel models should not have skin animation, mesh index, or position model.
        also, voxel models always should have exactly one frame.
        note that you can omit frame definition if your source model has only one frame
        (or you want to use only one frame).
        you can use additional attributes:
          int mesh_index -- mesh for this model (mostly used for md3 models)
          int version -- model version. this is used to assign different player models to different weapons, using `Weapon.PlayerModelVersion`
          string position_file -- sets "position model"
          int skin_anim_speed -- sets skin animation speed, in seconds; requires `skin_anim_range`
          int skin_anim_range -- number of skins in animation loop
          bool fullbright -- this model is fullbright (default is `false`)
          bool noshadow -- this model doesn't cast shadow (default is `false`)
          bool usedepth -- force depth flag (for things like monsters with alpha transaparency) (TODOCUMENT)
          bool allowtransparency -- allow transparency in skin files, for skins that are transparent in solid models (TODOCUMENT)
          float alpha_mul -- multiplier for entity alpha; can be used to make some submodels translucent (like glass on a complex lamp model)
        you can use "transform" tag here, see above. this sets default transformation for all following frames.
      -->
      <frame index="0">
        <!--
          this defines model frames. each used frame in model file should be listed here, and assigned an index.
          you can omit this if you only want to use the first submodel frame.
          note that "index" is model file frame index (voxels currently has only one)
          indexes:
            int index -- model frame index
            int end_index -- model frame end index (inclusive), default: index
          or:
            int count -- number of frames to create, default: 1
          if no index/count specified, create one frame with index of the last frame plus 1
          you can use additional attributes:
            int position_index
            float alpha_start
            float alpha_end
            int skin_index
          frame-local "transform" tags are allowed here
        -->
      </frame>
      <!--
        you can define model skins with `skin` tag
        required attributes:
          string file
        you can use additional attributes:
          rgbcolor shade
      -->
      <!--
        you can define model subskins for MD3 models with `subskin` tag (for MD3 submodels)
        required attributes:
          int submodel_index
          string file
        you can use additional attributes:
          rgbcolor shade
      -->
    </md2>
  </model>

  <!--
    this attaches models to actor classes.
    you can use additional attributes:
      bool noselfshadow -- this class won't shadow self (default is `false`)
      bool iwadonly -- replace frames only if sprites are from IWAD
      bool thiswadonly -- replace frames only if sprites are from the current WAD/PK3
      bool rotation
      bool bobbing
      bool spriteshadow -- use sprite instead of 3d model for shadowmaps
  -->
  <class name="ClipBox">
    <!--
      attach model to state.
      you can assign model either to state with the given number (int index), or to srpite (string sprite).
      assign to indicies:
        int index -- starting state index; use `-1` for "all states"
        int last_index -- used to assign model to state range
      assign to sprites:
        string sprite -- base sprite name (4 chars)
        string sprite_frame -- sprite frame (1 char)
      specify model:
        string model (can be omited if only one model is defined)
        int frame_index (can be omited if the given model has only one frame)
        optional int submodel_index
        optional bool hidden -- TODOCUMENT
      interpolation
        optional float inter -- if you want to assign more than one model to some state/sprite, use this to specify interstate time [0..1]
      optional attributes:
        float angle_yaw
        float angle_pitch
        float angle_roll
        float rotate_yaw
        float rotate_pitch
        float rotate_roll
        bool rotation
        bool bobbing
        float rotation_speed (default is 100)
        float bobbing_speed (default is 180)
        string usepitch ("actor", "momentum", "default", "false"; default is "actor")
        string useroll ("actor", "momentum", "default", "false"; default is "false")
        float angle_start
        float angle_end
        float alpha_start
        float alpha_end
        float random_zoffset_min (0)
        float random_zoffset_max (0)
      for angle/rotate, you can specify "random". random value will be different for each map entity.
      this can be useful for things like blood splats, for example.
      note that this random value is always the same for the given entity, i.e. two states with random
      angle will get the same value for the same entity.
      random z offset can be used for blood pools and such, so they will less likely end with the same Z
      coord, to get rid of z-fighting.
    -->
    <state index="-1" model="base" frame_index="0" />
  </class>
</vavoom_model_definition>
