nethack-gwaa-kiwi/nethack
1
0
Fork 0
Code Pull Requests Activity

Lua doc bits

Browse Source
This commit is contained in:
Pasi Kallinen
2023-01-24 09:37:32 +02:00
parent 0bfd6b22f1
commit fd25cb177f
1 changed files with 101 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
doc/lua.adoc
View File

@@ -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.