From: Pasi Kallinen <paxed@alt.org>
Date: Mon, 2 Mar 2020 15:38:31 +0000 (+0200)
Subject: Start of lua api docs
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=00be8be45a7f6fc71a83ac187609d2467af37566;p=nethack

Start of lua api docs

... in asciidoc format. Use "asciidoctor -b html5 lua.adoc"
to generate the HTML version.
---

diff --git a/doc/lua.adoc b/doc/lua.adoc
new file mode 100644
index 000000000..56cb2e4a7
--- /dev/null
+++ b/doc/lua.adoc
@@ -0,0 +1,677 @@
+= 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);
+
diff --git a/src/nhlua.c b/src/nhlua.c
index 54fd25ab5..358d50925 100644
--- a/src/nhlua.c
+++ b/src/nhlua.c
@@ -256,8 +256,8 @@ lua_State *L;
                 nhl_add_table_entry_int(L, "ttyp", ttmp->ttyp);
                 nhl_add_table_entry_str(L, "ttyp_name",
                                         get_trapname_bytype(ttmp->ttyp));
-                nhl_add_table_entry_int(L, "tseen", ttmp->tseen);
-                nhl_add_table_entry_int(L, "madeby_u", ttmp->madeby_u);
+                nhl_add_table_entry_bool(L, "tseen", ttmp->tseen);
+                nhl_add_table_entry_bool(L, "madeby_u", ttmp->madeby_u);
                 switch (ttmp->ttyp) {
                 case SQKY_BOARD:
                     nhl_add_table_entry_int(L, "tnote", ttmp->tnote);
@@ -334,7 +334,7 @@ lua_State *L;
             nhl_add_table_entry_bool(L, "edge", levl[x][y].edge);
             nhl_add_table_entry_bool(L, "candig", levl[x][y].candig);
 
-            nhl_add_table_entry_int(L, "has_trap", t_at(x,y) ? 1 : 0);
+            nhl_add_table_entry_bool(L, "has_trap", t_at(x,y) ? 1 : 0);
 
             /* TODO: FIXME: levl[x][y].flags */