sm64pc/doc/gamebridge.org

55 lines
2.3 KiB
Org Mode

#+TITLE: gamebridge
An interface between Super Mario 64 and just about anything else your heart
desires.
* High level ideas
the rust program has two threads, one is getting the inputs from $SOMEWHERE and
the other is doing the file I/O to the game
the game bridge thread has two file descriptors open, a fifo for feeding inputs
to the game and a fifo opened by the game for signaling vblanks
the game will then write a readiness signal to the rust program and read the
button data fifo
then things will progress normally
the getting the input thread of the rust program will have some logic for
telling how long ago it got liveness of the input source (explicitly vaguely
defined to allow a controller to sit there and do nothing as long as it still
exists), and then "sticking" it until, say, 10 frames have passed and then it
will block infinitely, freezing the game in place
* Goals
+ Blocking, synchronous rust as much as possible
+ unix fifos are great, let's use them
* Protocol
The protocol between the game and the bridge will be as follows (based on the
[[http://tasvideos.org/EmulatorResources/Mupen/M64.html][Mupen64 demo format]]). Two unix fifos will be created by the bridge.
The game and the bridge will both need to take care that the files are opened in
*unbuffered I/O modes*. This can be done with
=setvbuf(f, (char *)NULL, _IONBF, 0);= in C and is the default in Rust.
The first one will be called =vblank= and will then be opened by the game in
write mode when it starts. The bridge will open this fifo in read mode.
The second one will be called =input= and will be opened by the game in read
mode. The bridge will open this fifo in write mode.
On every frame, the game *MUST* write the text ="OK\n"= to the vblank fifo. This
will signal the bridge that it *MUST* write four bytes of data to the input
fifo, conforming to the [[http://tasvideos.org/EmulatorResources/Mupen/M64.html#ControllerData][Controller Data]] specification of the Mupen64 format.
This data will be interpreted by the game as actions for Mario to take.
The bridge *MUST* block on waiting for the vblank fifo to be written to by the
game and the game *MUST* block on the input fifo being written to by the bridge.
When the game is exiting, the game *SHOULD* write ="BYE"= to the vblank fifo.
When the bridge recieves a ="BYE"= message, it *MUST* exit.