Difference between revisions of "NetHack 4 Network Protocol"

From NetHackWiki
Jump to navigation Jump to search
(prompt placement hints being added in upcoming patch :-D)
Line 2: Line 2:
  
 
The protocol is based on JSON. Each client command and each server response is a single, valid JSON object in UTF8 encoding.
 
The protocol is based on JSON. Each client command and each server response is a single, valid JSON object in UTF8 encoding.
−
 
−
 
  
 
== Interaction ==
 
== Interaction ==
−
Once the client has connected to the server, it must send either an <tt>auth</tt> or a <tt>register</tt> command. If the client sends a successful register command, a following <tt>auth</tt> command is not necessary. When the client is authenticated any other command may be sent to the server.
+
Once the client has connected to the server, it must send either an <tt>auth</tt> or a <tt>register</tt> command. If the client sends a successful register command, a following <tt>auth</tt> command is not necessary. When the client is authenticated any other command may be sent to the server.
−
 
 
−
Normal flow is driven by the client sending commands and receiving responses from the server.  Server responses can also carry an attached <tt>display</tt> element with map updates (see later in this document).  Sometimes the server might need further information to complete a command; in this case a server request will be sent to the client, for which a response must be sent to the server.
 
−
 
 
  
 +
Normal flow is driven by the client sending commands and receiving responses from the server. Server responses can also carry an attached <tt>display</tt> element with map updates (see later in this document). Sometimes the server might need further information to complete a command; in this case a server request will be sent to the client, for which a response must be sent to the server.
  
 
== Client commands ==
 
== Client commands ==
 
These commands are sent by the client, expecting a response from the server.
 
These commands are sent by the client, expecting a response from the server.
−
 
  
 
=== auth ===
 
=== auth ===
Line 35: Line 30:
 
**[1]  integer
 
**[1]  integer
 
**[2]  integer
 
**[2]  integer
−
 
  
 
=== describe_pos ===
 
=== describe_pos ===
Line 53: Line 47:
 
* '''objdesc''':  string
 
* '''objdesc''':  string
 
* '''trapdesc''':  string
 
* '''trapdesc''':  string
−
 
  
 
=== exit_game ===
 
=== exit_game ===
Line 67: Line 60:
 
Arguments:
 
Arguments:
 
* '''return''':  boolean
 
* '''return''':  boolean
−
 
  
 
=== game_command ===
 
=== game_command ===
Line 95: Line 87:
 
**[8]  GAME_PANICKED;  something went wrong in libnethack and panic() was called
 
**[8]  GAME_PANICKED;  something went wrong in libnethack and panic() was called
 
**[9]  ERR_FORCED_EXIT;  exit from the command loop was forced by a call to nh_exit_game
 
**[9]  ERR_FORCED_EXIT;  exit from the command loop was forced by a call to nh_exit_game
−
**[10]  ERR_GAME_NOT_RUNNING;  possibilities: the init sequence was incorrect and the game is not running YET or some api call other than nh_do_move caused a panic, which killed the game or an attempt was made to call nh_do_move after some other final status (>= GAME_OVER) was returned
+
**[10]  ERR_GAME_NOT_RUNNING;  possibilities: the init sequence was incorrect and the game is not running YET or some api call other than nh_do_move caused a panic, which killed the game or an attempt was made to call nh_do_move after some other final status (>= GAME_OVER) was returned.
  
 
==== Type: direction ====
 
==== Type: direction ====
Line 112: Line 104:
 
**[10]  DIR_SELF
 
**[10]  DIR_SELF
 
**[-1]  DIR_NONE
 
**[-1]  DIR_NONE
−
 
  
 
=== get_commands ===
 
=== get_commands ===
Line 125: Line 116:
 
** '''flags''':  bitflags
 
** '''flags''':  bitflags
 
** '''name''':  string
 
** '''name''':  string
−
 
  
 
=== get_drawing_info ===
 
=== get_drawing_info ===
Line 160: Line 150:
 
**[1]  charcode ''("character")''
 
**[1]  charcode ''("character")''
 
**[2]  colourcode ''("colour")''
 
**[2]  colourcode ''("colour")''
−
 
  
 
=== get_obj_commands ===
 
=== get_obj_commands ===
Line 174: Line 163:
 
** '''flags''':  bitflags
 
** '''flags''':  bitflags
 
** '''name''':  string
 
** '''name''':  string
−
 
  
 
=== get_options ===
 
=== get_options ===
Line 213: Line 201:
 
** '''oclass''':  integer
 
** '''oclass''':  integer
 
** '''pattern''':  string
 
** '''pattern''':  string
−
 
  
 
=== get_pl_prompt ===
 
=== get_pl_prompt ===
Line 225: Line 212:
 
Arguments:
 
Arguments:
 
* '''prompt''':  string
 
* '''prompt''':  string
−
 
  
 
=== get_roles ===
 
=== get_roles ===
Line 246: Line 232:
 
* '''rolenames_f''':  list of string
 
* '''rolenames_f''':  list of string
 
* '''rolenames_m''':  list of string
 
* '''rolenames_m''':  list of string
−
 
  
 
=== get_root_pl_prompt ===
 
=== get_root_pl_prompt ===
Line 258: Line 243:
 
Arguments:
 
Arguments:
 
* '''prompt''':  string
 
* '''prompt''':  string
−
 
  
 
=== get_topten ===
 
=== get_topten ===
Line 312: Line 296:
 
**[14]  ESCAPED
 
**[14]  ESCAPED
 
**[15]  ASCENDED
 
**[15]  ASCENDED
−
 
  
 
=== list_games ===
 
=== list_games ===
Line 341: Line 324:
 
***[-1]  LS_INVALID;  not a nethack log/savegame
 
***[-1]  LS_INVALID;  not a nethack log/savegame
 
***[-2]  LS_CRASHED;  the game crashed (or was SIGKILLed)
 
***[-2]  LS_CRASHED;  the game crashed (or was SIGKILLed)
−
 
  
 
=== register ===
 
=== register ===
Line 362: Line 344:
 
**[1]  integer
 
**[1]  integer
 
**[2]  integer
 
**[2]  integer
−
 
  
 
=== restore_game ===
 
=== restore_game ===
Line 378: Line 359:
 
**[5]  ERR_RESTORE_FAILED;  restoring the saved game state did not succeed, maybe try replaying the log instead
 
**[5]  ERR_RESTORE_FAILED;  restoring the saved game state did not succeed, maybe try replaying the log instead
 
**[6]  ERR_REPLAY_FAILED;  replaying the action log did not succeed
 
**[6]  ERR_REPLAY_FAILED;  replaying the action log did not succeed
−
 
  
 
=== set_email ===
 
=== set_email ===
Line 387: Line 367:
 
Arguments:
 
Arguments:
 
* '''return''':  boolean
 
* '''return''':  boolean
−
 
  
 
=== set_option ===
 
=== set_option ===
Line 438: Line 417:
 
** '''oclass''':  integer
 
** '''oclass''':  integer
 
** '''pattern''':  string
 
** '''pattern''':  string
−
 
  
 
=== set_password ===
 
=== set_password ===
Line 447: Line 425:
 
Arguments:
 
Arguments:
 
* '''return''':  boolean
 
* '''return''':  boolean
−
 
  
 
=== shutdown ===
 
=== shutdown ===
Line 457: Line 434:
  
 
Always returns 1.
 
Always returns 1.
−
 
  
 
=== start_game ===
 
=== start_game ===
Line 472: Line 448:
 
* '''return''':  boolean
 
* '''return''':  boolean
  
−
Returns true if a game is successfully created. A gameid of -1 also means failure, so check both.
+
Returns true if a game is successfully created. A gameid of -1 also means failure, so check both.
  
 
==== Type: gamemode ====
 
==== Type: gamemode ====
Line 480: Line 456:
 
**[1]  MODE_EXPLORE
 
**[1]  MODE_EXPLORE
 
**[2]  MODE_WIZARD
 
**[2]  MODE_WIZARD
−
 
  
 
=== view_finish ===
 
=== view_finish ===
Line 487: Line 462:
 
==== view_finish response ====
 
==== view_finish response ====
 
Arguments: none
 
Arguments: none
−
 
  
 
=== view_start ===
 
=== view_start ===
Line 502: Line 476:
 
** '''nextcmd''':  string
 
** '''nextcmd''':  string
 
* '''return''':  boolean
 
* '''return''':  boolean
−
 
  
 
=== view_step ===
 
=== view_step ===
Line 526: Line 499:
 
** '''nextcmd''':  string
 
** '''nextcmd''':  string
 
* '''return''':  boolean
 
* '''return''':  boolean
−
 
−
 
  
 
== Server requests ==
 
== Server requests ==
 
These requests are sent by the server, expecting a response from the client.
 
These requests are sent by the server, expecting a response from the client.
−
 
  
 
=== display_menu ===
 
=== display_menu ===
Line 563: Line 533:
 
**[1]  MI_NORMAL
 
**[1]  MI_NORMAL
 
**[2]  MI_HEADING
 
**[2]  MI_HEADING
−
 
  
 
=== display_objects ===
 
=== display_objects ===
Line 583: Line 552:
 
* '''return''':  integer
 
* '''return''':  integer
  
−
I think this returns the number of objects selected. The list is possibly their indices in the input list? Plus a count, if partial stacks are taken.
+
I think this returns the number of objects selected. The list is possibly their indices in the input list? Plus a count, if partial stacks are taken.
  
 
==== Type: objitem ====
 
==== Type: objitem ====
Line 599: Line 568:
 
**[9]  charcode ''("group_accel")''
 
**[9]  charcode ''("group_accel")''
 
**[10]  boolean ''("worn")''
 
**[10]  boolean ''("worn")''
−
 
  
 
=== getdir ===
 
=== getdir ===
Line 609: Line 577:
 
Arguments:
 
Arguments:
 
* '''return''':  direction
 
* '''return''':  direction
−
 
  
 
=== getline ===
 
=== getline ===
Line 618: Line 585:
 
Arguments:
 
Arguments:
 
* '''line''':  string
 
* '''line''':  string
−
 
  
 
=== getpos ===
 
=== getpos ===
Line 639: Line 605:
  
 
The return value depends on which key the user used to finish off the selection.
 
The return value depends on which key the user used to finish off the selection.
−
 
  
 
=== query_key ===
 
=== query_key ===
Line 650: Line 615:
 
* '''count''':  integer
 
* '''count''':  integer
 
* '''return''':  charcode
 
* '''return''':  charcode
−
 
  
 
=== yn ===
 
=== yn ===
Line 663: Line 627:
 
Arguments:
 
Arguments:
 
* '''return''':  charcode
 
* '''return''':  charcode
−
 
  
 
=== server_error ===
 
=== server_error ===
Line 671: Line 634:
  
 
There is no expected response.
 
There is no expected response.
−
 
−
 
  
 
== Display elements ==
 
== Display elements ==
−
Any message sent by the server, whether as a request or a response, might have a <tt>display</tt> element attached, which specifies updates to the map. The exceptions are <tt>auth</tt> and <tt>register</tt>, which never carry map data. The <tt>display</tt> element is an array of elements to draw; each element can be one of the below types.
+
Any message sent by the server, whether as a request or a response, might have a <tt>display</tt> element attached, which specifies updates to the map. The exceptions are <tt>auth</tt> and <tt>register</tt>, which never carry map data. The <tt>display</tt> element is an array of elements to draw; each element can be one of the below types.
−
 
 
  
 
=== delay_output ===
 
=== delay_output ===
 
Value:
 
Value:
 
* '''delay_output''':  nil
 
* '''delay_output''':  nil
−
 
  
 
=== display_buffer ===
 
=== display_buffer ===
Line 688: Line 647:
 
** '''buf''':  string
 
** '''buf''':  string
 
** '''trymove''':  boolean
 
** '''trymove''':  boolean
−
 
  
 
=== level_changed ===
 
=== level_changed ===
Line 699: Line 657:
 
**[4]  LDM_SOKOBAN
 
**[4]  LDM_SOKOBAN
 
**[5]  LDM_ROGUE
 
**[5]  LDM_ROGUE
−
 
  
 
=== list_items ===
 
=== list_items ===
Line 709: Line 666:
  
 
If the invent flag is on then this is a list of items in inventory; otherwise, a list of items on the floor.
 
If the invent flag is on then this is a list of items in inventory; otherwise, a list of items on the floor.
−
 
  
 
=== outrip ===
 
=== outrip ===
Line 728: Line 684:
 
** '''tombstone''':  boolean
 
** '''tombstone''':  boolean
 
** '''year''':  integer
 
** '''year''':  integer
−
 
  
 
=== pause ===
 
=== pause ===
Line 737: Line 692:
  
 
The value is the reason for pausing.
 
The value is the reason for pausing.
−
 
  
 
=== print_message ===
 
=== print_message ===
Line 744: Line 698:
 
** '''msg''':  string
 
** '''msg''':  string
 
** '''turn''':  integer
 
** '''turn''':  integer
−
 
  
 
=== print_message_nonblocking ===
 
=== print_message_nonblocking ===
Line 751: Line 704:
 
** '''msg''':  string
 
** '''msg''':  string
 
** '''turn''':  integer
 
** '''turn''':  integer
−
 
  
 
=== raw_print ===
 
=== raw_print ===
 
Value:
 
Value:
 
* '''raw_print''':  string
 
* '''raw_print''':  string
−
 
  
 
=== update_screen ===
 
=== update_screen ===
Line 765: Line 716:
 
** '''ux''':  coordinate
 
** '''ux''':  coordinate
  
−
A map delta can be an integer 0 if nothing at all has changed. Otherwise it is a list of column deltas. A column delta of 0 means that column is empty, and 1 means it is unchanged since last time. Otherwise a column delta is a list of cell deltas. Again, 0 means empty, 1 means unchanged. Otherwise the cell delta is a simple list, as below.
+
A map delta can be an integer 0 if nothing at all has changed. Otherwise it is a list of column deltas. A column delta of 0 means that column is empty, and 1 means it is unchanged since last time. Otherwise a column delta is a list of cell deltas. Again, 0 means empty, 1 means unchanged. Otherwise the cell delta is a simple list, as below.
  
 
==== Type: mapdeltacell ====
 
==== Type: mapdeltacell ====
Line 780: Line 731:
 
**[8]  integer ''("invis")''
 
**[8]  integer ''("invis")''
 
**[9]  integer ''("visible")''
 
**[9]  integer ''("visible")''
−
 
  
 
=== update_status ===
 
=== update_status ===
Line 816: Line 766:
 
** '''y''':  coordinate
 
** '''y''':  coordinate
 
** '''z''':  coordinate
 
** '''z''':  coordinate
−
 
−
 
  
 
== Summary of selected types ==
 
== Summary of selected types ==
−
Here are the structures of certain types mentioned above. A few types are implemented as simple arrays rather than structures, for performance reasons.
+
Here are the structures of certain types mentioned above. A few types are implemented as simple arrays rather than structures, for performance reasons.
−
 
 
  
 
=== Assorted integral types ===
 
=== Assorted integral types ===
Line 947: Line 894:
 
*[6]  PLHINT_CONTAINER;  Similar to PLHINT_INVENTORY, but for things not actually in inventory (in case clients want to put those alongside)
 
*[6]  PLHINT_CONTAINER;  Similar to PLHINT_INVENTORY, but for things not actually in inventory (in case clients want to put those alongside)
 
*[7]  PLHINT_INVENTORY;  Probably placed on top of the inventory pane if it exists
 
*[7]  PLHINT_INVENTORY;  Probably placed on top of the inventory pane if it exists
−
These are hints about prompt positioning. The exact interpretation is up to the client implementation.
+
 
 +
These are hints about prompt positioning. The exact interpretation is up to the client implementation.
 +
{{variant-343}}
 +
[[Category:Annotations]]
 +
[[Category:Variants]]

Revision as of 01:41, 11 October 2012

This is a description of the NetHack 4 networking protocol.

The protocol is based on JSON. Each client command and each server response is a single, valid JSON object in UTF8 encoding.

Contents

Interaction

Once the client has connected to the server, it must send either an auth or a register command. If the client sends a successful register command, a following auth command is not necessary. When the client is authenticated any other command may be sent to the server.

Normal flow is driven by the client sending commands and receiving responses from the server. Server responses can also carry an attached display element with map updates (see later in this document). Sometimes the server might need further information to complete a command; in this case a server request will be sent to the client, for which a response must be sent to the server.

Client commands

These commands are sent by the client, expecting a response from the server.

auth

Arguments:

  • password: string
  • reconnect: connid (optional)
  • username: string

auth response

Arguments:

  • connection: connid
  • return: an enumerated value:
    • [0] NO_CONNECTION
    • [1] AUTH_FAILED_UNKNOWN_USER
    • [2] AUTH_FAILED_BAD_PASSWORD
    • [3] AUTH_SUCCESS_NEW
    • [4] AUTH_SUCCESS_RECONNECT
  • version: simple array:
    • [0] integer
    • [1] integer
    • [2] integer

describe_pos

Arguments:

  • is_in: boolean
  • x: coordinate
  • y: coordinate

describe_pos response

Arguments:

  • bgdesc: string
  • effectdesc: string
  • in: boolean
  • invisdesc: string
  • mondesc: string
  • objcount: integer
  • objdesc: string
  • trapdesc: string

exit_game

Arguments:

  • exit_type: an enumerated value:
    • [0] EXIT_REQUEST_SAVE
    • [1] EXIT_FORCE_SAVE
    • [2] EXIT_REQUEST_QUIT
    • [3] EXIT_FORCE_QUIT
    • [4] EXIT_PANIC

exit_game response

Arguments:

  • return: boolean

game_command

Arguments:

  • arg:
    • argtype: integer
    • d: direction (optional)
    • invlet: charcode (optional)
    • x: coordinate (optional)
    • y: coordinate (optional)
  • command: string
  • count: integer

The argtype parameter can be 2 (no arguments), 4 (directional argument), 8 (coordinate pair), 16 (inventory letter).

game_command response

Arguments:

  • return: an enumerated value:
    • [0] READY_FOR_INPUT
    • [1] MULTI_IN_PROGRESS
    • [2] OCCUPATION_IN_PROGRESS
    • [3] POST_ACTION_DELAY
    • [4] ERR_NO_INPUT_ALLOWED
    • [5] ERR_COMMAND_FORBIDDEN; tried to alter the game state while viewing a replay
    • [6] GAME_OVER; i.e. player died
    • [7] GAME_SAVED
    • [8] GAME_PANICKED; something went wrong in libnethack and panic() was called
    • [9] ERR_FORCED_EXIT; exit from the command loop was forced by a call to nh_exit_game
    • [10] ERR_GAME_NOT_RUNNING; possibilities: the init sequence was incorrect and the game is not running YET or some api call other than nh_do_move caused a panic, which killed the game or an attempt was made to call nh_do_move after some other final status (>= GAME_OVER) was returned.

Type: direction

A datum of type "direction" has the following structure:

  • direction: an enumerated value:
    • [0] DIR_W
    • [1] DIR_NW
    • [2] DIR_N
    • [3] DIR_NE
    • [4] DIR_E
    • [5] DIR_SE
    • [6] DIR_S
    • [7] DIR_SW
    • [8] DIR_UP
    • [9] DIR_DOWN
    • [10] DIR_SELF
    • [-1] DIR_NONE

get_commands

Arguments: none

get_commands response

Arguments:

  • cmdlist: list of:
    • alt: charcode
    • def: charcode
    • desc: string
    • flags: bitflags
    • name: string

get_drawing_info

Arguments: none

get_drawing_info response

Arguments:

  • bgelements: list of glyph
  • effects: list of glyph
  • explsyms: list of glyph
  • expltypes: list of glyph
  • feature_offset: integer
  • invis: list of glyph
  • monsters: list of glyph
  • num_bgelements: integer
  • num_effects: integer
  • num_expltypes: integer
  • num_monsters: integer
  • num_objects: integer
  • num_traps: integer
  • num_warnings: integer
  • num_zaptypes: integer
  • objects: list of glyph
  • swallowsyms: list of glyph
  • traps: list of glyph
  • warnings: list of glyph
  • zapsyms: list of glyph
  • zaptypes: list of glyph

Type: glyph

A datum of type "glyph" has the following structure:

  • glyph: simple array:
    • [0] string ("name")
    • [1] charcode ("character")
    • [2] colourcode ("colour")

get_obj_commands

Arguments:

  • invlet: charcode

get_obj_commands response

Arguments:

  • cmdlist: list of:
    • alt: charcode
    • def: charcode
    • desc: string
    • flags: bitflags
    • name: string

get_options

Arguments:

  • list: an enumerated value:
    • [0] CURRENT_BIRTH_OPTIONS
    • [1] ACTIVE_BIRTH_OPTIONS
    • [2] GAME_OPTIONS

get_options response

Arguments:

  • options: list of:
    • desc: exactly one of:
    • - nil
    • - structure:
        • max: integer
        • min: integer
    • - list of string
    • - integer ("length")
    • - list of string
    • helptxt: string
    • name: string
    • type: optiontype
    • value: exactly one of:
    • - boolean
    • - integer
    • - enumerated
    • - string
    • - list of autopickuprule

Type: autopickuprule

A datum of type "autopickuprule" has the following structure:

  • autopickuprule:
    • action: an enumerated value:
      • [0] AP_GRAB
      • [1] AP_LEAVE
    • buc: buccode
    • oclass: integer
    • pattern: string

get_pl_prompt

Arguments:

  • align: integer
  • gend: integer
  • race: integer
  • role: integer

get_pl_prompt response

Arguments:

  • prompt: string

get_roles

Arguments: none

get_roles response

Arguments:

  • alignnames: list of string
  • def_align: integer
  • def_gend: integer
  • def_race: integer
  • def_role: integer
  • gendnames: list of string
  • matrix: list of integer
  • num_aligns: integer
  • num_genders: integer
  • num_races: integer
  • num_roles: integer
  • racenames: list of string
  • rolenames_f: list of string
  • rolenames_m: list of string

get_root_pl_prompt

Arguments:

  • align: integer
  • gend: integer
  • race: integer
  • role: integer

get_root_pl_prompt response

Arguments:

  • prompt: string

get_topten

Arguments:

  • around: integer
  • own: boolean
  • player: string
  • top: integer

get_topten response

Arguments:

  • msg: string
  • toplist:
    • birthdate: integer
    • death: string
    • deathdate: integer
    • deaths: integer
    • end_how: endclass
    • entrytxt: string
    • highlight: boolean
    • hp: integer
    • maxhp: integer
    • maxlvl: integer
    • moves: integer
    • name: string
    • patchlevel: integer
    • plalign: string
    • plgend: string
    • plrace: string
    • plrole: string
    • points: integer
    • rank: integer
    • ver_major: integer
    • ver_minor: integer

Type: endclass

A datum of type "endclass" has the following structure:

  • endclass: an enumerated value:
    • [0] DIED
    • [1] CHOKING
    • [2] POISONING
    • [3] STARVING
    • [4] DROWNING
    • [5] BURNING
    • [6] DISSOLVED
    • [7] CRUSHING
    • [8] STONING
    • [9] TURNED_SLIME
    • [10] GENOCIDED
    • [11] PANICKED
    • [12] TRICKED
    • [13] QUIT
    • [14] ESCAPED
    • [15] ASCENDED

list_games

Arguments:

  • completed: boolean
  • limit: integer
  • show_all: boolean

list_games response

Arguments:

  • games: list of:
    • death: string (optional)
    • depth: integer (optional)
    • gameid: gameid
    • has_amulet: boolean (optional)
    • level_desc: string (optional)
    • moves: integer (optional)
    • plalign: string
    • playmode: gamemode
    • plgend: string
    • plname: string
    • plrace: string
    • plrole: string
    • status: an enumerated value:
      • [0] LS_SAVED; an ordinary save
      • [1] LS_DONE; quit, died, ascended, etc
      • [2] LS_IN_PROGRESS; this game is active in a different process
      • [-1] LS_INVALID; not a nethack log/savegame
      • [-2] LS_CRASHED; the game crashed (or was SIGKILLed)

register

Arguments:

  • email: string (optional)
  • password: string
  • username: string

register response

Arguments:

  • connection: connid
  • return: an enumerated value:
    • [0] NO_CONNECTION
    • [1] AUTH_FAILED_UNKNOWN_USER
    • [2] AUTH_FAILED_BAD_PASSWORD
    • [3] AUTH_SUCCESS_NEW
    • [4] AUTH_SUCCESS_RECONNECT
  • version: simple array:
    • [0] integer
    • [1] integer
    • [2] integer

restore_game

Arguments:

  • gameid: gameid

restore_game response

Arguments:

  • return: an enumerated value:
    • [0] GAME_RESTORED
    • [1] ERR_BAD_ARGS
    • [2] ERR_BAD_FILE; file isn't a saved game
    • [3] ERR_GAME_OVER; this is the log of a completed game, play cannot be resumed
    • [4] ERR_IN_PROGRESS; this game is active in a different process
    • [5] ERR_RESTORE_FAILED; restoring the saved game state did not succeed, maybe try replaying the log instead
    • [6] ERR_REPLAY_FAILED; replaying the action log did not succeed

set_email

Arguments:

  • email: string

set_email response

Arguments:

  • return: boolean

set_option

Arguments:

  • isstr: boolean
  • name: string
  • value: exactly one of:
  • - string
  • - integer
  • - list of autopickuprule

set_option response

Arguments:

  • option:
    • desc: exactly one of:
    • - nil
    • - structure:
        • max: integer
        • min: integer
    • - list of string
    • - integer ("length")
    • - list of string
    • helptxt: string
    • name: string
    • type: optiontype
    • value: exactly one of:
    • - boolean
    • - integer
    • - enumerated
    • - string
    • - list of autopickuprule
  • return: integer

Type: optiontype

A datum of type "optiontype" has the following structure:

  • optiontype: an enumerated value:
    • [0] OPTTYPE_BOOL
    • [1] OPTTYPE_INT
    • [2] OPTTYPE_ENUM
    • [3] OPTTYPE_STRING
    • [4] OPTTYPE_AUTOPICKUP_RULES

Type: autopickuprule

A datum of type "autopickuprule" has the following structure:

  • autopickuprule:
    • action: an enumerated value:
      • [0] AP_GRAB
      • [1] AP_LEAVE
    • buc: buccode
    • oclass: integer
    • pattern: string

set_password

Arguments:

  • password: string

set_password response

Arguments:

  • return: boolean

shutdown

Arguments: none

shutdown response

Arguments:

  • return: integer

Always returns 1.

start_game

Arguments:

  • alignment: integer
  • gender: integer
  • name: string
  • race: integer
  • role: integer

start_game response

Arguments:

  • gameid: gameid
  • return: boolean

Returns true if a game is successfully created. A gameid of -1 also means failure, so check both.

Type: gamemode

A datum of type "gamemode" has the following structure:

  • gamemode: an enumerated value:
    • [0] MODE_NORMAL
    • [1] MODE_EXPLORE
    • [2] MODE_WIZARD

view_finish

Arguments: none

view_finish response

Arguments: none

view_start

Arguments:

  • gameid: gameid

view_start response

Arguments:

  • info:
    • actions: integer
    • max_actions: integer
    • max_moves: integer
    • moves: integer
    • nextcmd: string
  • return: boolean

view_step

Arguments:

  • action: an enumerated value:
    • [0] REPLAY_FORWARD
    • [1] REPLAY_BACKWARD
    • [2] REPLAY_GOTO
  • count: integer
  • info:
    • actions: integer
    • max_actions: integer
    • max_moves: integer
    • moves: integer

view_step response

Arguments:

  • info:
    • actions: integer
    • max_actions: integer
    • max_moves: integer
    • moves: integer
    • nextcmd: string
  • return: boolean

Server requests

These requests are sent by the server, expecting a response from the client.

display_menu

Arguments:

  • how: an enumerated value:
    • [0] PICK_NONE
    • [1] PICK_ONE
    • [2] PICK_ANY
  • icount: integer
  • items: list of:
    • accel: charcode
    • caption: string
    • group_accel: charcode
    • id: integer
    • role: menurole
    • selected: boolean
  • plhint: placementhint
  • title: string

display_menu response

Arguments:

  • results: list of integer
  • return: integer

I think this returns the number of items selected, and their indices in the input list.

Type: menurole

A datum of type "menurole" has the following structure:

  • menurole: an enumerated value:
    • [0] MI_TEXT
    • [1] MI_NORMAL
    • [2] MI_HEADING

display_objects

Arguments:

  • how: an enumerated value:
    • [0] PICK_NONE
    • [1] PICK_ONE
    • [2] PICK_ANY
  • icount: integer
  • items: list of objitem
  • plhint: placementhint
  • title: string

display_objects response

Arguments:

  • pick_list: list of:
    • count: integer
    • id: integer
  • return: integer

I think this returns the number of objects selected. The list is possibly their indices in the input list? Plus a count, if partial stacks are taken.

Type: objitem

A datum of type "objitem" has the following structure:

  • objitem: simple array:
    • [0] string ("caption")
    • [1] integer ("id")
    • [2] menurole ("role")
    • [3] integer ("count")
    • [4] integer ("otype")
    • [5] integer ("oclass")
    • [6] integer ("weight")
    • [7] buccode ("buc")
    • [8] charcode ("accel")
    • [9] charcode ("group_accel")
    • [10] boolean ("worn")

getdir

Arguments:

  • query: string
  • restricted: boolean

getdir response

Arguments:

  • return: direction

getline

Arguments:

  • query: string

getline response

Arguments:

  • line: string

getpos

Arguments:

  • force: boolean
  • goal: string
  • x: coordinate
  • y: coordinate

getpos response

Arguments:

  • return: an enumerated value:
    • [0] SELECTED_DOT
    • [1] SELECTED_COMMA
    • [2] SELECTED_SEMICOLON
    • [3] SELECTED_COLON
    • [-1] ABORTED
  • x: coordinate
  • y: coordinate

The return value depends on which key the user used to finish off the selection.

query_key

Arguments:

  • allow_count: boolean
  • query: string

query_key response

Arguments:

  • count: integer
  • return: charcode

yn

Arguments:

  • def: charcode
  • query: string
  • set: string

Since the set of values is a parameter, you can use this for other tiny prompts too.

yn response

Arguments:

  • return: charcode

server_error

Arguments:

  • error: boolean
  • message: string

There is no expected response.

Display elements

Any message sent by the server, whether as a request or a response, might have a display element attached, which specifies updates to the map. The exceptions are auth and register, which never carry map data. The display element is an array of elements to draw; each element can be one of the below types.

delay_output

Value:

  • delay_output: nil

display_buffer

Value:

  • display_buffer:
    • buf: string
    • trymove: boolean

level_changed

Value:

  • level_changed: an enumerated value:
    • [0] LDM_DEFAULT
    • [1] LDM_HELL
    • [2] LDM_QUEST
    • [3] LDM_MINES
    • [4] LDM_SOKOBAN
    • [5] LDM_ROGUE

list_items

Value:

  • list_items:
    • icount: integer
    • invent: boolean
    • items: list of objitem

If the invent flag is on then this is a list of items in inventory; otherwise, a list of items on the floor.

outrip

Value:

  • outrip:
    • gold: integer
    • how: endclass
    • icount: integer
    • items: list of:
      • accel: charcode
      • caption: string
      • group_accel: charcode
      • id: integer
      • role: menurole
      • selected: boolean
    • killbuf: string
    • name: string
    • tombstone: boolean
    • year: integer

pause

Value:

  • pause: an enumerated value:
    • [0] P_MESSAGE
    • [1] P_MAP

The value is the reason for pausing.

print_message

Value:

  • print_message:
    • msg: string
    • turn: integer

print_message_nonblocking

Value:

  • print_message_nonblocking:
    • msg: string
    • turn: integer

raw_print

Value:

  • raw_print: string

update_screen

Value:

  • update_screen:
    • dbuf: mapdelta
    • uv: coordinate
    • ux: coordinate

A map delta can be an integer 0 if nothing at all has changed. Otherwise it is a list of column deltas. A column delta of 0 means that column is empty, and 1 means it is unchanged since last time. Otherwise a column delta is a list of cell deltas. Again, 0 means empty, 1 means unchanged. Otherwise the cell delta is a simple list, as below.

Type: mapdeltacell

A datum of type "mapdeltacell" has the following structure:

  • mapdeltacell: simple array:
    • [0] integer ("effect")
    • [1] integer ("bg")
    • [2] integer ("trap")
    • [3] integer ("obj")
    • [4] integer ("obj_mn")
    • [5] integer ("mon")
    • [6] integer ("monflags")
    • [7] integer ("branding")
    • [8] integer ("invis")
    • [9] integer ("visible")

update_status

Value:

  • update_status:
    • ac: integer
    • align: integer
    • can_enhance: boolean
    • ch: integer
    • co: integer
    • coinsym: charcode
    • cur_monnum: integer
    • dx: integer
    • en: integer
    • enmax: integer
    • gold: integer
    • hp: integer
    • hpmax: integer
    • in: integer
    • level: integer
    • level_desc: string
    • max_rank_sz: integer
    • monnum: integer
    • moves: integer
    • nr_items: integer
    • plname: string
    • rank: string
    • score: integer
    • st: integer
    • st_extra: integer
    • statusitems: list of string
    • wi: integer
    • x: coordinate
    • xp: integer
    • y: coordinate
    • z: coordinate

Summary of selected types

Here are the structures of certain types mentioned above. A few types are implemented as simple arrays rather than structures, for performance reasons.

Assorted integral types

All of the following are really just integers with a false nose and moustache.

  • All enumerated types
  • bitflags
  • boolean
  • charcode
  • connid
  • coordinate
  • gameid

autopickuprule

structure:

  • action: an enumerated value:
  • [0] AP_GRAB
  • [1] AP_LEAVE
  • buc: buccode
  • oclass: integer
  • pattern: string

buccode

an enumerated value:

  • [0] B_UNKNOWN
  • [1] B_BLESSED
  • [2] B_UNCURSED
  • [3] B_CURSED
  • [4] B_DONT_CARE; used for pattern matching only

direction

an enumerated value:

  • [0] DIR_W
  • [1] DIR_NW
  • [2] DIR_N
  • [3] DIR_NE
  • [4] DIR_E
  • [5] DIR_SE
  • [6] DIR_S
  • [7] DIR_SW
  • [8] DIR_UP
  • [9] DIR_DOWN
  • [10] DIR_SELF
  • [-1] DIR_NONE

endclass

an enumerated value:

  • [0] DIED
  • [1] CHOKING
  • [2] POISONING
  • [3] STARVING
  • [4] DROWNING
  • [5] BURNING
  • [6] DISSOLVED
  • [7] CRUSHING
  • [8] STONING
  • [9] TURNED_SLIME
  • [10] GENOCIDED
  • [11] PANICKED
  • [12] TRICKED
  • [13] QUIT
  • [14] ESCAPED
  • [15] ASCENDED

gamemode

an enumerated value:

  • [0] MODE_NORMAL
  • [1] MODE_EXPLORE
  • [2] MODE_WIZARD

glyph

simple array:

  • [0] string ("name")
  • [1] charcode ("character")
  • [2] colourcode ("colour")

mapdeltacell

simple array:

  • [0] integer ("effect")
  • [1] integer ("bg")
  • [2] integer ("trap")
  • [3] integer ("obj")
  • [4] integer ("obj_mn")
  • [5] integer ("mon")
  • [6] integer ("monflags")
  • [7] integer ("branding")
  • [8] integer ("invis")
  • [9] integer ("visible")

menurole

an enumerated value:

  • [0] MI_TEXT
  • [1] MI_NORMAL
  • [2] MI_HEADING

objitem

simple array:

  • [0] string ("caption")
  • [1] integer ("id")
  • [2] menurole ("role")
  • [3] integer ("count")
  • [4] integer ("otype")
  • [5] integer ("oclass")
  • [6] integer ("weight")
  • [7] buccode ("buc")
  • [8] charcode ("accel")
  • [9] charcode ("group_accel")
  • [10] boolean ("worn")

optiontype

an enumerated value:

  • [0] OPTTYPE_BOOL
  • [1] OPTTYPE_INT
  • [2] OPTTYPE_ENUM
  • [3] OPTTYPE_STRING
  • [4] OPTTYPE_AUTOPICKUP_RULES

placementhint

an enumerated value:

  • [0] PLHINT_ANYWHERE; The client can just stick this wherever it feels like.
  • [1] PLHINT_LEFT; At the left of the map display
  • [2] PLHINT_RIGHT; At the right of the map display
  • [3] PLHINT_URGENT; A very important prompt of some sort.
  • [4] PLHINT_INFO; An informational notice, rather than a "real" prompt.
  • [5] PLHINT_ONELINER; A short prompt or somesuch. Can probably be put on top of or inside the message pane if it exists.
  • [6] PLHINT_CONTAINER; Similar to PLHINT_INVENTORY, but for things not actually in inventory (in case clients want to put those alongside)
  • [7] PLHINT_INVENTORY; Probably placed on top of the inventory pane if it exists

These are hints about prompt positioning. The exact interpretation is up to the client implementation.

Retrieved from "https://nethackwiki.com/index.php?title=NetHack_4_Network_Protocol&oldid=80981"