Design

clanehin edited this page Mar 16, 2011 · 1 revision
Clone this wiki locally

Client - Server Protocol

Roguestar has a client-server architecture. roguestar-engine is the server, and contains all of the game state. roguestar-gl is the client. roguestar is the program that binds the two processes, currently, using stdin/stdout pipes. The client transmits instructions to the server, and re-enacts changes that it observes in the state.

Communication takes place via a plain text ASCII protocol. Instructions are delimited by spaces and newlines. The server understands simple one-line directives. The client understands both simple one-line answers, and multi-line data tables.

In the client -> server direction, game query directives are read-only operations that answer information about the state of the game. game action directives modify state. Each directive is followed by at least one string, and at as many more strings

In the server -> client direction, the server sends one-line answer directives to provide simple information. When the server sends a data table, it frames the data with begin-table and end-table directives. The table consists of space-delimited columns and newline-delimited rows. Understanding these tables may require relational joins with other tables.

The client and server both cache incoming information.

Whenever the server finishes sending a batch of information, it sends the text over on one line. This signal delimits orthogonal responses, and allows the client to recover from any error. The client may otherwise ignore this signal.

Whenever the server finishes making a change, it sends the text done on one line. This signal indicates that any cached information is now out-of-date. The client may ignore this signal, since issuing any action directive has this effect.

The protocol can be observed on stderr by passing the --echo-protocol flag to the roguestar binary.

The Server

Protocol Directives

roguestar-engine reads directives line-by-line from stdin. It dispatches each query or action as described in Protocol.hs.

Internally, the server expects that requests will arrive as a long sequence of querys interrupted by occasional actions. To this end, it caches incoming queries, and automatically re-issues them immediately after any action. These queries are processed in parallel, and the results cached. Inevitably, some of these queries will yield errors, because the queries that applied to previous action are likely but not guaranteed to apply to the next action, but the errors are cached and not emitted until requested.

The Client

Protocol Information

The Driver.hs module reads information line-by-line from stdin. It caches each response, clearing the cache whenever it sends an game action directive.

Loops

roguestar-gl has several critical loops: the scene accumulation loop, the rendering loop and the action loop.

The scene accumulation loop occurs primarily inside the RSAGL FRP arrow. It reads information from the driver and constructs an abstract scene graph.

The rendering loop displays the scene graph on screen. The RSAGL library does most of the work here.

The action loop reads keyboard input, verifies the correctness of the user's request, and dispatches the appropriate game action directive to the server. The Action.hs module describes the majority of the work done by the action loop.