meddle.zip

KEYS.TXT

This is a quick ref sheet for keys.

2D Mode:

  ARROW Keys: move cursor

  Esc : exit

  3 : goto 3d mode

  1 : goto help (about)

  t : draw triangles

  v : draw vertices

  s : SAVE MDL FILE

  p :

  m :

  . or > :     next skin

  , or < : previous skin

  " or ' : next pants color

  ; or : : previous pants color

  } or ] :     next shirt color

  { or [ : previous shirt color

  MOUSE move : move cursor

  MOUSE left button: grab hi-lighted vertex

3D Mode:

  ARROW up/down : move eye position up/down

  ARROW left/right : previous/next animation frame

  Esc : exit

  2 : goto 2d mode

  1 : goto help (about)

  t : draw triangles

  v : draw vertices

  s : TAKE SCREEN SHOT (saved as pic#.bmp)

  h : show header

  c : auto cycle through animation frames

  b : change background color (black, gray, white)

  r : reset view

  . or > :     next skin

  , or < : previous skin

  " or ' : next pants color

  ; or : : previous pants color

  } or ] :     next shirt color

  { or [ : previous shirt color

  Tab :        change rendering mode

(flat shade, gourourd shade, texture, texture + shade)

  MOUSE up/down + right button : zoom in/out

  MOUSE move + left button : rotate model

  MOUSE move : move light source

Command line:

  load model.mdl and view

  mdl model.mdl

          import bmp/gif (asc/wrl/dxf/map/raw/pov) to skin (frame)

          number # in model.mdl

          (if # is greater than model skins (frames), skin  (frame) is added)

  mdl -i pic.bmp # model.mdl

          export skin (frame) number # to bmp/gif (asc/wrl/dxf/map/raw/pov)

          frome model.mdl

          (if # is 0 or negetive, a new blank skin with triangles is exported)

  mdl -e pic.bmp # model.mdl

          run a script

                mdl script.med

MDL.TXT

-----------------------------------------------------------------------------

MedDLe v1.5

-----------------------------------------------------------------------------

by brian martin

brian@phyast.pitt.edu

http://www.phyast.pitt.edu/~brian

also look at http://www.phyast.pitt.edu/~brian/meddle

Disclaimer: The author takes no responsiblity for misuse of

this program. He also is not responsible for any damage caused by it.

This documentation needs work. period. it should be helpful though.

-----------------------------------------------------------------------------

Quick Start:

-----------------------------------------------------------------------------

edit mdl.cfg to fit your needs

run mdl (i.e. "mdl player.mdl")

hit key '1' for help

what's new??

fixed some bugs

script language

model generation

gif support

improved frame export/import functions

command line options slightly different

-----------------------------------------------------------------------------

Contents:

-----------------------------------------------------------------------------

1. About MedDLe

2. Installation

3. Basic Use

4. Editing MDL files (step by step)

4.a Textures

4.b Frames

5. Script Language

6. Notes about file types

7. History

-----------------------------------------------------------------------------

1. About

-----------------------------------------------------------------------------

MedDLe is a program which lets you look at and edit the mdl

files in quake. These are the files which describe the objects

in quake and are located in the QUAKE\PROGS directory. You have to first

unpack the id1.pak file with a program like unpack or qube. These can both

be found at ftp.cdrom.com.

Features :

View bitmaps (object textures)

View/edit point mapping of the vertices

Export model textures to a BMP or GIF file

Import BMP or GIF files to give objects a new 'skin'

Export animation frames to wrl,asc,dxf,pov,map, and raw files

Import RAW files to make new animations

Small script language which will allow you to totally screw an mdl

3D View of object (vertex / wireframe / flatshaded / texture mapped views)

Animation frame browser

Played color changer

.more.

-----------------------------------------------------------------------------

2. Installation

-----------------------------------------------------------------------------

You should stick MedDLe in its own directory. Just unzip it

in a suitable directory (i.e. c:\mdl).  You should have these files

in the MedDLe directory:

MDL.EXE         -the executable

MDL.CFG         -the configuration file

MDL.FNT         -the fonts

MDL.PAL         -the palette

MDL.MAP         -the colormap

KEY.TXT         -quick reference sheet

        -MDLSRC.ZIP     -the source code- i will release separately or mail me

CWSDPMI.EXE     -dpmi environment (not needed if in windows)

EXAMPLE/        -directory with script example(s)

If everything is in place, bring up MDL.CFG in a text editor and set

the path variable and video driver to match your system. You can set

the video resolution here too. When your done, save the file. That's it!

note: You may need a 386/483sx and math co-procesor or a 486dx or higher

to run this. I don't know. There are several math emulators on the net

if it doesn't work on your numerically challenged machine.

-----------------------------------------------------------------------------

3. Basic Use

-----------------------------------------------------------------------------

MedDLe has no GUI at this point. Live with it. :)

MedDLe can both be used to view and edit mdl files. To

start the program just type 'mdl file.mdl' where 'file.mdl'

is a valid mdl filename.

You start in 3D mode.

ARROW up/down : move eye position up/down

ARROW left/right : previous/next animation frame

Esc : exit

2 : goto 2d mode

1 : goto help (about)

t : draw triangles

v : draw vertices

s : TAKE SCREEN SHOT (saved as pic#.bmp)

h : show header

c : auto cycle through animation frames

b : change background color (black, gray, white)

r : reset view

. or > :     next skin

, or < : previous skin

" or ' : next pants color

; or : : previous pants color

} or ] :     next shirt color

{ or [ : previous shirt color

Tab :        change rendering mode

(flat shade, gourourd shade, texture, texture + shade)

MOUSE up/down + right button : zoom in/out

MOUSE move + left button : rotate model

MOUSE move : move light source

Just think of the mouse as your hand grabbing the object. It should

then be easy to control. If you hit the '2' key, you will go to

2D mode. Here the keys are:

ARROW Keys: move cursor

Esc : exit

3 : goto 3d mode

1 : goto help (about)

t : draw triangles

v : draw vertices

s : SAVE MDL FILE

p :

m :

. or > :     next skin

, or < : previous skin

" or ' : next pants color

; or : : previous pants color

} or ] :     next shirt color

{ or [ : previous shirt color

MOUSE move : move cursor

MOUSE left button: grab hi-lighted vertex

The mouse can be used to move vertices in this mode.

** NEW **

Command line options of importance.. Now meddle figures out if it's

a skin or frame by the extension.

import gif (or bmp) to skin number # in model.mdl

(if # is greater than model skins, skin is added)

mdl -i pic.gif # model.mdl

export skin number # to gif (or bmp) from model.mdl

(if # is 0 or  negetive, a new blank skin with triangles is exported)

mdl -e pic.gif # model.mdl

import raw to frame number # in model.mdl

mdl -i frame.raw # model.mdl

export frame number # to asc from model.mdl

mdl -e frame.asc # model.mdl

run a script file (must have a .med extension)

mdl script.med

!IMPORTANT!

NOTE: When you use MedDLe, it will read the original mdl files from

the path you set BUT will do all saving and reading from the

current directory. If you load MedDLe in your quake/progs directory,

you may end up erasing something you wish you hadn't. Of course you

can change the read directory in the cfg file, but the save directory

is always the current one.

It may be a hassel, but you'll have to copy the saved mdl to the progs

directory for quake to see the changes (duh).

-----------------------------------------------------------------------------

4. Editing MDL files

-----------------------------------------------------------------------------

I have some info at http://www.phyast.pitt.edu/~brian/meddle but this

ought to help you get started.

4.a Textures

The following explains the basic proceedure for adding a new skin to

the player model.

In this example the 'player.mdl' file is modified with the texture

'play1.bmp'.

1. First export the original texture. It will be saved in your

MedDLe directory.

'mdl -e play0.bmp 1 player.mdl'

NOTE: If you want to start from stratch (blank skin), use

'mdl -e play0.bmp 0 player.mdl'

2. Now go off and modify the texture in your favorite paint

program. Make sure you save the new skin with 8-bit color

in GIF or BMP format. Save the modified texture as 'play1.bmp'

and place it in your MedDLe directory. The file mdl.pal (included)

can be loaded into programs like Paint Shop Pro so you can use the

correct palette, but MedDLe will try to match it up with the quake

palette if you don't. MedDLe also resizes the picture if necessary.

3. Import the new texture (play1.bmp).

'mdl -i play1.bmp 2 player.mdl'

Since we said '2' it will add the skin in addition to the original

skin.

4. Get into 2D mode (hit '2'). You can use the mouse to tweak some

of the vertices. You want to make sure that you don't change the

original layout too much, but also want to make sure there is no

background showing through any of the polygons. You should toggle back

and forth between 2D mode and 3D mode to check that the texture mapping

is ok. When your done tweaking, PRESS 's' IN 2D MODE to save your changes.

Also, you can now change the shirt and pants color to see if you used

some colors you shouldn't have. Use the " [ ] ; ' " keys to do this.

NOTE: If you don't press 's' in 2D mode your imported texture

will NOT be saved!

5. Copy the new 'player.mdl' file to the quake/progs directory.

You may want to back up the original 'player.mdl' before doing this.

6. Run QUAKE!

Of course the player.mdl is you, so you won't see your changes... :)

** NEW **

4.a Textures

The following explains the basic proceedure for replacing animation

frames. In this example the 'player.mdl' file is modified with the

3d data file 'play1.raw'.

1. First export the original frame. It will be saved in your

MedDLe directory.

'mdl -e play0.raw 1 player.mdl'

MedDLe will figure out the type of file it is by the extension. So

'mdl -e play0.asc 1 player.mdl'

will save it as a 3d studio asc file. Exportable file types are

pov (POVRay), dxf (cadd type), raw (raw points), asc (ascii),

map (quake map), wrl (vrml file) and 3ds (3dstudio file).

The wrl file is the most complete. If you export the skin and convert

it to a GIF file named 'skin.gif', the wrl file will be texture mapped.

The 3ds file isn't quite working perfect so use asc if you have 3d studio.

The raw file can be read by the 3d editor called Breeze Designer which

is a shareware program (or freeware?) which allows vertex editing. I like

it and recommend it.

Remember, to see the frame number of the frames, hit 'h' while in 3d mode.

Use that number when extracting frames.

2. Now go off and modify the frame data in your favorite program.

(like i said, Breeze Designer is nice) Save the modified frame as

'play1.raw' and place it in your MedDLe directory.

One word about 3d editing. DON'T CHANGE THE NUMBER OF POINTS IN A FRAME

IF YOU PLAN ON IMPORTING TO AN EXISTING MDL FILE! JUST MOVE POINTS.

DON'T ADD OR DELETE POINTS! Making a model from scratch is a different

story. Read mdl script section below for that.

3. Import the new frame (play1.raw).

'mdl -i play1.raw 1 player.mdl'

4. Get into 2D mode (hit '2'). PRESS 's' IN 2D MODE to save your changes.

NOTE: If you don't press 's' in 2D mode your new frame won't be saved!

5. Copy the new 'player.mdl' file to the quake/progs directory.

You may want to back up the original 'player.mdl' before doing this.

6. Run QUAKE!

Some added features that a serious editor will use are..

- the file mdl.pal is used for quake. If you are editing a custom game,

you can replace mdl.pal with your own palette. The colormap can also

be changed (mdl.map).

- if you want to add a skin, just make sure the number is greater that

the current number of skins (same for frames)

- if you want to extract a blank skin is a number equal to or less

than zero.

-----------------------------------------------------------------------------

5. Scripting Language

-----------------------------------------------------------------------------

There is a small, but powerful scripting language. It is easy to

use and is the only way to really do serious work. Hopefully

there are some examples with this distribution.

The script isn't high tech, so you must use proper syntax. That is,

you better have a space between words and suff.

-Anything after a # is ignored.

-the progspath in the cfg file is NOT used.

-all script files must have extension .med

-type "mdl <name>.med" to run the script

Here are th commands followed by a description. Things in <> are

necessary arguments:

path <workingpath>

this sets the working path <workingpath> for following file io.

you should end the path with a slash or back-slash (like oj).

load_mdl <name>

this will load <name> into MedDLe. You need to load a file

before you can change things.

save_mdl <name>

this saves the current (modified) mdl file to <name>

new_mdl <frame.name>

this creates a brand spanking new mdl file. You must supply

a base frame. A blank skin will be created. Note that the base

frame usually is not ever going to be used for the model, but

serves as a template for all of the other frames. The frame is

stored in the first frame slot.

get_info <name>

this outputs some of the model info to a file <name>.

decompose <medfile> <skin extension> <frame extension>

this extracts all skins and frames from a model. you must specify

the file extensions for the extracted data (i.e. gif or bmp for

<skin extension>). You must also give a med file name which will

be created to help put things back together. To use the created

file, make sure to un-comment out the 'save' line at the end of

the file.

add <filename>

adds <filename> to the current loaded model

insert <filename> <index>

inserts <filename> to the current loaded model in position <index>

extract <filename> <index>

extracts frame or skin number <index> to <filename>

set <data_type> <value>

sets certain header values in the model. the valid data types are:

(these are floating point values)

xscale, yscale, zscale, xoffset, yoffset, zoffset

eyex, eyey, eyez

average_size, radius

(these are unsigned integer values)

version, num_skins, num_frames, num_vertices,

skin_width, skin_height, sync_type, flags

if you don't know what your doing you can really screw things up here.

this only sets the value, it doesn't modify the data, so changing the

skin width will most likely just crash quake (and meddle) when you

try loading a file.

frame_name <index> <new name>

this changes the frame <index>'s name to <new name>. Remember that

with MedDLe all indices start at 1 (not 0).

(I know I need to add a delete feature as well)

Here are some examples:

example 1:

path c:\quake\progs\    #set path to progs directory

load_mdl armor.mdl      #load armor model into memory

path c:\mdl\script\     #set path to script directory

decompose armor.med gif raw  #extract all of model into script dir

#save skins in gif format and frames in raw format

#create a file armor.med which will put the model

#back together

example 2:

path c:\quake\progs\    #set path to progs directory

load_mdl player.mdl     #load player model into memory

path c:\pictures\       #set path to pictures directory

add newskin.bmp         #adds a new skin

set zscale .1           #squash the model (why? who knows..)

path c:\quake\progs\    #set path to progs directory

save_mdl player2.mdl    #save changes to player2.mdl in progs dir

example 3:

path c:\quake\progs\    #set path to progs directory

load_mdl player.mdl     #load player model into memory

path c:\mdl\            #set path to mdl

extract frame1.raw 71   #extract frame 71 to frame1.raw in mdl dir

new_mdl frame1.raw      #generate a new model

extract skin1.gif 1     #get the blank skin (so we can modify it)

save_mdl newplay.mdl    #save the new model

Hope this helps out.

I should mention that ripping appart existing mdl files with decompose

and rebuilding them will not produce the original models. Why? you ask.

Well as I mentioned earlier, a base frame is used to generate the

texture and mapping. If you just use the first frame of the model,

you may get crappy results. For instance, the ogre.mdl has a chain

saw which won't generate a nice mdl. So what do you do? I think this

is what id did: You create your objects (ogre and chainsaw) separately

and then place them in the model file such that they are facing in

the x direction and are fairly symmetric about the y axis. (z points up).

Then generate a model with that frame. You can then move the chain saw to

the hand of the ogre in the other frames. So the script may look like:

new_mdl base.raw

insert frame1.raw

instead of just:

new_mdl frame2.raw

Now you may still have some problem getting the texture map to show

all sides of the chainsaw (or any square object for that matter). In

this case you should rotate the object around it's y axis 45 degrees

in the base frame. This will expose the sides of object better in

some cases. Because of all these little tricks, you can't just

expect to make the player.mdl from decompose. (you'll have to move

things so that the gun, axe, and fire flash generate a nice base skin).

If you make a model from scratch, you should keep in mind that

your probably using a PC, not a CRAY. KISS. Keep It Simple Stupid.

Between 1 and 500 triangles is good. Also remember that the models

only have a resolution of 255x255x255 in discrete units, but are scaled.

The typical height of a model (in your editors coordinates) is

about 70. and monsters like the ogre is over 100. Models face in the

x direction, z is up, and y to the models left. They should be centered

about the origin, but this can be changed later using the 'set'

command. Also try to keep all the frame sizes about the same. You'll

find out that if you make the base frame too different, things will

be screwed.

Is that good enough for now?

One last note. Because MedDLe wasn't written with speed in mind

when it comes to import/extract, things get slower and slower the

more frames you add. It should't crash though.

        I take that back. Another note: you may want to pipe the out put

        from the script to a file : "mdl script.med > out.txt"

-----------------------------------------------------------------------------

6. Notes about file types

-----------------------------------------------------------------------------

Since there is a lot of file importing and exporting going on,

I decided to say say a little about each file type.

For the pictures, there is not much to say except to keep

the colors to 8-bit (256 color). GIF and BMP are supported

and are color matched and resized when imported.

Now the 3d files. Since it seems like every editor interperates

the 3d coordinates differently...

        RAW: this file is just ascii numbers. the first 3 are the x,y,z

        coordinates of the first vertex in the first triangle. The next 3

        are the second vertex of the first triangle. The third set of 3

        are the last vertex. The vertices are arranged such that the

        surface normal points out (counter clockwise). (or maybe it points

        in, can't remember.. just don't change the order). You can use a text

        editor to create models with this format.

        ASC: this is a text format saved by 3d Studio. The coordinate

        system in 3d studio is a bit different from quake. In quake,

        z points up, in 3ds it points towards you. I fixed MedDLe such that

        if you export an asc file, 3d Studio will display it properly,

        but the coordinates are different. (so to convert an exported RAW

        to an ASC and then import may screw things). By properly, I mean

the 'front' view is the front, the 'left' is the left, etc...

        Importing an asc file works the same. The front remains the front,

        but the x y z values are changed around behind your back. You can

        also create this file by hand. I just want to warn you that here the

        vertices are stored in opposite order from the raw file.

        Those two formats allow import/export of frames and model generation.

        The other formats are just export for now. I haven't had a chance to

        really test them, but the WRL works nicely. Again I had to change

        the coordinate system to get things to look ok, but don't worry

        about it for now. The export of the quake MAP format is a little

        different. This is because it exports the model in the raw byte

        format, that is, each x,y,z value ranges from 0 to 255. I did this

        because I didn't see a quake map editor taking any negative values.

        When a really good map editor is out, I'll fix the import function

        for this. The other file types are DXF and POV. Which I haven't

        had a chance to test.

-----------------------------------------------------------------------------

7. History

-----------------------------------------------------------------------------

v1.5

-3d export added and some import

-script language

-gif support

v1.4

-fixed import/export- now its rocks

-shirt/pants color changing

-multi skins handled better

-saving enabled

-some new key mappings

v1.3

-includes source with public release

-gouraud shading with colormap

-new file format support

-help screens

-more comments in source and some cleaning

v1.2

-released with source

-better mouse control

v1.1

-not released-gui experiments

-gouraud shading

v1.0

-now you can edit the 2d vertices

-fixed bugs which caused crashes in 3d mode

-expanded video support via GRX20

-added flat shading to 3d models and texture mapping

-you can now cycle through the frames of animation

-several other little things

v0.1

-added wire frame 3d view

-added importing/exporting BMP files

v0.00002

- same as v0.00001 but with correct palette

v0.00001 (not released, except on IRC)

- displayed the skin texture

Wish list..

-stick man... you'll see

-gui

-more time

------------------------------------------------------------------------------

Programmers Note: in this version GRX20 was used along with 3DGPL.

I sorta merged the two together and stuck some of my own stuff in there.

The program is not optimized at all, and a sharp eye will notice that

there is no _perspective_ texture mapping. Oh well, maybe I'll get around

to that in a later version. Or maybe not.

Special thanks goes out to...

Gershon Elber for the source to gif-lib (which I completely trashed)

John Carmack for release of utility source

Chris Babcock for making me aware of the frame data

Raphael Quinet and Sean Werkema for giving out their source which

made learning to read BMP files easy (also the source taught me a few tricks)

Sergei Savchenko for 3DGPL. I learned a lot of 3D programming from that and

use several modified versions of his routines for clipping and texture mapping.

DJGPP v2 and the excellent GRX20 graphics lib.

Id for quake.

Becky for putting up with me :)

-end document------------------------------------------------------------------