// MAD DOG'S PANTHER XL CONFIG for KINGPIN (ADVANCED VERSION)
// 	         FOR SINGLE-PLAYER & DEATHMATCH
// 			December 29, 1999
// 	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_KPa.cfg
settings.cfg
save.cfg
binds.cfg
prefer.cfg
PXL_KPa.bmp
PXL_KPa_readme.txt (this file, duh)

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

	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 \KINGPIN\MAIN\ folder. When done, you should now have a subdirectory \KINGPIN\MAIN\_PXL_KPa\. Within that folder you should find all the files listed above. No matter what mod or mission pack you play, KINGPIN.EXE will find config files there, AS LONG AS you add the line:

	exec _PXL_KPa/PXL_KPa.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_KPa\ 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". What follows is 1 commented line setting the value for "fov". Lines beginning with 2 forward slashes (//) are ignored by Kingpin. If you are relying on the game to save settings for you (in other words, config.cfg), you should uncomment this lines so that the values for fov is specified here where it won't be overwritten. The values given is the default: if you want a a field of view of 120 degrees for example, change the "fov" line to read "fov 120". This will avoid problems later.

	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" (specifically the "ZOOM 2X;ZOOM 10X" listing) 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 exhausive explanation of how this works.

	Open 'prefer.cfg'. Here's where the most common user preferences can be set. What you want to do here is select your preferred Handswitch Cycle. You can choose between cycling "Right/Left" handedness, or "Right/Center/Left/Center" handedness. Various options are here so you can not only choose which cycle option you want, but also what hand setting you'll start with when the game loads. "Right/Left, Start Right" is selected by default. Make sure only ONE line is uncommented.

	Still in 'prefer.cfg', you can select if you want to return to your "default" hand setting or your "last" hand setting when a Sniper mode is cancelled. Again, uncomment only ONE line.

	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_KPa.bmp" so you can see what the buttons do, and fire up Kinpin!

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

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":
	=================
// ***HAT1***
// N
bind AUX29 +29
set 1_29 "alias +29 lp;alias -29 "
set 2_29 "alias +29 cb;alias -29 "
	alias lp "use pipe"
	alias cb "use crowbar"
	=================

	The line "bind AUX29 +29" you should LEAVE ALONE. Instead, look to where you see "alias +29 lp;alias -29 " 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 "lp" and "cb" 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, Kingpin 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 +11 weaplast;alias -11 "
	=================
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 "weaplast" command. But we have to tell Quake2 that the aliased command "-11" exists since we've defined a "+11" command. So we define "-11" as doing nothing. Kingpin 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.

	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 hm;alias -05 "
set 2_05 "alias +05 hm;alias -05 "
	alias hm "use heavy machinegun"
	=================

	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 my PXL configs, the Sniper and FullSpeed scripts use this method. To keep the scripts 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_KP.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 player scores in multiplay or the F1 notepad in single-play. Also in single-play you will need keys bound to the "yes" and "no" commands ("key1" and "key3"). 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 -- load 'em up with "say" commands, that's what I do.

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

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. 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.

BEST WEAPON1: This is an alias string found in the configs which attempt to select my favorite weapon. The preferences can be reordered.

ZOOM 2X;ZOOM 10X: A couple of sniper modes. They set you to center-handedness for greater accuracy, and adjust sensitivity proportionally too. THEY DON'T MESS WITH THE NORMAL SETTINGS. When you release the 'zoom' button, everything gets restored. If you adjust your normal pitch or yaw sensitivity, it would be best to tweak the settings for the sniper modes, but is not absolutely necessary. Instructions are found in "settings.cfg" itself so you don't have to try and dig up this file when you want to make changes.

NPC ATTACK
This is just the 'key2' command. Point your crosshair at one of your hired guns, press SHIFT+NPC ATTACK, then point at a victim, and press ACTIVATE. He'll go to work.

LAST WEAPON: An undocumented game command, 'weaplast'. It switches you back to the weapon you had before. Switch to the crummy crowbar, break something or smack someone upside the back of the head, and press "LAST WEAPON" as you proceed. Works well.

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.

HANDSWITCH: Switch the gun hand between the right and left, OR between right, center, and left. Your choice - see Section#1: "Initial Setup".

ROCKET JUMP: There is none! The reason is simple: I have never found a rocket jump alias to be 100 percent reliable, and freestyling RJ's with the PXL is easy.

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

8. Troubleshooting

	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.

	Handswitching doesn't work or works oddly.
See section #1: "Initial Setup". You have to decide if you want "Right/Left" or "Right/Center/Left/Center" style handswitching, and once done, you have to comment ALL LINES which are inappropriate, and uncomment to ONE LINE that is. Sorry to put you through this, but everybody wants something different.

	Hand setting returns to what I started with rather than what I Handswitched to after cancelling a Sniper mode.
See section #1: "Initial Setup". This is a preference you must set.

	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 12/29/99
-Filenames: PXL_KPa.cfg, settings.cfg, save.cfg, binds.cfg, prefer.cfg
-Format is now identical to my Quake2 configs... making it easier to write versions for all Quake2-engine games. The readme is hauntingly similar too.
-The config is broken up into 5 configs (hopefully in a logical way). Simply put, when one file is too large Kingpin fails to initialize with a "SZ_GetSpace Overflow without overflow set" error; my file grew too large to keep everything in a single config. The 5 files are now in a subdirectory of \MAIN\ to keep them nice and cozy.
-Added option to save 'fov' for those who are overly dependent on config.cfg.
-Added 3-hand handswitch option.
-Added hand setting restore option to the sniper modes. Now you can decide if you want your 'default' or your 'last' hand setting restored when a sniper mode is cancelled.
-Added "FullSpeed" option.
-Removed dynamic lighting alias from flashlight command.
-Juggled stuff around with the button functions.
-Replaced .JPG with a 16-color .BMP everyone can open.

Initial Version: Release date 7/12/99
-Filename: PXL_KP.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 hotkeys accessed through the hat switches, including the pipe and silencer pistol.
-2 sniper modes.
-A best weapon string.
-Hand-switching.
-NPC attack function.
-JPG 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
"Kingpin" is a trademark of XATRIX ENTERTAINMENT
These trademarks are being used here *without* permission.

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