-----------------------------------------------------------------------------
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------------------------------------------------------------------
