Lua script

The maps for the dungeon are generated using layouts specified in .des files using LUA script. LUA script is also used when specifying vaults, although those mostly use .des file syntax. This page is for possible changes of additions to the functions that generate these maps and vaults.

Currently, LUA script commands are changed on an ad hoc basis, where (as I understand it) a respected developer just makes the change (either on his own initiative or by request) and it is added to Trunk. While this certainly works well in most cases, it sometimes has problems:

• Requests are (sometimes) communicated over IRC channels, limiting the complexity to single-line explanations
• Some things should be considered before being added. Many commands are undocumented and even unused, meaning there might already be a command that does almost (or exactly) the same thing. In addition, there might be a better way of designing the command that someone else would notice.
• There is the danger of creating an inconsistency with someone else's work, especially if it is in a branch.

To avoid conclusion, I think the current system works well in almost all cases. I made this page for cases where more consideration is needed.

The existing specifications for .des files and LUA script in them can be found here (the same syntax is used for layouts).

Lua in general is good for code a few lines long: doing that in C++ would need several lines of syntax, a prototype in the header, actual call, etc – while Lua can do that ad-hoc. On the other hand, Lua fails badly for anything above around a screen of code. It's just incapable of storing any structured code and keeping it readable.

We recently got two big pieces of lua: layout_loops which is bad but semi-manageable, then layout_vaults which is beyond hope even with its monstrous comment-to-code ratio. Especially with the latter, I have serious doubts if it's a good idea to have code in Crawl that's understandable to only its creator (if even that). I have spend quite a bit of time sanitizing Ziggurat code (and there's a lot left to do there), let's avoid using languages unfit for large pieces of code in large amounts. You write one-liners in Perl not Java, and don't write a 300KLOC program in assembly… — KiloByte 2012-10-06 10:21

The existing SUBVAULT command (or dgn.subvault(…) in LUA) replaces a portion of the map with a vault. This command is very nice, but it is only well-defined and implemented for cases with a : following a single glyph

SUBVAULT: Z : my_subvault_tag

There are no specifications for replacing multiple glyphs with a subvault

SUBVAULT: XYZ : my_subvault_tag

although the current implementation behaves as if it had been replaced replaced by

SUBST:    YZ : X
SUBVAULT: X : my_subvault_tag

In the case of an = instead of a :, the documentation for SUBVAULT: reads:

The use of an equal sign to pick a different subvault per-glyph, e.g. "X = some_vault_tag" is not supported at this time.

Allow the SUBVAULT command to be used with multiple glyphs on the left of the : (or =) to assign several subvaults at once. Using a : would assign each glyph the same subvault, while using an = would assign each glyph a different subvault with the appropriate tag. A single subvault would always be used for each glyph.

We have the following subvaults:

NAME:     example_subvault_lava
TAGS:     allow_dup example_subvault
MAP
 l
lll
 l
ENDMAP

and

NAME:     example_subvault_glass
TAGS:     allow_dup example_subvault
MAP
 m
mxm
 m
ENDMAP

In the following vault

NAME:     example_supervault
SUBVAULT: ABCD : example_subvault
MAP
xxxxx+xxxxx
x.........x
x..A...B..x
x.AAA.BBB.x
x..A...B..x
+....G....+
x..C...D..x
x.CCC.DDD.x
x..C...D..x
x.........x
xxxxx+xxxxx
ENDMAP

either A, B, C, and D would all be replaced by lava pools, or they all would be replaced by glass-coated pillars.

If ABCD : example_subvault had be replaced by ABCD = example_subvault, then each of A, B, C, and D would have independently been replaced with a lava pool or a glass-coated pillar. This would allow 0, 1, 2, 3, or 4 lava pools, but there would be no half-lava/half-glass messes. An example resulting layout would be:

xxxxx+xxxxx
x.........x
x..l...m..x
x.lll.mxm.x
x..l...m..x
+....G....+
x..l...l..x
x.lll.lll.x
x..l...l..x
x.........x
xxxxx+xxxxx

By extension, a SUBVAULT: command with a single glyph and an = would behave as if it had a :. This is consistent with the difference between : and = in other .des commands.

A function that allowed the default wall type to be changed for a map. This would be useful for layouts such as layout_city that make walls of another type. At present, a vault with rock walls (x) placed on such a map still has rock walls, making it appear out of place and easy to recognize.

dgn.set_default_wall_feature(feature_name)

where feature_name is a string or a glyph, similar to what is used in KFEAT. Wall features could be limited to reasonable values, but that risks disallowing a new feature if it is added and no one to updates the “reasonable” list.

There should be a KMASK: or KPROP: command to mark some glyphs of a vault with the overwritable tag as not overwritable. This would be useful for layouts, as it would allow a significant area to be marked as inviolate. Examples would be the special rooms in the new (September 2012) layout_roguey layout (mantis) and the clumped-together staircases in the layout_big_octagon layout.

There are times when it is desirable to place a single (without a band) random creature. This can be done by listing several creature, possibly with weights, but cannot be easily scaled by depth.

I propose adding an extra bandless keyword that can be appended to a random creature list. For example:

MONS: random bandless
MONS: 8 bandless
MONS: place:Zot:1 simulacrum bandless

The first of these would place a single depth-appropriate monster, the second would place a single OOD monster (never with a band), and the last would place s single simulacrum of a Zot:1 minster (probably a draconian).

This would be useful to place monsters in some pattern (e.g. in a ring around a staircase), or if a monster was being deliberately contained (e.g. behind glass walls).

A simple implementation of this would just remove the band command from a monster if it was selected. A more sophisticated implementation would only select monsters that did not have a band. A fallback case would be needed.

The opposite command, possibly called banded, would always select as monster with a band. This would probably be less applicable, although not entirely useless.

Bad idea, I'd say – or at least, not good enough to complicate the structures. Most monsters that spawn outside several first D levels (like gnolls) that have packs do so because they're mostly pointless without them. A clutch of floating skulls is flavourful, one is odd. A band of ogres with both bruisers and an ogre mage can pack a punch even in mid-Vaults, a lone mage without help is not meaningful past, say, Orc:1. — KiloByte 2012-10-06 10:21