= NetHack lua
:toc: right


== Core functions

Functions exposed from the NetHack core. They are all in the `nh` table.

=== an

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

Example:

 local str = nh.an("unicorn");


=== getlin

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

Example:

 local str = nh.getlin("What do you want to call this?");


=== getmap

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

|===
| field name | type     | description
| glyph      | integer  |
| typ        | integer  | terrain type
| typ_name   | text     | name of terrain type
| mapchr     | text     | map character
| seenv      | integer  | seen vector
| horizontal | boolean  |
| lit        | boolean  |
| waslit     | boolean  |
| roomno     | integer  | room number
| edge       | boolean  |
| candig     | boolean  |
| has_trap   | boolean  |
| flags      | table    | See below
|===

|===
| field name | type     | description
| nodoor     | boolean  | door
| broken     | boolean  | door
| isopen     | boolean  | door
| closed     | boolean  | door
| locked     | boolean  | door
| trapped    | boolean  | door
| shrine     | boolean  | altar
| looted     | boolean  | throne, tree, fountain
| swarm      | boolean  | tree
| warned     | boolean  | fountain
| pudding    | boolean  | sink
| dishwasher | boolean  | sink
| ring       | boolean  | sink
|===

Example:

 local x = 20;
 local y = 10;
 local loc = nh.getmap(x,y);
 nh.pline("Map location at (" .. x .. "," .. y .. ) is " .. (loc.lit ? "lit" : "unlit") );

=== gettrap

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

|===
| field name  | type    | description
| tx, ty      | integer | trap coordinates
| ttyp        | integer | trap type
| ttyp_name   | text    | name of trap type
| tseen       | boolean | trap seen by you?
| madeby_u    | boolean | trap made by you?
| tnote       | integer | note of a squeaky board trap
| launchx, launchy, launch2x, launch2y | integer | coordinates of a boulder for a rolling boulder trap
| conjoined   | integer | encoded directions for a [spiked] pit.
|===

Example:

 local t = nh.gettrap(x, y);


=== deltrap

Delete a trap at x,y

Example:

 nh.deltrap(x, y);



=== ing_suffix

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

Example:

 local str = nh.ing_suffix("foo");


=== makeplural

Pluralize the given string.

Example:

 local str = nh.makeplural("zorkmid");


=== makesingular

Make the given string singular.

Example:

 local str = nh.makesingular("zorkmids");


=== menu

Show a menu to the player.

Synopsis:

 s = nh.menu(prompt, default, pickx, { option1, option2, ... } );

* 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:

 local selected = nh.menu("prompt", default, pickX, { "a" = "option a", "b" = "option b" });
 local selected = nh.menu("prompt", default, pickX, { {key:"a", text:"option a"}, {key:"b", text:"option b"} } );


=== pline

Show the text in the message area.

Example:

 nh.pline("Message text to show.");


=== s_suffix

Return a string converted to possessive.

Example:

 local str = nh.s_suffix("foo");


=== verbalize

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

Example:

 nh.verbalize("Message to say.");

== Special level functions

Functions for creating special levels. They are in the `des` table.

=== altar

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:

 des.altar({ x=6, y=12 });
 des.altar({ coord = {5, 10}, align = "noalign", type = "altar" });

=== corridor

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:

 des.corridor({ srcroom=1, srcdoor=2, srcwall="north", destroom=2, destdoor=1, destwall="west" });

=== door

Create a door at a coordinate on the map, or in a room's wall.

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

Example:

 des.door({ x = 1, y = 1, state = "nodoor" });
 des.door({ coord = {1, 1}, state = "nodoor" });
 des.door({ wall = "north", pos = 3, state = "secret" });
 des.door("nodoor", 1, 2);

=== drawbridge

Example:

 des.drawbridge({ dir="east", state="closed", x=05,y=08 });
 des.drawbridge({ dir="east", state="closed", coord={05,08} });

=== engraving

Example:

 des.engraving({ x = 1, y = 1, type = "burn", text = "Foo" });
 des.engraving({ coord = {1, 1}, type = "burn", text = "Foo" });
 des.engraving({x,y}, "engrave", "Foo");

=== feature

Create a fountain, a sink, or a pool.

Example:

 des.feature("fountain", 2, 3);
 des.feature("fountain", {4, 5});
 des.feature({ type = "fountain", x = 12, y = 6 });
 des.feature({ type = "fountain", coord = {4, 6} });

=== gold

Create a pile of gold.

Example:

 des.gold(500, 3,5);
 des.gold(500, {5, 6});
 des.gold({ amount = 500, x = 2, y = 5 });
 des.gold({ amount = 500, coord = {2, 5} });
 des.gold();

=== grave

Example:

 des.grave(40,11, "Text");
 des.grave({ x = 10, y = 20, text = "Epitaph text" });
 des.grave({ coord = {10, 20}, text = "Epitaph text" });
 des.grave({ text = "Epitaph text" });
 des.grave();

=== ladder

Example:

 des.ladder("down");
 des.ladder("up", 6,10);
 des.ladder({ x=11, y=05, dir="down" });
 des.ladder({ coord={11, 05}, dir="down" });

=== level_flags

Set flags for this level.

|===
| noteleport    | Prevents teleporting
| hardfloor     | Prevents digging down
| nommap        | Prevents magic mapping
| shortsighted  | Prevents monsters from seeing the hero from far away
| arboreal      | Notionally an outdoor map; replaces solid stone with trees
| mazelevel     | 
| shroud        | Unseen locations on the level will not be remembered by the hero, instead of rendering as out-of-sight map, trap, and object glyphs like they normally do.
| graveyard     | Treats the level as a graveyard level (causes graveyard sounds and undead have a reduced chance of leaving corpses).
| icedpools     | Ice generated with the level will be treated as frozen pools instead of frozen moats.
| corrmaze      | 
| premapped     | Map, including traps and boulders, is revealed on entrance.
| solidify      | Areas outside the specified level map are made undiggable and unphaseable. 
| inaccessibles | If inaccessible areas are generated, generate ways for them to connect to the "accessible" area.
| noflip        | Prevent flipping the level.
| noflipx       | Prevent flipping the level horizontally.
| noflipy       | Prevent flipping the level vertically.
|===

Example:

 des.level_flags("noteleport", "mazelevel");

=== level_init

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

Example:

 des.level_init({ style = "solidfill", fg = " " });
 des.level_init({ style = "mines", fg = ".", bg = "}", smoothed=1, joined=1, lit=0 })

=== levregion

Example:

 des.levregion({ region = { x1,y1, x2,y2 }, exclude = { x1,y1, x2,y2 }, type = "portal", name="air" });

=== map

Example:

 des.map({ x = 10, y = 10, map = [[...]] });
 des.map({ coord = {10, 10}, map = [[...]] });
 des.map({ halign = "center", valign = "center", map = [[...]] });
 des.map([[...]])

=== mazewalk

Example:

 des.mazewalk({ x = NN, y = NN, typ = ".", dir = "north", stocked = 0 });
 des.mazewalk({ coord = {NN, NN}, typ = ".", dir = "north" });
 des.mazewalk(x,y,dir);

=== message

Example:

 des.message("Foo");

=== mineralize

Example:

 des.mineralize({ gem_prob = 10, gold_prob = 20, kelp_moat = 30, kelp_pool = 40 });

=== monster

Example:

 des.monster();
 des.monster("wood nymph");
 des.monster("D");
 des.monster("giant eel",11,06);
 des.monster("hill giant", {08,06});
 des.monster({ id = "giant mimic", appear_as = "obj:boulder" });
 des.monster({ class = "H", peaceful = 0 });

=== non_diggable

Example:

 des.non_diggable(selection);
 des.non_diggable();

=== non_passwall

Example:

 des.non_passwall(selection);
 des.non_passwall();

=== random_corridors

Create random corridors between rooms.

Example:

 des.random_corridors();

=== region

Example:

 des.region(selection, lit);
 des.region({ x1=NN, y1=NN, x2=NN, y2=NN, lit=BOOL, type=ROOMTYPE, joined=BOOL, irregular=BOOL, prefilled=BOOL [ , contents = FUNCTION ] });
 des.region({ region={x1,y1, x2,y2}, type="ordinary" });

=== replace_terrain

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:

 des.replace_terrain({ x1=NN,y1=NN, x2=NN,y2=NN, fromterrain=MAPCHAR, toterrain=MAPCHAR, lit=N, chance=NN });
 des.replace_terrain({ region={x1,y1, x2,y2}, fromterrain=MAPCHAR, toterrain=MAPCHAR, lit=N, chance=NN });
 des.replace_terrain({ selection=selection.area(2,5, 40,10), fromterrain=MAPCHAR, toterrain=MAPCHAR });
 des.replace_terrain({ selection=SEL, mapfragment=[[...]], toterrain=MAPCHAR });
 des.replace_terrain({ mapfragment=[[...]], toterrain=MAPCHAR });
 des.replace_terrain({ fromterrain=MAPCHAR, toterrain=MAPCHAR });

=== reset_level

Only used for testing purposes.

Example:

 des.reset_level();

=== room

Example:

 des.room({ type="ordinary", lit=1, x=3,y=3, xalign="center",yalign="center", w=11,h=9 });
 des.room({ lit=1, coord={3,3}, xalign="center",yalign="center", w=11,h=9 });

=== stair

Example:

 des.stair("up");
 des.stair({ dir = "down" });
 des.stair({ dir = "down", x = 4, y = 7 });
 des.stair({ dir = "down", coord = {5,12} });
 des.stair("down", 4, 7);

=== teleport_region

Example:

 des.teleport_region({ region = { x1,y1, x2,y2} });
 des.teleport_region({ region = { x1,y1, x2,y2}, region_islev = 1, exclude = { x1,y1, x2,y2}, exclude_islen = 1, dir = "up" });

=== terrain

Example:

 des.terrain({ x=5, y=6, typ="L", lit=1 });
 des.terrain({ coord={10, 11}, typ="T", lit=0 });
 des.terrain({ selection=selection.rect(15,5, 20,7), typ="F", lit=0 });
 des.terrain(selection.area(25, 3, 30,6), "C");
 des.terrain({20,11}, ".");
 des.terrain(21,12, ".");

=== trap

Example:

 des.trap({ type = "hole", x = 1, y = 1 });
 des.trap({ type = "hole", coord = {2, 2} });
 des.trap("hole", 3, 4);
 des.trap("level teleport", {5, 8});
 des.trap("rust")
 des.trap();

=== wall_property

Example:

 des.wall_property({ x1=0, y1=0, x2=78, y2=20, property="nondiggable" });
 des.wall_property({ region = {1,0, 78,20}, property="nonpasswall" });

=== wallify

Example:

 des.wallify({ x1=NN,y1=NN, x2=NN,y2=NN });
 des.wallify();


== Selection

Selection object can be used to "select" areas of the map with graphic primitives.

=== new

Create a new selection.

Example:

 local sel = selection.new();


=== Logical and

Choose locations that are selected in both selections.

Example:

 local sel = selection.area(4,5, 40,10) & selection.rect(7,8, 60,14);


=== Logical or

Choose locations that are selected in either or both selections.

Example:

 local sel = selection.area(4,5, 40,10) | selection.rect(7,8, 60,14);


=== Logical xor

Choose locations in either selection, but not both.

Example:

 local sel = selection.area(4,5, 40,10) ~ selection.rect(7,8, 60,14);


=== area

Alias for <<_fillrect>>.

=== circle

Example:

 local s = selection.circle(x,y, radius);
 local s = selection.circle(x, y, radius, filled);
 local s = selection.circle(sel, x, y, radius);
 local s = selection.circle(sel, x, y, radius, filled);


=== clone

Clone a selection.

Example:

 local sel2 = selection.clone(sel);

=== ellipse

Example:

 local s = selection.ellipse(x, y, radius1, radius2);
 local s = selection.ellipse(x, y, radius1, radius2, filled);
 local s = selection.ellipse(sel, x, y, radius1, radius2);
 local s = selection.ellipse(sel, x, y, radius1, radius2, filled);

=== fillrect

Example:

 local s = selection.fillrect(sel, x1,y1, x2,y2);
 local s = selection.fillrect(x1,y1, x2,y2);
 s:fillrect(x1,y1, x2,y2);
 selection.area(x1,y1, x2,y2);

=== filter_mapchar

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:

 local s = selection.filter_mapchar(sel, mapchar);
 local s = selection.filter_mapchar(sel, mapchar, lit);

=== floodfill

Select locations by starting floodfill at (x,y),
matching the same map terrain in cardinal directions.

Example:

 local s = selection.floodfill(sel, x, y);
 local s = selection.floodfill(x,y);

=== get

Get the selection value at (x,y).

Example:

 local value = selection.get(sel, x, y);

=== grow

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:

 local s = selection.grow(sel);
 local s = selection.grow(sel, "north");

=== iterate

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

Example:

 sel:iterate(function(x,y) ... end);

=== line

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

Example:

 local s = selection.line(sel, x1,y1, x2,y2);
 local s = selection.line(x1,y1, x2,y2);
 s:line(x1,y1, x2,y2);

=== match

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:

 local s = selection.match([[
 ...
 .L.
 ...]]);

=== negate

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

Example:

 local s = selection.negate(sel);
 local s = selection.negate();

=== percentage

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

Example:

 local s = selection.percentage(sel, 50);

=== randline

Example:

 local s = selection.randline(sel, x1,y1, x2,y2, roughness);
 local s = selection.randline(x1,y1, x2,y2, roughness);

=== rect

Draw a rectangle.

Example:

 local s = selection.rect(sel, x1,y1, x2,y2);

=== rndcoord

Choose one of the selected locations, and return the x,y coordinates.
If the optional second argument is 1, removes the location from the selection.

Example:

 local x,y = selection.rndcoord(sel);
 local x,y = selection.rndcoord(sel, 1);

=== set

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

Example:

 selection.set(sel, x, y);
 selection.set(sel, x, y, value);
 local sel = selection.set();
 local sel = sel:set();
 local sel = selection.set(sel);

