This file is intended for use by authors wishing to write their
own front-ends for SAGE.

I freely give permission for this, with the only condition that
my name (Paul Johnson) is mentioned as the original author, and
that technical support questions regarding operation of your front
end are to be directed to you and not me !


SAGE can be run with or without a command line. If there are no
arguments, then the front-end will kick in and run normally. If one
argument is passed in, then this is taken as a game name. Only the
first argument is examined, and no errors are generated based on
any subsequent arguments.

When exiting, error codes are passed back to the calling program,
the codes for which are listed below.

Please feel free to mail me with any queries or to report mistakes
in either this document or the manner of operation of SAGE via a
command line.




========================================
		GAME NAMES
========================================

Following is a list of games that SAGE currently supports. Next to
them, in the quotes (which are for illustration only) are the command
line names required to run the games. Obviously when newer games are
added to SAGE, then this list will grow. SAGE is *NOT* sensitive to
case, but while your here, why not block copy them out of this list !


Galaga			"GALAGA"
Commando		"COMMANDO"
Ghosts n Goblins	"GNG"
1942			"1942"
MrDo			"MRDO"
MrLo			"MRLO"
Space Firebird		"FIREBIRD"
Moon Cresta		"CRESTA"
Scramble		"SCRAMBLE"
Phoenix			"PHOENIX"
Pleiades		"PLEIADES"
Space Invaders		"INVADERS"
Invaders Deluxe		"INVADERSD"
Invaders Revenge	"REVENGE"
Space Attack		"ATTACK"
Super Earth Invasion	"INVASION"
Galaxy Wars		"GALAXY"
Lunar Rescue		"RESCUE"
Galaxian (Midway)	"GALAXIAN1"
Galaxian (Namco)	"GALAXIAN2"
Galaxian Part 1		"GALAXIAN3"
Galaxian Part 4		"GALAXIAN4"
Galaxian (Turbo)	"GALAXIANT"
Super Galaxian		"GALAXIANS"
Uniwars			"UNIWARS"
War of the Bugs		"BUGS"
Pisces			"PISCES"








========================================
		CONTROLS
========================================

All user control stuff such as keyboard congigurations
are passed to SAGE via the "SAGE.CFG" file. You may make
alterations to this file to change how SAGE reacts to
the keyboard etc.. You know the drill.

The file format is dead simple, explanations follow after


  DWORD		SoundCard
  DWORD		Player1Up
  DWORD		Player1Down
  DWORD		Player1Left
  DWORD		Player1Right
  DWORD		Player1Fire1
  DWORD		Player1Fire2
  DWORD		Player1Fire3
  DWORD		Player2Up
  DWORD		Player2Down
  DWORD		Player2Left
  DWORD		Player2Right
  DWORD		Player2Fire1
  DWORD		Player2Fire2
  DWORD		Player2Fire3
  DWORD		DipSwitch
  DWORD		Joystick
  DWORD		Accuracy

  18*4 = 72 Bytes in total


SoundCard	0 = Silence
		1 = Soundblaster
		2 = Ensonique
		3 = Gravis

Player1Up	Scan codes for various keys in *MY* format
.....		See below !
Player2Fire3

DipSwitch	N/A No longer in use, value ignored but needed
		for padding

Joystick	0 = Don't use joystick
		1 = Use joystick

Accuracy	0 = Smooth display
		1 = Accurate speed




========================================
		SCAN-CODES
========================================

I, for reasons best known to me, use a non-standard scancode system
for handling the keyboard. You should be able to extrapolate from
the following table which key for SAGE maps to which keyboard key.
You can obviously use this table to print up the relevant ASCII
text for the keypress should you wish.

I know this is a pain in the arse, but I am not prepared to change
or explain it. This whole thing is because two people asked for it
and whilst I am obviously willing to help, am not prepared to get into
debate about how my code works !



//	String			Key				SAGE
char	*ScanCodeToString[256]
={
	"",		//	Nul				00	
	"Esc",		//	Escape				01	
	"1",		//	'1!'				02	
	"2",		//	'2"'				03	
	"3",		//	'3œ'				04	
	"4",		//	'4$'				05	
	"5",		//	'5%'				06	
	"6",		//	'6^'				07	
	"7",		//	'7&'				08	
	"8",		//	'8*'				09	
	"9",		//	'9('				10	
	"0",		//	'0)'				11	
	"-",		//	'-_'				12	
	"=",		//	'=+'				13	
	"BkSpc",	//	Backspace			14	
	"Tab",		//	Tab				15	
	"Q",		//	'qQ'				16	
	"W",		//	'wW'				17	
	"E",		//	'eE'				18	
	"R",		//	'rR'				19	
	"T",		//	'tT'				20	
	"Y",		//	'yY'				21	
	"U",		//	'uU'				22	
	"I",		//	'iI'				23	
	"O",		//	'oO'				24	
	"P",		//	'pP'				25	
	"[",		//	'[{'				26	
	"]",		//	']}'				27	
	"Ret",		//	Return				28	
	"Lctrl",	//	Left Control			29	
	"A",		//	'aA'				30	
	"S",		//	'sS'				31	
	"D",		//	'dD'				32	
	"F",		//	'fF'				33	
	"G",		//	'gG'				34	
	"H",		//	'hH'				35	
	"J",		//	'jJ'				36	
	"K",		//	'kK'				37	
	"L",		//	'lL'				38	
	";",		//	';:'				39	
	"'",		//	''@'				40	
	"'",		//	''@'				41	
	"Lshft",	//	Left Shift			42	
	"#",		//	'~#'				43	
	"Z",		//	'zZ'				44	
	"X",		//	'xX'				45	
	"C",		//	'cC'				46	
	"V",		//	'vV'				47	
	"B",		//	'bB'				48	
	"N",		//	'nN'				49	
	"M",		//	'mM'				50	
	",",		//	',<'				51	
	".",		//	'.>'				52	
	"/",		//	'/?'				53	
	"Rshft",	//	Right Shift			54	
	"*",		//	KeyPad '*'			55	
	"Lalt",		//	Left Alt			56	
	"Space",	//	Space				57	
	"Caps",		//	Caps lock			58	
	"F1",		//	F1				59	
	"F2",		//	F2				60	
	"F3",		//	F3				61	
	"F4",		//	F4				62	
	"F5",		//	F5				63	
	"F6",		//	F6				64	
	"F7",		//	F7				65	
	"F8",		//	F8				66	
	"F9",		//	F9				67	
	"F10",		//	F10				68	
	"NumLck",	//	Numlock				69	
	"Scroll",	//	Scroll lock			70	
	"kp7",		//	Keypad '7'			71	
	"kp8",		//	Keypad '8'			72	
	"kp9",		//	Keypad '9'			73	
	"kp-",		//	Keypad '-'			74	
	"kp4",		//	Keypad '4'			75	
	"kp5",		//	Keypad '5'			76	
	"kp6",		//	Keypad '6'			77	
	"kp+",		//	Keypad '+'			78	
	"kp1",		//	Keypad '1'			79	
	"kp2",		//	Keypad '2'			80	
	"kp3",		//	Keypad '3'			81	
	"kp0",		//	Keypad '0'			82	
	"kp.",		//	Keypad '.'			83	
	"?1",		//	?				84	
	"?2",		//	?				85	
	"\\",		//	?				86	
	"F11",		//	?				87	
	"F12",		//	?				88	
	"?6",		//	?				89	
	"?7",		//	?				90	
	"?8",		//	?				91	
	"?9",		//	?				92	
	"?10",		//	?				93	
	"?11",		//	?				94	
	"?12",		//	?				95	
	"?13", 		//	?				96	
	"?14",		//					97	
	"?15",		//					98	
	"?16",		//					99	
	"?17",		//					100
	"?18",		//					101
	"?19",		//					102
	"?20",		//					103
	"?21",		//					104
	"?22",		//					105
	"?23",		//					106
	"?24",		//					107
	"?25",		//					108
	"?26",		//					109
	"?27",		//					110
	"?28",		//					111
	"?29",		//					112
	"?30",		//					113
	"?31",		//					114
	"?32",		//					115
	"?33",		//					116
	"?34",		//					117
	"?35",		//					118
	"?36",		//					119
	"?37",		//					120
	"?38",		//					121
	"?39",		//					122
	"?40",		//					123
	"?41",		//					124
	"?42",		//					125
	"?43",		//					126
	"?44",		//					127
	"?45",		//					128
	"?46",		//					129
	"?47",		//					130
	"?48",		//					131
	"?49",		//					132
	"?50",		//					133
	"?51",		//					134
	"?52",		//					135
	"?53",		//					136
	"?54",		//					137
	"?55",		//					138
	"?56",		//					139
	"?57",		//					140
	"?58",		//					141
	"?59",		//					142
	"?60",		//					143
	"?61",		//					144
	"?62",		//					145
	"?63",		//					146
	"?64",		//					147
	"?65",		//					148
	"?66",		//					149
	"?67",		//					150
	"?68",		//					151
	"?69",		//					152
	"?70",		//					153
	"?71",		//					154
	"?72",		//					155
	"kpEnt",	//					156
	"Rctrl",	//					157
	"?75",		//					158
	"?76",		//					159
	"?77",		//					160
	"?78",		//					161
	"?79",		//					162
	"?80",		//					163
	"?81",		//					164
	"?82",		//					165
	"?83",		//					166
	"?84",		//					167
	"?85",		//					168
	"?86",		//					169
	"",		//	SysReq				170 
	"?88",		//					171
	"?89",		//					172
	"?90",		//					173
	"?91",		//					174
	"?92",		//					175
	"?93",		//					176
	"?94",		//					177
	"?95",		//					178
	"?96",		//					179
	"?97",		//					180
	"kp/",		//					181
	"?99",		//					182
	"?100",		//					183
	"AltGr",	//					184
	"?102",		//					185
	"?103",		//					186
	"?104",		//					187
	"?105",		//					188
	"?106",		//					189
	"?107",		//					190
	"?108",		//					191
	"?109",		//					192
	"?110",		//					193
	"?111",		//					194
	"?112",		//					195
	"?113",		//					196
	"Break",	//					197
	"?115",		//					198
	"Home",		//					199
	"Up",		//					200
	"PgUp",		//					201
	"?119",		//					202
	"Left",		//					203
	"?121",		//					204
	"Right",	//					205
	"?123",		//					206
	"End",		//					207
	"Down",		//					208
	"PgDn",		//					209
	"Ins",		//					210
	"Del",		//					211
	"?129",		//					212
	"?130",		//					213
	"?131",		//					214
	"?132",		//					215
	"?133",		//					216
	"?134",		//					217
	"?135",		//					218
	"Lwin",		//					219
	"Rwin",		//					220
	"Start",	//					221
	"?139",		//					222
	"?140",		//					223
	"?141",		//					224
	"?142",		//					225
	"?143",		//					226
	"?144",		//					227
	"?145",		//					228
	"?146",		//					229
	"?147",		//					230
	"?148",		//					231
	"?149",		//					232
	"?150",		//					233
	"?151",		//					234
	"?152",		//					235
	"?153",		//					236
	"?154",		//					237
	"?155",		//					238
	"?156",		//					239
	"?157",		//					240
	"?158",		//					241
	"?159",		//					242
	"?160",		//					243
	"?161",		//					244
	"?162",		//					245
	"?163",		//					246
	"?164",		//					247
	"?165",		//					248
	"?166",		//					249
	"?167",		//					250
	"?168",		//					251
	"?169",		//					252
	"?170",		//					253
	"?171",		//					254
	"?172"		//					255
	};





This enumeration may or may not be of use to you. It gives names and
positions of codes

enum	KeyCodes
	{
	SC_ESC=0x01,SC_1,SC_2,SC_3,SC_4,SC_5,SC_6,SC_7,SC_8,SC_9,SC_0,SC_MINUS,
	SC_EQUAL,SC_BKSPC,SC_TAB,SC_Q,SC_W,SC_E,SC_R,SC_T,SC_Y,SC_U,SC_I,SC_O,
	SC_P,SC_LBRACE,SC_RBRACE,SC_RETURN,SC_LCTRL,SC_A,SC_S,SC_D,SC_F,SC_G,SC_H,
	SC_J,SC_K,SC_L,SC_SEMICOLON,SC_QUOTE,SC_BACKQUOTE,SC_LSHIFT,SC_BACKSLASH,
	SC_Z,SC_X,SC_C,SC_V,SC_B,SC_N,SC_M,SC_COMMA,SC_FULLSTOP,SC_SLASH,SC_RSHIFT,
	SC_NUMSTAR,SC_LALT,SC_SPACE,SC_CAPSLOCK,SC_F1,SC_F2,SC_F3,SC_F4,SC_F5,
	SC_F6,SC_F7,SC_F8,SC_F9,SC_F10,SC_NUMLOCK,SC_SCROLLLOCK,SC_NUM7,SC_NUMHOME=SC_NUM7,
	SC_NUM8,SC_NUMUP=SC_NUM8,SC_NUM9,SC_NUMPGUP=SC_NUM9,SC_NUMMINUS,SC_NUM4,
	SC_NUMLEFT=SC_NUM4,SC_NUM5,SC_NUM6,SC_NUMRIGHT=SC_NUM6,SC_NUMPLUS,
	SC_NUM1,SC_NUMEND=SC_NUM1,SC_NUM2,SC_NUMDOWN=SC_NUM2,SC_NUM3,SC_NUMPGDOWN=SC_NUM3,
	SC_NUM0,SC_NUMINS=SC_NUM0,SC_POINT,SC_NUMDEL=SC_POINT,SC_SYSREQ,SC_F11=0x57,
	SC_F12,SC_NUMENTER=0x9c,SC_RCTRL,SC_PRTSC=0xaa,SC_NUMDIVIDE=0xb5,SC_PRINTSCREEN=0xb7,
	SC_RALT,SC_PAUSE=0xc5,SC_BREAK,SC_HOME,SC_UP,SC_PGUP,SC_LEFT=0xcb,SC_RIGHT=0xcd,
	SC_END=0xcf,SC_DOWN,SC_PGDOWN,SC_INSERT,SC_DELETE,SC_MACRO=0xef};