From 4fe67e14cab6affd2a69a864dda356440d50e0ca Mon Sep 17 00:00:00 2001 From: Enne Walker Date: Sat, 28 Nov 2009 18:06:49 -0500 Subject: Subvaults. Vaults can now include other vaults as a part of their definition. These subvaults are currently included by tag only and replace glyphs in their parent vault. See documentation for more details. Vault:8 has been modified to use subvaults. --- crawl-ref/docs/develop/levels/syntax.txt | 99 ++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) (limited to 'crawl-ref/docs') diff --git a/crawl-ref/docs/develop/levels/syntax.txt b/crawl-ref/docs/develop/levels/syntax.txt index a1561ba84c..8fba8bed49 100644 --- a/crawl-ref/docs/develop/levels/syntax.txt +++ b/crawl-ref/docs/develop/levels/syntax.txt @@ -1016,6 +1016,105 @@ MARKER: A = feat: or lua: SHUFFLE: Oa/|c MARKER: O = lua: +SUBVAULT: X : some_vault_tag / some_other_vault_tag:20 + + Pick a vault that matches the tag and replace matching glyphs in + the current map with the cells from that vault. + + Multiple glyphs can be specified on the left hand side and + weighted sets of tags can be used on the right hand side. + + 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. Use + a ':' instead to fix the choice of vault tag among all glyphs. + + When a subvault is applied, the first step is finding the smallest + bounding box around the glyphs. For example, in the following vault + definition, the smallest bounding box around the X glyph is a 4x3 + rectangle: + + ...... + ..XXX. + ..XXX. + .XXX.. + ...... + + After the bounding box is calculated, a valid subvault that matches + the given tags and is no larger than the bounding box will be found. + If no subvault can be found, the vault will throw an error. If a + subvault is found that is smaller than the provided bounding box, + then it will be randomly placed and possibly rotated within the + bounding box. + + There is not much optimization to best fit a subvault into the + glyphs provided by the parent vault. So, take some care when using + non-rectangular subvaults. The only special case is if you provide + a subvault that is the exact same shape as what the parent vault + requests. + + Everything from the subvault cell (feature, items, monsters, + properties, markers) overwrite the glyph in the parent map. + Once replaced, this cell is immutable and cannot be changed + with something like SUBST, MARKER, or KFEAT. + + Additional glyphs that are not replaced by the subvault will be left + untouched so that the parent vault can replace them with whatever + feature it desires. These untouched glyphs can occur either because + the subvault was smaller than the bounding box or because the + subvault left the glyph blank (' '). Because of this, a SUBVAULT + command should usually be followed by a SUBST command to clean up + these remaining glyphs. + + Subvaults are allowed to include subvaults themselves, recursively. + However, there is no checking for infinite loops or cycles of + subvaults, so use this feature with some care. + + During map verification, the SUBVAULT command does not do anything. + Therefore, the compilation step for Lua vaults will not catch errors + where no maps exist for a given tag or where all maps that do exist + are too big to fit into the provided space in the parent map. (The + reasoning for not verifying the subvault command is so that you can + specify maps by tag that may be defined later in the file or even in + another file that hasn't been loaded yet.) So, test your subvaults! + + As the size of the subvault may vary depending on the parent vault, + there are some helpful Lua functions (in the dgn library) that can + be used to get more information about what the parent vault is + requesting. Here's a quick reference: + + is_subvault() + + This function returns true if the current map is being used as a + subvault and false if the current map is a normal vault. + + local width, height = subvault_size() + + This function returns the width and height of the subvault. + If not a subvault, it returns 0. + + iter.subvault_iterator(_G) + + Can be used to iterate through all the 0-indexed coordinates + in the subvault that will get copied back to the parent vault. + It will return no points if this is not a subvault. + + default_subvault_glyphs() + + This is a convenience function that replaces the current + subvault map with one that is the exact size of the bounding + box. For any valid square that the parent map will replace with + the subvault, it will place a '.' in the map. For any invalid + square that will not be replaced by the subvault, it will place + a ' ' in the map. If not a subvault, it does nothing. + + The advantage of this is that a vault author can then use nsubst + on the '.' feature to ensure that a fixed number of objects will + be created in the parent vault. + + NOTE: This function will also entirely clear the current map, so + call it first in the subvault definition. + + Handling long lines ------------------- -- cgit v1.2.3-54-g00ecf