Updated: December 9, 1999
=====================================================================

Title                   : TyrLite
Filename                : Tyrlite.exe
Version                 : 0.5 beta

Author                  : Kevin Shanahan
Net Nick                : Tyrann
Web Site                : http://www.planetquake.com/tyrann
Email Address           : tyrann@planetquake.com

Description             : New enhanced version of "light":
                          * Scale fade distances of individual lights
                            (without changing brightness)
                          * Choice of four different attenuation
                            formulas for individual lights
                          * Progress indicator
        [new in 0.2beta]  * Set a global minimum light level
                            (eliminate those totally dark spots)
        [new in 0.3beta]  * Supports Ritual's 'Scourge of Armagon'
                            map extensions
        [new in 0.4beta]  * Lights can cast darkness ('Anti-lights')
        [new in 0.4beta]  * Set spotlight direction by yaw and pitch
        [new in 0.5beta]  * Set a sun angle and brightness so that your
                            outdoor areas can be lit by your skybrushes

Requirements            : Pentium compatible processor, A Win32 operating
                          system (e.g. WinNT, Win95/98)

Additional Credits to   : id Software & Ritual Entertainment for
                          their source code,
                          Tim 'Argh!' Wright for "ArghLite",
                          Iikka 'fingers' Keranen for "IKLite"

=====================================================================

* Usage *

If you have ever used ArghLite (by Tim Wright) or IKLite (by Iikka
Keranen) before then this will seem very straight forward.

TyrLite's fade distance feature behaves identically to Arghlite's,
so any map that you can compile with ArghLite, you can compile
identically with this.

The attenuation formulae feature behaves identically to the one
provided in IKLite, provided that you make the appropriate key/value
substituions. IKLite uses the "angle" key to set the attenuation
formulae, but this means your use of spotlights is restricted.
TyrLite uses the "delay" key to avoid this. Also note that the number
values correspond to different formulae (I thought it was more
intuitive this way). Read the sections below for specifics.

--------------
Fade distance
--------------
To modify the fade distance of a light, add a new key of the form
"wait" "n", where n is the number to scale the distance.  N>1 will
make the light fade faster, n<1 will make it fade slower (just like
the -dist command line parameter).  

For example, n=2 would make the
light fade out at twice the normal distance and similarly n=0.5
would make the light fade out at half the normal distance.

---------------------
Attenuation Formulae
---------------------
You can select from four different attenuation formulae for a light.
To do this, add a new key of the form "delay" "n", where n is an
integer from 0-3, described below:

n=0 (default)  - Linear falloff, identical to id's original light
                 program.
n=1            - Uses the 1/x attenuation formula.
n=2            - Uses the 1/(x^2) attenuation formula.
n=3            - No attenuation. (light stays same brightness at
                 any distance).

----------
Antilights
----------
Lights can now cast darkness!  Just set the brightness to a negative
number.  These "antilights" will only darken lights of the same
style.  For instance, a normal antilight will darken other normal
lights, but wouldn't affect a flickering light.

-------------------
Spotlight Yaw/Pitch
-------------------
Spotlights can be optionally aimed by specifying yaw and pitch
values, instead of targeting an info_null entity.  Add a new key in
the form "mangle" "# # 0".  The first # is the yaw angle, 0 to 360
degrees around the Z-axis.  The second # is the pitch angle, 90 to
-90 degrees up to down.  The 0 is just a required placeholder.

Example:
   {
   "classname" "light"
   "origin"    "100 50 150"
   "light"     "200"
   "mangle"    "45 -20 0"
   }

-----------------
Minimum lighting
-----------------
Setting a minimum light level allows you to eliminate any spots in
your map that you feel are too dark, without affecting the brightness
of any of the lights in the level.

There are two ways to set the minimum light level.  The first is by
adding a new key in the form "light" "n" to the map's "worldspawn"
entity, where n is the minimum light value.  Example:
   {
   "classname" "worldspawn"
   "wad"       "quake101.wad"
   "light"     "20"
   }

The second method is by using the command line parameter -light n,
where n is the minimum light value.  The command line option
overrides any value set in "worldspawn". For example:

   C:\>TyrLite.exe -light 10 example.bsp

---------
Sunlight
---------
You can set the brightness of the sun, as well as the direction of
the incoming light and any sky brush will cast light in that direction.

To set the brightness of the sunlight, add a new key in the worldspawn
of the form: "_sunlight" "#", where # is an integer value the same as for
any other light. To set the direction of the incoming sunlight, add a key
of the form: "_sun_mangle" "# # #", where "# # #" is a vector pointing in
the desired direction of the sunlight.

For example "0 0 -1" would be directed straight down, and "1 1 -1" could
come down on an angle. You should experiment to find values that look good.
If your level was set in early morning or late afternoon, you would make
the light appear as though the sun was near the horizon - e.g. "5 1 -1"
might suit in this case.

-----
Other
-----
Note that the above features can be used in any combination.
For example, you could have a light with fields like this:
   {
   "classname" "light"
   "origin"    "100 50 150"
   "light"     "200"
   "wait"      "3"
   "delay"     "2"
   }
Which would give an attenuation formula: 1/((3x)^2)


There are two other command line options:
-nocount  - Disables the progress indicator. Use this if you want
            to run the program from inside Worldcraft.
-compress - If you don't understand this, don't worry. It's only
            useful in rare circumstances.
            Basically, after lighting the map, it removes all
            key/value pairs from the light entities in the bsp
            (no, it won't affect the map file) except for
            'classname' and 'origin'. Try using this if you start
            getting 'entity text too long' errors.


The original command line options still work:
-extra    - Turns on extra sampling for smoother lighting/shadows.
-dist n   - Scales the fade distance of ALL lights.  N>1 fades 
            faster, n<1 fades slower.  A light with a "wait" will be
            scaled once for that, then scaled again by -dist.
-range n  - Scales the brightness range of ALL lights without
            affecting their fade distance.  N>.5 makes them brighter,
            n<.5 makes them darker.  Can achieve the same affect on
            individual lights by increasing or decreasing both the
            brightness and "wait" factors.

=====================================================================
* Construction *

Base                    : Quake light source code from id
                          Software and Ritual Entertainment.
                          Features were inspired by "Arghlite" by
                          Tim Wright and "IKLite" by Iikka Keranen,
                          however modifications are completely
                          original.
                          (most of the explanations in this text file
                           are however, only slightly modified from Tim
                           Wright's arghlite explanations).

Compiler used           : Microsoft VC++ 5.0
Construction time       : A couple of day I suppose.
Known Issues            : None known. I use this program to make my
                          own maps, and I haven't yet found a
                          problem.

=====================================================================

* Copyright / Permissions *

You MAY distribute this EXE, provided you include this file, with no
modifications.  You may distribute this file in any electronic format
(BBS, Diskette, CD, etc.) as long as you include this file intact.

* Disclaimer *

Usage of TyrLite is at your own risk.  I accept NO responsibility
for any form of damage incurred through the usage of this program.

(Okay, with that officially stated... I can say you probably have
nothing to worry about.  This is as stable as id's or Ritual's
versions.  If those didn't do anything nasty to ya, this isn't likely
to either. :)
