723 lines
17 KiB
Plaintext
723 lines
17 KiB
Plaintext
= 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
|
|
|
|
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.
|
|
|
|
[options="header"]
|
|
|===
|
|
| parameter | description
|
|
| x, y | Coordinates on the level.
|
|
| coord | Coordinates in table format.
|
|
| halign | Horizontal alignment on a rough 3x3 grid.
|
|
| valign | Vertical alignment on a rough 3x3 grid.
|
|
| map | Multi-line string describing the map.
|
|
| contents | A function called with one parameter, a table with "width" and "height", the map width and height. All coordinates in the function will be relative to the map.
|
|
|===
|
|
|
|
Example:
|
|
|
|
des.map({ x = 10, y = 10, map = [[...]] });
|
|
des.map({ coord = {10, 10}, map = [[...]] });
|
|
des.map({ halign = "center", valign = "center", map = [[...]] });
|
|
des.map([[...]]);
|
|
des.map({ halign = "center", valign = "center", map = [[
|
|
....
|
|
....
|
|
....]], contents = function(map)
|
|
des.terrain(0,0, "L");
|
|
des.terrain(map.width-1, map.height-1, "T");
|
|
end });
|
|
|
|
=== 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
|
|
|
|
Create a room of certain type and size. Takes one parameter, a table with the following
|
|
fields:
|
|
|
|
[options="header"]
|
|
|===
|
|
| parameter | description
|
|
| type | The room type. Default is "ordinary"
|
|
| chance | Percentage chance this room is of type, otherwise it will be created as ordinary room. Default is 100.
|
|
| x,y | Room coordinates.
|
|
| coord | Room coordinates, in table format.
|
|
| w, h | Width and height. Both default to -1 (random). If one is set, then both must be set.
|
|
| xalign | Horizontal alignment on a rough 3x3 grid. Default is "random".
|
|
| yalign | Vertical alignment on a rough 3x3 grid. Default is "random".
|
|
| lit | Is the room lit or unlit? Defaults to -1 (random).
|
|
| filled | Is the room filled as per the room type. Defaults to 1 (filled).
|
|
| joined | Is the room joined to the rest of the level with corridors? Default is 1 (joined).
|
|
| contents | A function called with one parameter, a table with "width" and "height", the room width and height, excluding the walls. All coordinates in the function will be relative to the 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 });
|
|
des.room({ type="ordinary", contents=function(room)
|
|
des.terrain(0,0, "L");
|
|
des.terrain(room.width, room.height, "T");
|
|
end });
|
|
|
|
=== 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);
|
|
|