Difference between revisions of "NetHack 4 Network Protocol"
m (start_game missing mode argument) |
|||
Line 442: | Line 442: | ||
* '''race''': integer | * '''race''': integer | ||
* '''role''': integer | * '''role''': integer | ||
+ | * '''mode''': gamemode | ||
==== start_game response ==== | ==== start_game response ==== |
Revision as of 03:20, 19 January 2013
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
- 1 Interaction
- 2 Client commands
- 2.1 auth
- 2.2 describe_pos
- 2.3 exit_game
- 2.4 game_command
- 2.5 get_commands
- 2.6 get_drawing_info
- 2.7 get_obj_commands
- 2.8 get_options
- 2.9 get_pl_prompt
- 2.10 get_roles
- 2.11 get_root_pl_prompt
- 2.12 get_topten
- 2.13 list_games
- 2.14 register
- 2.15 restore_game
- 2.16 set_email
- 2.17 set_option
- 2.18 set_password
- 2.19 shutdown
- 2.20 start_game
- 2.21 view_finish
- 2.22 view_start
- 2.23 view_step
- 3 Server requests
- 4 Display elements
- 5 Summary of selected types
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
- action: an enumerated value:
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
- action: an enumerated value:
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
- mode: gamemode
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.
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
Arguments:
- results: list of integer
- return: integer
I think this returns the number of items selected, and their indices in the input list.
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")
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.