-= SUSongPlayer =-

Title (Package): Simple Unreal Songplayer
         Author: }TCP{Wolf aka Mia_The_Chaotic
           Date: 4th of May 2002
                 30th of May 2002


    == TABLE OF CONTENTS ==

  I. Introduction - WHAT IS IT ?
 II. Requirements, Installation
III. Setup (there ain't much to set up actually :)
 IV. Commands (so to say...)
  V. Creating CUSTOM UMX packages from IT/S3M/XM/MOD files

           == * ==


I. Introduction
---------------
The Simple Unreal Songplayer (SUSongPlayer) is a server/client mod which plays
Unreal music on any map which does not have music already on its own.
By default, SUSongPlayer uses most Unreal Classic 225f standard umx song
files, which are statically loaded together with the mod. They can be used from
on the moment the player is installed (there is a complete preset for all major
suitable songs). Only setting up non-standard songs may be a bit tricky :)



II. Installation
----------------
Requirements:
   Unreal Classic 225f or newer
   This mod is NOT for Unreal Tournament or any other Unreal Engine game. The
   mod works with Unreal Return To Napali, but I don't know if it has packages
   of the 225f non-Napali version... if not, get them!

   RAM
   All used music must be loaded on startup - for the server they COULD be
   loaded dynamically, but not so on the client :( so you need the additional
   RAM for all UMX files you use.
   I am not totally sure about the amount of RAM the basic setup requires when
   it loads the standard UMX files, but it is far less than your gaming machine
   needs as texture cache to run smoothly...

Copy all contents of the zip (this textfile excluded) into your Unreal\system
directory.

The mod alone requires you to add the following 2 lines in your "Unreal.ini"
within the section "[Engine.GameEngine]":
ServerPackages=SUSongPlayer
ServerActors=SUSongPlayer.SUSongPlayer



III. Setup
----------
There is a new menu in your advanced preferences. From a dedicated server,
right-click on the Unreal Icon in the icon area of your task-bar to get to the
advanced options.

On a listening server, hit tab and type "preferences" or hit escape, choose
options -> Advanced options (only for 225f).

Songs:
A song is normally a complete songfile which may include several tracks and
sections - just like on a complete CD you may have tracks and even within the
tracks you might have sections.
However, one song usually has only ONE track inside and only ONE section, so
that in most cases, the SONG is the complete file and is only ONE single piece
of music :)
In Unreal, songs are loaded by package+trackname out of a umx file, so the
complete class specifier would be: Music'package.track'
A section in Unreal is simply a byte value from 0 to 255. Most songs will be
just a single piece of music, so the complete specifier is reduced to this:
Music'song.song' section=0

However, I have left this explanation inside so that you understand why there
is a . (DOT) in the preset songs and what the section variable is good for.

Another side note: Not all standard Unreal Classic UMX files play well when
started directly and the started section is NOT 0... no idea why.

Settings:
---------
enabled:  true/false - like all my mods, they can be enabled/disabled very
          simple. The mod will do NOTHING if enabled=false. However, if you
          already have all the songs installed as you had planned, they will
          still be downloaded no matter what this setting is, because songs are
          installed as means of "serverpackage" all on their own.

SongChances:
   ChanceBackground / ChanceUnreal / ChanceTechno
          All three settings are a value between 0 and 1 and indicate the
          probability with which one out of the 3 types are chosen per map.
          0=no chance 1=max chance, 0.5 would be 50% max chance. If there are
          only songs in ONE list the chance for that list just has to be bigger
          than zero but is otherwise irrelevant.

   Z_AlwaysPlayThis: This overrides all "Chances" settings and forces the mod
          to ALWAYS play the song indicated here. This is only meant if you
          test a new song how it sounds in game and should NOT be used
          otherwise.
   Z_AlwaysSection: The section belonging to the song you force to play at all
          times using the setting just above this one.

BackGroundSongs: The list of "Background Songs". Background songs are "Unreal
          Themes" which are not so "action-like", so maybe not really so good
          as "fighting song"...
UnrealSongs: True "Unreal" songs of average "action/loudness".
TechnoSongs: "Techno" and anything loud :)

each of the song lists can hold 64 songs (music files).



IV. "Commands"
--------------
SUSongPlayer does not have a real Command interface, but it has been tweaked
so administrators can do a few things while the server is running.
Some 0 / 1 behind commands are needed (standing for true/false). So now you
already guessed likely, these are just a few variables you do not see in the
advanced options menu, but you can actually set them :)

Please start ALL of the following lines with "admin set SUSongPlayer":

bsong <nr>            Use one of these commands in game to immediately have
tsong <nr>            a new song started, whereas b/t/u is for "Background /
usong <nr>            Techno / Unreal" as the lists suggest. <nr> is 0-64

silent 1              Use this to silence SUSongPlayer completely. Players
                      already hearing music will stop hearing it, new players
                      will just see a strange message but wont hear music
                      either.
                      This does NOT work if the music is in the MAP!! You can
                      only stop songs which were started by SUSongPlayer!

blist 1               Will display the list of installed Background songs...
tlist 1               ... same for Techno songs...
ulist 1               ... same for Unreal songs...
                      Note: ALL players will see the lists, not just admins.



V. Creating your custom UMX files from MODs
-------------------------------------------
I am not sure from which mods you can import, but I would guess IT, XM, S3M and
MOD (protracker) are obvious choices to import from.
Start the Unreal Editor. Go to the MUSIC browser. Click on IMPORT. Select the
mod you want to import. If successful, you will now see a UMX package
representation of the mod you imported in the editor. Now click on SAVE to
write mod into a UMX file.
Voila! Your new mod should usually have a section start of 0, and a specifier
like Music'umx.mod' where "mod" is the name of your original mod file and umx
is the name of the UMX file you wrote, but I suggest you keep the two identical
for easy of use.

NOTE: I have included the file "music.htm" from epic Megagames regarding the
matter. You will certainly find some interesting additional infos in it.

<EOF>
