• Developers Corner
• GUI separation

Intro

This might be the base for ToME 4 display modules. Feel free to enhance the design, it surely needs it! Feel free to code it, it definitively needs it...

Preface

In all this document there are a few rules:

• All byte orders are in network order
• "u8b" means an unsigned integer of 1 byte
• "u16b" means unsigned integer of 2 bytes
• "u32b" means unsigned integer of 4 bytes
• "string" means a string of characters. The len is denoted by the first byte

General communication

Communication between the core and the engine:

• The GUI is connected to the Core with a socket, this implies it is possible to run the client over the internet without the core.
• The core sends out a stream of commands to the gui that it will then interpret to display the various GUI elements(buttons, menus, ...) but also the actual game map
• The GUI sends "events" with a similar stream mechanism
• It should be extremely easy to squize in a zlib layer to compress the streams for easier internet play
• Each command is a packet following this format:
  1. 2 "magic" byte: 0xFF 0x00
  2. 2 bytes for the command index. Note that Core and Gui commands are completly separate entities, as such command 3 in the Core is not the same as command 3 in the GUI
  3. x bytes of parameters, depends of the command. Commands that have fixed length parameters are fine. Commands with variable length parameters should take some bytes to describe the parameters length, or else be extremely smart about finding the length.

• This total separation of the Core and the GUI should allow to make GUIs in whatever language we can dream of(provided it has a socket library). Possible we could even make a Java applet to play from a browser that connects to your home computer. The first goal is to have those GUIS: SDL and ncurses based. The ncurse one being for ssh users and the SDL one for the rest Hell, this mean we could write a client for mobile phones

Commands list

Core to GUI

RegisterGraphic

This command registers a graphical element that is possible to display in the map. Such elements can be anything from a monster, an object, to a spell, a floor tile, a cloud, ...

• Each has an unique identifier that is sent and defined by the Core
• Each element is composed of:
  • at least one letter/RGB code pair
  • an abstract image identifier

If more than one letter/color pair is given, or if the image contains an animation the rate at which switch them is left to the GUI. A curses UI could change only when a key is pressed while a graphical UI might want to put that on timer. The image identifier can be used for many things. One could imagine a 3D port in which this would reference a 3D model to use.

Params:

1. u32b id
2. u8b number of pairs
3. (u8b + 3*u8b) * number of pairs; the letter and the RGB code
4. string image identifier

The Core may:

• Send the full list at startup(slower at sartup, eaasier to code)
• Be smart and send only them the first time they are needed(slower at runtime, harder to code)

GetTile

Receieves(and most likely draws) a tile on the map. This command takes an arbitrary number of graphic elements identifiers and displays them in order of arrival, possibly discarding all bu the last if the GUI cannot handle transparency

Params:

1. u8b number of ids
2. (u32b) * number of ids; the elements ids to display

The GUI is responsible for storing those in order to do redraws and such, the Core wont resend them on such events.

NewWindow

Creates a new window with a given name.

Params:

1. string identifier
2. string window title
3. u8b window width in % of the screen size
4. u8b window height in % of the screen size

AddMap

Creates a map displaying widget in the given window.

Params:

1. string window name

AddLabel

Gui to Core