Convert a room- or map-relative coordinate to absolute. Can accept one table with x and y keys (and in that case, returns similar), or two integer values (and returns two integer values) des, nh, and obj routines all treat inputs as relative coordinates, but this is here in case an absolute one is needed for some reason (debugging?).

Example:

Returns a string with "a " or "an " prepended to it.

Example:

Add or remove a lua function to callback list. First argument is the callback list, second is the name of the lua function to be called. Two arguments adds the callback, if optional 3rd argument is true, removes the callback. Cannot add the same function to the same callback list does nothing.

Example:

Set debugging flags.

Example:

Returns the full dungeon name (as defined in dungeon.lua) for the dungeon number given as parameter.

Example:

Execute gameloop once, or until multi-turn action is done if optional boolean parameter is true.

Example:

Returns a string replacing special format chars with game data. Only available if NetHack was compiled with DUMPLOG.

Example:

Return the key bound to an extended command, or the full extended command name, if it is not bound to any key.

Example:

Asks the player for a text to enter, and returns the entered string.

Example:

Get information about the map location. Returns a table with the following elements:

Example:

Get current value of a boolean or a compound configuration option.

Example:

Get trap info at x,y Returns a table with the following elements:

Example:

Does location at x,y have a timer?

Example:

Delete a trap at x,y

Example:

Issue an impossible, signaling a possible error in the code.

Example:

Construct a gerund (a verb formed by appending "ing" to a noun).

Example:

Returns an integer value describing the level difficulty. Normally this is the level’s physical depth from the surface.

Example:

Pluralize the given string.

Example:

Make the given string singular.

Example:

Show a menu to the player.

Synopsis:

• prompt is a string.

• default is the default returned value, if player cancelled the menu.

• pickx is how many entries user is allowed to choose, one of "none", "one" or "any".

Options is a table with either { "key" = "text" }, or { { key : "a", text: "text of option a"} }.

Example:

Parse string as if it was read from a config file. Always call parse_config_errors afterwards to check for any parsing errors.

Example:

Returns any errors found when parsing a config file string with parse_config.

Example:

When does timer at location at x,y trigger? See [_timer_types].

Example:

Show the text in the message area. Second parameter is an optional boolean; if true, force a --more-- prompt.

Example:

Push a key into the command queue.

Example:

Generate a random number.

Example:

Generate a random number.

Example:

Return a string converted to possessive.

Example:

Returns an array of stairway data. Each entry is a hash with the following keys:

Example:

Start a timer at location x,y, with trigger time of when - relative to current turn. See [_timer_types].

Example:

Stop a timer at location x,y. See [_timer_types].

Example:

Show long texts in a menu window. Wordwraps automatically.

Example:

Set or get a global variable. These are persistent, saved and restored along with the game. Supports only strings, booleans, numbers, or tables.

Example:

Show the text in the message area as if someone said it, obeying eg. hero’s deafness.

Example:

Create an altar of certain type and alignment.

• align is one of "noalign", "law", "neutral", "chaos", "coaligned", "noncoaligned", or "random", defaulting to "random".

• type is one of "altar", "shrine", or "sanctum", defaulting to "altar".

Example:

Create a random corridor from one room to another.

• srcwall and destwall are one of "all", "random", "north", "west", "east", or "south", defaulting to "all".

Example:

Create a door at a coordinate on the map, or in a room’s wall. When adding a door to a [_room], it must be added after the subrooms in the room.

• state is one of "random", "open", "closed", "locked", "nodoor", "broken", or "secret", defaulting to "random".

Example:

Create a drawbridge. Location is where the open drawbridge would be, and there should be a wall when moving one step towards the diven direction; this is where the portcullis will be placed.

• dir is one of "north", "south", "west", "east", or "random".

• state is one of "open", "closed", or "random".

Example:

Create an engraving.

• type is one of "dust", "engrave", "burn", "mark", or "blood".

• optional boolean degrade defaults to true; engraving can degrade or be wiped out.

• optional boolean guardobjects defaults to false (unless making a level and the text is "Elbereth"); are items on the engraving protected from monsters.

Example:

Create a feature, and set flags for it. Valid features are a fountain, a sink, a pool, a throne, or a tree. Throne has looted flag, tree has looted and swarm, fountain has looted and warned, sink has pudding, dishwasher, and ring.

Example:

Only used for testing purposes. See also [_reset_level].

Example:

Create a pile of gold.

Example:

Create a grave. A missing text results in a random epitaph being used.

Example:

Create a ladder.

Example:

Set flags for this level.

Example:

Initialize the map with a random generator of a certain type.

Example:

Create a region where a stair, a branch stair, or a portal is created, or a region which limits teleportation.

• type is one of "stair-down", "stair-up", "portal", "branch", "teleport", "teleport-up", or "teleport-down".

• name is used for portals as the target level name.

Example:

Construct a piece of the level from text map. Takes one parameter, either a text string describing the map, or a table with multiple parameters. Returns a [_selection] where the map locations were put down on. If a contents-function is used, the commands following the map are not relative to it.

Example:

Create a maze.

• dir is one of "north", "south", "east", "west", or "random", and tells which direction the maze creation starts. Default is "random".

• stocked tells whether the maze is stocked with default monsters and objects.

• typ is the map terrain used for the walkable parts of the maze.

Example:

Message shown to the player when entering the level for the first time.

Example:

Place random gems, gold, and kelp on the level.

Example:

Create a monster.

The hash parameter accepts the following keys:

Example:

Set walls in an area of the map as non-diggable. See also: [_wall_property].

Example:

Set walls in an area of the map as non-passwall, so they can’t be phased through. See also: [_wall_property].

Example:

Create an object. Returns the object as an Obj class. The table parameter accepts the following:

Example:

Create random corridors between rooms.

Example:

Create a room region, which can be irregular; use the boundary map character to restrict the floodfilled area.

If using the first form with a selection and "lit", the lit area will extend outward 1 space from the selection to attempt to accomodate adjacent walls, regardless of whether they are actually walls or not. If using "unlit", this will not happen.

Example:

Replaces matching terrain on the area, selection, or whole map. The mapfragment case is similar to the selection [_match], but the replacement is done immediately when matched.

Example:

Only used for testing purposes. See also [_finalize_level].

Example:

Create a room of certain type and size. Takes one parameter, a table with the following fields:

Create stairs.

Example:

Example:

Example:

Create a trap. The launchfrom is relative to the rolling boulder trap coord.

Example:

Set walls in an area nondiggable or non-passwall. See also: [_non_diggable] and [_non_passwall].

Example:

Example:

Create a new selection.

Example:

Choose locations that are selected in both selections.

Example:

Choose locations that are selected in either or both selections. The addition operator also does this.

Example:

Choose locations in either selection, but not both.

Example:

Choose locations in the first selection but not in the second selection.

Example:

Alias for [_fillrect].

Get the bounding box for the selection. Returns a table with lx, ly, hx, hy integer fields.

Example:

Example:

Clone a selection.

Example:

Example:

Example:

Filter points in selection by choosing those that match the map character, and optionally the light state of the map location.

lit can be 1 or 0 (which matches the lit or unlit locations), or -1, in which case it will choose either all lit or all unlit map locations.

Example:

Select locations by starting floodfill at (x,y), matching the same map terrain in cardinal directions. If the optional third parameter is true, also checks diagonals.

Example:

Get the selection value at (x,y).

Example:

Create a "gradient" of selected positions, radiating outward from a center point or line. x and y are required; x2 and y2 are not required. If they are provided and are different from x and y, the center of the gradient will be a line; otherwise it will be a point source at (x,y). type is either "radial" or "square"; defaults to "radial" if not provided. mindist is not required and is 0 by default. Points within (mindist) tiles of the center will always be added to the selection. maxdist is required. Points more than (maxdist) tiles from the center will never be added to the selection. For any given point between mindist and maxdist, there is a random chance it will be added to the selection; this chance starts at 100% at mindist and decreases linearly to 0% at maxdist.

Example:

Add locations to the selection by choosing unselected locations to the given direction from selected locations. If no direction is given, picks all directions.

Example:

Iterate through the selection, calling a function for each set point.

Example:

Draw a line from (x1,y1) to (x2,y2).

Example:

Every location on the map, centered on the map fragment and matching it, are added to the selection. The map fragment must have odd width and height, and the center must not be the "transparent" map character.

Example:

Negate the selection. Alias for "unary minus" and "bitwise not".

Example:

Return the number of points in the selection.

Example:

Each selected location has a percentage chance of being selected in the new selection.

Example:

Example:

Draw a rectangle.

Example:

Choose one of the selected locations, and return a table with x and y keys. If the optional second argument is 1, removes the location from the selection. If there are no coordinates in the selection, returns -1, -1.

Example:

Create a selection of locations inside the (current) room.

Example:

Set the value for location (x,y) in the selection.

Example:

Create a new object via wishing routine.

Example:

Is the object a "null" object? Meaning, the object variable exists in lua, but NetHack core has freed it.

Example:

Get the topmost object on the map at x,y.

Example:

Get the next object in the object chain. When called without an object, returns the first object in the object chain. When called with an object, an optional boolean parameter can be given. When it is true, and the object is on the map, the next object at the same location is returned. Otherwise the normal object chain is followed.

Example:

Create a lua table representation of the object, unpacking all the object fields.

Example:

Get a lua table of object class data.

Example:

Place object on the map at x,y.

Example:

Get the container object is in.

Example:

Get the contents of an object.

Example:

Put object inside another object.

Example:

Does object have an attached timer of certain type? See [_timer_types].

Example:

Peek at an object timer. Returns the turn when timer triggers. Returns 0 if no such timer attached to the object. See [_timer_types].

Example:

Stop object timer(s). Return the turn when timer would have triggered. Returns 0 if no such timer was attached to the object. Without a timer type parameters, stops all timers for the object, and returns nothing. See [_timer_types].

Example:

Start an object timer. See [_timer_types].

Example:

Bury an object. Returns true if object is gone (merged with ground), false otherwise. Without parameters, buries the object at the location it is.

Example: