From 2f10cb1eefbbd00277363a93af0a08863cc56e9f Mon Sep 17 00:00:00 2001 From: Marco Hladik Date: Mon, 9 Aug 2021 10:19:14 +0200 Subject: [PATCH] Add vvm.txt and usage entry --- README.md | 4 ++ vvm.txt | 124 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 vvm.txt diff --git a/README.md b/README.md index af41a75..73b68c7 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,10 @@ Make sure you have a C++ compiler installed and issue: ```make``` +# Usage + +Please read the `vvm.txt` file included in this repository for more information. + # LICENSE Copyright (c) 2010-2016 Lee Salzman diff --git a/vvm.txt b/vvm.txt new file mode 100644 index 0000000..4dd9e5e --- /dev/null +++ b/vvm.txt @@ -0,0 +1,124 @@ +Vera Visions Model +Readme 1.1 +=================== + +Vera Visions Model, short VVM, used to be called IQM-EXT (or sometimes IQM-FTE). +Due to the fact that the IQM prefix will cause confusion in regards +to compatibility and the format not entirely being exclusive to FTE (the engine +we are using for The Wastes) we decided to name it something more specific. +Thanks a lot to Spike for the implementation of our spec. Without him +we'd still be stuck with the original tools. + +This documentation is for our exporter - while its primary use was +to create a new, extended format that's compatible with the FTE QuakeWorld engine +the exporter and its output are completely compatible with engines that do not read +the enhanced format yet. Do NOT expect to use any of the new features though. + +Features that the original IQM exporter did not offer: + +- Rotating the entire output or single scenes +- Proper position offsetting of the entire output or single scenes +- Support for external configuration files for IQM generation (ala studiomdl) + +Some features that our extended specification (VVM) has to offer: + +- Support for hitmeshes for faster, content-aware collision detection +- Automatic hitmesh generation +- Submodels that allow showing/hiding specific groups of the model via the game-logic +- Support for frame triggered events that can be read by the game-logic + +Let's get started! + +Basic Usage +=========== + +The official exporter has the following usage: + +./iqm output.iqm reference.file [--options] ...sequences (optional) + +If you are working on models with more than a dozen animations, you will already +feel the pain of having to scroll horizontally with most text-editors. + +With our updated exporter, we decided to ditch the parameter oriented approach +to take full advantage of the features and to improve readability and our workflow. + + ./vvm input.file + +...is all you'd need. +Now, let's show you a basic input file: + +input.file: + output output.vvm + scene reference_mesh.smd + scene animation1.smd fps 25 + +And that's about it. +The 'model' line tells you the output filename, aka that's the file the exporter will generate. +The first 'scene' line refers to a reference mesh file, the one with all the polygons. You +can have as many as you like and they will be stitched together "as one" in the exported file. +The second scene line in this example imports an animation file and specifies the playback +framerate to be 25 frames per second. + +Note that you can still use other formats instead of SMD as input files for references/sequences. + +Let's take a look at an older example input file +right from the development of The Wastes: + + output view_tommygun.vvm + bone "Bone55" rename "Muzzleflash" + scene ref_tommygun.smd + rotate 0 -90 0 + scene idle.smd fps 20 + scene idle_fidget1.smd fps 20 + scene idle_fidget2.smd fps 20 + scene reload.smd fps 22 + scene draw.smd fps 25 + scene holster.smd fps 25 + scene shoot.smd fps 34 + scene shoot_last.smd fps 34 + scene shoot_empty.smd fps 34 + +This is one of the lesser-simple ones, since we are renaming a bone, had to rotate +the model by 90 degrees and have a bunch of animations with varying framerates. + +Command reference +================= + +Here is a list of all the commands you can issue when constructing your input file ( [xyz] parameters being optional ): + +Header/Command Format: + output - specified the output file name. you should only have one of these. + exec - exec the specified command file, before parsing the rest of the current file. + hitbox - generates a hitmesh as a bbox centered around the bone in the base pose (the hitbox will rotate/move with animations). The bodynum will be visible to gamecode, and may merge with other hitboxes with the same group. + modelflags - enables the specified bit in the iqm header. supported names include q1_rocket, q1_grenade, q1_gib, q1_rotate, q1_tracer1, q1_zomgib, q1_tracer2, q1_tracer3 + - defined below and applied as the defaults to the following import lines as well as mesh lines. + mesh [MESH PROPERTIES LIST] - provides overrides for a single named mesh (properties used will be those as they're already defined, if not otherwise listed). + bone [rename ] [group ] - provides bone renaming and grouping. try to avoid renaming two bones to the same resulting name... groups may have limitations if a parent/child relationship cannot be honoured. lowest group numbers come before higher groups. by default bones will inherit their group from their parent. + - defined below and applied as the defaults to the following import lines. + import [IMPORT PROPERTIES] [MESH PROPERTIES] - imports the meshes and animations from the specified file. + +Shared Scene Properties: + rotate - rotates the model + scale - rescales the model + origin - moves the thing + materialprefix - provides a text prefix on the material name, which should make it easier for editors while still honouring shader paths. + nomesh <1|0> - discards all meshed from the affected files. + noanim <1|0> - discards animations from the affected files, does not disclude the base pose. + +Reference Properties: + contents - 'body' or 'empty' are the two that are most likely to be used. 'solid' may also be desired, or possibly also 'corpse'. + surfaceflags - self explanatory, can also use 'q3_nodraw/fte_nodraw' + body - this is the 'body' value reported to gamecode when a trace hits this surface. + geomset - pretty much submodels. + lodrange - not yet implemented by the engine. 0 for both is the default. + +Animation Properties: + name - the imported animations will be assigned this name. May be problematic if the imported file(s) share the same name, so try to avoid using this at global scope. + fps - framerate for any imported animations. + loop - flags animations as looping. + clamp - disables looping. + unpack - seperates each pose/frame of the animations into a seperate single-pose animation for compat with q1 or q2-style model animations. + pack - disables unpacking again + start - the first pose/frame to import. + end - the last pose/frame to import. + event [ANIM] <"EVENTDATA"> - embeds event info within the animation. If used at global scope, can be reset with 'event reset' in order to not apply to later files.