Released: October 16, 1997
=====================================================================
Title                   : ArghLite
Filename                : arghlite.exe
Version                 : 2.0

Author                  : Tim Wright
Net Nick                : Argh!
Email Address           : argh@ntplx.net (<-- new address)
                          (comments, questions, bug reports, etc.
                          welcome... flames aren't ;)
WWW                     : workin on it...

Description             : Enhanced version of "light":
                          * Scale fade distances of individual lights
                          * Lights can cast darkness
                          * Set a global minimum light level
                          * Set spotlight direction by yaw and pitch
                            (added by popular demand)
                          * Supports Ritual's "Scourge of Armagon"
                            map extensions.
                          * Fast (consistently outperformed all other
                            release versions of light I tried)
                          * More feedback output

Requirements            : Pentium, A Win32 operating system (I use
                          Win95, WinNT is untested but I assume it
                          works), and whatever the requirements are
                          for id/Ritual's "light" code. :}

Additional Credits to   : id Software & Ritual Entertainment Inc. for
                          source, Rich Tollerton for antilight mods,
                          Janis Jagars for mangle mod.  Also Jagars
                          for "LightDis", and Eric Sambach for
                          "MinLight" which were the original
                          inspirations for ArghLite v1.0.

=====================================================================
* Usage *

It's pretty easy to use, I hope my long-winded explanations don't
actually make it worse. :}  I'll explain everything as how it looks
in the map file.  For mapping I use Worldcraft (shareware), so I'll
also give a little info on configuring that below.  Note that you'll
probably have to rename arghlite.exe to light.exe to get it to work
automatically with your map editor.

Fade distance
-------------
The fade distance of individual lights can be scaled.  Just add a
new key (a new setting) to the light in the form: "wait" "#".  The
fade distance will be scaled by 1/#.  For instance, if # is 3.0, the
light will go 1/3 as far.  Or, if # is 0.5, the light will go twice
as far (1/.5 = 2).

Example:
   {
   "classname" "light"
   "origin"    "100 50 150"
   "light"     "200"
   "wait"      "2"
   }

(In Worldcraft, turn off "smart edit" to add the new key.  See info
below on how to add this entry to "smart edit" mode.)

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.  Note that non
normal styles might rarely have small shading errors.

Minimum Lighting
----------------
Levels can have a minimum light level to eliminate pitch-black areas.
I find low values look best, just enough to show a little detail in
those camper spots. :>  There are two ways to set this value.  The
first method is to add a new key in the form "light" "#" to the map's
"worldspawn" entity (the first thing in the map file).  # is the
minimum light value.

Example:
   {
   "classname" "worldspawn"
   "worldtype" "0"
   "wad"       "quake.wad"
   "light"     "20"

(In Worldcraft, this is set in the map properties)

The second method is to use the command line parameter [-light #].
The command line option overrides any value set in "worldspawn".
That lets you re-minlight a bsp without needing to change the
"worldspawn" value.

Example:
   C:\>arghlite.exe -light 10 argh.bsp

There's also another command line parameter [-nominlimit].  This
allows antilights to get darker than the minlight value.

Example:
   C:\>arghlite.exe -light 10 -nominlimit argh.bsp

Note:  Minlighting works like Quake's r_ambient console command.
BUT, minlighting is scaled by [-range #].  The default for -range
is 0.5, so minlighting will be half as bright as Quake's r_ambient
value.  If you use r_ambient to test different minlight values, be
sure to account for -range before setting it for ArghLite! (by
default, multiply the r_ambient value by 2)

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

Note:  Don't confuse this "mangle" with the intermission camera's
"mangle".  That one is a set of x,y,z coordinates that the camera
points at.  Also, remember you can change the width of the
spotlight cone with the "angle" "#" key (default for # is 40
degrees).

Other Command Line Options
--------------------------
The original command line options still work:
-extra    - Turns on extra sampling for smoother lighting/shadows.
-dist #   - Scales the fade distance of ALL lights.  Distance is
            scaled by 1/#.  A light with a "wait" will be scaled
            once for that, then scaled again by -dist.
-range #  - Scales the brightness range of ALL lights without
            affecting their fade distance.  Brightness is scaled
            by #.  The default for # is 0.5.

Configuring Worldcraft
----------------------
If you want to make the ArghLite mods always available in
Worldcraft's "smart edit" mode, that's fairly easy to do.  Load
the quake.fgd into a text-editor (make a backup first if you don't
really know what you're doing), and find the block that starts with:

   @baseclass = Light [

Now right before the last (second) "]" in that block, add:

   wait(string) : "Fade distance factor"
   mangle(string) : "Spotlight angle (yaw pitch 0)"

These values will be blank by default.  Only enter values when you
need to.

=====================================================================
* History *

Version 2.0:
   * fixed incorrect light count
   * added antilights
   * sped up minlighting
   * added mangle key
   * cleaned up / added more output

Version 1.0:
   * first release

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

Base                    : * "Light" source code from id Software.
                          * "Scourge of Armagon" light mods from
                            Ritual Entertainment.
                          * Rich Tollerton's antilight code.
                          * Janis Jagar's mangle code.
                          * Other features are my own mods inspired
                            by Janis Jagar's "LightDis" and Eric
                            Sambach's "MinLight"
Compiler used           : Microsoft VC++ 4.0
Construction time       : Couple hours a day over several days?
Known Issues            : non style-0 antilights might rarely shade
                          incorrectly

=====================================================================
* 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 ArghLite 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. :)

=====================================================================
* Where to get this Utility *

ftp://ftp.cdrom.com/pub/quake/utils/level_edit/bsp_builders/
 arghlite.zip (and all mirrors)
