1= NetHack lua 2:toc: right 3 4 5== Core functions 6 7Functions exposed from the NetHack core. They are all in the `nh` table. 8 9=== an 10 11Returns a string with "a " or "an " prepended to it. 12 13Example: 14 15 local str = nh.an("unicorn"); 16 17 18=== getlin 19 20Asks the player for a text to enter, and returns the entered string. 21 22Example: 23 24 local str = nh.getlin("What do you want to call this?"); 25 26 27=== getmap 28 29Get information about the map location. 30Returns a table with the following elements: 31 32|=== 33| field name | type | description 34| glyph | integer | 35| typ | integer | terrain type 36| typ_name | text | name of terrain type 37| mapchr | text | <<_map_characters,map character>> 38| seenv | integer | seen vector 39| horizontal | boolean | 40| lit | boolean | 41| waslit | boolean | 42| roomno | integer | room number 43| edge | boolean | 44| candig | boolean | 45| has_trap | boolean | 46| flags | table | See below 47|=== 48 49|=== 50| field name | type | description 51| nodoor | boolean | door 52| broken | boolean | door 53| isopen | boolean | door 54| closed | boolean | door 55| locked | boolean | door 56| trapped | boolean | door 57| shrine | boolean | altar 58| looted | boolean | throne, tree, fountain 59| swarm | boolean | tree 60| warned | boolean | fountain 61| pudding | boolean | sink 62| dishwasher | boolean | sink 63| ring | boolean | sink 64|=== 65 66Example: 67 68 local x = 20; 69 local y = 10; 70 local loc = nh.getmap(x,y); 71 nh.pline("Map location at (" .. x .. "," .. y .. ) is " .. (loc.lit ? "lit" : "unlit") ); 72 73 74=== get_config 75 76Get current value of a boolean or a compound configuration option. 77 78Example: 79 80 local wt = nh.get_config("windowtype"); 81 82 83=== gettrap 84 85Get trap info at x,y 86Returns a table with the following elements: 87 88|=== 89| field name | type | description 90| tx, ty | integer | trap coordinates 91| ttyp | integer | trap type 92| ttyp_name | text | name of trap type 93| tseen | boolean | trap seen by you? 94| madeby_u | boolean | trap made by you? 95| tnote | integer | note of a squeaky board trap 96| launchx, launchy, launch2x, launch2y | integer | coordinates of a boulder for a rolling boulder trap 97| conjoined | integer | encoded directions for a [spiked] pit. 98|=== 99 100Example: 101 102 local t = nh.gettrap(x, y); 103 104 105=== deltrap 106 107Delete a trap at x,y 108 109Example: 110 111 nh.deltrap(x, y); 112 113 114 115=== ing_suffix 116 117Construct a gerund (a verb formed by appending "ing" to a noun). 118 119Example: 120 121 local str = nh.ing_suffix("foo"); 122 123 124=== level_difficulty 125 126Returns an integer value describing the level difficulty. 127Normally this is the level's physical depth from the surface. 128 129Example: 130 131 local diff = nh.level_difficulty(); 132 133=== makeplural 134 135Pluralize the given string. 136 137Example: 138 139 local str = nh.makeplural("zorkmid"); 140 141 142=== makesingular 143 144Make the given string singular. 145 146Example: 147 148 local str = nh.makesingular("zorkmids"); 149 150 151=== menu 152 153Show a menu to the player. 154 155Synopsis: 156 157 s = nh.menu(prompt, default, pickx, { option1, option2, ... } ); 158 159* prompt is a string. 160* default is the default returned value, if player cancelled the menu. 161* pickx is how many entries user is allowed to choose, one of "none", "one" or "any". 162 163Options is a table with either { "key" = "text" }, or { { key : "a", text: "text of option a"} }. 164 165Example: 166 167 local selected = nh.menu("prompt", default, pickX, { "a" = "option a", "b" = "option b" }); 168 local selected = nh.menu("prompt", default, pickX, { {key:"a", text:"option a"}, {key:"b", text:"option b"} } ); 169 170 171=== parse_config 172 173Parse string as if it was read from a config file. 174Always call parse_config_errors afterwards to check for any parsing errors. 175 176Example: 177 178 nh.parse_config("OPTIONS=color"); 179 180 181=== parse_config_errors 182 183Returns any errors found when parsing a config file string with parse_config. 184 185Example: 186 187 nh.parse_config("OPTIONS=color\nOPTIONS=!color"); 188 local errors = nh.parse_config_errors(); 189 nh.pline("Line: " .. errors[1].line .. ", " .. errors[1].error); 190 191 192=== pline 193 194Show the text in the message area. 195 196Example: 197 198 nh.pline("Message text to show."); 199 200 201=== random 202 203Generate a random number. 204 205Example: 206 207 nh.random(10); -- returns a number between 0 and 9, inclusive. 208 nh.random(1,5); -- same as 1 + nh.random(5); 209 210=== rn2 211 212Generate a random number. 213 214Example: 215 216 nh.rn2(10); -- returns a number between 0 and 9, inclusive. 217 218=== s_suffix 219 220Return a string converted to possessive. 221 222Example: 223 224 local str = nh.s_suffix("foo"); 225 226 227=== verbalize 228 229Show the text in the message area as if someone said it, obeying eg. hero's deafness. 230 231Example: 232 233 nh.verbalize("Message to say."); 234 235== Special level functions 236 237Functions for creating special levels. They are in the `des` table. 238 239=== altar 240 241Create an altar of certain type and alignment. 242 243* align is one of "noalign", "law", "neutral", "chaos", "coaligned", "noncoaligned", or "random", 244 defaulting to "random". 245* type is one of "altar", "shrine", or "sanctum", defaulting to "altar". 246 247Example: 248 249 des.altar({ x=6, y=12 }); 250 des.altar({ coord = {5, 10}, align = "noalign", type = "altar" }); 251 252=== corridor 253 254Create a random corridor from one room to another. 255 256* srcwall and destwall are one of "all", "random", "north", "west", "east", or "south", defaulting to "all". 257 258Example: 259 260 des.corridor({ srcroom=1, srcdoor=2, srcwall="north", destroom=2, destdoor=1, destwall="west" }); 261 262=== door 263 264Create a door at a coordinate on the map, or in a room's wall. 265 266* state is one of "random", "open", "closed", "locked", "nodoor", "broken", or "secret", defaulting to "random". 267 268Example: 269 270 des.door({ x = 1, y = 1, state = "nodoor" }); 271 des.door({ coord = {1, 1}, state = "nodoor" }); 272 des.door({ wall = "north", pos = 3, state = "secret" }); 273 des.door("nodoor", 1, 2); 274 275=== drawbridge 276 277Example: 278 279 des.drawbridge({ dir="east", state="closed", x=05,y=08 }); 280 des.drawbridge({ dir="east", state="closed", coord={05,08} }); 281 282=== engraving 283 284Example: 285 286 des.engraving({ x = 1, y = 1, type = "burn", text = "Foo" }); 287 des.engraving({ coord = {1, 1}, type = "burn", text = "Foo" }); 288 des.engraving({x,y}, "engrave", "Foo"); 289 290=== feature 291 292Create a feature, and set flags for it. 293Valid features are a fountain, a sink, a pool, a throne, or a tree. 294Throne has `looted` flag, tree has `looted` and `swarm`, fountain has `looted` and `warned`, 295sink has `pudding`, `dishwasher`, and `ring`. 296 297Example: 298 299 des.feature("fountain", 2, 3); 300 des.feature("fountain", {4, 5}); 301 des.feature({ type = "fountain", x = 12, y = 6 }); 302 des.feature({ type = "fountain", coord = {4, 6} }); 303 des.feature({ type = "throne", coord = {4, 6}, looted = true }); 304 des.feature({ type = "tree", coord = {4, 6}, looted = true, swarm = false }); 305 306=== gold 307 308Create a pile of gold. 309 310Example: 311 312 des.gold(500, 3,5); 313 des.gold(500, {5, 6}); 314 des.gold({ amount = 500, x = 2, y = 5 }); 315 des.gold({ amount = 500, coord = {2, 5} }); 316 des.gold(); 317 318=== grave 319 320Example: 321 322 des.grave(40,11, "Text"); 323 des.grave({ x = 10, y = 20, text = "Epitaph text" }); 324 des.grave({ coord = {10, 20}, text = "Epitaph text" }); 325 des.grave({ text = "Epitaph text" }); 326 des.grave(); 327 328=== ladder 329 330Example: 331 332 des.ladder("down"); 333 des.ladder("up", 6,10); 334 des.ladder({ x=11, y=05, dir="down" }); 335 des.ladder({ coord={11, 05}, dir="down" }); 336 337=== level_flags 338 339Set flags for this level. 340 341|=== 342| noteleport | Prevents teleporting 343| hardfloor | Prevents digging down 344| nommap | Prevents magic mapping 345| shortsighted | Prevents monsters from seeing the hero from far away 346| arboreal | Notionally an outdoor map; replaces solid stone with trees 347| mazelevel | 348| 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. 349| graveyard | Treats the level as a graveyard level (causes graveyard sounds and undead have a reduced chance of leaving corpses). 350| icedpools | Ice generated with the level will be treated as frozen pools instead of frozen moats. 351| corrmaze | 352| premapped | Map, including traps and boulders, is revealed on entrance. 353| solidify | Areas outside the specified level map are made undiggable and unphaseable. 354| inaccessibles | If inaccessible areas are generated, generate ways for them to connect to the "accessible" area. 355| noflip | Prevent flipping the level. 356| noflipx | Prevent flipping the level horizontally. 357| noflipy | Prevent flipping the level vertically. 358|=== 359 360Example: 361 362 des.level_flags("noteleport", "mazelevel"); 363 364=== level_init 365 366Initialize the map with a random generator of a certain type. 367 368Example: 369 370 des.level_init({ style = "solidfill", fg = " " }); 371 des.level_init({ style = "mines", fg = ".", bg = "}", smoothed=true, joined=true, lit=0 }) 372 des.level_init({ style = "maze", corrwid = 3, wallthick = 1, deadends = false }); 373 374=== levregion 375 376Example: 377 378 des.levregion({ region = { x1,y1, x2,y2 }, exclude = { x1,y1, x2,y2 }, type = "portal", name="air" }); 379 380=== map 381 382Construct a piece of the level from text map. Takes one parameter, either a text string 383describing the map, or a table with multiple parameters. 384 385[options="header"] 386|=== 387| parameter | description 388| x, y | Coordinates on the level. 389| coord | Coordinates in table format. 390| halign | Horizontal alignment on a rough 3x3 grid. 391| valign | Vertical alignment on a rough 3x3 grid. 392| map | Multi-line string describing the map. See <<_map_characters>> 393| 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. 394|=== 395 396Example: 397 398 des.map({ x = 10, y = 10, map = [[...]] }); 399 des.map({ coord = {10, 10}, map = [[...]] }); 400 des.map({ halign = "center", valign = "center", map = [[...]] }); 401 des.map([[...]]); 402 des.map({ halign = "center", valign = "center", map = [[ 403 .... 404 .... 405 ....]], contents = function(map) 406 des.terrain(0,0, "L"); 407 des.terrain(map.width-1, map.height-1, "T"); 408 end }); 409 410=== mazewalk 411 412Example: 413 414 des.mazewalk({ x = NN, y = NN, typ = ".", dir = "north", stocked = 0 }); 415 des.mazewalk({ coord = {NN, NN}, typ = ".", dir = "north" }); 416 des.mazewalk(x,y,dir); 417 418=== message 419 420Example: 421 422 des.message("Foo"); 423 424=== mineralize 425 426Example: 427 428 des.mineralize({ gem_prob = 10, gold_prob = 20, kelp_moat = 30, kelp_pool = 40 }); 429 430=== monster 431 432Example: 433 434 des.monster(); 435 des.monster("wood nymph"); 436 des.monster("D"); 437 des.monster("giant eel",11,06); 438 des.monster("hill giant", {08,06}); 439 des.monster({ id = "giant mimic", appear_as = "obj:boulder" }); 440 des.monster({ class = "H", peaceful = 0 }); 441 442=== non_diggable 443 444Example: 445 446 des.non_diggable(selection); 447 des.non_diggable(); 448 449=== non_passwall 450 451Example: 452 453 des.non_passwall(selection); 454 des.non_passwall(); 455 456=== object 457 458Create an object. The table parameter accepts the following: 459 460[options="header"] 461|=== 462| key | type | description 463| id | string | Specific object type name 464| class | string | Single character, object class 465| spe | int | obj-struct spe-field value. See table below. Also accepts "random". 466| buc | string | one of "random", "blessed", "uncursed", "cursed", 467 "not-cursed", "not-uncursed", "not-blessed". 468 Default is "random" 469| name | string | Object name 470| quantity | int | Number of items in this stack. Also accepts "random". 471| buried | boolean | Is the object buried? 472| lit | boolean | Is the object lit? 473| eroded | int | Object erosion 474| locked | boolean | Is the object locked? 475| trapped | boolean | Is the object trapped? 476| recharged | boolean | Is the object recharged? 477| greased | boolean | Is the object greased? 478| broken | boolean | Is the object broken? 479| achievement | boolean | Is there an achievement attached to the object? 480| x, y | int | Coordinates on the level 481| coord | table | x,y coordinates in table format 482| montype | string | Monster id or class 483| historic | boolean | Is statue historic? 484| male | boolean | Is statue male? 485| female | boolean | Is statue female? 486| laid_by_you | boolean | Is an egg laid by you? 487| contents | function | Container contents 488|=== 489 490Example: 491 492 des.object(); 493 des.object("/"); 494 des.object("sack"); 495 des.object("scimitar", 6, 7); 496 des.object("scimitar", {6, 7}); 497 des.object({ class = "%" }); 498 des.object({ id = "boulder", x = 03, y = 12}); 499 des.object({ id = "chest", coord = {03, 12}, locked = true, contents = function() des.object("rock"); end }); 500 501=== random_corridors 502 503Create random corridors between rooms. 504 505Example: 506 507 des.random_corridors(); 508 509=== region 510 511Example: 512 513 des.region(selection, lit); 514 des.region({ x1=NN, y1=NN, x2=NN, y2=NN, lit=BOOL, type=ROOMTYPE, joined=BOOL, irregular=BOOL, filled=NN [ , contents = FUNCTION ] }); 515 des.region({ region={x1,y1, x2,y2}, type="ordinary" }); 516 517=== replace_terrain 518 519Replaces matching terrain on the area, selection, or whole map. 520The mapfragment case is similar to the selection <<_match>>, but the replacement is done immediately when matched. 521 522Example: 523 524 des.replace_terrain({ x1=NN,y1=NN, x2=NN,y2=NN, fromterrain=MAPCHAR, toterrain=MAPCHAR, lit=N, chance=NN }); 525 des.replace_terrain({ region={x1,y1, x2,y2}, fromterrain=MAPCHAR, toterrain=MAPCHAR, lit=N, chance=NN }); 526 des.replace_terrain({ selection=selection.area(2,5, 40,10), fromterrain=MAPCHAR, toterrain=MAPCHAR }); 527 des.replace_terrain({ selection=SEL, mapfragment=[[...]], toterrain=MAPCHAR }); 528 des.replace_terrain({ mapfragment=[[...]], toterrain=MAPCHAR }); 529 des.replace_terrain({ fromterrain=MAPCHAR, toterrain=MAPCHAR }); 530 531=== reset_level 532 533Only used for testing purposes. 534 535Example: 536 537 des.reset_level(); 538 539=== room 540 541Create a room of certain type and size. Takes one parameter, a table with the following 542fields: 543 544[options="header"] 545|=== 546| parameter | description 547| type | The room type. Default is "ordinary" 548| chance | Percentage chance this room is of type, otherwise it will be created as ordinary room. Default is 100. 549| x,y | Room coordinates. 550| coord | Room coordinates, in table format. 551| w, h | Width and height. Both default to -1 (random). If one is set, then both must be set. 552| xalign | Horizontal alignment on a rough 3x3 grid. Default is "random". 553| yalign | Vertical alignment on a rough 3x3 grid. Default is "random". 554| lit | Is the room lit or unlit? Defaults to -1 (random). 555| filled | Is the room filled as per the room type. Defaults to 1 (filled). 556| joined | Is the room joined to the rest of the level with corridors? Default is true. 557| 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. 558|=== 559 560 561Example: 562 563 des.room({ type="ordinary", lit=1, x=3,y=3, xalign="center",yalign="center", w=11,h=9 }); 564 des.room({ lit=1, coord={3,3}, xalign="center",yalign="center", w=11,h=9 }); 565 des.room({ type="ordinary", contents=function(room) 566 des.terrain(0,0, "L"); 567 des.terrain(room.width, room.height, "T"); 568 end }); 569 570=== stair 571 572Example: 573 574 des.stair("up"); 575 des.stair({ dir = "down" }); 576 des.stair({ dir = "down", x = 4, y = 7 }); 577 des.stair({ dir = "down", coord = {5,12} }); 578 des.stair("down", 4, 7); 579 580=== teleport_region 581 582Example: 583 584 des.teleport_region({ region = { x1,y1, x2,y2} }); 585 des.teleport_region({ region = { x1,y1, x2,y2}, region_islev = 1, exclude = { x1,y1, x2,y2}, exclude_islen = 1, dir = "up" }); 586 587=== terrain 588 589Example: 590 591 des.terrain({ x=5, y=6, typ="L", lit=1 }); 592 des.terrain({ coord={10, 11}, typ="T", lit=0 }); 593 des.terrain({ selection=selection.rect(15,5, 20,7), typ="F", lit=0 }); 594 des.terrain(selection.area(25, 3, 30,6), "C"); 595 des.terrain({20,11}, "."); 596 des.terrain(21,12, "."); 597 598=== trap 599 600Example: 601 602 des.trap({ type = "hole", x = 1, y = 1 }); 603 des.trap({ type = "hole", coord = {2, 2} }); 604 des.trap("hole", 3, 4); 605 des.trap("level teleport", {5, 8}); 606 des.trap("rust") 607 des.trap(); 608 609=== wall_property 610 611Example: 612 613 des.wall_property({ x1=0, y1=0, x2=78, y2=20, property="nondiggable" }); 614 des.wall_property({ region = {1,0, 78,20}, property="nonpasswall" }); 615 616=== wallify 617 618Example: 619 620 des.wallify({ x1=NN,y1=NN, x2=NN,y2=NN }); 621 des.wallify(); 622 623 624== Selection 625 626Selection object can be used to "select" areas of the map with graphic primitives. 627 628=== new 629 630Create a new selection. 631 632Example: 633 634 local sel = selection.new(); 635 636 637=== Logical and 638 639Choose locations that are selected in both selections. 640 641Example: 642 643 local sel = selection.area(4,5, 40,10) & selection.rect(7,8, 60,14); 644 645 646=== Logical or 647 648Choose locations that are selected in either or both selections. 649 650Example: 651 652 local sel = selection.area(4,5, 40,10) | selection.rect(7,8, 60,14); 653 654 655=== Logical xor 656 657Choose locations in either selection, but not both. 658 659Example: 660 661 local sel = selection.area(4,5, 40,10) ~ selection.rect(7,8, 60,14); 662 663 664=== area 665 666Alias for <<_fillrect>>. 667 668=== circle 669 670Example: 671 672 local s = selection.circle(x,y, radius); 673 local s = selection.circle(x, y, radius, filled); 674 local s = selection.circle(sel, x, y, radius); 675 local s = selection.circle(sel, x, y, radius, filled); 676 677 678=== clone 679 680Clone a selection. 681 682Example: 683 684 local sel2 = selection.clone(sel); 685 686=== ellipse 687 688Example: 689 690 local s = selection.ellipse(x, y, radius1, radius2); 691 local s = selection.ellipse(x, y, radius1, radius2, filled); 692 local s = selection.ellipse(sel, x, y, radius1, radius2); 693 local s = selection.ellipse(sel, x, y, radius1, radius2, filled); 694 695=== fillrect 696 697Example: 698 699 local s = selection.fillrect(sel, x1,y1, x2,y2); 700 local s = selection.fillrect(x1,y1, x2,y2); 701 s:fillrect(x1,y1, x2,y2); 702 selection.area(x1,y1, x2,y2); 703 704=== filter_mapchar 705 706Filter points in selection by choosing those that match the map character, 707and optionally the light state of the map location. 708 709`lit` can be 1 or 0 (which matches the lit or unlit locations), 710or -1, in which case it will choose either all lit or all unlit map locations. 711 712Example: 713 714 local s = selection.filter_mapchar(sel, mapchar); 715 local s = selection.filter_mapchar(sel, mapchar, lit); 716 717=== floodfill 718 719Select locations by starting floodfill at (x,y), 720matching the same map terrain in cardinal directions. 721 722Example: 723 724 local s = selection.floodfill(sel, x, y); 725 local s = selection.floodfill(x,y); 726 727=== get 728 729Get the selection value at (x,y). 730 731Example: 732 733 local value = selection.get(sel, x, y); 734 735=== gradient 736 737Create a "gradient" of selected positions. 738 739Example: 740 741 local s = selection.gradient({ type = "radial", x = 3, y = 5, x2 = 10, y2 = 12, mindist = 4, maxdist = 10, limited = false }); 742 743=== grow 744 745Add locations to the selection by choosing unselected locations 746to the given direction from selected locations. 747If no direction is given, picks all directions. 748 749Example: 750 751 local s = selection.grow(sel); 752 local s = selection.grow(sel, "north"); 753 754=== iterate 755 756Iterate through the selection, calling a function for each set point. 757 758Example: 759 760 sel:iterate(function(x,y) ... end); 761 762=== line 763 764Draw a line from (x1,y1) to (x2,y2). 765 766Example: 767 768 local s = selection.line(sel, x1,y1, x2,y2); 769 local s = selection.line(x1,y1, x2,y2); 770 s:line(x1,y1, x2,y2); 771 772=== match 773 774Every location on the map, centered on the map fragment and matching it, 775are added to the selection. The map fragment must have odd width and height, 776and the center must not be the "transparent" map character. 777 778Example: 779 780 local s = selection.match([[ 781 ... 782 .L. 783 ...]]); 784 785=== negate 786 787Negate the selection. Alias for "unary minus" and "bitwise not". 788 789Example: 790 791 local s = selection.negate(sel); 792 local s = selection.negate(); 793 794=== percentage 795 796Each selected location has a percentage chance of being selected in the new selection. 797 798Example: 799 800 local s = selection.percentage(sel, 50); 801 802=== randline 803 804Example: 805 806 local s = selection.randline(sel, x1,y1, x2,y2, roughness); 807 local s = selection.randline(x1,y1, x2,y2, roughness); 808 809=== rect 810 811Draw a rectangle. 812 813Example: 814 815 local s = selection.rect(sel, x1,y1, x2,y2); 816 817=== rndcoord 818 819Choose one of the selected locations, and return the x,y coordinates. 820If the optional second argument is 1, removes the location from the selection. 821 822Example: 823 824 local x,y = selection.rndcoord(sel); 825 local x,y = selection.rndcoord(sel, 1); 826 827=== set 828 829Set the value for location (x,y) in the selection. 830 831Example: 832 833 selection.set(sel, x, y); 834 selection.set(sel, x, y, value); 835 local sel = selection.set(); 836 local sel = sel:set(); 837 local sel = selection.set(sel); 838 839== Map characters 840 841[%header, cols="10%,90%"] 842|=== 843| Character | Dungeon feature 844| `" "` | solid stone wall 845| `"#"` | corridor 846| `"."` | room floor 847| `"-"` | horizontal wall 848| `"\|"` | vertical wall 849| `"+"` | door 850| `"A"` | air 851| `"B"` | crosswall / boundary symbol hack 852| `"C"` | cloud 853| `"S"` | secret door 854| `"H"` | secret corridor 855| `"{"` | fountain 856| `"\"` | throne 857| `"K"` | sink 858| `"}"` | moat 859| `"P"` | pool of water 860| `"L"` | lava pool 861| `"I"` | ice 862| `"W"` | water 863| `"T"` | tree 864| `"F"` | iron bars 865| `"x"` | "transparent" - used for <<_map>> parts. 866| `"w"` | "any wall" - see <<_match>> 867|=== 868