# PBUS

The PBUS (player bus) is not at all well documented. There exists
the patent WO09410636A1 "PLAYER BUS APPARATUS AND METHOD" which was
filed on 1992-02-11. The primary details of the protocol can be
found in pages 21 - 23.

> Since the above described arrangement permits 448 bits to be
> transferred per field and the minimum bit transfer per device is
> 8bits, a maximum of approximately 56 devices can be on the bus at
> one time.
>
> Each of the player devices has an ID code embedded in its response
> data. An ID code is mapped by software in the system to the number
> of input and output bits for the device identified. Since the ID
> code is embedded, it is received by the system 100 both at
> initialization and when data is being read in under normal
> operation. In this manner, it is possible to reconfigure the
> system (add or delete devices) without re-initializing and without
> adversely affecting those device already on the line.
>
> During an initialization sequence, a string of zeros is shifted
> out from the system 100. A requirement for all of the player
> devices is that they see a string of zeros either as an
> initialization or don't cares.
>
> The first 4 bits of data stream received by the system 100 from
> each device is that device's basic identification code (ID
> code). The embedding of an ID code in the data stream functions as
> follows for a joystick 15. The basic joystick 15 will have 8 bits
> of data that are (inverted): down, up, right, left, switch-2,
> switch-1, fire-2 and fire-1. Using the inability of the joystick
> to indicate both up and down at the same time, the ID codes for a
> basic joystick are 01QQ, 10QQ and 11QQ, where QQ is 01, 10 or
> 11. All other devices start with 00QQ. All joysticks are incapable
> of generating 00 for their first 2 bits. With regard to the escape
> function, the 1100 sequence indicates escape for the joystick. In
> all other devices, the escape function is indicated by the bit
> immediately following the 4 bit identification code. A string of
> zeros indicate the end of input data into the system 100 device.

However, information from the original FreeDO release and later
discovered does not match with the specifics of the patent.

## Device Data Formats

### JOYPAD

The joypad's data layout is clear but less so in regards to it's
layout in the stream. 3DO's SDK indicates the ID is 0x80. Unlike other
device IDs it appears the joypad's ID is embedded. In the FreeDO
source it was questionably referred to as a connection bit.

MSB -> LSB

1bit: set, the high order bit from the ID (0x80)
2bit: unused, unset, part of the joypad mask
1bit: down
1bit: up
1bit: right
1bit: left
1bit: A
1bit: B
1bit: C
1bit: P
1bit: X
1bit: right trigger
1bit: left trigger
2bit: unused / 0


### FLIGHTSTICK

MSB -> LSB

* 8bit: identifier 0 (0x01)
* 8bit: identifier 1 (0x7B)
* 8bit: length? (0x08)
* 8bit: horizontal position
* 2bit: 0
* 8bit: vertical position
* 2bit: 0
* 8bit: depth position
* 4bit: 0x02 (unsure what this means)
* 1bit: trigger / fire
* 1bit: A
* 1bit: B
* 1bit: C
* 1bit: up
* 1bit: down
* 1bit: right
* 1bit: left
* 1bit: P
* 1bit: X
* 1bit: left trigger
* 1bit: right trigger
* 4bit: 0


### MOUSE

MSB -> LSB

* 8bit: identifier (0x49)
* 1bit: left button
* 1bit: middle button
* 1bit: right button
* 1bit: shift button
* 10bit: X delta (signed)
* 10bit: Y delta (signed)


### LIGHTGUN

x = 0 - 639
y = 0 - 240
offset = (((y * 794.386) + x) / 5.0)

MSB -> LSB
8bit: identifier (0x4D)
1bit: trigger
1bit: service button (arcade shooters)
1bit: coin button (arcade shooters)
1bit: start (arcade shooters)
1bit: holster (arcade shooters) / option (retail)
1bit: unused?
1bit: unused?
17bit: screen offset

It's not clear where '794.386' or '5.0' are derived from. Also, unlike
the mouse, when placed twice in a buffer it doesn't get picked up as
1p and 2p. One instance shows up as player 2.

To reload in Mad Dog II (retail) requires "shooting off screen" which
appears to be represented as y = 0 and x = ~20 - ~640.

According to the 3DO SDK's lightgun.c:

```
DESCRIPTION OF LIGHTGUN HARDWARE
--------------------------------
The lightgun is not capable of returning an (X, Y) position value when
reporting events.  It does report a counter value that returns the
time it took between the beginning of a field (vertical blank) and
when the scan-beam passes into the field of view of the light sensor
in the lightgun.  The X and Y value can be calculated from the timer
value returned from the lightgun based on how long it takes to draw
from the start of one scan line to the start of the scan line
immediately below it (YSCANTIME) and how long it takes to draw from
the first pixel to the last pixel on the same scan line (XSCANTIME).
A third required value, is a time offset value that takes into
consideration the time between the beginning of a field and when
scan-beam begings drawing to the first pixel on the first scan line
(TIMEOFFSET).

#define	NTSC_DEFAULT_XSCANTIME	  1030
#define NTSC_DEFAULT_YSCANTIME	 12707
#define NTSC_DEFAULT_TIMEOFFSET	-12835
#define PAL_DEFAULT_XSCANTIME	  1051
#define PAL_DEFAULT_YSCANTIME	 12796
#define PAL_DEFAULT_TIMEOFFSET  -58995
#define PAL_WIDTH		   388
#define NTSC_WIDTH		   320

x = ((((10 * counter) % NTSC_DEFAULT_YSCANTIME) * NTSC_WIDTH) /
     (NTSC_DEFAULT_XSCANTIME * 10));
y = ((10 * counter) / NTSC_DEFAULT_YSCANTIME);
```


### ORBATAK TRACKBALL

Orbatak uses two different devices. The trackballs are just mice as
described above. The buttons (coins, start, service) are managed via
the "SILLY_CONTROL_PAD" as defined in the 3DO SDK (event.h) or in the
least uses the same identifier.

MSB -> LSB
8bit: identifier (0xC0)
8bit: 0x00
3bit: unused
1bit: coin (p1)
1bit: coin (p2)
1bit: start (p2)
1bit: start (p1)
1bit: service
8bit: 0x00


## Device Usage In Games

### Games supporting 3DO mouse

* Crime Patrol (1993)
* Cyberdillo (1996)
* Drug Wars (1994)
* Fun 'n Games (1994)
* Kingdom: The Far Reaches (1995)
* Lemmings (1993)
* Mad Dog II: The Lost Gold (1994)
* Myst (1995)
* Policenauts (1995)
* Shanghai: Triple-Threat (1994)
* Space Pirates (1994)
* The Last Bounty Hunter (1995)
* World Cup Golf: Hyatt Dorado Beach (1994)
* Zhadnost: The People's Party (1995)

### Games supporting GAMECON (3DO lightgun)

* Corpse Killer (1994) (1 Player)
* Crime Patrol (1993) (1 Player or 2 Players simultaneously)
* Demolition Man (1995) (1 Player)
* Drug Wars (1994) (1 Player or 2 Players simultaneously)
* Mad Dog McCree (1994) (1 Player or 2 Players simultaneously)
* Mad Dog II: The Lost Gold (1994) (1 Player or 2 Players simultaneously)
* Policenauts (1995) (1 Player)
* Space Pirates (1994) (1 Player or 2 Players simultaneously)
* The Last Bounty Hunter (1995) (1 Player or 2 Players simultaneously)
* Who Shot Johnny Rock (1995) (1 Player or 2 Players simultaneously)

### Games supporting 3DO flight stick

* Blade Force (1995)
* Cyberia (1996)
* Doom (1996)
* Flying Nightmares (1994)
* Killing Time (1995)
* Mega Race (1994)
* Phoenix 3 (1995)
* PO'ed (1995)
* Return Fire (1995)
* Scramble Cobra (1995)
* Shockwave 2: Beyond The Gate (1995)
* Space Ace (1995)
* Star Fighter (1996)
* Star Wars: Rebel Assault (1995)
* Super Wing Commander (1994)
* VR Stalker (1994)
* Wing Commander III: Heart Of The Tiger (1995)
