Joysticks

Joysticks or similar controllers on the host may have thair axes mapped to the usual ADC channels on the emulated BBC micro or set to generated simulated keypresses. Buttons on the host joysticks may be mapped to one of the fire buttons understood by the BBC micro or to keys.

Table of Contents Host Joysticks Single Joystick Device Multiple Joystick Devices Joymaps

Host Joysticks

When B-Em starts it asks the Allegro library which joystick devices are available which Allegro will, in turn, get from the operating system. As seen by B-Em each joystick device has a name, a number of buttons and a number of logical sticks. Each logical stick in turn has a number of axes. Logical sticks and axes do not necessarily correspond to physical sticks and axes on the device. On the Xbox One controller, for example, one physical joystick drives axes on two different logical sticks. Often, no useful names are returned for sticks and axes so B-Em refers to these by number. That also means B-Em does not know whether an axis is in the X or Y direction.

Internally, B-Em sees each axis as a number between -1.0 and +1.0 with 0.0 being the centre position. This is converted into a suitable value for the BBC's ADC when the ADC is read. On the Master Compact the joystick interface is digital so thresholds of -0.5 and +0.5 are applied. Anything between those two is considered centre.

B-Em will choose some defaults to make it likely that the joystick device will do something useful without needing to configure it. The defaults depend on whether there is one joystick device attached or more than one.

Single Joystick Device

Where only one joystick device is attached B-Em will initially map the channels as follows:

BBC ADC Channel	Joystick Device	Stick	Axis
1	0 (only)	0 (1st)	0 (1st)
2	0 (only)	0 (1st)	1 (2nd)
3	0 (only)	1 (2nd)	0 (1st)
4	0 (only)	1 (2nd)	1 (2nd)

All other sticks and any additional axes on the first two sticks will be ignored. All even numbered buttons, counting from zero, will be mapped to the BBC fire button 1 and all odd numbered buttons will be mapped to BBC fire button 2.

Multiple Joystick Devices

Where there are multiple joystick devices the default is to split the channels between the first two devices as follows:

BBC ADC Channel	Joystick Device	Stick	Axis
1	0 (1st)	All	0 (1st)
2	0 (1st)	All	1 (2nd)
3	1 (2nd)	All	0 (1st)
4	1 (2nd)	All	1 (2nd)

All other devices will be unmapped. All the buttons on the first joystick device will be mapped to the first BBC fire button and all the buttons on the second joystick device will be mapped to the second BBC fire button.

Joymaps

For cases when the defaults chosen by B-Em are not suitable it is possible to provide a custom mapping via a joymap. Joymaps are stored in the B-Em config file and there can be more than one map in the config file at the same time. The current map can be chosen from the Settings menu and then selecting Joystick.

There are two reasons for having a custom joymap:

• To deal with the particular joystick device which may have multiple dissimilar sticks and various quirks.
• To work better with a particular game or other program. This is particularly true of mapping joystick axes to key presses which are often specific to a game.

A typical joymap section in the config file would look like this:

 [joymap Test X-Box Map]
 joystick=Microsoft X-Box One S pad
 stick0axis0adc=1
 stick0axis0scale=0.8
 stick0axis1adc=2
 stick1axis0adc=0
 stick1axis1adc=4
 stick2axis0adc=3
 stick2axis1adc=0
 stick0axis0nkey=A
 stick0axis0pkey=S
 button0btn=1
 button1key=Z

The section name, between the brackets, will always start with the word joymap followed by the name of the joymap. Without the initial joymap' B-Em has no way of knowing the section concerned is joymap and will therefore not process it. Spaces between the end of the word joymap and the rest of the name are ignored. The keys within this section are as follows:

Key Name	Description
joystick	This is the name of the joystick device. If this is present, when selected, this joymap will be applied to the first device found with this name and, if there is no such device found, it will not be applied at all. If this key is not present, when the map is selected it is applied to the first joystick device found regardless of name.
stick0axis0adc	A key in this form is mapping a particlar axis on a particular stick to a BBC ADC channel. The BBC ADC channels are numbered 1 to 4 corresponding to the argument to ADVAL in BASIC that would be needed to read that channel. 0 means ignore this axis. Other values will generate a warning and the mapping will be left at the default setting.
stick0axis0scale	This sets the scale factor for the specified stick and axis, useful if you want to make the stick more or less sensitive. The default scaling factor is 1.0.
stick0axis0nkey	This sets a mapping such that when this axis goes negative a press of the corresponding key is simulted. When the axis returns towards zero the key is released. The threshold is -0.5 so the stick will need to be moved approximately half way between the centre point and the extreme to trigger a keypress. The value can either be the ASCII character produced by the key when unshifted or the name of the key as it appears on the drawn keyboard accessible from Settings, Keyboard, Remap Keyboard
stick0axis0pkey	As above, but for a positive value for the axis, i.e. moving in the opposite direction and with a threshold of +0.5
button0btn	This maps the specified button on the joystick device to the specified BBC joystick fire button (1 or 2).
button1key	This maps the specified button on the joystick device to the specified key so when the joystick button is clicked a press of the correponding key is simulated.