//             MAD DOG'S PANTHER XL CONFIG for
//          SOLDIER OF FORTUNE (ADVANCED VERSION)
// 	       FOR SINGLE-PLAYER & DEATHMATCH
// 		       April 22, 2000
// 	No redistributions of this file or any part of its
// 			contents permitted.
// See the end of this document for details and exclusions.
//              http://doghouse.gamedesign.net/
// ===========================================================


[Use EDIT>WORD WRAP to read this file.]

Files enclosed:
PXL_SoFa.cfg
settings.cfg
save.cfg
binds.cfg
prefer.cfg
PXL_SoFa.bmp
PXL_SoFa_readme.txt (this file, duh)
...also there's a 'readme1.txt' which hopefully won't be needed in the future.

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

	1.  Initial Setup
	2.  Adjustments
	3.  Bindings and Editing
	4.  Variable Values and Scripting
	5.  The Keyboard
	6.  The Mouse
	7.  Function Explanations
	8.  Troubleshooting
	9.  Revision History
	10. Redistribution Limitations

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

1. Initial Setup

	First off, you should have a MadCatz PantherXL hooked up to your machine, the latest drivers installed, and the controller configured properly. http://www.pantherxl.com/ is a site you should bookmark.

	Unzip all the files in this archive using "Use Folder Names" option into your \SOF\BASE\ folder. When done, you should now have a subdirectory \SOF\BASE\_PXL_SoFa\. Within that folder you should find all the files listed above. No matter what mod or mission pack you play, SoF.EXE will find config files there, AS LONG AS you add the line:

	exec _PXL_SoFa/PXL_SoFa.cfg

...to your AUTOEXEC.CFG file (make one if you haven't already). If you use multiple AUTOEXEC.CFG files for different game folders for some reason, add the line to each one. Preferably it should be the last line in the config, so it is loaded last.

	Now open the newly created \_PXL_SoFa\ folder.

	Open 'settings.cfg' with Notepad. You will see a section entitled "GAME SETTINGS THAT MUST BE SET HERE IF YOU DON'T SET THEM IN ANOTHER CONFIG". This is a section that does not apply to current version of the PXL config, which is why it is empty. This may change in the future.

	Still in 'settings.cfg', if you scroll down you will find all of the PXL axis settings. See section #2: "Adjustments" and Section #7: "Function Explanations" for more info on what to do here. If you're unsure about these things, you can leave them as is for now.

	Open 'binds.cfg'. Lots of stuff here that may look like Greek to you; that's OK. If you don't understand what's going on with this particular config, then leave it alone for now -- after all you might end up liking it the way it is. But if you want to change button function, this is the place to do it. HOWEVER: Contrary to what you might expect, CHANGING BINDINGS is not the most effective or the easiest way to remap buttons. Instead, what you should do here in the event you want to make changes is REDEFINE THE ALIASES INSTEAD. Read section #3: "Bindings and Editing" for a rather exhaustive explanation of how this works. (Note: There is one exception to this, and it is described fully in README1.TXT).

	The file 'prefer.cfg' does nothing in the current version of the PXL config (but it is still called). This may change in the future.

	Open 'save.cfg'. This config saves variable values into new variables which can be recalled later. Leave this alone at least for now. See section #4: "Variable Values and Scripting" if you're interested in why this is sort of thing is important.

	OK, you're done! Print out that cheesy "PXL_SoFa.bmp" so you can see what the buttons do, and fire up Soldier of Fortune!

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

2. Adjustments

	The sensitivity and threshold settings for all axes are mine, I have no idea what your preferences are. If you already have tried-and-true settings that you want to use then edit them under the "CONFIGURE CONTROLLER" section of "settings" config. If you are unfamiliar with this stuff then I strongly advise you read my article on "Understanding JoyAdvanced Commands" that I maintain at the DogHouse:
	http://doghouse.gamedesign.net/articles/joyadv.html

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

3. Bindings and Editing

	This config uses a method of redefining existing aliased commands through a macro. Each time you press the "SHIFT" button (not the 'shift' key on your keyboard - see the .BMP), all other buttons change to their "secondary" functions, and are returned to their "primary" functions when you release the "SHIFT" button. The config does this by executing variables I have defined in the "PRIMARY-SECONDARY SELECT" section of "binds.cfg".

	IMPORTANT NOTE: The bindings are static and never change. If you wish to remap any of the buttons, changing the bindings IS NOT THE WAY TO GO ABOUT IT, unlike what you may expect. Instead, what changes are how the aliased commands bound to those buttons are defined.

	Using this example from "binds.cfg":
	=================
// ***HAT2***
// N
bind AUX5 +05
set 1_05 "alias +05 ws5;alias -05 "
set 2_05 "alias +05 ws6;alias -05 "
	alias ws5 "weaponselect 5"	// SNIPER RIFLE
	alias ws6 "weaponselect 6"	// SILENCED SMG
	=================

	The line "bind AUX5 +05" you should LEAVE ALONE. Instead, look to where you see "alias +05 ws5;alias -05 " on two lines. The first line defines what command is available as a primary function, and the second line defines what command is available as a secondary function. This is where changes should be made if desired. Since "ws5" and "ws6" are aliased commands themselves, the scripts that define them are found here also; it makes them easier to find and edit too.

	For the greatest flexibility, all of the bound commands are "action" commands (commands that start with "+"). As such, the "-" or "cancel" version must be defined as well. When a "+" command is executed from a key- or button-press, Quake2 looks for a "-" command when that key or button is released. A couple of examples from the "binds.cfg":
	=================
	"alias +01 +attack ;alias -01 -attack"
	"alias +30 weaponbestsafe;alias -30 "
	=================
Now in the first case we need "-01" defined as "-attack" so we can stop firing the selected weapon, but in the second there's no need to "cancel" the "weaponbestsafe" command. But we have to tell SoF that the aliased command "-30" exists since we've defined a "+30" command. So we define "-30" as doing nothing. SoF is then happy and won't pester you with "unknown command" messages.

	Note that if both primary and secondary choices are true action commands, then the "cancelling" alias needs to be able to cancel them both. This is because the "SHIFT" button has no way of knowing what commands are active when it is pressed and released. Consider the following theoretical example where both jumping and crouching are on the same button:
	=================
	"alias +02 +moveup  ;alias -02 -moveup  "
	"alias +02 +movedown;alias -02 -movedown"
	=================
In this example if you pressed an held the "SHIFT" button, then the button (JOY2) with "+02" bound to it becomes your "crouch" button. But if you release "SHIFT" before releasing your crouch, then when you attempted to 'uncrouch', you would cancel moving up instead, and be stuck in a crouch. Not good.

	To solve this, you would then do something like this:
	=================
	"alias +02 +moveup  ;alias -02 cancel_updown"
	"alias +02 +movedown;alias -02 cancel_updown"
		alias cancel_updown "-moveup;-movedown"
	=================
As you can see, the position of the "SHIFT" button would not matter here, since either way both jumping and crouching would be canceled whenever the button (JOY2) with "+02" bound to it is released.

****SPECIAL NOTE: In the current version of Soldier of Fortune, there is an issue concerning the "+use" command which is relevant here. See README1.TXT for details.

	You may also have to construct some aliases for those command strings that have spaces in them, as I did for selecting weapons and using items. Again, right from "binds.cfg":
	=================
bind AUX5 +05
set 1_05 "alias +05 ws5;alias -05 "
set 2_05 "alias +05 ws6;alias -05 "
	alias ws5 "weaponselect 5"	// SNIPER RIFLE
	alias ws6 "weaponselect 6"	// SILENCED SMG
	=================

	On a side note, yes my choice for using the joystick pinky button for jumping is unusual. I've arrived at this because my right thumb can be very busy with the hats and 2 joybuttons, and I want jumping to be always available to me even when I'm selecting a new weapon. Change it around if you wish, but I know my way is best :-)

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

4. Variable Values and Scripting

	Some aliases/scripts need the "normal" values for certain variables to be recallable, so they can be reset when the script action ceases. In the case of my SoF PXL config, the FullSpeed script uses this method. To keep the script more portable and to eliminate unnecessary editing when settings are changed in the "CONFIGURE CONTROLLER" section of "settings.cfg", the settings for the relevant variables are saved in the form of custom variables so they may be recalled later. These custom variables can be seen in "save.cfg". These need not be changed, but "PXL_SoFa.cfg" calls "save.cfg" *after* calling the other configs for a very important reason. First, your game settings need to be set to begin with, then the values are safely saved using "save.cfg". Otherwise previous 'bad' values are saved, spoiling your preferences.

	If you want to add your own scripts and need to do something similar by saving a variable value in the form of a custom variable, then "save.cfg" is the place to add it.

	Many have difficulty understanding this, but this is really not so difficult, and is in fact the simplest application of using custom variables. For example, when the config is read, the line:

	set _forward $joy_forwardsensitivity

...results in the custom variable "_forward" to be equal to the setting for "joy_forwardsensitivity", whatever it happens to be. Then later, when the FullSpeed script is turned on, the value of joy_forwardsensitivity is increased, as the script directs it to be. When FullSpeed is turned off, the previous setting of joy_forwardsensitivity is restored. This is done with the FullSpeed script:

	set joy_forwardsensitivity $_forward

...This sets the value of "joy_forwardsensitivity" to whatever "_forward" is, which is exactly what joy_forwardsensitivity was originally. See, it's not that hard.

This is a very useful tool for use in scripts that require variable settings to be changed. Let's say the FullSpeed script, when it was turned off, set joy_forwardsensitivity to a value directly. Then if you made a change to joy_forwardsensitivity in the "CONFIGURE CONTROLLER" in "settings.cfg", you would also have to pore over the configs looking for toggle scripts that hold the possibility of hosing that setting. Not fun.


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

5. The Keyboard

	You still will need the keyboard for some crap, like for the ability to drop weapons/items, and accessing the mission briefing or player scores in multiplay. None of these types of things are essential for moment-to-moment gameplay, so the keyboard is a fine place for them. With this config, hotkeys are on the controller so you will have lots of keyboard keys available -- you can load 'em up with "say" commands and obnoxious taunts.

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

6. The Mouse

	No, the mouse isn't used for anything; who needs it when you have a trackball? But knocking the mouse around during a game can have annoying results. If you wish, you could add:

	m_yaw 0
	m_pitch 0

...to any config you're loading, and this will make the mouse totally unresponsive. The mouse cursor actions in the menu will be unaffected. You could consider the now-dead mouse on your desk as a kind of mascot if that amuses you.

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

7. Function Explanations

	Most are self-explanatory and can be read more easily from the enclosed .BMP than from a text file. But here I'll explain some of the less-obvious ones:

SHIFT: is a modifier. When pressed and held, secondary functions found on other buttons become active. When released, all returns to "normal".

THROTTLE AXIS: Mapped to moving up/down as an auxiliary control for special effects (your primary up/down controls are joystick buttons). You can use the throttle to "hold" a crouch or "walk" on water. TAKE CARE THAT THE THROTTLE IS CENTERED WHEN YOU DON'T WISH TO USE THIS. I've set a lot of slop so it's not necessary to be too precise. I mapped this axis since I hate to see anything go unused. If you don't like it, change the setting for "joy_advaxisz" to "0" to disable it.

FULLSPEED: This is a toggle which when activated makes forward/back movement and strafing movement sensitivity very high. This is useful when standing on a narrow ledge and you need to get up to full speed instantly to make a jump. Activating this again restores the stick to the more customary proportional control. An on-screen echo and a sound cue when FullSpeed mode is changed will alert you that FullSpeed is on or off.

All other controls are standard game controls. There are no weapon scroll or item scroll functions, since weapon selection and item use is handled fully with hotbuttons.

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

8. Troubleshooting

	The PXL does not work as expected.
Make sure the config is indeed being loaded. Enable the Soldier of Fortune console by adding "+set console 1" (no quotes) to the end of the command line used to run SoF.EXE. (You can edit a the shortcut to SoF.EXE to do this). Assuming you have CD autoplay enabled, holding the "SHIFT" key while inserting the CD (and continuing to hold it until the CD has spooled up!) will temporarily disable autoplay. Then start the game using the aforementioned shortcut to SoF.EXE. Start a new game, and after a map has loaded, use the tilde (~) key to bring down the console. You should see "Loading MadDog's SoF PXL Config blah blah" somewhere in the list of things that the game has done to bring you where you are. If you don't, then the config didn't load. In that case, see section #1: "Initial Setup".

	You find you can't come out of a crouch, or jumping is unreliable.
Probably the throttle is not centered. See 'thottle axis' in section #7: "Function Explanations".

	You've edited the "PRIMARY-SECONDARY SELECT" section of "binds.cfg", and now you stay crouched sometimes or something similar.
See section #3: "Bindings and Editing". Read that crap carefully.

	You can't stop leaning.
This is a known issue with the current config, having to do with what buttons are pressed and released in what order. Tap the "use" button again and all should be well. See the enclosed README1.TXT for a rather lengthy explanation.

	After leaning you find you can't strafe any more.
Read the enclosed README1.TXT, you've edited the config and inadvertently disabled the workaround for this problem.

	You can't stop moving when you let go of the stick.
My guess would be you haven't calibrated the PXL too well in the Windows control panel. Increasing threshold values would be another solution, but should't be necessary to solve this problem. To do so, see section #2: "Adjustments".

	The trackball doesn't work properly.
Recalibrate in the Windows control panel. You really need to spin that bad boy; don't be shy. Also make sure you're using the latest PXL drivers from MadCatz. Early shipping drivers would often cause the settings to be lost after a reboot.

	Other controller-specific problems.
Visit http://www.pantherxl.com . Here you will find solutions, access to tech support, and a message board specifically for PXL owners.

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

9. Revision History

Current Version: Release date 4/23/99
-Filenames: PXL_SoFa.cfg, settings.cfg, save.cfg, binds.cfg, prefer.cfg
-Makes use of "shift" button macro to redefine aliases for selected buttons.
-All 5 axes used, including the throttle for water-walking and crouch-holding.
-All weapon/item hotkeys accessed through the hat switches.
-"FullSpeed" option allows for toggling between 2 stick sensitivity settings on the fly.
-All commonly used controls on the controller, including: WeaponSpecial1 & 2, Best Safe & Unsafe Weapon, Use and Reload.
-Uses the same scripting format and file/folder format as my other Q2-engine game 'advanced' PXL configs.
-A very ramblingly long readme file and a eye-assaulting image file.


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

10. Redistribution Limitations

Redistribution of these files IS NOT PERMITTED UNDER ANY CIRCUMSTANCES. I'd like to retain some quality and version control here. Especially since the included configs are still being tweaked.

SPECIAL EXCEPTION TO THE ABOVE IS GRANTED TO:

	Steveo and http://www.clana3d.com/ 
	(A site you should visit on a regular basis if you have a PXL)
and:
	MadCatz - http://www.pantherxl.com/
	The Source :-)

- Mad Dog/Cannis Rabidus
http://doghouse.gamedesign.net/


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

"PantherXL" is a trademark of MADCATZ
"Soldier of Fortune" is a trademark of RAVEN SOFTWARE
These trademarks are being used here *without* permission.

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