**** WMutate ****   Author: }TCP{Wolf alias Mia_The_Chaotic

Version history:
10/29/2001 original V1.0 release
           planning of WMUtator 2 has been ICED for lack of time
03/29/2002 Version 1.1 quick bugfix version
           + added quicklaunch


TABLE OF CONTENTS
-------------------------------
    I. Welcome / Intro
   II. Install
  III. Easy Setup
   IV. Advanced Setup
    V. Recommendations
   VI. ExampleConfigs
  VII. Bugs / Problems / Issues
 VIII. Developers' notes
   IX. Thanx
-------------------------------


< I > Welcome

What is a mutator? Basically, it's something which changes how a game behaves.
Unreal Tournament (UT) has a lot of built in mutators in those BonusPacks,
like "this weapon only, fatboy, instagib....". This means you can play as you
always can, but some attributes of your game will be different :)

Who am I?
Well, I am a dedicated Unreal player, and I got pretty pissed by how the game
behaves in some aspects. I wanted to put an end to those lame items like the
"AMP"lifier, the "INV"isibility and address a few other inconveniences, like
with RealCTF you run out of ammo all the time on most maps :(
That's all history now. Sure, HbG and other programmers (I think some THC
member also made something) have also programmed mutators, but give this one
a chance. It uses a very flexible and powerful approach to modifying a game.
So before you dump it, try it :)  Some functions could not be implemented for
unknown reasons (or maybe I'm just too stupid for some things), so take
other mods IN ADDITION to this one if you need to. This MOD should work well
with any other mod, but I can't guarantee it, of course, I only tested it
with RealCTF.



< II > Install

Copy the WMutate.u file and the WMutate.int file into your Unreal\system
directory. Edit your Unreal.ini by adding the line:

ServerActors=WMutate.main

to your other ServerActors. !!! IMPORTANT !!! Do not add this package
to your ServerPackages!!! It is not needed that any clients download this,
it is pure server side :)



< III > Easy Setup

You did as told in < II >? Good, then start your server. Go to advanced
options to find a new entry below "Rendering", it reads "WMutators".
Let's see what we find there:

The first thing to do is: ENABLE THE MOD, you do this by setting
WMutator_enabled to "true" (it's sorted alphabetically, so scroll down).
I made this so you can disable the mod any time quickly without uninstalling
and without losing your preferences :)

By default, most things are disabled.

AmmoModifier: leave_as_is   will do nothing with ammo
              add           will add a certain amount to all ammopickups
              multiply      will multiply ammoamounts of ammopickups

AmmoModifierAmount: This is a float value. What finally happens depends on the
                    AmmoModifier. Say you set the Modifier to "add", and enter
                    a AmmoModifierAmount of "10", all ammo pickups will now
                    give you 10 more ammo. Now guess what the "multiply" does
                    with this AmmoModifierAmount :)
                    Aw... btw, Unreal rounds down! So when you make "*1.6"
                    a rifle round will still contain only 1 bullet :(

AmmoRespawnTimeAdjustmentFactor: Same as with the Ammo, you can modify the
              RespawnTime of Ammo easily. This is a float value, final action
              depends on AmmoRespawnTimeModifier.

AmmoRespawnTimeModifier: Same as with ammo, leave_as_is, add or multiply the
              Amount of time to all ammo pickups. If you choose "add", your
              AmmoRespawnTimeAdjustmentFactor should be NEGATIVE if you want
              to actually have faster respawns :)
              Same for multiply, the value of "0.5" will halve respawntime.
              Note: You can not set it to zero - uh, well you can, but then
                    time will be reset to "0.1" internally.

AMP: allow         do nothing
     charge0       "discharge" - AMP will remain on maps, but it runs dry the
                              moment you pick it up, so it's pretty useless :)
     charge10      Multiply charge with 10. Yup, have some AMP games, erm....
     charge100     Multiply charge with 100. Even more AMP games, erm....
     chargeLarge   Will make AMP very long lasting....
     Destroy       Will remove the AMP from the map (very safe choice)
     KICKtheLamer  Will terminate the UDP/IP Connection to the player who
                              picks it up - so as a fact the player will
                              be kicked
     KILLtheLamer  Will cause 5000 damage to the player who picks it up...
                              Should result in immediate death of the player.
     ReplaceHealth Will destroy the AMP, and create a Health item in its
                              location

DAMP   Works same as Amp, for the "DAMP"ener (Sound Dampener)

Destroy225fBuggyItems:   Some map makers still include the Quadshot and the
         shells (Quadshot ammo) in their maps. That's pretty useless if you
         are not using a mod which makes use of those items, so on normal
         servers, you can safely destroy those items without any side effects.
         But feel free to turn it "off" once you have a working Quadshot.

DestroyDispersion:  Let's be honest... Who uses the Dispersion??!? And why do
         some map makers have Dispersion Pistols as weapons lying around!?
         Again, if you don't use a specific mod, it's mostly useless. Still,
         if you think you need those Pistol Powerups on your maps, leave it
         on false, but to remove this crap (Dispersion Pistols AND Powerups)
         turn it on. Of course, your default weapon will not be touched...
         But who uses it....

Inv:   Same as Amp and DAMP for the Invisibility...

quicklaunch: This is intended for quick "training matches", for example to
             easily have "Rifle" matches, or "Flak" only matches. To set this
 new         variable online (while you are playing on a server where you have
 since       admin rights) hit tab and type
 Version
 1.1         admin ser main quicklaunch <value>
 :-)
             It will use the last 2 advanced filters to fill your needs, so
             if you have anything programmed in filters BEFORE the last 2,
             your old instructions will be ignored. This is just meant for
             training excercises, and it only supports Unreal Classic guns
             (no UPak). Originally I wanted to make scripts doing this, but
             I got pissed accessing arrays from the console, so I hardcoded
             this.

             Allowed values for quicklaunch are:
             "off" or "none" -- will just disable filters 62+63
             "restore"       -- will restore default values to filters 62+63
             "2"..."10"      -- will configure filters 62+63 to replace all guns
                                with the gun number you chose - e.g. "6" would
                                be "Flak" only, "9" would be "Rifle" only...
                                All ammo will also be replaced with what the
                                selected gun needs
             Any other settings are ignored... One map change is needed for the
             quicklaunch to work... as usual...

RealAMP:  same, for the "RealCTF" version of the Amplifier, as you see at this
          point and the next 2, this mod directly supports RealCTF, as I made
          this with RealCTF in mind, too :)

RealDamage: same, will handle the "RealDamage" powerup in RealCTF (the red/blue
            and color-less...)

RealINV: same, will handle the RealCTF version of Invisibility...

ok... Everything I did NOT mention here, are advanced features.



< IV > Advanced setup

Now let's get serious...

ClassFinder: This is not a setting, it is meant as a help for someone using
             the "WMutateAdvancedReplace" filters (below...). In brief, this
             setting has no effect at all, but when you type in a known class
             name, you will get the full qualified package.class name back.
             For example, start "dmdeck16" and then type "asmd" and hit
             return at that line. You will be given:
             Class'UnrealShare.ASMD'
             This may be useful later (you will see :))

debug: If true, the console outputs advanced filter results. Good idea to
       turn this on if you check out new advanced filters and think they
       don't work. Acutally if they really don't, you usually made a type
       or something, and the debug output will tell you what it found. So
       when it finds no match check your spelling and class/package
       naming and see if the lookup is by "ItemName" or "ClassName" (see
       later). Actually, there's a real difference :)

SimplyShowAllInventory: If true, all WMutators are disabled, but when starting
        a new map, your console will contain all existing inventory items
        with Item name and Class (instance) Name. So if you can't find out an
        item name this might be a way to look it up :)


WMutateAdvancedReplace:
HARR!!! This will open a submenu for 64 (0-63) filters to perform neat
replacing and other actions. Every single filter has the following settings:

Action:
        REcharge:    Will give an item the charge given in "Modifier".
        REspawntime: Will give an item the RespawnTime given in "Modifier".
        Replace:     Will replace an item with what is defined in "ReplaceWithClass".
        Destroy:     Will banish/destroy an item.
        KICKonTAKE:  Will KICK players trying to take an item.
        KILLonTAKE:  Will cause 5000 damage on players trying to take an item.

ActionMaxNumber: The MAXIMUM amount of times this filter is actually executed.

ActionOnEvery: "1" will affect ALL items (0 makes no sense!), "2" will affect
               every 2nd item this filter finds, "3" every third, and so on...

Enabled: hmm, self explaining, every filter can be turned on and off easily
         without losing all the other nice preferences you made with it :)

Modifier: A float value needed for actions like Recharge, RespawnTime.

ReplaceWithClass: If your action is "Replace", you must enter your fully
          qualified class here with which you want to replace the item.
          For example you want to create an ASMD for some other item, then
          it's not enough to enter "ASMD" here, you need
          UnrealShare.ASMD
          remember the ClassFinder??? Understand its use now????
          External classes are no problem. For example if you have my weapon
          mods installed, you could enter "Shredder.Shredder" to create a
          Shredder weapon :)

SearchBaseClass: This field requires a classname. Only the FINAL classname
          will be accepted, e.g. "Health", not "UnrealShare.Health". This is
          both good and bad (see examples below). Actually, this is ONE of
          the possible parameters you can look up items with, depending on
          their class.

SearchBaseClassByName: Normally you search by Classname, but you can also
          search by ItemName, but then you must set this to true here.
          ItemName? ClassName?? Ain't that the same? Well, NO!!! Some Unreal
          items have the same class and item name for somplicity, but for
          example the Sniper Rifle has the Class Name "Rifle", but the item
          name "Sniper Rifle" (yes with a space!) :)

SearchBaseClassITEMNAME: If you chose to look up items by their Names
          instead of looking up classes, enter the item name here.

NOTE: Choose to lookup itemNAME or classNAME whatever is easier in order to
      get your filter do what you want :)


Now so much theory, let's give some examples so you understand how the shit
really works:

1) Action                   "Destroy"
   ActionMaxNumber          "5"
   ActionOnEvery            "3"
   Enabled                  "False"
   Modifier                 <no matter>
   ReplaceWithClass         <no matter>
   SearchBaseClass          "Health"
   SearchBaseClassByName    "False"
   SearchBaseClassITEMNAME  <no matter>

What will 1) do??? NOTHING!!! Because it is not enabled :P
Ok, let's set "Enabled" to "True", then what will happen?
It will Destroy every 3rd health item in any map, but altogether no more than
5 total! So this "thins out" health items a bit, but doesn't remove them
all :)   If you wanted to thin out all - without "max", just set the
ActionMaxNumber to "100", because maps usually have faar less items, even less
of the same kind, so don't worry :)

Hmm... now you get back on your map and you find out that this filter
effected not only your health items, it also affected your superhealth,
your nali fruit, your bandages... what's up??? Well... you looked for a
CLASS!!! Superhealth and all the others are also class "Health" children,
so the filter will include them in the action too!!!! You don't want that??
Then you should do this:
SearchBaseClassByName: True
SearchBaseClassITEMNAME: Health

Class "Health" also is item-named "Health", so this way you can make sure it
only destroys real health items, not any subclasses of this kind :)
Now that was kewl, wasn't it?

You wanted to remove ALL HEALTH??
no prob, just set "ActionMaxNumber" very high, and "ActionOnEvery" to 1 :)
Bang, no more health of any kind, except if there are seeds in the map,
you must handle them extra, I think they are no subclass of health... not
sure right now :)


2) Action                   "REcharge"
   ActionMaxNumber          "10"
   ActionOnEvery            "1"
   Enabled                  "True"
   Modifier                 "6"
   ReplaceWithClass         <no matter>
   SearchBaseClass          "JumpBoots"
   SearchBaseClassByName    "False"
   SearchBaseClassITEMNAME  <no matter>

This will recharge all JumpBoots with a charge of 10, so you can jump 10
times with them...


3) Action                   "Replace"
   ActionMaxNumber          "1"
   ActionOnEvery            "1"
   Enabled                  "True"
   Modifier                 <no matter>
   ReplaceWithClass         "ASMDRailGunV7.ASMDRailGunV7"
   SearchBaseClass          "RealASMD"
   SearchBaseClassByName    "False"
   SearchBaseClassITEMNAME  <no matter>

This will replace the first asmd found in any RealCTF game with my self
made ASMDRailGun Version 7. Actually you need the ASDMRailGunV7.u file
in your system dir for this to work, and you must have ASMDRailGunV7 as
ServerPackage :)


4) Action                   "Recharge"
   ActionMaxNumber          "1"
   ActionOnEvery            "2"
   Enabled                  "True"
   Modifier                 "400"
   ReplaceWithClass         <no matter>
   SearchBaseClass          "Armor"
   SearchBaseClassByName    "False"
   SearchBaseClassITEMNAME  <no matter>

This one will set the 2nd Armor (Assault Vest) to a charge of 400, but only
the 2nd, not the first, so if you pick up the first one you will get a normal
assault vest, find the other to get a 400 protecting assault vest. If the map
contains only 1 Armor, then the filter does nothing.


MIXING EASY FILTERS WITH ADVANCED FILTERS:
It is possible to use a mixture of the two set-ups. All you need to know is
that the Advanced Filters are executed first, then the easy ones. So you
could set up your easy config to make AMPs be disabled, but in advanced you
have 1 AMP exchanged... result: one AMP will be exchanged, all remaining
AMPs will be disabled.


< V > Recommendations

For really fun Servers:
Destroy the Dispersion stuff, and the INVIS, set AMP recharge a bit higher.
Set JumpBoot Charge a bit higher, possibly even replace some less important
items with extra items such as flare -> shieldbelt... or, health -> JumpBoots
Destroy 225fBuggy things.

Official Classic Servers:
Destroy all AMPs, INVis, charge up the Silencer (DAMP) really high.
Destroy 225fBuggy things.

RealCTF servers:
Modify RespawnTimes and/or Ammamounts for ammo pickups. Charge JumpBoots a
bit higher (warning, other class), banish all RealAMPs, RealDAmages and
INVis, charge up Silencers... Destroy 225fBuggy things, destroy Dispersion.
RECOMMENDATIONS NOT DEPENDING ON THIS MOD:
Disable the beamer, if your maps depend on the beamer, don't play them, the
beamer sucks!!!!
You do not have enough Real_maps? Try normal dmmaps with RealCTF, the CTF mod
will spawn the bases as far away from each other as possible. DMDECK17 and even
DMDECK16 make good CTF maps, try other bigger dmmaps :))

Anti-Aimbot / LAMER servers:
Replace all Rifles, ASMDs and the ammo with some other weapons which are less
"bot"able. Make invis and amp to "KICKtheLAMER". HA HA, BYE BYE BOB!!

Interesting servers:
Do same as Official Classic servers, in addition replace one "2nd" 
stinger with a MUltiRL, and one "2nd" ASMD with a Railgun, all ForceFields
with my improved forcefield. Might also be very nice for RealCTF servers.



< VI > Example Configs

Just look into the directory to see what the settings are good for.



< VII > Bugs / Problems / Issues

Before you mail me any bugs, check your typos. That's extremely true for any
advanced filters. Use the debug function to check if the item isn't found, and
carefully see if you really looked up the correct one.

Ok, this mod has some inconveniences, marginally, I did some bugfixing to the
best my poor skills allowed - known issues:

1) Doesn't work with BotPlay/SinglePlayer
   Hmm... sorry, no idea...

2) Automatic Lamer KICK / KILL
   May fail to work in some very odd locations, when "banned" item has very
   unusual positioning vectors :(

3) Automatic Lamer KICK / KILL
   Normally you won't pick up the PROTECTED item, only the "killer" item.
   WHen a bot or player happens to really pick up both, it sometimes
   happens that respawning takes longer and looks a bit odd, as if the item
   respawns all the time, actually it doesn't. If this happens, an "empty"
   player will sometimes be reported to have picked up the protected item.

4) Automatic Lamer KILL
   Pick up such a "banned" item in GOD mode, and the protection will be gone.

5) Classfinder finds no classes
   LOL... not my fault! The class finder can only search through KNOWN
   packages, so if the package your item you look for hasn't been loaded
   yet, you're out of luck :)

6) Replaced items look "stuck" in wall/floor - or levitating
   Simple thing, items have different sizes, and the replaced item will be
   created EXACTLY at the location of the old item, but of course with its
   own size properties. So if you e.g. replace Stingerammo with Rifleammo,
   the Rifleammo is higher in size, and will look as if stuck in the floor.
   Don't worry about that...

7) When I replace a LAAARGE amount of items (such as all ammopickups or so)
   it seems as if the mod is going over just the same pickups over and over
   AGAIN (using debug mode this is visisble)...
   Yes... that is unfortunately true. The problem seems to be that Unreal
   reorders the items after one destroyed and a new one spawned in its place,
   so... Let's say you exchange all ASMDs with railguns, there are exactly
   5 ASMDs in the map and you have "ActionOnEvery = 1" and
   "ActionMaxNumber = 5". This setting actually >>SHOULD<< replace all ASMDs
   in this case, but maybe does not. Why? Because as soon as one item is
   replaced, the order of the remaining items is unspecified again. I did
   not figure this out 100%, but it seems the "starting off point" from
   where to start looking for items seems to change each time a replace
   occured, so could just go over the same items again and again, because
   Railgun is subclass of ASMD, too!!
   You can help this a bit by looking for NAMES instead of classes, but then
   your powerful filter replacing all weapon types losses it's potential.
   To make it easier, just set the "actionMaxNumber" to an insane value like
   200. This may cause a slowdown when your server changes maps, but will
   solve your problem...
   Ok, actually the problem really only gets apparent for real large
   replacements like 20 items at once and so. With 5 you should be out of
   danger anyway, but the reordering mess is applicant always, of course :(

If you find any more inconveniences, let me know, but don't bombard me, duh :)



< VIII > Developers' notes:

You have my permission to do with this code whatever you want... well, just be
nice with it, make improvements if you want, give it to people if you want...
offer it for download on any website if you want... just LET ME KNOW
(ChaosWorx@gmx.de) what you do with it.

!!!!! There is only one thing you may not do !!!!!

>> DO NOT EXPLOIT THIS MOD COMMERCIALLY - DO NOT CHARGE MONEY FOR IT <<


You only get the U file, but start the editor, load the package and use the
"Export" function to get the plain sources.



< IX > Thanx

Very special thanx go to Hollebollegijs (-=O-HbG-O=-) for his thoughts and
sources I was allowed to get a look at. Most of his stuff created more
riddles for me than solved problems, but all in all I could get some
interesting ideas from him. I just don't have all the time to try everything
:(

Many thanx also to my clanmate }TCP{Carnage for testing my weapon mods on
his server, though this doesn't directly belong here :))

added thanx since 29th March 2002

Big thanx to Rewind{KDS} for his friendship and lasting cooperation with
server issues.

[GOD]Smirftsch for his trust and the availability of www.oldunreal.com
without which the Unreal community would miss one good source of stuff for
this great game.



So... you really read down to here? Then thank YOU!

Enjoy,

}TCP{Wolf / Mia_The_Chaotic
