From: Pasi Kallinen <paxed@alt.org>
Date: Tue, 24 Jan 2023 07:37:32 +0000 (+0200)
Subject: Lua doc bits
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=fd25cb177fa770743961a3608423a7b3c0dc4c9f;p=nethack

Lua doc bits
---

diff --git a/doc/lua.adoc b/doc/lua.adoc
index a5032f093..51bf77897 100644
--- a/doc/lua.adoc
+++ b/doc/lua.adoc
@@ -9,6 +9,7 @@ Functions exposed from the NetHack core. They are all in the `nh` table.
 All core functions involving xy coordinates interpret these as relative to the
 last defined map or room.
 
+
 === abscoord
 
 Convert a room- or map-relative coordinate to absolute.
@@ -88,6 +89,7 @@ Example:
 
  local filename = nh.dump_fmtstr("/tmp/nethack.%n.%d.log");
 
+
 === getlin
 
 Asks the player for a text to enter, and returns the entered string.
@@ -102,6 +104,7 @@ Example:
 Get information about the map location.
 Returns a table with the following elements:
 
+[%header]
 |===
 | field name | type     | description
 | glyph      | integer  |
@@ -119,6 +122,7 @@ Returns a table with the following elements:
 | flags      | table    | See below
 |===
 
+[%header]
 |===
 | field name | type     | description
 | nodoor     | boolean  | door
@@ -159,6 +163,7 @@ Example:
 Get trap info at x,y
 Returns a table with the following elements:
 
+[%header]
 |===
 | field name  | type    | description
 | tx, ty      | integer | trap coordinates
@@ -310,6 +315,7 @@ Example:
 
  nh.pushkey("i");
 
+
 === random
 
 Generate a random number.
@@ -319,6 +325,7 @@ Example:
  nh.random(10);  -- returns a number between 0 and 9, inclusive.
  nh.random(1,5); -- same as 1 + nh.random(5);
 
+
 === rn2
 
 Generate a random number.
@@ -327,6 +334,7 @@ Example:
 
  nh.rn2(10); -- returns a number between 0 and 9, inclusive.
 
+
 === s_suffix
 
 Return a string converted to possessive.
@@ -397,6 +405,7 @@ Example:
 
  nh.verbalize("Message to say.");
 
+
 == Special level functions
 
 Functions for creating special levels. They are in the `des` table.
@@ -404,6 +413,7 @@ Functions for creating special levels. They are in the `des` table.
 All special level functions involving xy coordinates interpret these as relative
 to the last defined map or room.
 
+
 === altar
 
 Create an altar of certain type and alignment.
@@ -417,6 +427,7 @@ 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.
@@ -427,6 +438,7 @@ 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.
@@ -440,21 +452,35 @@ Example:
  des.door({ wall = "north", pos = 3, state = "secret" });
  des.door("nodoor", 1, 2);
 
+
 === drawbridge
 
+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:
 
  des.drawbridge({ dir="east", state="closed", x=05,y=08 });
  des.drawbridge({ dir="east", state="closed", coord={05,08} });
 
+
 === engraving
 
+Create an engraving.
+
+* type is one of "dust", "engrave", "burn", "mark", or "blood".
+
 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 feature, and set flags for it.
@@ -471,6 +497,7 @@ Example:
  des.feature({ type = "throne", coord = {4, 6}, looted = true });
  des.feature({ type = "tree", coord = {4, 6}, looted = true, swarm = false });
 
+
 === finalize_level
 
 Only used for testing purposes. See also <<_reset_level>>.
@@ -479,6 +506,7 @@ Example:
 
  des.finalize_level();
 
+
 === gold
 
 Create a pile of gold.
@@ -491,8 +519,11 @@ Example:
  des.gold({ amount = 500, coord = {2, 5} });
  des.gold();
 
+
 === grave
 
+Create a grave.  A missing text results in a random epitaph being used.
+
 Example:
 
  des.grave(40,11, "Text");
@@ -501,8 +532,11 @@ Example:
  des.grave({ text = "Epitaph text" });
  des.grave();
 
+
 === ladder
 
+Create a ladder.
+
 Example:
 
  des.ladder("down");
@@ -511,6 +545,7 @@ Example:
  des.ladder({ x=11, y=05, dir="down" });
  des.ladder({ coord={11, 05}, dir="down" });
 
+
 === level_flags
 
 Set flags for this level.
@@ -541,6 +576,7 @@ Example:
 
  des.level_flags("noteleport", "mazelevel");
 
+
 === level_init
 
 Initialize the map with a random generator of a certain type.
@@ -551,12 +587,20 @@ Example:
  des.level_init({ style = "mines", fg = ".", bg = "}", smoothed=true, joined=true, lit=0 })
  des.level_init({ style = "maze", corrwid = 3, wallthick = 1, deadends = false });
 
+
 === levregion
 
+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:
 
  des.levregion({ region = { x1,y1, x2,y2 }, exclude = { x1,y1, x2,y2 }, type = "portal", name="air" });
 
+
 === map
 
 Construct a piece of the level from text map. Takes one parameter, either a text string
@@ -591,26 +635,40 @@ Example:
  end });
  local sel = des.map([[LLL]]);
 
+
 === mazewalk
 
+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:
 
  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
 
+Message shown to the player when entering the level for the first time.
+
 Example:
 
  des.message("Foo");
 
+
 === mineralize
 
+Place random gems, gold, and kelp on the level.
+
 Example:
 
  des.mineralize({ gem_prob = 10, gold_prob = 20, kelp_moat = 30, kelp_pool = 40 });
 
+
 === monster
 
 Create a monster.
@@ -657,15 +715,21 @@ Example:
  des.monster({ id = "giant mimic", appear_as = "obj:boulder" });
  des.monster({ class = "H", peaceful = 0 });
 
+
 === non_diggable
 
+Set walls in an area of the map as non-diggable.  See also: <<_wall_property>>.
+
 Example:
 
  des.non_diggable(selection);
  des.non_diggable();
 
+
 === non_passwall
 
+Set walls in an area of the map as non-passwall, so they can't be phased through.  See also: <<_wall_property>>.
+
 Example:
 
  des.non_passwall(selection);
@@ -726,14 +790,18 @@ Example:
 
  des.random_corridors();
 
+
 === region
 
+Create a room region, which can be irregular; use the boundary <<_map_characters,map character>> to restrict the floodfilled area.
+
 Example:
 
  des.region(selection, lit);
  des.region({ x1=NN, y1=NN, x2=NN, y2=NN, lit=BOOL, type=ROOMTYPE, joined=BOOL, irregular=BOOL, filled=NN [ , contents = FUNCTION ] });
  des.region({ region={x1,y1, x2,y2}, type="ordinary" });
 
+
 === replace_terrain
 
 Replaces matching terrain on the area, selection, or whole map.
@@ -748,6 +816,7 @@ Example:
  des.replace_terrain({ mapfragment=[[...]], toterrain=MAPCHAR });
  des.replace_terrain({ fromterrain=MAPCHAR, toterrain=MAPCHAR });
 
+
 === reset_level
 
 Only used for testing purposes. See also <<_finalize_level>>.
@@ -756,6 +825,7 @@ Example:
 
  des.reset_level();
 
+
 === room
 
 Create a room of certain type and size. Takes one parameter, a table with the following
@@ -777,6 +847,7 @@ fields:
 | contents  | A function called with one parameter, a table with room data. See <<_room_contents>>.
 |===
 
+
 ==== room contents
 
 The room contents function is called when the room is created.
@@ -805,8 +876,11 @@ Example:
     des.terrain(room.width, room.height, "T");
  end });
 
+
 === stair
 
+Create stairs.
+
 Example:
 
  des.stair("up");
@@ -816,6 +890,7 @@ Example:
  des.stair("down", 4, 7);
  des.stair("down", {4, 7});
 
+
 === teleport_region
 
 Example:
@@ -823,6 +898,7 @@ 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:
@@ -834,6 +910,7 @@ Example:
  des.terrain({20,11}, ".");
  des.terrain(21,12, ".");
 
+
 === trap
 
 Create a trap. The `launchfrom` is relative to the rolling boulder trap coord.
@@ -849,13 +926,17 @@ Example:
  des.trap("rust")
  des.trap();
 
+
 === wall_property
 
+Set walls in an area nondiggable or non-passwall. See also: <<_non_diggable>> and <<_non_passwall>>.
+
 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:
@@ -868,6 +949,7 @@ Example:
 
 Selection object can be used to "select" areas of the map with graphic primitives.
 
+
 === new
 
 Create a new selection.
@@ -919,6 +1001,7 @@ Example:
 
 Alias for <<_fillrect>>.
 
+
 === bounds
 
 Get the bounding box for the selection. Returns a table with lx, ly, hx, hy integer fields.
@@ -947,6 +1030,7 @@ Example:
 
  local sel2 = selection.clone(sel);
 
+
 === ellipse
 
 Example:
@@ -956,6 +1040,7 @@ Example:
  local s = selection.ellipse(sel, x, y, radius1, radius2);
  local s = selection.ellipse(sel, x, y, radius1, radius2, filled);
 
+
 === fillrect
 
 Example:
@@ -965,6 +1050,7 @@ Example:
  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,
@@ -978,6 +1064,7 @@ 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),
@@ -990,6 +1077,7 @@ Example:
  local s = selection.floodfill(x,y);
  local s = selection.floodfill(x,y, true);
 
+
 === get
 
 Get the selection value at (x,y).
@@ -999,6 +1087,7 @@ Example:
  local value = selection.get(sel, x, y);
  local value = selection.get(sel, { x = 10, y = 14 });
 
+
 === gradient
 
 Create a "gradient" of selected positions.
@@ -1007,6 +1096,7 @@ Example:
 
  local s = selection.gradient({ type = "radial", x = 3, y = 5, x2 = 10, y2 = 12, mindist = 4, maxdist = 10, limited = false });
 
+
 === grow
 
 Add locations to the selection by choosing unselected locations
@@ -1018,6 +1108,7 @@ Example:
  local s = selection.grow(sel);
  local s = selection.grow(sel, "north");
 
+
 === iterate
 
 Iterate through the selection, calling a function for each set point.
@@ -1026,6 +1117,7 @@ Example:
 
  sel:iterate(function(x,y) ... end);
 
+
 === line
 
 Draw a line from (x1,y1) to (x2,y2).
@@ -1036,6 +1128,7 @@ Example:
  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,
@@ -1049,6 +1142,7 @@ Example:
  .L.
  ...]]);
 
+
 === negate
 
 Negate the selection. Alias for "unary minus" and "bitwise not".
@@ -1058,6 +1152,7 @@ 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.
@@ -1066,6 +1161,7 @@ Example:
 
  local s = selection.percentage(sel, 50);
 
+
 === randline
 
 Example:
@@ -1073,6 +1169,7 @@ Example:
  local s = selection.randline(sel, x1,y1, x2,y2, roughness);
  local s = selection.randline(x1,y1, x2,y2, roughness);
 
+
 === rect
 
 Draw a rectangle.
@@ -1081,6 +1178,7 @@ Example:
 
  local s = selection.rect(sel, x1,y1, x2,y2);
 
+
 === rndcoord
 
 Choose one of the selected locations, and return a table with x and y keys.
@@ -1118,10 +1216,12 @@ Example:
  local sel = sel:set();
  local sel = selection.set(sel);
 
+
 == Obj
 
 Handling objects via obj-class.
 
+
 === new
 
 Create a new object via wishing routine.
@@ -1306,6 +1406,7 @@ Example:
 | `"w"`     | "any wall" - see <<_match>>
 |===
 
+
 == Constants
 
 These constants are in the `nhc` table.