
CoW (c) Copyright by Tels 1999-2000. All Rights Reserved.

What The Hell is This?
======================

This is a project to generate levels for Thief, Thief Gold, Thief II (and very
probably SystemShock2 or Halflife/Q3 via Worldcraft) via Perl scripts. It will
hopefully make it easier to create and re-use complex structures like spiral 
staircases, hallways with columns aso. It is intended to give you some other 
usefull routines for debugging/maintaining/checking/fixing your levels.

This archive contains several things: 

*.map        - texture mapping files
*.pl         - scripts to show you how how to actually build VBRs, extract
               information or convert between the different formats
bench/       - benchmark results
 benchXXX.txt  - benchmark for the various versions
doc/         - documentation and info texts
 readme.txt    - This file 
 pm2html.pl    - generate HTML doc
 html          - here will the HTML doc be placed
 notes.txt     - some annotations to my source code, only for programmers
 todo.txt      - what is on my todo list
 devel.txt     - if you want to be developing scripts for genVBR
 whatsnew.txt  - what is new in this version
 knownbugs.txt - Things that are know to not work (properly)
data         - Some template files used by the routines. Output files are 
               usually written hereinto. Here under are also the templates 
               for CowEd stored (in things/)
Cowgen       - the modules that are used to generate levels. You dont need to
               look into them except if you want to know exactly what is going
               on
CowEd        - the modules for the GUI. You dont need to look into them except
               if you want to know exactly what is going on
Config       - Configuration files are stored here.

Short intro
===========

You can create something called "Bunch". A Bunch is simple a virtual container
to contain brushes, rooms, flows and objects (all these I call thingies to save
key presses :). Each of the thingies a bunch does contain is associated with a
group id and each group has a name. When you merge a bunch into another, all
the thingies from it will get a new group id and this new group will get the
name of the bunch you merged in. Thus we can later on seperate the thingies
from the different originating bunches by their groupid.
Thingies can be added manually to a bunch, or a bunch of thingies can be 
created with simple commands. There are commands to create stairs, ramps, 
bends, tables, doorframes, sheds, a privy and even entire houses! A bunch can 
be rotated, merged, transformed, optimized and last but not least written out 
to a text or .MIS or .VBR file. A bunch can also be read back in from a text 
file.
A VBR file (called multibrush file) or a .MIS (mission file) is what DromEd, 
the Thief & System Shock 2 level editor, can read or import. For more see
the section General Documentation later in this document.
There is now a method to describe an entire world by splitting it recursively
into rooms and then let it be created. Please see webpage for more infos and
documentation or try the scripts vroom.pl and vroom1.pl. Also the cowed.pl 
script implements this method with a grafical GUI.

Documentation
=============

For developers:
 I prepared my source code, so that it can be converted to doc. See inside the
 /doc directory for a script which generates that documentation for offline
 browsing. Although this will only list the functions and their parameters,
 this will be usefull, nevertheless.
For users:
 Please read the cowed.htm file in the doc/ directory as well as the 
 vworld.htm document on my webpages.
 There are some text files in the /doc directory for some scripts like 
 maxobj, strip and chknfix. These may be interesting for you.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Warning
=======

ALPHA! This is still not perfect! DromEd is currently not able to read the
created text files (DromEd just cant import anything other then VBR). The
created MIS/VBR/GAM files may crash DromEd or your computer, may give you bad
hair for the day and probably damage seriously your family life as well as
defrost your fridge!!

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


System Requirements
===================

You will need Perl for Windows (current is build 519, but 517 will do fine)
(http://www.activestate.com/ActivePerl/download.htm) and DCOM, if you havent
got Windows 98 or better (e.g. you still have Win95) 
(http://www.microsoft.com/com/dcom/).
For the GUI: Windows: You will need the Tk module. Under Linux you 
should already have it.
(http://www.activestate.com/packages/zips/Tk.zip - mind the capital T!)
You need about 2 MByte (18 Mb and long filenames for the doc), but that is nowadays
hardly important ;o)

Perl is a straightforward installation which will only insert it's path into 
the autoexec.bat, but you can even leave this out and start it by using the 
complete path. DCOM should not break anything on your system, but since it is
from M$, you never know ;o)

To check if Perl is installed properly, just open a MSDOS Command line window
and type:

perl -v[Enter]

If it prints out the Perl version, all is well now. If it complains about "File
or command not found", then something went wrong. Did you reboot after 
installing Perl? Did you get the full install version?

Linux will do just fine out of the box. So why not have a spare Linux 
installation on your harddisk? ;)

 Why Perl?
 =========

 Perl is slow for some things (like number crunching), but speed is hardly
 the issue here. Good Perl can be read and understand even by non-programmers
 fairly well, and if someone wants to make changes, it doesn't need the 
 author (e.g. my time ;). 

 Perl has some advantages, that are build right into the language. 
 The texture hashes, for instance, were not planned, but tackeled onto later
 on. However, they fit in very nicely, without forcing the user not using
 them to change a single line of his code. That you can leave out parameters
 to functions at will (although only at the right side) is cool, anonymous
 hashes that function as named parameters are endcool, and overall, the easy
 access to complicated things like OO and references make the life easier for
 programmers. Out of the box portability is a big plus (no pragmas, no
 defines, no OS dependend includes, it just works on my Linux box as well as
 on windooze :-) That you have no pointers supresses most of the bugs,
 anyway. I couldn't accidentily crash my windows with a Perl script, could I?
 My code is pretty much self-contained and doesnt need more then the standard
 Perl installation, no lib, no fees, no problems. It's free. But don't let us go
 into Language Wars here...

 Okay, your milage may vary, but I just _love_ Perl. Understood? :-)


Contents
========

Various *.pm files: This are the modules, that are used by the various scripts.
I made them pretty re-usable, so that they hopefully will be usable for other
games as well. They are object-oriented, for these programmers under us. Mere
mortals dont need to look into these files ;)

 Demo scripts
 ============

 Demo scripts to show usage of Bunch.pm, Dromed.pm, etc. Most of them need 
 either "dummy.vbr" or "houses.mis" as a basis. Both files should be in data,
 otherwise create them. Houses.mis is just any mission file, and dummy.vbr
 just any multibrush file. You should put a copy of Dark.gam from your Thief/TG
 directory to the data subdir.

 To use the scripts: 
 Open a MSDOS Command prompt. To get one, use Start->Programms->MSDOS Prompt.
 Then change to the drive and  path you unzipped CoW into, then type

 doskey[Enter]
 perl -v[Enter]

 You should see some version info of Perl. If not, you have not properly installed
 Perl. Check if you got the full install version and that you rebooted.

 Then type
  
 perl script.pl[Enter] 

 Replace "script.pl" with one of below. To run the command again (hence the DOSKEY)
 just hit [Cursor-Up] and then [Enter].

 Then start Dromed, load the mission file rightaway, or add_family core, 
 and load the resulting vbr file. Add light_bright, portalize, build the
 room database and hit ALT+G.
 For generated vbr files please read the topic about texture mapping and GenMap!
 I advise you to generate MIS files, anyway.

 Thats all, folks!

 cowed   : The GUI frontend. Not ready yet! You need the Tk module for it.
 Texture : Shows you to use the texture mapping. There is only one map file,
           core.map.
           If you have another sequence of textures in your level, you have to
           write your own map file. To make this easier, there is a script to
           generate the .map file from your .MIS file. Just add and compress
           texture families as you like, save your mission and then create the
           texture map with "perl genMap mymiss.mis". 
           If you are using the .MIS file directly as a template and generate
           a .MIS file, you don't even need genMap. See "vroom" for an example.
 stairs  : Shows you to create various stairs, including spiral ones!
 bot     : simple demo script for generating an VBR
           shows you also how bunches are created/freed by the garbage
           collection of Perl as well as the usage of Bunch->debug()
 maze    : generates a maze with random rooms and textures
 bend    : generate some tunnels and some arcs, round walls
 align   : show alignment, bunch group management, dimensions, cloning etc
 brushes : shows you what brushes are available, including virtual brushes
 bridge  : two small bridges over a canyon and a dome
 objects : Shows you how to create and use objects as well as using Dark.gam
 insides : show usage of fireplace, table, basin, shed, privy, cross, frame
           and much more, including texture hashes to set (scale,rot,u,v) 
           and usage of Inside.pm
 vattic  : usage of the attic room generator, as well as virtual brushes
 vroom   : shows you the usage of VRoom and VHouse. The world is a cube! :-)
 vroom1  : Yet another VRoom example, showing you more tricks. That one was
           created in 25 minutes based on a map I got as GIF via email. Go 
           figure! It now features lamps, lanterns and a table and a lootable gem!
 vroute  : Shows you how to use the automatic terrainpoint feature of VRoom.pm
           in conjunction with Route.pm
 vtut    : An Advanced Thiefery Tutorial. Both as a learning document for the VWorld
           concept as well as some practice in the First Person Sneaker games.
 vlinks  : Shows you what you can do by linking objects together...
 schema  : Add voices and schematas to a gamefile, query the voice index etc.
 hl_wc   : Show how to create a worldcraft map.
 
 General documentation
 =====================
 
 If you want to write your own scripts, please read doc/scripts.txt.

 VWorld & CowEd
 ==============

 Please see 
  http://www.gamedev.net/reference/design/features/vworld/
  http://bloodgate.com/thief/cow/vworld.htm 
 for more info on that.

  
Disclaimer & Lizence
====================

Delivered as is. Use it at your own risk. No warranties or berries. If you 
break it, you own both halves. I mean it. Really.

Always make a backup of your data before using CoW!

If you use CoW to generate parts of a (or an entire) level, then you MUST
include the following text in the mission description text (please insert the
version number you used or leave it out):

Parts of this level were generated with the scripts from CoW v0.0.0.
(c) Copyright Tels (http://bloodgate.com/thief) 1999-2000. All Rights Reserved.

You may not use this stuff for commercial use without a written permission from
me. You shouldn't send me money...I would love to work for you, though...

Authors, Contact
================
 
Bug reports, suggestions and comments are very welcome!

email: thief at bloodgate dot com
WWW  : http://bloodgate.com/thief/cow

Jdsmith (xarax) pointed out many bugs and requested some very usefull features.
Big thanx! Please visit his page at http://www.angelfire.com/va2/jdsmith, he 
does wonderfull city houses with CoW!

Stay DromEd!

Credits
=======

Go to:
 Mahk and Doug at Looking Glass Studios for their hints and tips.
 Looking Glass Studios, for making such cool games and creating one of the
  most flexible game engines in the world!
 Alex Fung for his help with the listbook script
 Larson, for his very usefull comments and emails and giving me cool ideas.
 jdsmith, for finding bux and actually fixing them :)
 Dan Nightfall, for running the coolest fan sites on the entire 'net
 O Love, for, you know what :) 
 To all taffers on the Thief Editor Guild's Forum: http://www.ttlg.com/forums/
 Thumper for his very usefull hints at the database file format. 
 Tran for the GUI code and the long email discussions. I have learned 
  a lot from you, pal!
 KFGecko for inspiring dome, Jonquil for the new fireplace idea.
 All game designers and map makers for their endless inspirations, especially
  from Thief, System Shock 2 and Unreal.
 Thanx to some games for their horrible architecture and maps as bad examples.

Nuff said!

Special Note
============

On May 24th of 2000 Looking Glass Studios died a sudden and unexpected dead.
            We will all miss you and your games, thank you for 
              all the joy and fun you brought into our lifes!
                                 R.I.P.