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
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-engine reads directives line-by-line from stdin. It dispatches each query or action as described in
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.
Driver.hs module reads information line-by-line from stdin. It caches each response, clearing the cache whenever it sends an
game action directive.
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.