
If you want to become a developer of scripts for CoW that are not only
usefull for your own purposes, but for more people, then please read the
following guidelines and tips. Thank you!

Creating MIS files
==================

You need a mission file as template:

$vbr = Cowgen::Vbr->create("mymiss.mis");

After creating a bunch, insert it into the template and write it out:

$bunch->stuff2vbr($vbr,$gf);
$vbr->writeFile($outfile);

There are two handy routines loadMission and saveMission that make this easier for 
you.

Creating VBR files
==================

This is similiar to MIS files except that you have to use a VBR file as template.
The catch is here that a VBR does not contain a texture palette and you will
probably need it. So use a MIS for for the textures and the VBR file for the actual
template:

$mis = Cowgen::Vbr->create("mymiss.mis");
$txt = Cowgen::Texture->create($mis->getTXT());
undef $mis; # free mem

$vbr = Cowgen::Vbr->create("dummy.vbr");

# later:

$bunch->stuff2vbr($vbr,$gf);
$vbr->writeFile($outfile);

VWorld
======

The VWorld concept will be completely rewritten from scratch. See /CoW and
http://Bloodgate.com/thief/cow/oocow.htm for details. The info below is
outdated:

Please make things you create compatible with the VWorld concept. See webpage
for details on that concept, here are the key features.

Things in VWorld are defined by functions that expect a certain set of
parameters and return a reference to a Bunch object. It is wise to use this
set of parameters for other functions as well.

The parameters are always:

x,y,z,w,l,h,p

X,Y,Z are the center coordinates, w,l,h are widht, length and height. p is a
reference to a hash containing more (named) parameters.

This is rather fixed, so if you dont need w, then ignore it, but you must
use the same parameter list format!

The named parameters can be choosen as you wish but please keep the following
on mind. It is wise to choose the same name for the same parameters so that
user hasn't to remember so much. So these standard parameter names are expected:

texture      - number or hash, always the standard/default texture
               floortexture/ceilingtexture and so on should default to
               texture if they are undefined.
gridsize   
light        - light brightness or light hash, alsways the standard light
facing       - the facing of the final generated bunch. initial and default
               is south (e.g. down on the dromed top view-screen) 
sidetexture  - texture at east/west
easttexture,
wetstexture,
southtexture,
northtexture - just as the name says 

You can pass texture and light directly to bunch, so you need not to worry 
wether it is a hash or direct number.

Always document your function and explain the possible (especially named)
parameters.

Always provide safe defaults. Perl gives you the undefined value for, well
undefined variables. You can check for it with "||". Although this will also 
be true for 0 (undefined is just handled as zero in that check) so you have for
values that can be zero, but should be a different default (e.g. 0.5) write it
a bit different:

# case 1:
$a = $p->{value} || 0;     # works if value is 0 or undefined
# case 2:
$a = $p->{value} || 0.25;  # $a can never be 0
# case 3:
$a = $p->{value}; 
$a = 0.5 if (!defined $a); # only set default if $a is undefined,
                           # but leave a 0 as it is

Always check for parameter ranges. Correct as much
as possible, if unable, bail out and return undef or empty bunch.

Please allow for relative sizes. If, f.i. you want a cube with a hole in it,
make it possible for the user to specify the hole size in relation to another
size, e.g. width. The handy rel2abs() function convertes a relative value (this
is always between 0 and -1) to the proper absolute value in the range of 
0..size. If you want it to be relative, but not clipped to size, then add a ,1 to
the rel2abs call. So caller can specify twice or more the time of the basis size.
(e.g. -2 will be 2*width not 1*width)

Snap computed values to the grid when possible.

Here is a complete example function, creating just a solid cube with an air
cube inside it. Always base your functions on that template.

sub cubeHole
  {
  # Create a cube with a cubic hole in it
  # named parameters: texture, innertexture (defaults to texture),
  # holesize (defaults to 0.5 if width), facing, gridsize
  my ($x,$y,$z,$w,$l,$h,$p) = @_;
  my $b = Bunch->create("cubeHole##num##");
  my $facing = $p->{facing} || aSouth();
  my $t = $p->{texture} || -1;
  my $ti = $p->{innertexture} || $t;
  $hs = $p->{holesize}; $hs = -0.5 if (!defined $hs);
  $hs = rel2abs($hs,$w);
  $grid = $p->{gridsize} || 0.25;
  $b->addBrush (solid(),cube(),$x,$y,$z,$w,$l,$h,$t);
  $b->addBrush (air(),cube(),$x,$y,$z,$hs,$hs,$h,$t) if ($hs != 0);
  $b->rotateByFacing($x,$y,$z,$facing);
  $b; # cube with hole
  }    

 Structure of Object System
 ==========================

 Object system refers here to the objects of an object oriented programming
 language, namely Perl, not the objects in DromEd/Thief. The actual objects
 from DromEd I call here object-thingie(s) (short OT), to mark the difference.
 An archetype in DromEd is really a basis object, from where you can create
 OT. If you want all OTs of a certain type have to have a certain
 effect/property/link, then you can either add it to each and every OT or,
 better create an archetype and base these OTs on it. When you create an
 archetype, then you must store the gamesys file and distribute this with your
 mission. You should do this anyway, to avoid problems with a different
 gamesys the user may have - another game version, Thief Gold, or just left
 over files from an prior fan mission will get your level into troubles.

 To make you understand more how things are laid out, as well as to provide me
 with a handy reference on what I intended, I wrote this small primer:

 VBR

 An VBR object is simple an object to hold one file, like a mission file, a
 multibrush file or a gamesys file. It can read and write them, dissect them
 into the various parts and reassemble them. It curently can dissect some of
 the chunks into smaller pieces, but that will be probably removed in the
 near future to another module.

 Gamfile

 An object to read and store the game sys file like Dark.gam. It uses an VBR
 for the actual reading/writing, but can dissect and understand the inner
 things of the gamsys file. It also contains the archetypes of the object
 hierarchy and the mission parameters, and just anything that goes into the
 gamesys file. It will be (later) posible to edit the things and thus modify
 the gamesys.
 This also will help you creating OTs based on the archetypes, and it stores
 the archetype in ObjList.
 It also should understand the various parts of a mis/vbr file.
 Knows about voices and schematas.

 Bunch

 Contains brushes/rooms/flows/OTs and other thingies. Needs ObjList as a
 container to store its objects and their links.

 ObjList

 A list of OTs or archetypes (there really is no difference between the two,
 excpet that you need the archetype to create an OT of it, but the OT could
 become an archetype by itself.)

 All the other pm files contain just routines that help you to get certain
 things done, like creating entire bunches, defining constants, manipulating
 things. They are not OO in that sense.

