-----BEGIN PGP SIGNED MESSAGE-----

                                JOYEMU v 3.3

                           by Simone Zanella, SZP

                (Based on an original utility by Pin Fei Sun)

INDEX


1   DISCLAIMER AND LEGAL STUFF
2   FILES IN THE PACKAGE
3   WHAT IS JOYEMU
4   CURRENT FEATURES (v3.3)
5   UPGRADING FROM VERSION 3.0
6   HOW TO USE JOYCP
7   HOW TO USE JOYEMU/JOYEM
8   TROUBLE SHOOTING
9   WHAT TO DO IF...
10  A NOTE FOR WINDOWS 95 USERS
11  COMPATIBILITY
12  HISTORY
13  CREDITS


1  DISCLAIMER AND LEGAL STUFF


This product comes with no warranty. It is freeware, but use it at your
own risk; the author takes no responsibilities of any sort related to
the use of this product.

Everyone that receives a FULL copy of this package (which includes this
file and the executables JOYCP, JOYEMU and JOYEM -- see section
"FILES IN THE PACKAGE") can freely install, duplicate and distribute the
package, as long as:
- - FULL, unmodified package is duplicated;
- - no additional fee is requested, apart from the cost of the media
  necessary for the copy;
- - the package is not distributed with other software or hardware.

Any WEB/FTP site can freely distribute this package as long as FULL,
unmodified package is downloadable in a single, compressed file (any
archiver will do).

The user acquire the right of using the package, but he can not alter,
disassemble or sell the software and the documentation that comes with it.

Simone Zanella retains intellectual property and copyright over the whole
package, shared with the original author (Pin Fei Sun) where applicable.

Written permission is required from Simone Zanella if you want to:
- - distribute this package together with other software;
- - include this package in a compilation of software;
- - bundle this package with any hardware device (especially joysticks,
  joypads and hardware interfaces).
The concept of 'written permission' applies also to digitally signed text,
i.e. a plain text that I'll send through e-mail, signed with my
private PGP key.

Simone Zanella reserves the right to charge money for releasing said
permission.

Inclusion of this package in shareware/freeware collections follows this
special policy: a written permission will be granted as soon as a full and
detailed list of the programs that will be distributed with this package
is received by Simone Zanella; the author of the collection is bound to
send a copy of the collection for which permission was granted to Simone
Zanella at the address written at the end of this document (CREDITS section)
or to another address stated in the permission as soon as the collection
becomes commercially available.

Any other form of distribution must be previously agreed upon with Simone
Zanella and requires a special, written license, which can be subject to
payment.

REMEMBER:

You may distribute this package only if this file (JOYEMU.TXT) is included
unmodified with the executables JOYCP, JOYEMU and JOYEM.

Under no circumstances you can charge money for this product, unless a
reasonable amount to cover copying and handling.

This package cannot be distributed with other software/hardware unless a
written permission for the distribution has been previously obtained from
Simone Zanella.


2  FILES IN THE PACKAGE


JOYCP.EXE                 Control panel for JOYEM/JOYEMU
JOYEMU.EXE                TSR for emulation (with hot keys)
JOYEM.EXE                 TSR for emulation (without hot keys)
CONVKS.EXE                KS file upgrader (3.0 -> 3.1-3.3)
JOYCP.ICO                 Icon for JOYCP (Windows 95/Windows 3.1)
JOYEMU.TXT                This file
FILE_ID.DIZ               Short package description


3  WHAT IS JOYEMU


JOYEMU and JOYEM are keyboard emulators for joysticks: they are two TSR
programs that let you use your joysticks with software that accepts only
keyboard input, or with those programs that have weak joystick support.

JOYEMU and JOYEM are essentially the same program, but JOYEM lacks hot keys
support. Hot keys let you change on the fly many parameters of the
emulation, but are not strictly necessary -- both JOYEMU and JOYEM accept
command line parameters to update the status of the resident emulator;
moreover, JOYCP can be used to change all the settings of TSR emulator.

JOYEMU and JOYEM can be easily uninstalled and reinstalled as needed
(read section "A NOTE FOR WINDOWS 95 USERS" to use the emulators with
Windows 95 native programs).

To configure the emulators for you system, JOYCP must be used.

JOYCP replaces the original utilities JOYSET and KEYSET, which are
no longer necessary.

JOYCP is by far more flexible than the older utilities; it can be used to:
- - calibrate your joystick(s) and define common emulation parameters such as
  the number of fire buttons, joystick sensibility and interface read mode;
- - define emulated keys (i.e. keys associated with joystick directions and
  fire buttons), autofire and repeat delay for each fire button and various
  other settings that depend on the application to run in foreground
  (hold mode, force break mode, shift mode, 8 way mode, sampling delay);
- - swap emulated keys between the two joysticks;
- - create separate configuration files and load them as needed;
- - update resident emulator with new settings.

Special care has been taken to ensure great compatibility and robustness;
both emulators could be cut down in size and made faster if I removed all
the checks and workarounds that I left to make them work on as many hardware
configurations as possible. Neverthless, it is possible that these programs
don't work on your system -- I'm sorry if they don't, but I really don't
know what else I could change to make them more compatible. If you have
troubles, read the TROUBLE SHOOTING section and, if you don't solve the
problem, try messing around with BIOS settings for the keyboard (but ONLY
if you know what you are doing!!).

JOYEMU and JOYEM are based on the original utilities written by Pin Fei Sun
(version 1.01); this version, however, is very different from the original
and add so many new features and controls that the code not even vaguely
remember the source written by Pin Fei.
This is not to say the original code wasn't noteworthy: it really helped
me in developing this package and was the spring that made me start this
project -- this is the reason why I kept the original name for the
emulator. I wish to thank once more Pin Fei for sharing his efforts with the
Internet community -- without him, you wouldn't be reading this notes.

JOYCP was written from scratch by me (Simone Zanella), to create a modern
interface both easy to use and pleasant to see.

JOYEMU takes up about 21K of memory while resident; JOYEM about 20K.


4  CURRENT FEATURES (v3.3)


* Up to TWO digital and/or analogue joysticks are supported (2 buttons)
* Support for joysticks with FOUR buttons
* Support for a single joystick with SIX buttons
* Capability of emulating all NORMAL AND EXTENDED keystrokes (arrow keys,
  Ctrl, Alt, Shift ..)
* Emulation of SHIFTED KEYS, i.e. keys combined with Ctrl, Alt, Shift
  (both left and right)
* TWO joystick reading modes (full or timed), to match your hardware
* AUTOFIRE AND REPEAT DELAY individually set for each fire button
* HOLD MODE setting, for games that require to hold directional keys
  instead of pressing and releasing them
* SHIFT MODE setting, to enter single keystrokes or allow shifted keys
* SELECTIVE KEY STUFFING: you can set to "none" the key stuffed by a
  certain direction/button (e.g. for games which don't require fire buttons)
* 8 WAY MODE to have different keys stuffed when joystick is moved in diagonal
  (instead of stuffing keys for the two directions)
* Two SEPARATE CONFIGURATION files: one keeps joystick calibration, number
  of buttons, sensibility and read mode (usually set once and for all);
  the other keeps key settings, sampling interval, force release mode, hold
  mode, shift mode and autofire settings, which are subject to change
  depending on the application to run
* Configuration files (JOYSET.JS and KEYSET.KS) are searched first in
  current directory and, if not found, in the DIRECTORY OF THE EMULATOR
* While JOYEMU IS RUNNING, through hot keys you can:
  - increase/decrease joystick sensibility
  - increase/decrease joystick sampling interval
  - switch 'force release mode' on/off
  - switch autofire on/off for each joystick
  - switch hold mode on/off
  - turn the emulation on and off
  - reload key settings from file in current directory
  - uninstall the emulator, if no other TSR was loaded on its top
* Support of COMMAND LINE PARAMETERS to:
  - print parameters list (both hot keys and command line parameters)
  - detect resident emulator (for batch processing)
  - uninstall TSR
  - set emulation on/off
  - reload key settings (from a file in current directory or from a specified
    file)
  - reload joystick settings (from a file in current directory or from a
    specified file)
  - set key associated with a direction/fire button
  - set hold mode for directional keys
  - set joystick sensibility to a specified value
  - set 'force release mode' on or off
  - set 'shift mode' on or off
  - set '8 way mode' on or off for each joystick
  - set autofire on/off and repeat delay for each button of every joystick
  - set sampling interval to a specified value
* Command line parameters can be used to INSTALL EMULATOR WITH SPECIFIED
  SETTINGS or UPDATE RESIDENT EMULATOR (same syntax)
* JOYEM, a version of JOYEMU without hot keys, is also provided, to better
  compatibility and speed up keyboard response
* Errors and confirmations signaled through different sounds from INTERNAL
  SPEAKER
* JOYEMU/JOYEM can be easily UNINSTALLED, freeing up its memory
* Greatly improved COMPATIBILITY AND ROBUSTNESS
* Works under DOS (real mode) and WINDOWS 95; Windows 3.1 is untested
* JOYCP, a control panel for both emulators, let you change ALL the parameters
  for resident emulator, create and manage configuration files, uninstall
  the emulator, swap key settings, all through an intuitive interface with
  repositionable windows that allows the use of both mouse and keyboard

Configuration files (".JS" and ".KS) are compatible with those created
with version 3.1; for previous versions, run JOYCP to recreate them for each
configured application.

JOYSET.JS and KEYSET.KS must exist in current directory or in the same
directory of the emulator when it is installed; KEYSET.KS must be located in
the current directory or in JOYEMU's directory when you press Shift-F8 to
change emulated keys. Both configuration files are created by JOYCP
(read on for further informations).


5  UPGRADING FROM VERSION 3.0


'.JS' configuration files for version 3.0 are compatible with version 3.3;
'.KS' files for version 3.0 must be converted with CONVKS for use under
version 3.3. CONVKS is useful only to users of JoyEmu 3.0.

CONVKS takes a single parameter: the name of a '.KS' file in version 3.0
format; it upgrades in place the file to version 3.1-3.3, i.e. the old file
is overwritten with the new configuration. CONVKS checks that the file is
actually in 3.0 format before upgrading; files already in 3.3 format or files
in 2.0 format are left unchanged and a warning message is issued.

The difference between 3.0 and 3.1-3.3 format lies in the new 8 way mode that
requires 4 additional key bindings for each joystick and the new configura-
tion flag that keeps diagonal mode status. Converted configuration files
have 8 way mode deactivated and all diagonal keys set to 'none' by default.


6  HOW TO USE JOYCP


Type JOYCP to setup emulation parameters.

JOYCP is structured in various menus; at any time, just one menu is
active and its window can be positioned anywhere on the screen by clicking
on the frame, moving the mouse and releasing the button; JOYCP remembers
the position for each window between different sessions; for this reason,
it modifies its executable (be aware of this if you use antivirus packages
that check file integrity by calculating CRCs on executables).
You can move the windows also by using arrow keys combined with Ctrl.

These are the keys recognized:
- - enter, space, right: select option;
- - up/down: change option;
- - esc, left: previous menu;
- - home, end, pag up, pag down: navigate the menu.

You can select an option also by clicking on it with the mouse or by pressing
highlighted letter; unselectable options are automatically grayed out,
reflecting your selections and TSR status. Right mouse button does the same
as the Esc key.
When an option is highlighted, a one-line help text is printed on the
bottom of the screen that explains what the option means/does.

JOYCP's main menu has 5 submenus:
- - Joy settings: for calibrating joystick(s), setting read mode, sensibility
  and number of fire buttons;
- - Key settings: for setting keyboard mode, emulated keys, autofire settings,
  sampling delay, shift mode and 8 way mode;
- - TSR settings: to force detection of resident emulators and connected
  joysticks, switch emulation and autofire on/off and uninstall TSR;
- - Configuration: for switching on/off auto-detection of JoyEm/JoyEmu on
  startup, change path to emulators and initial path for configuration
  files, switch auto update mode on/off;
- - Exit: to return to Dos (same as pressing Esc).

On startup, JOYCP will search JOYEM and JOYEMU in the Dos path and in its
directory, and warn you if it cannot find them. JOYEM and JOYEMU must be
reachable to let JOYCP determine the presence in memory of the emulator.


The "Configuration.." submenu is used to specify default paths and TSR
detection on startup.

If you want to keep JOYEM/JOYEMU in a separate directory, change "Executables
path..".

Upon start, if an emulator is resident, JOYCP will load its configuration
and set menus accordingly; if it isn't, JOYCP will search default configuration
files (JOYSET.JS and KEYSET.KS) following this order:
1) JOYCP directory;
2) current directory, or directory specified as "Config files path..".
If no file is found or loading fails (files corrupted or not accessible),
JOYCP set parameters to default values.

Every time you have to enter a path or a pathname, a window pops up and
these keys are active:
- - left/right: navigate string;
- - enter: confirm string;
- - esc: abort editing;
- - tab: self-complete name (Unix like);
- - backspace/delete: delete previous/current character;
- - home: beginning of string;
- - end: end of string;
- - ins: switch between insert/overwrite mode;
- - mouse: reposition cursor.

To avoid detecting resident emulators on startup, in the same menu you can
turn off "Check JoyEm" or "Check JoyEmu".

The "Auto update" option is very useful if you keep the emulator resident
and change on the fly parameters as needed; when auto update is on, as soon
as you change the value of each parameter the resident emulator is updated
accordingly. Because of program design, ALL parameters of the same group
are actually updated, that is: all joystick settings, all key settings or
all TSR settings, depending on the position of modified parameter in the
menu tree.

With the last option ("Config files path..") you can enter the initial path
for configuration files: this is the path in which ".JS" and ".KS" files are
saved/loaded, if not changed explicitly.


The "Joy settings.." submenu must be used to calibrate joystick(s).

Before running the calibration, you must choose if you want to adopt the
timed or full reading mode for joysticks. Timed reading is the default --
you should switch to full reading ONLY if you have a very fast machine AND
you experience directional lock-ups. If you change reading mode, you must
recalibrate the joysticks; you will not be able to save/update TSR until
all joysticks detected are calibrated with the SAME reading mode.
Auto-update takes place ONLY when joystick(s) are calibrated and reading
mode is set to the same value under which joystick(s) were calibrated.

For each joystick you can set:
- - status: enabled/disabled; when disabled, joystick will not be read during
  emulation;
- - fire buttons: 2, 4 or 6 for first joystick, 2 or 4 for second joystick;
  select 2 even if the joystick has just one fire button; if you select 6-
  buttons mode, the options for the second joystick will be disabled;
- - sensibility: from 2 to 7; 2 is VERY hard and 7 is VERY sensible:
  typical values are 5 for a digital joystick and 3 or 4 for an analogue one.

The calibration is very simple: for each joystick, center the stick and press
fire button 1 or 2; then, move the stick to upper left and press fire; at
last, move the stick to lower right and confirm with fire.
For 6 buttons joysticks, there's an additional procedure: you will be asked
to press fire button 5 together with 3 or 4 and then fire button 6 with 3 or
4; this is necessary since fire buttons 5 and 6 are connected to direction
lines for the second joystick, which do not return digital (0-1) values.
If TSR emulation is active, you won't be able to calibrate joysticks until
emulation is turned off: see "TSR settings.." submenu.

As a rule of thumb, select timed reading mode, 2 buttons and enter 5
for sensibility.

The option "Change directory.." can be used to change the path for ".JS"
files for the current session.

Use:
- - "Load settings..", to load joystick calibration from a saved file;
- - "Save settings..", to save current joystick configuration to disk;
- - "Import from TSR", to update menu values from TSR settings;
- - "Update TSR", to update TSR settings from current menu values.


The "Key settings.." submenu is used to setup keys for emulation.

"Sampling delay" let you enter sampling interval for joystick readings;
a value of 0 means continuous probing; higher values (2, 3) helps in a few
games which are VERY time critical; you should probably leave this value
to 0 if you have a fast machine or if you don't experience slow downs during
emulation. Higher values COULD help if you have a slow machine.
Sampling interval can also be changed while JOYEMU is running by using
Shift-F3 (increase) or Ctrl-F3 (decrease), or updated by running JOYEMU with
parameter S (read on).

There are three switches that control how keys are stuffed during emulation:

- - "Hold mode": if you activate hold mode, when you push the stick in a
  direction the associated key will be pressed and when you re-center the
  stick it will be released; if hold mode is off, as long as you keep the
  joystick off center the corresponding key will be stuffed to the keyboard
  buffer. This setting depends on how the user is supposed to enter data in
  the application in foreground; if you experience slow downs, activating
  hold mode could solve the problem; the default should be hold mode ON -
  use Shift-F7 in JOYEMU to switch hold mode on/off;

- - "Force break": this switch determines if JOYEMU should force release before
  each keypress; forcing release is more compatible, but since a higher number
  of scan codes is stuffed to the keyboard buffer it COULD slow down the
  emulation on slower machines; this setting depends heavily on your
  particular hardware; the default should be force release mode ON -
  use Shift-F4 in JOYEMU to switch force release mode on/off;

- - "Shift mode": when shift mode is on, if configured keys are actually
  combinations of a key with shift keys (alt, ctrl, shift) these other
  keys are also stuffed to keyboard buffer; if shift mode is off, only
  single keys are stuffed - you should turn off shift mode if key combinations
  are not needed.

For each joystick there is a separate submenu that let you select keys to be
emulated and autofire settings; there are 4 directions (+ 4 diagonals) and 4
or 6 fire buttons to be configured (read on to understand why).

You can set directions and buttons even for joysticks not connected: it
doesn't matter, since keys configured for non-existent devices are simply
ignored during emulation.

IMPORTANT! If you don't want to stuff any key at all for a certain button/
direction, select the option with the SPACE BAR, that is:
- - move selection bar to highlight desired direction or button;
- - press the space bar.
If you select the option with return, right arrow or left mouse button,
you will set the key to be stuffed as usual, by pressing any key on the
keyboard (the key can be the space bar as well).

All keys are supported: shift keys (Shift, Ctrl, Alt), as well as other
special keys (as CapsLock and NumLock) and key combinations with shift keys
(ctrl, alt, shift).

If your joystick has 6 fire buttons, remember to set this parameter in the
joy settings menu, before entering the key settings; thus, the menu will
change to include the two additional fire buttons (both for assigned key and
autofire rate).

NOTE: the key assignments for fire buttons 5 and 6 are stored in place of key
assignments for the buttons 1 and 2 of the second joystick; this is done
both to spare memory and because one 6-buttons joystick uses all the lines
available in the joystick interface, so you cannot connect any other device.

The "Diagonals.." submenu let you (de)activate 8 way mode and set keys to be
stuffed for diagonals. When 8 way mode is on, you can stuff different keys
for, say, up, left and up + left; if 8 way mode is off, a diagonal is
translated as two keypresses, corresponding to the two directions.

In the "Autofire rate.." submenu, for each button enter 0 for repeat delay if
you don't want autofire (default), or a value between 1 and 18.
Lower values (except 0) mean faster repetition, since these numbers refer to
the repeat delay, that is the number of joystick pollings after which a
keypress is generated if a fire button is held down.
If 'force break' is active, settings should be >= 2, since 1 = 2 (one delay
state is necessary for releasing the button); in this mode, at most 9 keys per
second are stuffed in the buffer.
Use Shift-F5 and Shift-F6 to turn on/off autofire for ALL buttons of joystick
1 or 2, respectively.

Important: SET ALL REPEAT DELAYS TO 0 TO SPEED UP EMULATION.

The option "Swap buttons 1 and 2" let you exchange keys bound to fire 1 and 2;
this is usually quicker than re-selecting keys and can be useful if the buttons
on the joystick are in different positions.

The option "Swap key bindings" exchange all keys, autofire rates, diagonal
and 8 way mode settings between joystick 1 and 2; this is useful if you have
two different joysticks and want to try which is best without desconnecting
cables. If you have just one joystick, this option can be used to have two
full configurations on line, which can be swapped as needed.

As a rule of thumb, enter 0 for sampling interval, activate hold mode and
force break and de-activate shift mode and 8 way mode.

You might ask why up to 6 buttons are requested for each joystick; the
reason is that there are PC controllers available that have more than 2 fire
buttons; buttons 3 and 4 use the lines in the interface for buttons on the
other joystick, buttons 5 and 6 use direction lines for the second joystick.
If you are going to connect two joysticks via a Y-adapter, you will probably
use traditional models with two buttons.

Note that if you change sampling interval you will probably want to change
also autofire settings, since now the key generation subsystem is invoked
less frequently.

The option "Change directory.." can be used to change the path for ".KS"
files for the current session.

Use:
- - "Load settings..", to load key configuration from a saved file;
- - "Save settings..", to save current key configuration to disk;
- - "Import from TSR", to update menu values from TSR settings;
- - "Update TSR", to update TSR settings from current menu values.


The "TSR settings.." submenu is used to change general TSR switches and to
manually detect emulator in memory (if "Check JoyEm" and "Check JoyEmu"
options are turned off in "Configuration.." menu), or to detect currently
connected joysticks if you have disconnected/reconnected devices.

Use:
- - "Force detection", to check for JOYEM/JOYEMU in memory and to detect
  connected joysticks;
- - "Autofire x", to switch on/off autofire for all buttons of joystick x;
- - "Emulation", to (de)activate keyboard emulation;
- - "Import from TSR", to update menu values from TSR settings;
- - "Update TSR", to update TSR settings from current menu values;
- - "Uninstall TSR", to remove from memory resident emulator.


JOYCP has also a special 'query mode' which is activated when you run
the program with '?' as the only parameter:

  JOYCP ?

While in this mode, JOYCP displays a 6 digit hexadecimal number for each key
pressed; this number can be used in the E parameter of JOYEMU/JOYEM (read on
for further details) to set the key emulated by a certain direction or a
fire button; press Esc to return to Dos.


7  HOW TO USE JOYEMU/JOYEM


Type JOYEMU to install the emulator in memory - hot keys available once
installed are:

 Shift-F1    increase sensibility for joystick 1
 Shift-F2    increase sensibility for joystick 2
 Ctrl -F1    decrease sensibility for joystick 1
 Ctrl -F2    decrease sensibility for joystick 2
 Shift-F3    increase sampling interval
 Ctrl -F3    decrease sampling interval
 Shift-F4    switch 'force release mode' on/off
 Shift-F5    switch autofire on/off for joystick 1
 Shift-F6    switch autofire on/off for joystick 2
 Shift-F7    switch 'hold mode' for directional keys on or off
 Shift-F8    reload keystrokes to emulate from the file KEYSET.KS
             (which must reside in the current directory or in
             JOYEMU's directory)
 Shift-F9    turn on/off the emulation
 Shift-F10   unload JOYEMU from memory; this is possible ONLY IF
             no other TSR was loaded on the top of it

It is a good idea to use these keys ONLY on Dos command line and not while an
application is running. Moreover, keys Shift-F10 and Shift-F8 are disabled
during Dos internal operations so if they don't work the first time keep
pressing them.

JOYEMU sounds the internal speaker to inform the user if requested operation
was completed successfully or not: you will easily distinguish an error beep
(lower) from a confirmation beep (brighter). If command line parameters are
used to change settings, only errors are acoustically signaled.

It is possibile to change parameters of resident JOYEMU by running JOYEMU
with the following command line options:

JOYEMU [ ?[1|2] | D | U | [K[filename]] [J[filename]] [+] [-] [Sjx] [Ix] [F[-]]
                          [H[-]] [T[-]] [Xj[-]] [Rjbx] [Aj[-]] [Ejbk] ]

?     display a summary of command line parameters; for JoyEmu, ?1 or ?
      print a list of command line parameters, ?2 print the hot keys available

D     exit setting errorlevel to 0 if emulator is NOT installed

U     unload resident JOYEMU

K     have resident JOYEMU load key settings from KEYSET.KS;
      if a pathname is present after K, settings are loaded from
      specified file

J     have resident JOYEMU load joy settings from JOYSET.JS;
      if a pathname is present after J, settings are loaded from
      specified file

+/-   enable keyboard emulation/disable keyboard emulation, but keeps JOYEMU
      in memory (use U to remove it)

Sjx   set joystick sensibility for joystick j (1 or 2) to x, which must be
      between 2 and 7

Ix    set sampling interval to x; x can be between 0 and 9

F     switch on 'force release mode'; if 'F-', switch it off

H     switch on 'hold mode'; if 'H-', switch it off

T     switch on 'shift mode'; if 'T-', switch it off

Xj[-] switch on (or off, if '-') 8 way mode for joystick j (1-2)

Rjbx  set repeat delay for joystick j (1 or 2) and button b (1 to 4)
      to x, which can be 0 (no autofire) or 1-18, where 1 is fast repeat
      and 18 is slow repeat

Aj    switch autofire on for joystick j (1 or 2); if 'Aj-', switch it off

Ejbk  set key emulated by joystick j (1 or 2) and button b to key k, which is
      a 6 digit hexadecimal number (AKA "magic number") that can be found by
      using 'JOYCP ?'. Warning! Magic numbers have changed from version 2.0!
      The following table shows values for b:

                                  9  6  B
                                    \|/
                       Joystick:  5 -O- 7    Fire buttons:  1 2 3 4
                                    /|\
                                  A  8  C

      In 6-buttons mode, fire buttons 5 and 6 are set as fire buttons 1 and 2
      for the second joystick, that is:

                       Button 5:   E21k
                       Button 6:   E22k

If JOYEMU is not in memory and parameters are specified (except '?', 'D' and
'U'), then JOYEMU goes resident and change settings according to parameters
specified.

e.g.   JOYEMU -             Install JOYEMU with emulation off,
                            or turn off emulation for resident emulator

       JOYEMU KMYKEYS.KS    Install JOYEMU with specified key settings,
                            or set emulated keys for resident emulator

       JOYEMU H F T-        Install JOYEMU with specified switches,
                            or change settings for resident emulator

Pay attention to the syntax of each parameter; the internal command
line interpreter should be safe, but it does not perform many checks (since
the code had to be very tight to save memory).

Remember that by reloading key configuration (Shift-F8 in JOYEMU, command
line parameter K in both JOYEM and JOYEMU) you will also set sampling
interval, force release mode, hold mode, shift mode, 8 way mode, diagonal and
autofire settings to the respective values stored in the configuration file.

JOYEM works exactly as JOYEMU, but it lacks hot keys support.
However, it has a few advantages:
- - the keyboard response is faster, since the handler does not search for
  hot keys at each keypress;
- - it uses less memory;
- - it can be used to avoid troubles with programs in which the hot keys
  have a special meaning or are used to enter data.
Command line parameters works exactly as in JOYEMU.

You must use JOYEM to update a resident JOYEM and JOYEMU to update a resident
JOYEMU; you can NOT set resident JOYEM with JOYEMU and vice-versa.


8  TROUBLE SHOOTING


NEVER disconnect a joystick while the emulator is in memory and is active;
this would lead to a continuous stream of keys stuffed into keyboard buffer,
that would prevent the use of the PC; in this case, always disable emulation
(by Shift-F9 or parameter -) or unload emulator (by Shift-F10 or parameter U)
before operating.
Moreover, disconnecting hardware while your PC is powered on is not very
healthy for both the attached device and your computer.

If you want to change on the fly the joysticks connected, there are several
ways of doing it; this is the suggested method -- replace JOYEMU with JOYEM
if you prefer using the version without the hot keys:

  AFTER THE EMULATOR IS INSTALLED IN MEMORY:

  1)  use:

      JOYEMU -

      to momentarily turn off emulation;

  2)  disconnect and reconnect joystick(s) as needed;

  3a) calibrate joystick(s) through JOYCP;

  3b) if you prefer, you can calibrate them once and for all and save
      configuration to MYJOY2.JS, for example;

  4)  now update resident emulator with the new configuration and turn on
      emulation; example is given for user selected configuration:

      JOYEMU JMYJOY2.JS +

      Always put '+' as the last parameter!

If you disconnect/reconnect your joysticks very frequently, you can automate
this sequence by writing a batch file.

Of course, the same operation can be accomplished entirely through JOYCP:

  1)  select "TSR settings..";
      switch off "Emulation" and select "Update TSR";

  2)  disconnect and reconnect joystick(s) as needed;

  3a) select "Joy settings.." and calibrate joysticks as needed;

  3b) if you prefer, you can calibrate them once and for all and save
      configuration to MYJOY2.JS, for example;

  4)  select "Update TSR" in the "Joy settings" submenu;
      select "TSR settings.."; switch on "Emulation" and select "Update TSR".

You don't need to "Update TSR" if "Auto update" is on.
Remember that repeat delay for autofire is directly connected to sampling
interval; if you increase sampling interval, you might want to decrease
repeat delay and vice-versa. That's because repeat delay should be interpreted
as 'NUMBER OF JOYSTICK POLLINGS after which a fire key should be stuffed in
the keyboard buffer while joystick fire button is kept pressed'.

Many programs (especially games) chain the keyboard handler to get faster
response and to filter unwanted keys; while these programs are running,
JOYEMU hot keys may not be accessible. Moreover, it is safer to use the hot
keys on Dos command line.

You can't uninstall JOYEMU/JOYEM if one or more TSR programs have been
installed after it; unload the other TSRs in reverse order of installation,
then uninstall the emulator.


9  WHAT TO DO IF...


- - joystick readings seem uncorrect:
+ try activating full read mode;

- - autofire does not work correctly or you get directional lock-ups:
+ turn on force release mode; to speed up key stuffing (up to 18 keypresses
  per second), turn off force release mode;

- - a game seems to run too slowly when the emulator is resident:
+ try setting sampling interval to higher values (2, 3) or
  switching on 'hold mode'; disable full read mode; set all repeat delays to 0;

- - game reaction to joystick movements seems too slow:
+ try setting sampling interval to lower values (1 or 2) or switch off
  'hold mode'; turning off force release mode and disabling full read mode
  could also help;

- - game action is not fluid:
+ try switching on 'hold mode' and/or disabling full read mode;

- - sometimes, a direction key is stuffed without moving the joystick:
+ try decreasing joystick sensibility (Ctrl-F1/F2 or parameter S);

- - you need to stuff different keys for diagonals:
+ in the "Key settings" menu, select "Keys joystick x.." and then
  "Diagonals.."; activate 8 way mode and select keys to be stuffed;

- - you are using an analogue joystick and you must push the stick too far from
  the center for JOYEMU/JOYEM to stuff direction key:
+ increase joystick sensibility (Shift-F1/F2 or parameter S);

- - the application in foreground uses the hot keys of JOYEMU as standard keys
  for entering data:
+ use JOYEM instead of JOYEMU;

- - you want to use the emulator with programs that have weak joystick support:
+ disable joystick support in these programs; you will probably use a
  command line switch or there will be an option for doing this; if you
  don't, you could get unexpected results or even lock-ups.


10  A NOTE FOR WINDOWS 95 USERS


To use JOYEM/JOYEMU for Windows 95 NATIVE programs, you MUST load the emulator
before you load Windows 95, i.e. put it in your AUTOEXEC.BAT; a good position
for JOYEM/JOYEMU is as the FIRST command in AUTOEXEC file. Then, you can use
JOYCP to update parameters of resident emulator; an icon is supplied if you
want to make a shortcut for it, but you can also open a Dos box and run JOYCP
from there to update the TSR program.

It has been reported that sometimes, after using JOYEM/JOYEMU in a Dos prompt
(that is: opening a Dos prompt; installing the emulator; running an app;
closing the Dos prompt) system returns in an odd status: a shift key (Alt,
Ctrl, Shift) seems to be always pressed.
To restore normal operation, press together CTRL and ALT on the left side of
the keyboard and press and release the shift-type key (ctrl, alt, left and
right shift) that seems pressed.

This is caused by the fact that JOYEM/JOYEMU has stuffed make codes for these
keys but no corresponding break code, so the BIOS presumes that these keys
are still pressed.


11  COMPATIBILITY


How much compatible is JOYEMU with games and other programs?

The answer is: VERY compatible.

If JOYEMU works with your hardware, you will find that almost EVERY program
works with it; you might need a little 'fine tuning' of the options requested
by JOYCP, though, so make sure to read carefully the sections 'HOW TO USE
JOYCP' and 'WHAT TO DO IF...'.

Actually, I've only found a couple of programs that refuse to work with
JoyEmu/JoyEm, and both use a weird method of reading keyboard.

JOYEMU was especially tested with DOZENS of arcade and console
emulators, since these programs are often developed without joystick support.
Moreover, I found that most of these programs worked BETTER if I disabled
their native joystick support and used JOYEMU to play.

Of course, even if I tried JOYEMU/JOYEM with a LOT of software, there may be
programs that refuse to operate while it is installed; if you find such a
program, just let me know.

JOYEM/JOYEMU is written in C and inline Assembly; though I paid special care
to optimize time critical parts, I can't be sure that it will work well on
smaller systems; presumably, you will need at least a Pentium 75 to achieve
a reasonable speed -- try it and let me know the results.


12  HISTORY


All versions from 2.0 upward were written by Simone Zanella, SZP.

Changes from v1.01:

KEYSET:
  * rewritten from scratch
  * now supports Alt, Ctrl and Shift on their own
  * display scan codes of keys pressed
  * added key configuration for second joystick
  * added sampling interval setting
  * added 'force release mode' setting
  * added 'hold mode' setting
  * added autofire setting
  * added displaying of scan and ASCII codes of keys pressed
  * added query mode, for parameter E of JOYEM/JOYEMU

JOYSET:
  * rewritten to work with analogue joysticks
  * added calibration for second joystick
  * added read mode setting
  * added 4 buttons/2 buttons mode
  * added sensibility setting

JOYEMU:
  * rewritten to better stability and add new features
  * changed keyboard handler for faster response
  * provided in two versions, with or without hot keys, for greater
    compatibility and faster keyboard response
  * emulates now both joysticks, if present
  * corrected function to reload key configuration while the emulator
    is resident (now WORKS)
  * added function to reload joystick configuration while the emulator
    is resident
  * corrected the auto-fire-every-30-minutes bug
  * added support for shift keys
  * added autofire and repeat delay for each fire button
  * added hold mode setting for directional keys
  * removed unnecessary break codes sent during emulation
  * added research of configuration files in the directory of the emulator,
    if not found in current directory
  * added keys to increase/decrease joystick(s) sensibility while JOYEMU is
    resident
  * added keys to increase/decrease sampling interval while JOYEMU is
    resident
  * added a new mode of reading joystick, user selectable
  * added a key to switch 'force release mode' on/off
  * added a key to switch 'hold mode' on/off
  * added keys to switch autofire on/off
  * added a key and corresponding code to unload the emulator from memory
  * added sound, to signal user the result of operations
  * added command line options to have resident emulator:
    - uninstall itself from memory
    - switch emulation on/off
    - reload key settings (even from a specified file)
    - change joystick sensibility
    - change sampling interval
    - set 'force release mode' on/off
    - set 'hold mode' on/off
    - set autofire on/off and repeat delay
    - set key associated to a direction/fire button
  * changed CFG files format and names

Changes from v2.0:

JOYEM/JOYEMU:
  * rewritten key stuffer for compatibility under pure Dos (1st layer)
  * perfectioned directional key stuffer (2nd layer)
  * added command line parameter '?' to display help text
  * deleted description of hot keys, which was printed when going TSR
  * added D parameter for JoyCP and batch processing
  * added ability to install emulator with specified CL parameters
  * corrected code for two joysticks
  * added support for shifted keys
  * changed parameter E according to new magic numbers
  * changed CFG files format and names

JOYSET/KEYSET:
  * removed from the package; they are superseded by JOYCP

JOYCP:
  * first release of the control panel for JOYEM/JOYEMU
    (LOT of work!)

Changes from v3.0:

JOYEM/JOYEMU:
  * support for selective key stuffing (don't stuff keys for certain
    directions/buttons, as configured by JoyCP)
  * added "8 way mode" (stuff different keys for diagonals)
  * added command line parameter 'X', to switch "8 way mode" on or off for
    each joystick
  * modified E parameter to accept setting of diagonal keys
  * added second help page (only for JoyEmu)
  * modified ? parameter syntax to accept help page number (only for JoyEmu)

JOYCP:
  * changed definitions for right ctrl and alt gr (were incorrect)
  * introduceded the possibility of setting to "none" the key stuffed by a
    certain direction/button (e.g. for games which don't require fire buttons)
  * added auto update mode: in this mode, when you change an option
    the resident emulator is updated immediately
  * added "swap key bindings" to key settings menu, to exchange emulated keys
    between the two joysticks
  * added "swap fire buttons" to exchange key bindings between the first two
    fire buttons of current joystick
  * added "8 way mode": in this mode, you can specify keys to be stuffed for
    diagonals as well as for straight directions.

Changes from v3.1:

JOYEM/JOYEMU:
  * added support for joysticks with 6 fire buttons

JOYCP:
  * added support for joysticks with 6 fire buttons

Changes from v3.3:

JOYEM/JOYEMU:
* "unrolled" functions and definitions in JoyEm and JoyEmu: should be
  faster (even though they take up a little more memory now..)

JOYCP:
* fixed a stupid bug that locked the computer in a strict loop
  with interrupts disabled if just one joystick was connected to the PC


13  CREDITS


Versions 2.x and later of JOYEMU and its utilities were written by Simone
Zanella, inspired by the original source code by Pin Fei Sun.
All the programs in the package are written in C with inline Assembly where
needed.

To contact Simone Zanella (bug reports, suggestions, donations :) write to:

Simone Zanella Productions
C.P. 51, 30035 Mirano (VE)
Italy

e-mail: szanella@dsi.unive.it
        zanella@prometeo.it

- -----BEGIN PGP PUBLIC KEY BLOCK-----
Version: 2.6.2i

mQCNAzARNUQAAAEEAMTn+IgTuJ5Ei99lzFa6D6GCDYPUimdSQ2I2keFCVG2sCVfB
uejwgdPp+u/mlwJDE2wZpAUfgHe8E3N/vmfO6bl0RxOc1Hkl0mc/np5/F4wZoeOB
GcaEpwJLkKlFoE93p8Bh/UwUNo9UaKjfwx0mqP9G+XgiVowo7NEsAHa/+Bl9AAUR
tCpTaW1vbmUgWmFuZWxsYSA8c3phbmVsbGFAbW9vLmRzaS51bml2ZS5pdD6JAJUD
BRAwETVz0SwAdr/4GX0BAXjLA/9IZD5mT/BHdRfDvH6AnFwaxqAuluhCcycchW0A
/SOUJPsmFnFjGUoCFrur603rEUJpR/JsZpVOXaQHcNSuitB2msDu8YZyrVPgcV86
vGptHkX31GrfIK8RR4hHRtt0suUBWZBDJRfLNbq7KMKxfNF3h4wRjC1NBzzU0orM
mj9d2A==
=HOga
- -----END PGP PUBLIC KEY BLOCK-----

 Ŀ
                                                                          
   If you like and use this program, send me what you want (your sister,  
   if 18+ years old and good looking would be much appreciated :).        
   Money, hardware, software, postcards are welcome (in this order).      
                                                                          
 

I wish to thank the following people who have contributed to the development
of this set of utilities:

Pin Fei Sun
  for writing the original emulator and utilities and distributing the
  source code without restrictions; it is very hard to find in this
  version even a small part of the original code, but it served as a general
  basis to build this package; without it, I would have spent MANY more
  hours in developing and debugging; moreover, I liked the simple design
  (the emulator + 2 utilities to set keys and calibrate joystick), which
  I think is far superior than having just one executable with a LOT of
  command line options pretty obscure

Scott Hall
  most interrupt handlers, from his package TSRFIL10.ZIP, available from
  Simtel

Tom Grubbe
  TSR detection, uninstall routines and keyboard handler (well, slightly
  modified) -- part of the code was taken from his package PCPILOT.ZIP,
  available from Simtel; many routines were eventually taken from a book
  by Al Stevens

Markus F.X.J. Oberhumer
  routines to read keyboard (used for setting keys to be emulated), which
  are based on his package LIBKB100.ZIP, available from Simtel

Thomas Brandenborg
  beep routine (slightly modified), from his package TSRDEMO2.ZIP, available
  from Simtel



To contact the author of the original program:

pfsun@undergrad.math.uwaterloo.ca

This is a note from Pin Fei Sun:

Again, Joyemu is a freeware.  However, because I am very poor, any type of
donation will be appreciated.

216-161 University Ave. West
Waterloo, Ontario N2L 3E5
Canada
                                        --Pin Fei Sun



             Support software authors! It is in your interest!

-----BEGIN PGP SIGNATURE-----
Version: 2.6.3ia
Charset: cp850

iQCVAwUBM66b+tEsAHa/+Bl9AQH/aAQAqRgU1AshCZNC17vdFRCvhbvCR3705z/s
J9rlQiDIl6/bLNwZtsTd2AoqFyleVV0qg3eL8iwNM280f/Q9AOGmyPxJsE8mgF4S
+gVgBpVps3ZYglLrhL2VvKQNV5ccvJnRgBDLJmQ+39EH8M6uikYzEqVRp9YKcRak
m/l1paCwXOs=
=J90L
-----END PGP SIGNATURE-----
