NetHack 4 Network Protocol

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.

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
• 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
• 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