################################################################################
#
# lxQuakeCDmusic -- CD audio support for Linux Quake (xquake/xf86quake)
#
# (C) 1996 Michael Schumacher (mike@hightec.saarlink.de)
#
################################################################################

Hello, fellow Quakers!

As you know, the original port of Quake to Linux (done by Dave D. Taylor)
doesn't support CD music. Of course, you can always run "xmcd" or any
other CD player to get music in parallel to playing Quake, but the DOS
version allows for level-specific music while the Linux version does
not. Really not? Nope, because ddt did a good thing by making xquake
pretty verbose: its output contains hints about which level is currently
mapped, when the game is paused, and when it's unpaused again. That's all
it takes to add level-specific CD music to the game -- thanks to the
multitasking capabilities of Linux and the excellent Expect extension to
the likewise excellent Tcl programming language. lxQuakeCDmusic works
with both, xquake and xf86quake up to version 1.06 (this is the latest
release as of this writing; I can't say much about future releases, if any).

Using my scripts, you can assign certain tracks of your favourite CD(s)
to arbitrary Quake levels just as with the DOS version. Of course, hitting
the "Pause" button not only pauses the game, but also the CD player, and
pressing it again will resume both, the game and the music (N.B.: just as
with the DOS version, this only works while actually playing Quake, but not
while the demos are running!). At startup, the volume of the CD and sound
channels are set according to the values found in id1/config.cfg; these
values (plus the master volume) can also be set from Quake's console.

This package contains everything you need to get started (except for
Quake itself, to be precisely). I've only included the binaries (*) of
the required programs; if they don't work for you because you don't have
the appropriate shlibs (or if you're paranoid and think this is nothing
but a Trojan horse :), you can of course compile them yourself. The
sources are available from:

- ftp://ftp.smli.com/pub/tcl/tcl7.*.tar.gz (**)
- ftp://expect.nist.gov/mel/div826/subject/expect/expect.tar.gz (***)
- ftp://sunsite.unc.edu/pub/Linux/system/Sound/cdtools-1.0.tar.gz
- ftp://sunsite.unc.edu/pub/Linux/apps/sound/cmix-v0.3.tar.gz

All of these packages contain information about how to compile and
install them, so please read it carefully (and please do not ask me
questions about that; use comp.lang.tcl or comp.os.linux.misc instead).
You don't have to install Tcl, Expect, cmix and the cdtools: just copy
the necessary shared libraries and binaries to the lxbin/ directory of
this package after successful compilation (see the original distribution
of lxQuakeCDmusic-1.1 for what's really needed).

(*)   the binaries are for Intel/x86 platforms; *if* the DEC/Alpha version
      of Linux-Quake is as verbose as the one for Intel, chances are that
      this package will also work with the Alpha port (just recompile the
      binaries in this case and let me know if it works, if you'd be so kind)
(**)  get at least version 7.5 of Tcl (lxQuakeCDmusic includes 7.6);
      type "./configure --enable-shared; make" to configure/compile Tcl
(***) type "./configure --enable-shared; make" to configure/compile Expect


=========================
Installing lxQuakeCDmusic
=========================

There are various ways to get this package up and running, but I will
only describe one of them, because it is safe and almost guaranteed to
work. If your Linux system doesn't support ELF binaries, stay away from
this program (well, Quake itself doesn't run on a.out-only systems, so
this is not exactly a hard restriction... ;).

1)  unpack this package in an arbitrary directory (but *not* on a DOS
    partition, because of the necessary symbolic links!); this will create
    a directory lxQuakeCDmusic-1.1; "cd" to this directory

2)  either "cp", "mv" or "ln -s" xquake and/or xf86quake to this directory
    (e.g. by typing "ln -s /dos/quake/xquake .", if that's where xquake is
    located on your system)

3)  create a subdirectory "id1" ("mkdir id1") and "cd" to it

4)  create symbolic links to (or mv/cp) "pak0.pak" and - should you have the
    commercial version of Quake - "pak1.pak" in this directory. You might
    also want to move/copy/symlink "config.cfg" and "s*.sav", so you can
    continue to use your current configuration and previously saved games

5)  type "cd ..; ./xquake"; if Quake won't start up, you've almost
    certainly made a mistake in steps 1-4 (don't continue until you've
    got this fixed!); if everything's OK, exit Quake

6)  insert an arbitrary audio CD and type "cd lxbin; ./cdplay"; you should
    now hear the first track of the CD (if not, try to find out what's
    wrong and fix it before continuing! If you've inserted the original
    Quake CD, you'll get some "strange sounds" as the first track is the
    data track, so it's ok if all you hear is some annoying beeping :-);
    type "./cdstop" to stop the CD player and then "cd .." to enter the
    toplevel directory (lxQuakeCDmusic-1.1) again

7)  edit "runquake" if you'd like to start xf86quake instead of xquake,
    or if you want to change the default command line options for Quake
 
8)  if you'd like to also start Quake (w/ CD audio support) from other
    directories, create a shell script containing the following lines:

    #!/bin/sh
    cd /path/to/lxQuakeCDmusic-1.1
    ./runquake $*

    save this script as "quake" or whatever name you like and put it
    into a directory which is in your PATH (don't forget to make the
    script executable using "chmod 755 quake" or so)

9)  insert your favourite CD prior to starting Quake (if you don't, you
    won't get music - dead simple); not every CD player is able to close
    the drawer by itself, so be a pal and do it manually if in doubt

10) type "./runquake" to fire up both, the Quake and the music server
    (you can add arbitrary command line options for Quake if you want to)

Now Quake should come up and run the three demos; you should also hear
the CD audio tracks assigned to them -- provided steps 5, 6 and 9 above
didn't fail. BTW: Unless you're really _very_ short of physical memory,
lxQuakeCDmusic won't slow down the game play at all! This is because it
takes zero CPU time to play audio tracks and only very few cycles to
parse xquake's output (Expect is very good at that!).


====================
Adjusting the volume
====================

  Even though there is a scale widget in xquake's "Options" menu to
adjust the volume of the CD channel, you might have noticed that it
doesn't really work. It only changes the value of the bgmvolume
variable (which is written to id1/config.cfg when exiting Quake),
but not the volume itself. So, the changed value will only take
effect the next time you start "runquake".

Therefore, I've added some "artificial" commands which can be typed on
the Quake console. Quake itself will respond with an "Unknown command"
error message, but lxQuakeCDmusic does recognize these commands and will
perform the appropriate action(s). Here's a list of the new commands:

  "lx vo[lume] val"	sets the current master volume
  "lx cd val"		sets the current CD volume
  "lx so[und] val"	sets the current sound (i.e. synthesizer) volume

The letters in brackets (e.g. [lume] as in "volume") may be omitted. The
whitespaces are optional, and "val" can either be empty, "+", "-" or a
real number between 0 and 1. "+" increases the value by ten percent,
"-" decreases it by the same amount (10%). If "val" is empty, you'll
get a report about the current settings for the master/CD/sound volume
on the xterm from which you started "runquake". Some examples:

  lx vol 1	sets the master volume to 100% (max. volume)
  lx cd .5	sets the CD volume to 50%
  lxso		displays the current settings for master/CD/sound
  lx vol	dito
  lx cd		dito
  lxcd+		increases the CD volume by 10%
  lx vol-	decreases the master volume by 10%
  lx so +.2	sets the sound volume to 20% (+.2 = 0.2 = 20%)

Note: these values are *not* automatically saved in id1/config.cfg at
the end of the game (due to technical reasons), so you'll have to do
that manually after exiting Quake! It's very easy, though: just search
for volume and bgmvolume, and replace their values with your desired
sound and CD volume settings. A much better solution is to use the
"official" commands from Quake's console, namely

  volume val	set the sound channel volume to "val" (0.0-1.0)
  bgmvolume val	set the CD channel volume to "val" (0.0-1.0)

If you use the "lx" commands above, I highly recommend to set the final
values once more with the "(bgm)volume" commands, so that they will be
saved in id1/config.cfg. Note that Quake has no variable to store
the master volume in, and that all "artificial" or simulated commands
(e.g. "volume") offered by lxQuakeCDmusic will only work when typed
from Quake's console. You might wonder why I've implemented the "lx"
commands at all. Well, it was easy and their functionality was needed
to implement the official "*volume" commands, anyway.


================================
Console commands for CD handling
================================

Quake usually offers the "cd" command to control the CD audio section.
Unfortunately, the Linux version does not. Therefore, lxQuakeCDmusic
introduces "artificial" commands which simulate the original behaviour.
"cd remap" is not implemented (methinks trackassign.tcl does a much
better job, no?), and the "cd current" command is new. Here's the list
of commands and what they do:

  cd on		if the CD player was disabled (using "cd off"), it is
		re-enabled (i.e. trackassign.tcl and the CD's directory
		are re-read); useless otherwise
  cd off	disables the CD player ("no more music, please"); use
		"cd on" to re-enable the player
  cd reset	same as "cd off" followed by "cd on"
  cd info	shows info on currently inserted CD
  cd eject	stops currently played track (if any) and opens the
		player's drawer (if supported by this player); see
		"Changing a CD while playing Quake" below for details
  cd stop	pauses the CD player
  cd resume	unpauses the CD player
  cd play nr	plays track number "nr" once
  cd loop nr	plays track number "nr" in auto-repeat mode
  cd current	shows which track is currently played

Unlike in original Quake, "cd info" doesn't report the CD volume, but
you can use the "lxcd" command to retrieve its current setting.


===================================
Customizing track/level assignments
===================================

lxQuakeCDmusic comes with two prefabed files which map audio tracks to
Quake levels, namely "NineInchNails" for the original Quake CD and
"ThrowingCopper" for my favourite "Live" album, respectively. It's
trivial and almost self-explanatory to create customized files for your
number-one-album(s). Here's how: "cd" to lxbin/CDs and copy one of these
files; it's best to give the new file a name that reflects the title of
your CD (however, you can name it as you please). Now edit this copy as
necessary. Lines starting with a hash character ('#') are considered
comments and are ignored. If you'd like to assign track #3 to level e1m6,
just write "set track(e1m6) 3"; if you'd like to have no music in deathmatch
level #4, write "set track(dm4) none". The entry map (where you select the
skill level and the episode you'd like to play) is called "start", so you'd
say something like "set track(start) 5". Whenever you finish a level, the
track assigned to track(exit) is played. The three demos which come with the
original Quake distribution are called demo1, demo2 and demo3 (it might be
possible to replace them with other LMPs (just as with DooM), but I don't
think it's possible to change the amount of these demos; therefore, it
should be safe to just define track(demo[1-3])). The end level (aka
Shub-Niggurath's Pit) is called "end". You should define all "track"
variables, i.e., all track-to-level assignments as demonstrated by
lxbin/CDs/{NineInchNails,ThrowingCopper}, or you'll experience strange
results. When creating your own "map-files", make sure to not insert
any whitespaces or other characters between "track", the level name
and the parentheses:

   "set track ( e1 m1 ) 3" is wrong,
   "set track	(e1m1) 3" is wrong,
   "set track(e1m1	) 3" is wrong, but

   "set track(e1m1) 3" is correct, and
   "set   track(e1m1) 	3" is also correct. Simple, no?

Actually, the file you're editing is a Tcl file which is "source"d
by "lxbin/playcd", but you don't have to know Jack about Tcl as long as
you follow the description above. The final step to activate your
file is to create a symbolic link called "trackassign.tcl" in the
"lxbin" directory (you could as well use a hard link or a copy, for
that matter). If you're in the "lxbin/CDs" directory and your new file
is called "NewAdventuresInHi-Fi", type:

   cd ..
   ln -sf CDs/NewAdventuresInHi-Fi trackassign.tcl
   cd ..
   ./runquake

This should fire up Quake and play the tracks you've assigned to
the various levels. If not, then you've made some mistake; please
read this chapter again and make sure you follow the steps exactly
as described above (and remember to insert your CD before starting
the game!).


=================================
Changing a CD while playing Quake
=================================

If you're tired of listening to the very same songs all over again,
you can replace the current CD by a new one following these steps:

  - pause the game (i.e. press the "Pause" key)
  - bring up the Quake console
  - type "cd eject" and hit the <Return> key (if your player can't
    open its drawer automatically, hit its manual eject button after
    issuing this command)
  - change the CD
  - type "cd on" and hit the <Return> key (make sure to close the player's
    drawer manually if it doesn't support this feature automatically
  - exit the console (i.e. press the "Esc" key)
  - unpause the game; go on and kill the baddies... :-)

Question: "How can I tell Quake which songs it should play from the
  new CD, and in which order?"
Answer: As usual -- through trackassign.tcl! After you've changed the
  CD (but before you type "cd on"), you create the necessary symbolic
  link "trackassign.tcl -> CDs/myNewCD". You can either use a shell
  window for that, or the "artificial" command "lxsh <cmd>" from the
  Quake console, which passes <cmd> to the shell (tip: create a shell
  script ("mkql") which creates this link; make the name of the desired
  CD its parameter and invoke it using "lxsh mkql myNewCD")
Question: "Okay, I did what you said, but I don't get music any more!"
Answer: Don't panic! The music will continue as soon as you exit the
  current level; if you'd like to have music until then, use the
  "artificial" commands "cd play nr" or "cd loop nr".
Question: "Oops, I just can't seem to be able to pause the game..."
Answer: Most likely you're participating in a multiplayer game, and
  the server forbids pausing. Better luck next time... ;)


=============================================
Enabling/disabling logging of xquake's output
=============================================

lxQuakeCDmusic suppresses xquake's output by default. However, there are
two ways to re-enable it:

- change the "log_user" command in lxbin/lxQuakeCDmusic (as described there)
- type "lxlog 1" on Quake's console to enable, and "lxlog 0" to disable it

"lxlog" is an "artificial" command, so Quake will complain about it, but you
can immediately see its result on the xterm from which you started runquake.


=======
Credits
=======

I'd like to thank the guys at id Software for their incredibly
realistic game Quake (I'm still wondering what they would create
if MIPS-powered SMP machines by Silicon Graphics were the industry
standard, instead of poorly equipped Intel PCs... ;-)  I'd also like
to thank Dave D. Taylor (>>-ddt->) at Crack Dot Com for his ports of
DooM and Quake to Linux, which both contributed to the attractivity
of this operating system. Which also means that it's a must to praise
Linus Torvalds (who ported Quake 1.06 himself -- Wow! :-) and the kernel
gang for creating this excellent Un*x clone, to admire the XFree86[tm]
Project for bringing X to Linux, and to say "Thanks!" to all the folks
who helped making Linux so successful by porting and writing all sorts
of software and docs, by making distributions available or by just
spreading the word. lxQuakeCDmusic is based on Expect, which in turn
is based on Tcl, so my thanks go to Don Libes at NIST and to John
Ousterhout and his Tcl/Tk-team at Sun Microsystems. The cmix program
was written by Panteltje (pante@epsilon.nl) -- thanks very much for
releasing it! And last but not least I'd like to thank Thomas Insel,
the author of the CDTOOL package, which of course is pretty crucial
to this program.


=========
Copyright
=========

"Expect" is in the public domain, "Tcl" is under a BSD-ish copyright
(see lxbin/tcl_library/license.terms) and both, the "CDTOOL" and the
"cmix" programs are protected by the GNU General Public License (GPL),
Version 2 (see lxbin/COPYING). The rest of this software package (hey,
that's what I actually contributed to all this mess! :-) is also placed
under the aforementioned GPL. In short, this means:

This software is provided "as is", so don't blame me if it won't
run on your system. There's no warranty that this software will run
on your system at all -- use it at your own risk. I'm not responsible
for any damage that may arise from using this software. You may
redistribute and modify this software as long as you include full
sources and state prominent notices about your changes (if any).
Please read lxbin/COPYING for all of the subtleties.


=================
Famous last words
=================

If you like this program, please send me an EMail (I'm just curious;
there's nothing worse than releasing a piece of software and nobody
seems to care or finds it necessary to provide any feedback at all!
Rest assured that I won't abuse your email address! ;-). Feel free to
also drop me a note if you can't get things up and running, but please
make sure that you won't bug me just because of a trivial mistake that
could have been avoided by carefully reading the docs (especially this
file). I'd also like to hear about features or corrections you'd like
to see in future releases. The latest release of this software is
available from ftp://sunsite.unc.edu/pub/Linux/games/quake (you might
also want to check sunsite's /pub/Linux/Incoming directory). Since some
folks asked me where to find Linux Quake 1.06 (Intel/x86 and DEC/Alpha
versions): ftp://ftp.cs.helsinki.fi/pub/Software/Linux/Kernel/testing.
This is certainly a weird directory name for a computer game, but the
funniest part is that Linus ported Quake 1.06 while making new releases
of Linux 2.1.x _and_ 2.0.x _and_ simultaneously working on his master
thesis! Oh, I bet it was *exactly* in that order... :-)


Happy Quaking & Have A Nice Death,
mike
