home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / games / gi / gi.tag < prev    next >
Text File  |  1993-12-16  |  32KB  |  629 lines

  1. .*---------------------------------------------------------------------------
  2. .*
  3. .* TAG-File for GI-Documentation
  4. .*
  5. .* Version: 1.0
  6. .*
  7. .* Revision History:
  8. .*
  9. .*      18.11.93    RF  Created
  10. .*      16.12.93    RF  Ready for XMAS-Release
  11. .*---------------------------------------------------------------------------
  12. :userdoc.
  13. :title.GI-Documentation
  14. .*---------------------------------------------------------------------------
  15. .* ABSTRACT                                                         1000
  16. .*---------------------------------------------------------------------------
  17. :h1 x=right width=75% res=1000.Abstract
  18. :p.
  19. :hp2.Abstract:ehp2.
  20. :p.GI is a generic Interface between :link reftype=hd res=6000.Games:elink.
  21.  and :link reftype=hd res=5000.Input Devices:elink..
  22. :p.GI was designed to detach the task of getting and normalizing data from
  23. input devices from the task of programming a game.
  24. :p.The following picture may clarify this&colon.
  25. :cgraphic.
  26.  
  27.       GAMES                                 INPUT DEVICES
  28.  
  29.   ┌───────────────┐                          ┌──────────┐
  30.   │ Wizard of Wor │<─┐                   ┌─<─│ Keyboard │
  31.   └───────────────┘  │                   │   └──────────┘
  32.   ┌───────────────┐  │      ╔══════╗     │   ┌──────────┐
  33.   │ Boulder Dash  │<─┼──<───║  GI  ║<────┼─<─│ Joystick │
  34.   └───────────────┘  │      ╚══════╝     │   └──────────┘
  35.   ┌───────────────┐  │                   │   ┌──────────┐
  36.   │ Tron          │<─┤                   ├─<─│ Straight │
  37.   └───────────────┘  │                   │   └──────────┘
  38.                      │                   │
  39.         ...                                      ...
  40.  
  41. :ecgraphic.
  42. :p.:hp2.Therefore&colon.:ehp2.
  43. :ul.
  44. :li.An Input Device knows how to handle data from a device
  45. (eg. a Joystick or a keyboard).
  46. :li.A Game does not care what kind of Input Device the user prefers. It just
  47. queries GI for user input.
  48. :eul.
  49. :p.Or with other words&colon.
  50. :p.GI is a black box that hides all information about the user preferences of
  51. input devices from the game.
  52. .*---------------------------------------------------------------------------
  53. .* HIGHLIGHTS                                                       2000
  54. .*---------------------------------------------------------------------------
  55. :h1 x=center y=center width=60% height=60% res=2000 .Highlights
  56. :p.:hp2.Special Highlights of GI version 1.0:ehp2.
  57. :ul compact.
  58. :li.Interface for Games and Input Devices fully written in C
  59. :li.Source code is available
  60. :li.Sample code for both Games and Input Devices available
  61. :li.GI is configured once for all Games!
  62. :li.Possibility for per-Game configuration exists
  63. :li.Analog Input Devices can be used with Games requireing digital user input and vice versa (although this has not been tested yet...)
  64. :li.Up to 10 Players can play simultaneously!
  65. :eul.
  66. .*---------------------------------------------------------------------------
  67. .* INSTALLATION                                                     3000
  68. .*---------------------------------------------------------------------------
  69. :h1 x=right y=bottom width=75% height=100% res=3000 .Installation
  70. :p.:hp2.Installation:ehp2.
  71. :p.
  72. GI consists of two ZIP-Files:
  73. :ul compact.
  74. :li.GIRUN.ZIP (all files needed to :hp1.run:ehp1. GI)
  75. :li.GISRC.ZIP (:hp1.all:ehp1. source files for GI)
  76. :eul.
  77. :p.These two ZIP-Files are bound together in GI.ZIP (as you noticed...).
  78. If you just want to :hp1.use:ehp1. GI, you just unzip GIRUN.ZIP. It contains
  79. all modules required.
  80. :p.The GISRC.ZIP file contains :hp1.all:ehp1. the source code of GI! You
  81. don't need to unzip the TOOLS.ZIP, PMTOOLS.ZIP and STD.ZIP files if you don't
  82. recompile GI.
  83. :p.:hp2.Installation step by step:ehp2.
  84. :ol.
  85. :li.Create a directory named "GI". GI is used in more than one game, so this
  86. step makes sense even if you don't like it...
  87. :li.Copy GIRUN.ZIP to this directory and change (cd) to it.
  88. :li.Unzip GIRUN.ZIP.
  89. :li.Make sure the following files have been unzipped correctly&colon.
  90.     :ul compact.
  91.     :li.GI.DLL
  92.     :li.GICONFIG.EXE
  93.     :eul.
  94. :li.Edit your CONFIG.SYS file&colon.
  95.   :ol.
  96.   :li.Append the full drive and path name of the GI-directory to your LIBPATH-entry&colon.
  97.     :xmp.:hp4.LIBPATH=...;C&colon.&bsl.GI:ehp4.:exmp.
  98.     :p.Otherwise you'll have to put all the dynamic link libraries (*.DLL) of GI to a location already mentioned in your LIBPATH-entry.
  99.   :li.Add the following line to the end of your CONFIG.SYS&colon.
  100.     :xmp.:hp4.SET GICONFIG=C&colon.&bsl.GI&bsl.GICONFIG.DAT:ehp4.:exmp.
  101.     :p.(Assuming you installed GI in a directory "GI" on the C&colon. drive.)
  102.   :li.If you have a PC-Joystick, add the following line to your CONFIG.SYS&colon.
  103.     :xmp.:hp4.DEVICE=C&colon.&bsl.GI&bsl.GAMEPORT.SYS:ehp4.:exmp.
  104.     :p.(Again assuming you installed GI in C&colon.&bsl.GI.)
  105.   :eol.
  106. :li.Restart your system for the changes in CONFIG.SYS to take effect...
  107. :eol.
  108. :p.That's it. After the restart of your system you can continue by 
  109. :link reftype=hd res=4000.configuring:elink. GI.
  110. .*---------------------------------------------------------------------------
  111. .* CONFIGURATION                                                    4000
  112. .*---------------------------------------------------------------------------
  113. :h1 res=4000 .Configuration
  114. :p.:hp2.Configuration:ehp2.
  115. :p.GI knows two diffrent kinds of configurations&colon.
  116. :ol compact.
  117. :li.Global/Default configuration
  118. :li.Local configuration
  119. :eol.
  120. :p.:hp2.Basics:ehp2.
  121. :p.One of the base ideas behind GI was, that one configuration should be
  122. enough for all kind of games. To statisfy this criterion GI has a global
  123. configuration file (GICONFIG.DAT) that holds all information for the input
  124. devices. This file is located as mentioned in the
  125. :link reftype=hd res=3000.installation:elink. section.
  126. :p.But since the restriction to only one configuration may be too hard (imagine
  127. a game that uses really weird controls) the possibility for a local
  128. configuration was introduced. This local or per-game configuration works just
  129. the same way as the global configuration does. The only difference being that
  130. the configuration file for the local configuration is located in the directory
  131. of the game whereas the global configuration file resides in the GI directory.
  132. :p.:hp2.Configuration of GI:ehp2.
  133. :p.Configuration of GI and its input devices is done with the 
  134. :hp4.GICONFIG:ehp4. program. This program uses a standard OS/2 Presentation Manager
  135. interface. Configuration is performed in two steps&colon.
  136. :ol compact.
  137. :li.Select an input device from the list or define a new by pressing the
  138. :hp4.New Player:ehp4. button and selecting one from the list presented.
  139. (You'll have to select the proper directory first, of course...)
  140. :note.Currently available devices are&colon.STRAIGHT.DLL, KBD.DLL, JOY.DLL and
  141. TAPEDEV.DLL. See :link reftype=hd res=5300.Devices:elink. for further information.
  142. :li.Start the configure part of the selected device by pressing the
  143. :hp4.Define:ehp4. button or double-clicking in the list of devices.
  144. :eol.
  145. :note.Device 1 will be queryed for input to move player 1, device 2 for player 2, etc.!
  146. :p.:hp2.Special Hint when inserting new devices:ehp2.
  147. :p.When you hit the :hp4.New Player:ehp4. button and :hp1.no device in the list is
  148. highlighted:ehp1., the new device will be inserted at the :hp1.end:ehp1. of the list. If
  149. there is already a device highlighted, the new one will be inserted 
  150. :hp1.before:ehp1. the highlighted device!
  151. .*---------------------------------------------------------------------------
  152. .* DEVICES                                                          5000
  153. .*---------------------------------------------------------------------------
  154. :h1 x=center y=center width=60% height=75% res=5000 .Devices
  155. :p.:hp2.Devices:ehp2.
  156. :p.GI cannot work without input devices (see :link reftype=hd res=1000 .Abstract:elink.).
  157. The most important devices have already been realized and are part of this
  158. version of GI.
  159. :p.Since GI is meant to be a generic interface, everybody is encouraged to
  160. implement further devices. Detailed info in :link reftype=hd res=5200 .Writting a new Device:elink..
  161. :p.Prepared, but not implemented yet, is the possiblity to implement
  162. "intelligent" computer players. Such a computer player device would of course
  163. need further information about the rules and strucutres of a game. But for
  164. the game (and the game programer) the computer player would be fully
  165. transparent. The game would not be able to distinguish a human player from
  166. a computer player. This concept hat already been used in realizing the
  167. :link reftype=hd res=5700 .Tape Recorder:elink. device.
  168. .*----------
  169. :h2 width=100% height=100% res=5100 .Interface from GI to Devices
  170. :p.:hp2.Interface from GI to Devices:ehp2.
  171. :note.This section is for programers only.
  172. :p.Every device is placed in a dynamic link library that gets loaded and
  173. called by GI. Therefore all devices have the same interface to GI and
  174. use excatly the same mechanism for excanging data.
  175. :p.A device must suffice to the following requirements:
  176. :ul.
  177. :li.Must contain the functions _GetDataSize, _InitializeDLL, _Name,
  178. _ConfigDLL, _Threshold and _Direction with the parameters as specified
  179. below
  180. :li.Must be callable with std. C-calling conventions
  181. :eul.
  182. :p.The reason for these requirements being that GI comunicates with the
  183. device :hp1.only:ehp1. through these functions. Furtheron, the adresses of
  184. these functions are calculated using a call-by-name mechanism (that's why
  185. the names are very important).
  186. :p.:hp2.Required functions in a device:ehp2.
  187. :ul.
  188. :li.:hp2._GetDataSize (void)&colon.:ehp2.
  189. Returns the number of bytes required to hold all data, that the device
  190. needs to run (see :hp4.instance data:ehp4. below).
  191. :li.:hp2._InitializeDLL (char __far16 *id)&colon.:ehp2.
  192. When GI is initialized, the devices are initialized with this function. They
  193. receive a pointer to a piece of memory (id) as parameter. The piece of memory
  194. has the size returned by the _GetDataSize() function of the device.
  195. I recommend to have a flag :hp4.initialized:ehp4. in the instance data
  196. to detect, if the data area has already been initialized with default
  197. values or not.
  198. :li.:hp2._Name (char __far16 *mm)&colon.:ehp2.
  199. Copies the name of the device in ascii representation to the memory location (mm)
  200. specified by the parameter. This name is shown in the device-list in GICONFIG.
  201. :li.:hp2._ConfigDLL (char __far16 *id)&colon.:ehp2.
  202. Every device should have a configuration part. GI calls this part, when the
  203. user selects a device and presses the :hp4.Define...:ehp4. button. The
  204. configuration should have a Presentation Manager interface (like the included
  205. devices have). In the configuration part, the user may do all that is
  206. needed to use the device for playing afterwards (definitions, calibrations of
  207. the device, ...).
  208. :note.The selections and definitions that should be saved, must be placed in
  209. the instance data. GI will save this area for you!
  210. :li.:hp2._Threshold (char __far16 *id)&colon.:ehp2.
  211. This function is called to convert analog to digital values.
  212. :xmp.
  213. Example 1:
  214.     analog Joystick:     device returns value=0..100
  215.  
  216.     GI:                  if game wants analog values then
  217.                              return value
  218.                          else
  219.                              if value < threshold then
  220.                                  return 0
  221.                              else
  222.                                  return 1
  223.  
  224. Example 2:
  225.     (digital) Keyboard:  device returns value=0 or threshold
  226.  
  227.     GI:                  return value to game
  228. :exmp.
  229. :p.As you notice, the threshold value has a different meaning for analog and
  230. digital devices.
  231. :note.All devices return values in the range 0..100. Digital devices must
  232. return the threshold value instead of 1.
  233. :li.:hp2._Direction (char __far16 *id, char __far16 *pi)&colon.:ehp2.
  234. This function is called whenever the game wants the actual values from the
  235. device. :hp2.Parameters:ehp2. are&colon.
  236. :ul.
  237. :li.:hp4.id&colon.:ehp4. Pointer to the instance data.
  238. :li.:hp4.pi&colon.:ehp4. Pointer to the PLAYERINFO-structure given to GI
  239. by the game. The device fills the :hp4.direction[]:ehp4. field of this
  240. structure. GI calculates the :hp4.direction:ehp4., :hp4.diagonal:ehp4. and
  241. :hp4.buttons:ehp4. fields afterwards from the values found in the :hp4.direction[]:ehp4.
  242. array.
  243. :eul.
  244. :eul.
  245. :note.The leading underscore (_) is appended automatically, if you program
  246. in C or declare the functions :hp4.extern "C":ehp4. in C++.
  247. :p.:hp2.Instance data:ehp2.
  248. :p.The same device may be configured for more than one player (eg. two players
  249. playing on the same keyboard). GI creates a new instance for every configured
  250. use of the device (eg. different keys to move the figures). Therefore all
  251. configured data should be placed in the instance data. GI will keep track
  252. of saving and reloading the instance data for the devices. :hp4.Don't create
  253. any configuration files and don't use the Profile-functions of Presentation
  254. Manager since you cannot be sure that your device will run with PM present!:ehp4.
  255. Furtheron you should avoid using global variables even if you define your
  256. device to have single nonshared data areas. The reason being that your
  257. device may be loaded more than once within the same process and hence sees
  258. the same global data in all instances.
  259. :p.:link reftype=hd res=5200.Writting a new Device:elink.
  260. .*----------
  261. :h2 x=right y=center width=75% height=100% res=5200 .Writting a new Device
  262. :p.:hp2.Writting a new Device:ehp2.
  263. :p.:hp4.It's easy!:ehp4.
  264. :note.This section is for programers only.
  265. :p.I suggest you copy one of the existing devices (as close as possible to
  266. the one you want to implement) and modify it. Some modifications are needed
  267. if you don't use Borland C++. But in principle, it's very easy&colon.
  268. :ul compact.
  269. :li.Make sure you :hp4.#include <gi.h>:ehp4.
  270. :li.Define :hp1.all:ehp1. functions as desrcibed in :link reftype=hd res=5100.
  271. Interface from GI to device:elink.
  272. :li.Implement a minimul functionality and compile your module to a DLL.
  273. :li.Verify the correctness of the names with a library manager (if GI cannot
  274. find :hp1.all:ehp1. functions, it will refuse to load the devie).
  275. :li.Try loading your device in GICONFIG
  276. :li.Implement the full functionality of your device
  277. :li.Send your device to me for distribution in the next release! :hp4.This
  278. step is optional but strongly recomended!:ehp4.
  279. :eul.
  280. :p.
  281. :note.If you need to debug your device, you'll need to recompile all parts
  282. of GI. To do this you need the sources in TOOLS.ZIP also contained in this
  283. distribution. You may use the GIMAKE.CMD command file if you work with
  284. Borland C++.
  285. .*----------
  286. :h2 x=center y=center width=70% height=60% res=5300 .Supported Devices
  287. :p.:hp2.Supported Devices:ehp2.
  288. :p.Distributed with GI are some input devices. The source code for these
  289. is also contained in the GISRC.ZIP file.
  290. :p.Planned are devices for&colon.
  291. :ul compact.
  292. :li.Game-Demos (Intros, etc.)
  293. :li.Computer-Player
  294. :li.Mouse (?)
  295. :eul.
  296. :p.Refinement and enrichment of existing devices is also possible...
  297. .*----------
  298. :h3 x=center y=center width=50% height=50% res=5400 .Straight Auto-Player
  299. :p.:hp2.Straight Auto-Player:ehp2.
  300. :p.This device was designed to make debugging of games easier. It provides
  301. the possibility of an player walking always in the same direction (or
  302. standing still).
  303. :p.This device is also very usefull to fill the list of installed players...
  304. .*----------
  305. :h3 x=right y=bottom width=75% height=100% res=5500 .Joystick
  306. :p.:hp2.Joystick:ehp2.
  307. :p.There are two kinds of joystick available on the market&colon.
  308. :ul compact.
  309. :li.Digital Joysticks and
  310. :li.Analog Joysticks
  311. :eul.
  312. :p.The difference is very simple: Digital joysticks have (mostly) a
  313. mechanical switch for every of the 4 directions (North, East, South and West)
  314. and the fire-buttons. Analog joysticks have (mostly again) 2 variable resistors
  315. which are connected to the stick in a manner, that their resitance changes
  316. as the stick is moved in x- or y-direction. The actual value of these
  317. resistors gets sampled (10 times per second) and digitized by the game-port.
  318. To access the game-port under OS/2 the GAMEPORT.SYS driver must be
  319. :link reftype=hd res=3000.installed:elink..
  320. :note.Support for digital joystick is not yet implemented.
  321. :p.:hp2.Configuring the analog Joystick:ehp2.
  322. :p.The values of the resistors in a joystick vary from product to product.
  323. To calculate the exact values and scale of the joystick, the resitor values
  324. at the extremal points (upper left and lower right corner) must be taken.
  325. This is called calibration.
  326. :p.The calibration part of the joystick input device configuration can be
  327. activated by pressing the :hp4.Define Max.:ehp4.-button in the joystick configuration.
  328. :p.The joystick configuration dialog shows on the left side the analog
  329. behaviour of the joystick. If you move the stick, the tiny black point
  330. (should) change its position...
  331. :note.If the tiny point does not follow the movements of your joystick,
  332. :hp4.JOYSTICK.SYS:ehp4. may not be installed. Check :link reftype=hd res=3000.Installation:elink.
  333. :p.On the right side of the configuration dialog you see the digital
  334. representation of the analog values on the left. Depending on the selected
  335. threshold the checkboxes check with more or less movement of the stick.
  336. We recomend to experiment with the setting for the threshold because this
  337. is crucial for the behaviour in games requireing digital input!
  338. .*----------
  339. :h3 x=right y=bottom width=75% height=100% res=5600 .Keyboard
  340. :p.:hp2.Keyboard:ehp2.
  341. :p.The Keyboard Device works both in OS/2 Presentation Manager and OS/2 Full-
  342. Screen mode (ever tried to do this?). It intercepts all keyboard activities
  343. and checks wheter the actually pressed key (or combination of keys) matches
  344. any defined pattern.
  345. :p.:hp2.Configuration:ehp2.
  346. :ol compact.
  347. :li.Select the direction or button you want to define the key(combination) for.
  348. :li.Press the :hp4.DEFINE:ehp4. button
  349. :li.Press the :hp4.START:ehp4. button in the new dialog window
  350. :li.Hit the key(combination). The scan-values and state of the control-keys
  351. are displayed.
  352. :li.If you hit the correct key(combination) press the :hp4.STOP:ehp4. button
  353. :li.Hit the :hp4.TEST:ehp4. button and afterwards press your key(combination).
  354. If you hear a short beep, your key(combination) was accepted.
  355. :li.Hit the :hp4.OK:ehp4. button, your definition is completed.
  356. :li.Go back to point 1 if you want to define more directions or buttons.
  357. :eol.
  358. :note.An asterisk :hp4.*:ehp4. on the left of a direction or key signals that
  359. it has been defined.
  360. :warning.Define diferent keys for button 1 and button 2 since some games
  361. may distinguish between the buttons!
  362. :p.:hp2.Threshold:ehp2.
  363. :p.The Threshold slider comes to action, when the keyboard is used in a
  364. game requesting analog input. Since it is impossible to tell how strong a
  365. key is typed, the treshold value is used instead of 0 (key not pressed) and
  366. 1 (key pressed)...
  367. :p.
  368. :note.The Keyboard device is also used XFEEL and BUILDER.
  369. .*----------
  370. :h3 x=right y=bottom width=75% height=100% res=5700 .Tape Recorder
  371. :p.:hp2.Tape Recorder:ehp2.
  372. :p.The Tape Recorder consists of two parts&colon.
  373. :ul compact.
  374. :li.TAPEDEV.DLL&colon. input device for GI
  375. :li.TAPE.EXE&colon. Program to control the tape
  376. :eul.
  377. :p.The idea of the tape recorder is, that you can monitor and record
  378. input from any other device and play it back later. The concept may be
  379. known from keyboard-monitors that let you define and play back a series
  380. of keystrokes. The Tape Recorder works just this way: You start recording
  381. and play the game. All your movements get recorded. Later on you can
  382. play this session back.
  383. :p.:hp2.Stop on Overplay option:ehp2.
  384. :p.This feature lets you interrupt (better stop) the playing back of a
  385. recorded tape. Just let the tape run until you feel to take over. As soon
  386. as you move your device you will override the tape and stop its running.
  387. :note.This feature can be turned on and off in the Tape Recorder program.
  388. :p.:hp2.Configuring the Tape Recorder:ehp2.
  389. :ol compact.
  390. :li.Install a Tape Recorder Device (TAPEDEV.DLL) for the player you want to record
  391. :li.Configure the Tape Recorder device&colon. The port number must match
  392. the device you want to move your figure with.
  393. :li.Finish configuring GI
  394. :eol.
  395. :xmp.
  396. Say: You want to monitor player 1 in a game. Input comes from keyboard.
  397.  
  398. Then: You define the tape device a device number 1. The keyboard must also
  399. be defined (eg. number 3). Then you configure the tape devie to monitor
  400. port number 3.  OK?
  401. :exmp.
  402. :p.:hp2.Recording:ehp2.
  403. :ol compact.
  404. :li.Start the Tape Recorder program (TAPE.EXE)
  405. :li.Select a file with the :hp4.File...:ehp4.-button or enter a filename for the tape.
  406. :li.Start your game and make selections and other stuff you don't want to
  407. be recorded.
  408. :li.Switch back to the Tape Recorder and press the :hp4.RECORD:ehp4. button.
  409. :li.Switch to the game again and play. The Tape Recorder is now recording!
  410. :li.As soon as you like, switch back to the Tape Recorder and press the
  411. :hp4.STOP:ehp4. button. Your tape is ready!
  412. :eol.
  413. :p.:hp2.Playing back:ehp2.
  414. :ol compact.
  415. :li.Start the Tape Recorder program (TAPE.EXE), but only if it's not running...
  416. :li.Select the file to play back.
  417. :li.Start your game and move to the point your recording started.
  418. :li.Switch back to the Tape Recorder and press the :hp4.PLAY:ehp4. button. Your
  419. tape is running!
  420. :li.If the "Stop on Overplay" option is checked, you can stop the show
  421. with a single movement from your original device!
  422. :eol.
  423. :note.Play back will stop as soon as the end of the tape is reached.
  424. :p.:hp2.Concept of the Tape Recorder:ehp2.
  425. :p.Let's look at it from the point of view of a game.
  426. :p.The game wants user input. It calls GI with the number of the player.
  427. GI looks at its internal table, which device corresponds to the requested
  428. player. Then, GI requests the actual data from the device, normalizes it
  429. and returns it to the game.
  430. :p.Now the Tape Recorder consists of a Tape Device which can be called 
  431. from GI as any other device. But the Tape Device does not query any hardware.
  432. Instead it calls GI and queries the actual data for the player
  433. configured. In Record-mode the data is stored in a file and in Play-back-mode
  434. data is loaded from disk instead of querying GI for the original
  435. device.
  436. .*---------------------------------------------------------------------------
  437. .* GAMES                                                            6000
  438. .*---------------------------------------------------------------------------
  439. :h1 x=center y=center width=60% height=75% res=6000 .Games
  440. :p.:hp2.Games:ehp2.
  441. :p.All started with :link reftype=hd res=6400.Wizard of Wor:elink.. At a
  442. certain point in the process of developing the game, we had to decide how
  443. to get the user input to move the figures. Since we didn't have a :link reftype=hd res=5500.joystick:elink.
  444.  or any other input device than mouse and :link reftype=hd res=5600.keyboard:elink.
  445.  we "hard coded" the input-part of the game.
  446. :p.But of course we were not content with this kind of restriction. And after
  447. we released the game to public several people asked for joystick support. Now
  448. it would have been easy to simply add this part, but as we were already
  449. planing our next game (:link reftype=hd res=6500.Boulder Dash:elink.), a
  450. generic solution to this problem seemed more convenient...
  451. :p.:hp4.Since GI cannot exist without GAMES, we want to encourage everybody to
  452. adapt existing games or write new games using GI for the user input!:ehp4.
  453. .*----------
  454. :h2 x=right y=bottom width=75% height=100% res=6100 .Interface from Game to GI
  455. :p.:hp2.Interface from Game to GI:ehp2.
  456. :note.This section is for programers only.
  457. :p.:hp2.Requirements:ehp2.
  458. :p.The game must be programmed in a language that allows C-functions to
  459. be called. Therefore the library GI.LIB must be linked to the game that
  460. uses GI.
  461. :p.There are no problems if the game is written in C or C++, allmost any
  462. compiler should be OK...
  463. :note.GI.LIB contains just the definitions for the linker to know, that
  464. GI.DLL must be loaded to actually execute the GI-functions.
  465. :p.:hp2.Interface functions and data structures:ehp2.
  466. :p.There are only two functions and one data structure required for using
  467. GI in a game&colon.
  468. :ul compact.
  469. :li.PLAYERINFO-structure
  470. :li.GIInitialize()
  471. :li.GIGetDirection (PLAYERINFO *)
  472. :eul.
  473. The prototypings and definitions are in GI.H which must be included to
  474. import the functionality of GI.
  475. :p.:hp2.Meanings of data-members in PLAYERINFO-structure:ehp2.
  476. :lines.
  477. typedef struct _playerinfo
  478.     {
  479.     // Input Data
  480.     unsigned            player;         // Number of actual player
  481.     BOOL                analog;         // Game wants analog-values
  482.     int                 x;              // Actual position x (optional)
  483.     int                 y;              // Actual position y (optional)
  484.  
  485.     // Output Data
  486.     char                dir[6];         // Values of directions: Up, Right, Down, Left, B1, B2
  487.     char                direction;      // Strongest direction or DIRNONE
  488.     char                diagonal;       // 2nd strongest direction or DIRNONE
  489.     char                buttons;        // 2 bits for buttons
  490.  
  491.     // Strategy Data
  492.     unsigned            (*Move) (unsigned x, unsigned y);   // Callback to Game!
  493.     void                *stratdata;     // Data for Strategy-Instance
  494.     } PLAYERINFO, *PLAYERINFOP;
  495. :elines.
  496. :p.:hp2.player&colon.:ehp2. Zero-based number of player for which you want
  497. the actual direction and button values.
  498. :p.:hp2.analog&colon.:ehp2. TRUE if game wants analog values in the range
  499. of 0..100 for each of the four directions (see below). FALSE if game wants
  500. digital input (eg. player moves up, strenght not required).
  501. :p.:hp2.dir[6]&colon.:ehp2. Actual values of the queried device of the
  502. 4 directions and the 2 buttons.
  503. :p.:hp2.direction&colon.:ehp2. Strongest/main direction coded as mentioned
  504. below.
  505. :p.:hp2.diagonal&colon.:ehp2. Second strongest/secondary direction. If you
  506. don't care about diagonal moves, just ignore this field. Otherwise the
  507. actual direction is between :hp1.direction:ehp1. and :hp1.diagonal:ehp1.
  508. (direction=up, diagonal=left --> diagonal left up).
  509. :p.:hp2.buttons&colon.:ehp2. Binary representation of the states of the
  510. two buttons. If a button is pressed the corresponding bit is 1.
  511. :note. All other fields in :hp1.PLAYERINFO:ehp1. are not used yet!
  512. :p.:hp2.Coding of the directions:ehp2.
  513. :lines.
  514. #define DIRNONE     -1
  515. #define DIRUP       0
  516. #define DIRRIGHT    1
  517. #define DIRDOWN     2
  518. #define DIRLEFT     3
  519.  
  520. #define DIRBUT1     1
  521. #define DIRBUT2     2
  522. :elines.
  523. :p.The definitions of the four directions are as well the indices into the
  524. :hp1.direction[]:ehp1. array as the values of the :hp1.direction:ehp1. and
  525. :hp1.diagonal:ehp1. fields in PLAYERINFO.
  526. :p.:hp2.Consider the following example&colon.:ehp2.
  527. :xmp.
  528.     /* pi.player and pi.analog must be initialized ! */    
  529.  
  530.     if (GIGetDirection (&.pi))
  531.         {
  532.         /* A error occured, see errdef.h for further coments...
  533.         }
  534.     if (pi.buttons)
  535.         {
  536.         /* process buttons now.... */
  537.         }
  538.     if (pi.direction != DIRNONE)  /* or use: pi.dir[] .... */
  539.         {
  540.         /* process direction .... */
  541.         }
  542. :exmp.
  543. :warning.Don't forget to call :hp1.GIInitialize():ehp1. somwhere in the
  544. startup of your game!
  545. :p.:hp2.Comments:ehp2.
  546. :ul.
  547. :li.Typically, you allocate a PLAYERINFO-structure for every player your
  548. game will support.
  549. :li.The fields for :hp1.strategy:ehp1. functionality are not yet used, since
  550. I don't have a good concept for an example of such a strategy player yet...
  551. :li.The interface was designed to be as narrow as possible to make it
  552. easier to use.
  553. :eul.
  554. .*----------
  555. :h2 x=center y=center width=65% height=65% res=6300 .Games supporting GI
  556. :p.:hp2.Games supporting GI:ehp2.
  557. :p.The three games that we wrote up to now have two things in common:
  558. :ol compact.
  559. :li.They use GI for getting user input
  560. :li.Two players can play at the same time
  561. :eol.
  562. :p.We don't want to make the impression of being "Game-Freaks", but we
  563. like playing games and even more than that, we like to write programs.
  564. Not necessarly games, well noted. Games are the ideal trade off between
  565. writting good software and having some fun afterwards...
  566. :p.And by the way&colon. We also wanted to show that OS/2 is a good operating
  567. system!
  568. .*----------
  569. :h3 x=center y=center width=75% height=60% res=6400 .Wizard of Wor
  570. :p.:hp2.Wizard of Wor:ehp2.
  571. :p.Wizard of Wor is a port from an old C64 game. It was always one of my
  572. favourite&colon. simple but fascinating...
  573. :p.The OS/2-port was done in C++, all code rewritten. The pictures and 
  574. dungeons are the same as in the original (took us quite some time to
  575. capture all the figures...). Some differences occur in the speed-up during
  576. the game and the speed of Worluk and the Wizard.
  577. :p.Wizard of Wor is a real CPU-hog. One big problem was, that the maximal
  578. timer resolution of OS/2 (32ms) was far too slow. So we decided to do a
  579. busy-waiting. The mechanism of slowing the game down in a way that fast
  580. maschines are slowed more than slow maschines was invented by Markus and
  581. is unique (well sort of...).
  582. :note.Our highscore on the original C64 Wizard of Wor is at 194'800 points
  583. in two player mode!
  584. .*----------
  585. :h3 x=center y=center width=75% height=60% res=6500 .Boulder Dash
  586. :p.:hp2.Boulder Dash:ehp2.
  587. :p.An all time goodie. It exists on almost every game computer. This can
  588. be seen as a port of the AMIGA version of Boulder Dash. Most of the ideas
  589. for the special objects such as bombs, enemies, swamp, ..., were taken from
  590. there.
  591. :p.:hp2.For those how don't know Boulder Dash:ehp2.
  592. :p.You (and perhaps your friend) are lost in a system of underground caves.
  593. Your task is to collect the diamonds and enter in the house. You can not
  594. proceed to the next level until you completed the level...
  595. .*----------
  596. :h3 x=center y=center width=50% height=50% res=6600 .Tron
  597. :p.:hp2.Tron:ehp2.
  598. :p.Famous motion picture. A real must for all computer freaks. First movie
  599. with computer animated sequences (as far as I know).
  600. :p.The game was introduced in the film. Two players, both try to lock each
  601. other without crashing into the walls. This game is anything but perfect,
  602. many bugs still wait to be fixed...
  603. .*---------------------------------------------------------------------------
  604. .* ABOUT / Credits                                                  7000
  605. .*---------------------------------------------------------------------------
  606. :h1 x=center y=center width=60% height=80% res=7000 .About 'n Credits
  607. :p.:hp2.About 'n Credits:ehp2.
  608. :p.GI is free! Please use, extend, spread, ... GI as you like.
  609. :p.For further enhancments, comments, questions or bugs please send
  610. an email or a short note:
  611. :lines.
  612.             Roman Fischer
  613.             Leonhardstr. 12
  614.             CH-8001 Zuerich
  615.             Switzerland
  616.  
  617.             rofische@iiic.ethz.ch
  618. :elines.
  619. :p.
  620. :p.:hp2.Credits:ehp2.
  621. :p.Special thanks go to Markus Hof, who always helps me out of conceptual
  622. troubles and ported :hp1.Wizard of Wor:ehp1. to GI!
  623. :p.Credits to: Andre "Infid" Miodonski, ...
  624. :p.Thanks to Frank Ivan, ICA Systems Inc. for the joystick driver, which is included
  625. in the standard version of GI.
  626. .*---------------------------------------------------------------------------
  627. :euserdoc.
  628.  
  629.