Rbox game protocol
Contents |
[edit] Status
This document is a DRAFT and is subject to change, but it will give you a good idea what the final definition will look like.
Feel free to add ideas and comments to the thoughts and ideas section, but please do not edit the actual protocol definition. For the sake of conformity, this will be maintained by a single user only. Thank you!
[edit] Message exchange definition
[edit] Introduction
Data is exchanged in a command/response fashion and each command is always be followed by a response from the host system. In addition, notifications may be generated as a result of events occurring on the host system.
[edit] Command definition
8 0x81 Start of transmission, used for synchronization 8 .CMD FCB and command code n .DATA *Command message, see individual definitions 8 .CS *Checksum
[edit] Response definition
8 0x82/0x83 Command successfully executed for FCB = 0/1
[edit] Notification definition
8 0x81 Start of transmission, used for synchronization 8 .NIF Notification code n .DATA *Notification message, see individual definitions 8 .CS *Checksum
[edit] FCB mechanism
The Frame Control Bit is used to prevent packet loss. This bit should always be toggled for each NEW message, but If a response is not received, the last packet should be sent again, without toggling the FCB-bit, letting the host know that this is a retransmission.
[edit] *Encoding algorithm
Characters 0x80…0x83 are encoded as a two octet sequence beginning with the escape character 0x80 followed by an extension that defines the original character:
0x80 >> 0x80 0x00 0x81 >> 0x80 0x01 … 0x83 >> 0x80 0x03
Extension characters 0x04…0xFF are unused by the protocol and may be user defined to extend into common sequences.
[edit] Checksum calculation
The checksum is calculated by adding the command code (.CMD with FCB masked out, ie: logical AND with 0x3F) to an octet-wise arithmetic addition of .DATA.
[edit] Commands
[edit] Thoughts and ideas
- Clipping rectangles for sprites?
- Clipping rectangles for direct drawing?
- Classic text effects, such as rainbow and others?
- Set color command to replace discrete color info in each command?
[edit] SND_GFX
Description:
Upload graphic to controller memory.
Command:
Command code: 0x01/0x41
U8 .SID Sprite identifier U8 .W Width of sprite U8 .H Height of sprite S8 .X X-origin of sprite S8 .Y Y-origin of sprite U8 .N Number of frames 16*.X*.Y*.N .DATA Graphics data
Graphics data is ordered first frame…last frame, top…bottom, left…right. Each pixel consists of two octets of the following format:
1 .A Opaque 3 Reserved U4 .R Red channel U4 .G Green channel U4 .B Blue channel
[edit] SND_SFX
Description:
Upload sound to controller memory.
Command:
Command code: 0x02/0x42
To be defined
[edit] GFX_ADD
Description:
Insert a sprite into overlay memory.
Sprites are persistent and will always be drawn to screen, on top of everything else.
Command:
Command code: 0x10/0x50
8 .SID Sprite identifier 8 .GID Graphic identifier U8 .G Group index S8 .X X-position S8 .Y Y-position U8 .N Frame index
[edit] GFX_DEL
Description:
Remove a sprite from overlay memory.
Command:
Command code: 0x11/0x51
8 .SID Sprite identifier
[edit] GFX_SET
Description:
Set parameters for a specific sprite or group
Command:
Command code: 0x12/0x52
1 .FT .ID is a [1] group [0] sprite 1 .FA .X, .Y and .N are [1] relative [0] absolute 1 .FID [1] .ID to be modified 1 .FG [1] .G to be modified 1 .FX [1] .X to be modified 1 .FY [1] .Y to be modified 1 .FN [1] .N to be modified 1 Reserved 8 .ID Sprite or group identifier (see .FT) 0/U8 .GID Graphic identifier (available only if .FID = 1) 0/U8 .G Group identifier (available only if .FG = 1) 0/S8 .X X-position (available only if .FX = 1) 0/S8 .Y Y-position (available only if .FY = 1) 0/S8 .N Frame index (available only if .FN = 1)
Notes:
.N will cycle within the frame boundaries of the currently assigned graphic.
As an example doing a relative update of .N over a group containing sprites with graphics having two frames, will effectively toggle all sprites between the two frames.
[edit] GFX_BLT
Description:
Draw a graphic to the frame buffer.
Command:
Command code: 0x13/0x53
8 .GID Graphic identifier U8 .X X-position U8 .Y Y-position U8 .N Frame index 1 .FS Draw using a solid color 1 .FI Draw [1] opaque [0] transparent areas (only applicable if .FS = 1) 2 Reserved U4 .R Red channel (only applicable if .FS = 1) 0/U4 .G Green channel (only available if .FS = 1) 0/U4 .B Blue channel (only available if .FS = 1)
[edit] GFX_TXT
Description:
Draw a text to the frame buffer.
Command:
Command code: 0x14/0x54
8 .F Font index (to be defined) S8 .X X-position S8 .Y Y-position U8 .N Number of characters .N .TEXT Text in ASCII-format 4 Reserved U4 .R Red channel U4 .G Green channel U4 .B Blue channel
[edit] GFX_PXL
Description:
Sets a single pixel in the frame buffer.
Command:
Command code: 0x15/0x55
S8 .X X-position S8 .Y Y-position 4 Reserved U4 .R Red channel U4 .G Green channel U4 .B Blue channel
[edit] GFX_LIN
Description:
Draw a line or box to the frame buffer.
Command:
Command code: 0x16/0x56
S8 .X1 X-position start S8 .Y1 Y-position start S8 .X2 X-position end S8 .Y2 Y-position end 1 .FB Draw a [1] box [0] line 1 .FF Draw a [1] filled box [0] box outline (only applicable if .FB = 1) 2 Reserved U4 .R Red channel U4 .G Green channel U4 .B Blue channel
[edit] GFX_CLS
Description:
Clear the entire frame buffer to a specified color.
Command:
Command code: 0x17/0x57
4 Reserved U4 .R Red channel U4 .G Green channel U4 .B Blue channel
Notes:
This call will not remove sprites from overlay memory.
These will still be drawn on top of the cleared screen.
[edit] GFX_FRM
Description:
Copy frame buffer to graphics memory and overlay all sprites.
Command:
Command code: 0x1F/0x5F
[edit] SFX_RUN
Description:
Starts or restarts the specified sound.
Command:
Command code: 0x20/0x60
8 .ID Sound identifier
[edit] SFX_BRK
Description:
Stops the specified sound.
Command:
Command code: 0x21/0x61
8 .ID Sound identifier
