ANSI protocol extension for Fortuna Terminal

Information

When the terminal receives the byte FD, it enters graphics mode. This is a binary protocol that allows the management of graphics, audio and input devices.

Moving from text mode to graphics mode and vice-versa can take up to 1 second. It's recommended that after sending the command, the communication is flushed and the client waits before sending more data.

When operating in graphics mode, the integers are sent in using this compression scheme:

Any value must be between -16127 and 16383. The terminal itself never sends data in RLE format, but it can accept from the computer.

Some commands require a response. The response itself is asynchronous, and it can come after some time.

---

Swapping to graphics mode while in text mode

To swap to graphics mode while in text mode, the following character sequence of bytes must be sent:

1 24 112 5

Configuration

These options configure or get information about Fortuna Terminal.

Sequence	Action
1	Reset terminal (clear screen and put it back in original state)
2	Reset computer (pull RESET line low)
3/4	Enable (3) or disable (4) VSYNC signal
5	Ask for the Fortuna Terminal version.

The following responses can be sent from these requests:

Sequence	Action
1 P1 P2 P3	Report the Fortuna Terminal version (major, minor, patch)

In communications mode where the VSYNC wire is not present (ex. TCP/IP), if the VSYNC signal is enabled, the following byte is sent at every VSYNC:

Sequence	Action
127	VSYNC reporting

Frame control

The following sequence of bytes, no matter where found, will reset the communication. Ideally this sequence should be sent at the end of the frame. The purpose of this is to avoid that the communication goes out of sync of one byte is lost.

Sequence	Action
54 EE C2 28	End of frame

Mouse input

Mouse input is reported by the terminal with the following escape code sequences:

Sequence	Action
2 P1 P2 P3	Mouse button P1 was pressed in position P2 (X) and P3 (Y).
3 P1 P2 P3	Mouse button P1 was released in position P2 (X) and P3 (Y).
4 P1 P2 P3	Mouse was moved to position P2 (X) and P3 (Y) while pressing button P1. Only when reporting of mouse moves is enabled.

The computer can configure these options in the terminal:

Sequence	Action
6/7	Enable (6) or disable (7) mouse. Mouse is disabled by default.
8/9	Enable (8) or disable (9) reporting of mouse movements. Disabled by default.

Joystick input

The joystick buttons are numbered as follows:

Number	Joystick Button	Keyboard button (if joystick emulation on)
16	Left	Left key
17	Right	Right key
18	Up	Up key
19	Down	Down key
1	A	X
2	B	Z
0	X	S
3	Y	A
9	Start	Enter
8	Select	Tab
4	L	Q
5	R	W

Whenever the joystick state changes, the following update is sent:

Sequence	Action
5 P1 P2	A joystick button press happened. P1 is the joystick number (starting at 1), P2 is the button.
6 P1 P2	A joystick button release happened. P1 is the joystick number (starting at 1), P2 is the button.

The computer can configure these options in the terminal:

Sequence	Action
10/11	Enable (10) or disable (11) joystick emulation via keyboard.

Graphics

The terminal is in text mode (80 columns) by default. For displaying graphics and using all the extended modes, it need to be swapped to the graphical mode, which supports 40-column text, and a 256x256 graphical canvas.

Sequence	Action
12	Disable (0) graphics mode.

Graphics setup

These are calls used to setup the state machine sprites and tiles. Sprites and tiles are 16x16. There can be 1024 different images. At most 128 sprites can be in the screen at the same time. The tiles can be used to make up maps - there can be 64 maps with a maximum of 512x512 tiles.

Sequence	Action
13 P1 P2 P3 P4	Change the palette index P1 with the color values (R: P2, G: P3, B: P4). Needs to be done before images are uploaded.
14 P1 P2 [VV * 256]	Create/update image P1 with transparent color P2 followed byte the 256 pixel colors.
15 P1 P2 P3 [VV * w*h]	Create/update map P1 with width P2 and height P3, followed by the list of tile indexes. A negative tile index can be used when there should be no tile at that position.

Image and map creation will respond with a checksum of the image/map. If the checksum is not correct, the image/map can be sent again. The algorithm used for checksum is Fletcher16, composed of two values.

Sequence	Action
7 P1 P2	For map P1, the checksum is P2.
8 P1 P2	For image P1, the checksum is P2.

Graphics draw

On the screen, there are these layers available:

Layer	Description
0	Deep background (only background color)
4	Tilemap 1 (background)
8	Tilemap 2 (obstacles)
12	Sprites
16	Tilemap 3 (foreground)
20	Tilemap 4 (UI)

These are the commands to draw graphics. Fortuna terminal is a state machine, so it will keep whatever is configured until configuration is changed. The VSYNC wire can be used to get the best moment to make these changes.

Sequence	Action
16 P1	Set background color on the background layer
17 P1/18 P1	Enable (17) or disable (18) layer P1
19 P1 P2 P3 P4	Configure tile map. On layer P1, set the map (P2) at position (P3, P4)

Sprite draw

Sequence	Action
20 P1 P2	Define sprite P1 image (P2)
21 P1 P2 P3	Define sprite P1 position (x: P2, y: P3)
22 P1	Define sprite P1 visible
23 P1	Define sprite P1 invisible
24 P1/25 P1	Define sprite P1 mirrored (24) or not mirrored (25) horizontally
26 P1/27 P1	Define sprite P1 mirrored (26) or not mirrored (27) horizontally
28 P1 P2	Define sprite P1 Z-order
29 P1 P2	Lock sprite P1 to the position of the layer P2 (use -1 to unlock)

Text

Text can be written on the screen using the following sequences. The graphics text matrix is 41x28, and the text is always on top.

Sequence	Action
30 P1 P2 [VV...]	Write zero terminated string in position P1, P2
31 P1 P2	Set text color to be background P1, foreground P2
32	Clear text of the whole screen

Sprite collisions

Sequence	Action
33 P1 P2	Subscribe to receive collisions between sprite P1 and P2.
34 P1 P2	Unsubscribe to not receive collisions between sprite P1 and P2.
35	Remove all collision subscriptions.

Whenever a collision happens between two subscribed sprites, the following notification is sent:

Sequence	Action
9 P1 P1	A collision happened between sprites P1 and P2.
10 P1 P2	A separation happened between sprites P1 and P2.

Audio

Audio setup

Audio playing