This document describes my proposal of a protocol to be used when NetHack calls a function located inside a plug-in window port. The complementary protocol (to be used for callbacks) has not been written yet.
NhExt requires a two-way, single duplex, connection between the game and the window-port. How that connection is set up is outside the scope of the protocol. The protocol is fully synchronous. That is, at any time either the game is waiting for input and the window-port is either writing data or is not yet ready to write data, or the reverse is true.
NhExt has provision for more than one sub-protocol, to allow for future backwards compatibility. Initially, both the game and the window port should be in sub-protocol 0.
The game will always start by writing a line consisting of the five characters "NhExt" which will be followed by a number of tags and values.
Tags are sequences of up to 64 alpha-numeric characters, plus "_".
Values are sequences of up to 64 printable ASCII characters (space to "~"), enclosed in double quote marks. Characters may be escaped with backslash. If every character was escaped, and including the two enclosing quotes, a 64 character sequence could take 130 bytes to transmit.
Tags need not be in any order within the line.
Tags and values are seperated from each other (and from the "NhExt" command) by one space character.
The following tags will always be present:
VERSION_STRING
.
Window ports should ignore tags they do not recognize.
Example:
NhExt game "NetHack" version "3.3.2" protocols "1" junk "foo \" bar"
The window-port should reply with either an error or an acknowledgment response.
An error response consists of the five characters "Error" followed by a "mesg" tag and a value. As a special case, this value may be up to 200 characters in length.
Example:
Error mesg "X11: Can't open display (Permission denied)"
There may also be other tags present, which will be ignored.
The game will respond to an error response by displaying the error message to the user and then terminating.
An acknowledgment response consists of the three characters "Ack" followed by a number of tags and values.
The following tags must always be present:
The game will ignore tags it does not recognize.
Example:
Ack windowtype "Gtk" protocol "1"On receipt of an acknowledgment response, the game will immediately start the requested sub-protocol. The window-port should enter listening mode.
This sub-protocol is heavily based on Sun Microsystem's XDR protocol, documented in RFC 1014. In addition, I use their XDR language to describe the structure of request and reply encodings. It should be possible to use their rpcgen program (supplied with Solaris) to generate routines to encode and decode data compatible with sub-protocol 1. There is, however, no need to use rpcgen.
I have also plagiarised window.doc mercilessly.
There are 5 basic window types, used to call create_nhwindow:
NHW_MESSAGE | (top line) |
NHW_STATUS | (bottom lines) |
NHW_MAP | (main dungeon) |
NHW_MENU | (inventory or other "corner" windows) |
NHW_TEXT | (help/text, full screen paged window) |
The tty window-port also uses NHW_BASE (the base display) internally.
NHW_MENU windows can be used for either menu or text display. Their basic feature is that for the tty-port, if the window is small enough, it appears in the corner of the tty display instead of overwriting the whole screen. The first call to add information to the window will decide if it is going to be used to display a menu or text. If start_menu() is called, then it will be used as a menu. If putstr() is called, it will be used as text. Once decided, there is no turning back. For the tty-port, if the data is too large for a single screen then the data is paged (with --more--) between pages. Only NHW_MENU type windows can be used for menus.
NHW_TEXT windows are used to display a large amount of textual data. This is the type of window one would use for displaying a help file, for example. In the tty window-port, windows of type NHW_TEXT can page using the DEF_PAGER, if DEF_PAGER is defined. There exists an assumption that the font for text windows is monospaced. The help files are all formatted accordingly.
"window" is always of type int. The proxy module will convert to and from winids if it ever needs to. There are a few fixed window names that are known throughout the code:
WIN_MESSAGE | (top line) |
WIN_STATUS | (bottom lines) |
WIN_MAP | (main dungeon) |
WIN_INVEN | (inventory) |
Other windows are created and destroyed as needed.
"Port" in this document refers to a CPU/OS/hardware platform (UNIX, MSDOS TOS, etc.) "window-port" refers to the windowing platform. This is orthogonal (e.g. UNIX might use either a tty window-port or an X11 window-port).
Procedure | ID |
---|---|
init | 0x01 |
init_nhwindows | 0x02 |
player_selection | 0x03 |
askname | 0x04 |
get_nh_event | 0x05 |
exit_nhwindows | 0x06 |
suspend_nhwindows | 0x07 |
resume_nhwindows | 0x08 |
create_nhwindow | 0x09 |
clear_nhwindow | 0x0A |
display_nhwindow | 0x0B |
destroy_nhwindow | 0x0C |
curs | 0x0D |
putstr | 0x0E |
display_file | 0x0F |
start_menu | 0x10 |
add_menu | 0x11 |
end_menu | 0x12 |
select_menu | 0x13 |
message_menu | 0x14 |
update_inventory | 0x15 |
mark_sync | 0x16 |
wait_sync | 0x17 |
cliparound | 0x18 |
update_positionbar | 0x19 |
print_glyph | 0x1A |
raw_print | 0x1B |
raw_print_bold | 0x1C |
nhgetch | 0x1D |
nh_poskey | 0x1E |
nhbell | 0x1F |
doprev_message | 0x20 |
yn_function | 0x21 |
getlin | 0x22 |
get_ext_cmd | 0x23 |
number_pad | 0x24 |
delay_output | 0x25 |
change_color | 0x26 |
change_background | 0x27 |
set_font_name | 0x28 |
get_color_string | 0x29 |
start_screen | 0x2A |
end_screen | 0x2B |
outrip | 0x2C |
Plug-in window ports may define non-standard procedures with IDs of 0x8000 and above. In response to all other IDs, the window port should return a reply packet with no results.
The proxy module will initiate a procedure by writing an unsigned integer (according to RFC1014) whose value is as follows:
value = (ID << 16) | (length >> 2);where
length
is the length of the following data (not
including value
) in bytes. It will then write the relevant
request structure (if a procedure takes no arguments then length will be
zero and no request structure will be written).
The proxy module will then read back an unsigned integer from the plug-in window-port and decode it as follows:
ID = value >> 16; length = (value & 0xffff) << 2;If
ID
is non-zero, this is a callback (protocol not yet defined).
If ID
is zero, this is a reply to the active procedure. The
proxy module will read that many bytes from the plug-in window-port and
process the reply.
This procedure will be called once before all other procedures.
typedef string argument<>; struct init_nhwindows_req { argument argv<>; }; struct init_nhwindows_res { bool inited; argument argv<>; };
TRUE
. Otherwise
all flags.inited FALSE
?
struct player_selection_req { int initrole; int initrace; int initgend; int initalign; }; struct player_selection_res { int role; int race; int gend; int align; bool quit; };
Do a window-port specific player type selection. If
player_selection offers a Quit option, it should return
TRUE
in quit if this is selected.
struct askname_res { string plname<>; };
Ask the user for a player name and return it.
Does window event processing (e.g. exposure events). A noop for the tty and X window-ports.
struct exit_nhwindows_req { string str<>; };exit_nhwindows returns no results.
Exits the window system. This should dismiss all windows, except the "window" used for raw_print(). str is printed if possible.
struct suspend_nhwindows_req { string str<>; };suspend_nhwindows returns no results.
Prepare the windows to be suspended.
Restore the windows after being suspended.
enum nhwindow_type { NHW_MESSAGE = 1, /* (top line) */ NHW_STATUS = 2, /* (bottom lines) */ NHW_MAP = 3, /* (main dungeon) */ NHW_MENU = 4, /* (inventory or other "corner" windows) */ NHW_TEXT = 5 /* (help/text, full screen paged window) */ }; struct create_nhwindow_req { enum nhwindow_type type; }; struct create_nhwindow_res { int window; };
Create a window of type type.
struct clear_nhwindow_req { int window; };clear_nhwindow returns no results.
Clear the given window, when appropriate.
struct display_nhwindow_req { int window; bool blocking; };display_nhwindow returns no results.
Display the window on the screen. If there is data
pending for output in that window, it should be sent.
If blocking is TRUE
, display_nhwindow will not
return until the data has been displayed on the screen,
and acknowledged by the user where appropriate.
All calls are blocking in the tty window-port.
Calling display_nhwindow(WIN_MESSAGE,???)
will do a
--more--, if necessary, in the tty window-port.
struct destroy_nhwindow_req { int window; };destroy_nhwindow returns no results.
Destroy will dismiss the window if the window has not already been dismissed.
struct curs_req { int window; int x; int y; };curs returns no results.
Next output to window will start at (x,y), also moves displayable cursor to (x,y). For backward compatibility, 1 <= x < cols, 0 <= y < rows, where cols and rows are the size of window.
For variable sized windows, like the status window, the behavior when curs is called outside the window's limits is unspecified. The mac port wraps to 0, with the status window being 2 lines high and 80 columns wide.
Still used by curs_on_u()
, status updates, screen locating
(identify, teleport).
NHW_MESSAGE
, NHW_MENU
and NHW_TEXT
windows do not currently support curs in the tty window-port.
enum nhwindow_atr { ATR_NONE = 0, ATR_BOLD = 1, ATR_DIM = 2, ATR_ULINE = 4, ATR_BLINK = 5, ATR_INVERSE = 7 }; struct putstr_req { int window; enum nhwindow_atr attr; string str<>; };putstr returns no results.
Print str on the window with the given attribute. Only
printable ASCII characters (040-0126) must be supported.
Multiple putstrs are output on separate lines. Attributes
can be one of
ATR_NONE
(or 0),
ATR_ULINE
,
ATR_BOLD
,
ATR_BLINK
,
ATR_INVERSE
.
If a window-port does not support all of these, it may map
unsupported attributes to a supported one (e.g. map them
all to ATR_INVERSE
). putstr may compress spaces out of
str, break str, or truncate str, if necessary for the
display. Where putstr breaks a line, it has to clear
to end-of-line.
putstr should be implemented such that if two putstrs
are done consecutively the user will see the first and
then the second. In the tty port, pline()
achieves this
by calling more()
or displaying both on the same line.
struct display_file_req { int fh; };display_file returns no results.
Display the file whose handle is fh.
The proxy module is responsible for opening the file to be displayed as if the dlb_fopen callback had been called. The window-port should read the data from the file using the dlb_fopen callback (passing it fh as the handle). When the display_file procedure returns, the proxy module will close the file again.
The proxy module is responsible for complaining (via pline
)
if the file cannot be opened (in which case this procedure will not
be initiated).
struct start_menu_req { int window; };start_menu returns no results.
Start using window as a menu. You must call start_menu
before add_menu. After calling start_menu you may not
putstr to the window. Only windows of type NHW_MENU
may
be used for menus.
struct add_menu_req { int window; int glyph; int identifier; int accelerator; int groupacc; int attr; string str<>; bool preselected; };add_menu returns no results.
Add a text line str to the given menu window. If identifier is 0, then the line cannot be selected (e.g. a title). Otherwise, identifier is the value returned if the line is selected. accelerator is a keyboard key that can be used to select the line. If the accelerator of a selectable item is 0, the window system is free to select its own accelerator. It is up to the window-port to make the accelerator visible to the user (e.g. put a - in front of str). The value attr is the same as in putstr. glyph is an optional glyph to accompany the line. If window port cannot or does not want to display it, this is OK. If there is no glyph applicable, then this value will be -1 (converted from NO_GLYPH by the proxy module).
All accelerators should be in the range [A-Za-z].
It is expected that callers do not mix accelerator choices. Either all selectable items have an accelerator or let the window system pick them. Don't do both.
groupacc is a group accelerator. It may be any character outside of the standard accelerator (see above) or a number. If 0, the item is unaffected by any group accelerator. If this accelerator conflicts with the menu command (or their user defined alises), it loses. The menu commands and aliases take care not to interfere with the default object class symbols.
If you want this choice to be preselected when the
menu is displayed, set preselected to TRUE
.
The proxy module is responsible for converting the game's
anything
identifiers into integers (and back again in select_menu).
struct end_menu_req { int window; string prompt<>; };end_menu returns no results.
Stop adding entries to the menu and flushes the window to the screen (brings to front?). prompt is a prompt to give the user. If prompt is an empty string, no prompt will be printed.
This probably shouldn't flush the window any more (if it ever did). That should be select_menu's job. -dean
enum menu_pick { PICK_NONE = 0, /* user picks nothing (display only) */ PICK_ONE = 1, /* only pick one */ PICK_ANY = 2 /* can pick any amount */ }; struct select_menu_req { int window; enum menu_pick how; }; struct select_menu_res_item { int item; /* identifier */ long count; /* count */ }; struct select_menu_res { int retval; select_menu_res_item selected<>; };
Set retval to the number of items selected;
0 if none were chosen,
-1 when explicitly cancelled. If items were selected, then
selected is filled in with an array of select_menu_res_item
structures, one for each selected line. The count field
of selected is a user supplied count. If the user did
not supply a count, then the count field is filled with
-1 (meaning all). A count of zero is equivalent to not
being selected and should not be in the list. If no items
were selected, then selected is empty. how is the
mode of the menu. Three valid values are PICK_NONE
,
PICK_ONE
, and PICK_ANY
, meaning:
nothing is selectable,
only one thing is selectable, and any number valid items
may selected. If how is PICK_NONE
,
retval should never be set to anything but 0 or -1.
You may call select_menu on a window multiple times -- the menu is saved until start_menu or destroy_nhwindow is called on the window.
Note that NHW_MENU
windows need not have select_menu
called for them. There is no way of knowing whether
select_menu will be called for the window at
create_nhwindow time.
The proxy module is responsible for converting the integer identifiers back
to the original anything
value.
struct message_menu_req { int let; int how; string mesg<>; }; struct message_menu_res { int retval; };
tty-specific hack to allow single line context-sensitive help to behave compatibly with multi-line help menus.
This should only be called when a prompt is active; it sends mesg to the message window. For tty, it forces a --More-- prompt and enables let as a viable keystroke for dismissing that prompt, so that the original prompt can be answered from the message line "help menu".
retval is either let, 0 (no selection was made), or 27 (explicit cancellation was requested).
Interfaces which issue prompts and messages to separate
windows typically won't need this functionality, and should
set retval to -1 (in which case the proxy module will
arrange for the message to be output via pline()
instead).
ALI: What does how do?
Indicate to the window port that the inventory has been changed.
Merely calls the display_inventory callback for window-ports that leave the window up, otherwise does nothing.
Don't go beyond this point in I/O on any channel until all channels are caught up to here. Can be an empty call for the moment
Wait until all pending output is complete (flush() for streams goes here).
May also deal with exposure events etc., so that the display is OK when return from wait_synch.
struct cliparounf_req { int x; int y; };cliparound returns no values.
Make sure that the user is more-or-less centered on the screen if the playing area is larger than the screen.
struct update_positionbar_req { string features<>; };update_positionbar returns no values.
Provide some additional information for use in a horizontal position bar (most useful on clipped displays). features is a series of char pairs. The first char in the pair is a symbol and the second char is the column where it is currently located. A '<' is used to mark an upstairs, a '>' for a downstairs, and an '@' for the current player location.
struct print_glyph_req { int window; int x; int y; int glyph; };print_glyph returns no values.
Print glyph at (x,y) on the given window. Glyphs are integers at the interface, mapped to whatever the window-port wants (symbol, font, color, attributes, ...there's a 1-1 map between glyphs and distinct things on the map).
struct raw_print_req { string str<>; };raw_print returns no values.
Print directly to a screen, or otherwise guarantee that the user sees str. raw_print appends a newline to str. It need not recognize ASCII control characters. This is used during startup (before windowing system initialization -- maybe this means only error startup messages are raw), for error messages, and maybe other "msg" uses. E.g. updating status for micros (i.e, "saving").
struct raw_print_bold_req { string str<>; };raw_print_bold returns no values.
Like raw_print, but prints in bold/standout (if possible).
struct nhgetch_res { int ch; };
Sets ch to a single character input from the user.
In the tty window-port, nhgetch assumes that tgetch()
will be the routine the OS provides to read a character.
The character returned must be non-zero.
enum mouse_click { CLICK_1 = 1, /* mouse click type 1 */ CLICK_2 = 2 /* mouse click type 2 */ }; struct nh_poskey_res { int retval; int x; int y; enum mouse_click mod; };
Returns a single character input from the user or a positioning event (perhaps from a mouse). If retval is non-zero, a character was typed, else, a position in the MAP window is returned in x, y and mod.
The different click types can map to whatever the hardware supports. If no mouse is supported, this routine always sets retval to a non-zero character.
Beep at user. [This will exist at least until sounds are redone, since sounds aren't attributable to windows anyway.]
struct doprev_message_res { int retval; };
Display previous messages. Used by the ^P command.
On the tty-port this scrolls WIN_MESSAGE back one line.
ALI: What purpose does retval serve?
struct yn_function_req { string ques<>; string choices<>; int default_response; }; struct yn_function_res { int retval; int count; };
Print a prompt made up of ques, choices and default. Read a single character response that is contained in choices or default. If choices is empty, all possible inputs are accepted and returned. This overrides everything else. The choices are expected to be in lower case. Entering ESC always maps to 'q', or 'n', in that order, if present in choices, otherwise it maps to default. Entering any other quit character (SPACE, RETURN, NEWLINE) maps to default.
If the choices string contains ESC, then anything after it is an acceptable response, but the ESC and whatever follows is not included in the prompt.
If the choices string contains a '#' then accept a count. Place this value in count and set retval to '#'.
This uses the top line in the tty window-port, other ports might use a popup.
struct getlin_req { string ques<>; }; struct getlin_res { string input<>; };
Prints ques as a prompt and reads a single line of text, up to a newline. The string entered is returned in input without the newline. ESC is used to cancel, in which case the string "\033" is returned.
getlin must call the flush_screen callback with cursor_on_u set
to TRUE
before doing anything.
This uses the top line in the tty window-port, other ports might use a popup.
struct get_ext_cmd_res { int extcmd; };
Get an extended command in a window-port specific way. An index into the extended command list (readable with the get_extended_commands callback) is returned on a successful selection, -1 otherwise.
enum number_pad_mode { NP_KEYPAD = -1, /* activate keypad mode (escape sequences) */ NP_NUMERIC = 1 /* activate numeric mode for keypad (digits) */ }; struct number_pad_req { enum number_pad_mode state; };number_pad returns no values.
Initialize the number pad to the given state.
Causes a visible delay of 50ms in the output. Conceptually, this is similar to wait_synch() followed by a nap(50ms), but allows asynchronous operation.
struct change_color_req { int color; int rgb; bool reverse; };change_color returns no values.
struct change_background_req { bool white_or_black; };change_background returns no values.
struct set_font_name_req { int window; string font<>; }; struct set_font_name_res { int retval; };
struct get_color_string_res { string retval<>; };
Only used on Unix tty ports. Sets up the tty to work in full-screen graphics mode. Look at win/tty/termcap.c for an example.
Only used on Unix tty ports. The complement of start_screen().
struct outrip_req { int window; string killed_by_prefix<>; }; struct outrip_res { bool handled; };
The tombstone code. If you want the traditional code set handled
to FALSE
(the proxy module will then call genl_outrip
).
ALI: I suspect we should pass rather more information to this procedure;
genl_outrip()
uses a lot of global variables.