Thanks so much for posting this! I've always wanted to get into vaulting but never really got around to it, and this is a perfect excuse to give it a shot!

I noticed a couple of things reading the documentation:

Reading paragraphs and paragraphs of text in notepad is not pleasant

I would definitely have appreciated a tiles version of the example temple vault (the one with plants, stones and butterflies)

Having not designed a vault before, I had no clue where to start trying out vaults - it would be nice for them to give an example - something like "Try creating a vault that has a long corridor full of dart traps and doors with a small pile of gold at the end" (or a list of several such ideas), though not a good vault, would have given me something to start with to see if I could do it.

It took me ages to find out that the keywords were available in the syntax.txt file - I was looking in section C that listed the .des files since it seemed to list all the files I'd need to start vaulting. I remembered I'd read about a file that would tell me what the commands did, but not where in the document the location of that file was given. Perhaps a note at the bottom of the document that says "Now you've read this, get started! Go to docs/develop/levels/syntax.txt for syntax info, dat/des/variable/entry/entry_simple.des for some example entry vaults, or dat/des/variable/entry/entry.des for information about creating new entry vaults" (probably in the form of a list I guess)

I loved that syntax.txt has information about the behavior/properties of each of the items in the list at the top (eg which walls are diggable, which walls reflect cold and fire, which walls can be melted, what can be seen through and what can't).

Syntax.txt refers to "dummy" vaults, which I had no idea what they are until reading further along in the file. Explaining what they are earlier, or even saying (see TAGS section of this document) would've reassured me that I hadn't missed reading something.

Syntax.txt is so full of things and explanations and everything that I didn't read through all of it, I just looked for the headings you asked me to include and learned about each in term. I think a list giving a quick overview of what each command does, preferably divided by complexity, would be kind of neat.

The instructions say that no matter how rare you make something, it will still be seen by tons of people and/or piss them off. In one of my vaults I wanted to make it produce a randart 1% of the time, but decided not to do that just in case that would be far too much. A ballpark figure for how often randarts should be generated in vaults (even if it's never!) owuld be great.

I wasn't sure which file to place non-entry vaults into (ended up using float.des but I'm not even sure if that's the right place)

To answer your specific questions:

1. NSUBST and SHUFFLE were a little bit hard to figure out, but with shuffle I got there without too much trouble. I understand the basics of NSUBST but my eyes sort of glazed over when it came to the more advanced parts of NSUBST.2. Very easy to create the vaults and put PLACE:1 on them, saw them in the game! Wizmode even let me put my vault in tons of times on the same level, which was great for figuring if SHUFFLE was moving the founts of water/blood around correctly.

Here's my trap corridor, it doesn't fit your rules but I wanted to make something that I could see . On that note, holy crap, I made a little tunnel and it appeared in the dungeon and my demonspawn dude walked through it! This is the happiest day of my life!

Slightly off-topic, but I want to say my favourite entry vault ever was one I got a few days ago - I was on one tile surrounded by lava. "What? Am I going to have to quit?!" I said to myself, and started searching for secret doors. Then a kobold came from around a corner and hit me with a dart of blinking! What a cool idea that one was

Absolut beginner noob questions.If I have made some vault, how to test it out in game? Just to copy it in a .des file in my tiles-trunk folder does not function. Adding some DEPTH or TAGS in the header brings CRAWL to crash when I want to start it.Have I to download the source and compile it in some way? Can I switch to wiz mode in the normal trunk?I just need some step by step explanations of how to test this out in game:

I just had a quick look at the documents in docs/develop/levels. If you're new, I'd expect you to check out introduction.txt first. There, you should learn something about maps in general, and it also tells you to look up details in syntax.txt (at the end of section B).

I am very happy about minmay's thread, as it will allow us to improve the documentation. But I wonder a bit what's really missing for a newcomer...

While what is already in place Works i think that a video tutorial would be very much welcome.I've read all of that stuff and I'm still a bit confused as to it how work does can?

Also i've brought this up before but it instantly got shot down (for some reason?)Alot of games have level editing side programs. Why can't Crawl have one for people to make their own Dungeon Sprints/Zot defense maps?

omndra wrote:While what is already in place Works i think that a video tutorial would be very much welcome.I've read all of that stuff and I'm still a bit confused as to it how work does can?

Also i've brought this up before but it instantly got shot down (for some reason?)Alot of games have level editing side programs. Why can't Crawl have one for people to make their own Dungeon Sprints/Zot defense maps?

Duh. Because it's a lot of work to code one. And there's already so much things to do on the game itself. If someone wants to contribute...

<+Grunt> You dereference an invalid pointer! Ouch! That really hurt! The game dies...

1. Did you have trouble understanding any part of introduction.txt or syntax.txt? If so, which part(s)? In particular, were NSUBST and SHUFFLE hard to figure out?2. Did you encounter difficulty getting your vaults to work in the game?

1) No, no they were fairly straightforward2) A couple times - it took me a while to figure out why it was crashing a couple times (and I honestly don't remember what the cause was, I believe I had monster names in incorrectly a couple times, and exceeding the map size as well). I think it may help to give suggestions for troubleshooting the vault (are they there and I just missed them?) such as commenting out code line by line or whatever until it launches so you can identify the exact problem without dumping your work. Not super important, as most people will figure it out themselves, but it may help someone down the road.

My initial impression of the docs is that they are certainly thorough with regards the information required. However the introduction.txt could maybe be structured a little better. For instance, it jumps into explaining all the different kinds of vault without clearing up some real basics first.

The first section should probably be a really short tutorial on creating your first vault. Without explaining what all the different files are, simply direct the reader to open up, say, float.des and add a very simple first vault, then give step-by-step instructions of how to see that on the screen in Crawl.

To get all this initial information I had to jump around in the document quite a bit. Somewhere along the way, Vim is mentioned - this should probably be right at the start in a "Tools you might find useful" section. You don't want to get part-way through the instructions then have to go off and start installing and configuring software. The levdes.vim file contains instructions for Vim configuration but the tutorial doesn't mention this, perhaps these instructions should just be included in introduction.txt.

Obviously it would be nice if the documentation was redone in HTML for readability and easy navigation (and including some screenshots to show how example vaults look once they're in the game).

I think a nice way to present the information, instead of just going through every topic in a pure reference style, would be if a series of example vaults were presented, each one introducing a few new features, so not so much to take in all at once. Then finally present the reference of all the different options, once the key concepts have been conveyed.

Right, those niggles aside, the principal bits of information I feel I'm lacking right now are;

- Instructions for entering and using wizmode- A list of monster names

Now, I know I'll be able to go off and find these somewhere but I don't have them in front of me looking at the documention. Again wizmode should be one of the first things covered, or at least pointing to instructions elsewhere, so you have a straightforward way of testing your vaults right from the get-go.

For the vaults I'm initally trying to make I'll only be using some basic monster types so I'll likely be able to guess the names, or find them in other vault definitions - but it would be great to see a complete list.

Ok, I'm going to find out about wizmode and report further on my progress...

Was all pretty easy once I'd figured out how to make it show in the game (easy enough with &L but the placement was sometimes a bit strange, wanted to see how it would organically appear in a level). Obviously the depth should be increased. I hope the monsters / items aren't too much after the various SUBSTs.

I wanted to have a couple of the rooms visible and a couple hidden, so seeing the first two would hint that the other ones might be there for searching / digging. But in the end the kobolds hear the fighting and just come out anyway - maybe should make some transparent rock instead of doors, or use non-intelligent monsters?

The only other problem I had was Crawl started crashing similar to how 7hm described. In the end it was nothing to do with my map, I reverted the changes and the crash still happened. Restarting my computer fixed it completely. When there's a problem with the map syntax, Crawl just quits without a message - would be good if it were possible to give any kind of hint as to what was wrong!

mumra wrote:To get all this initial information I had to jump around in the document quite a bit. Somewhere along the way, Vim is mentioned - this should probably be right at the start in a "Tools you might find useful" section. You don't want to get part-way through the instructions then have to go off and start installing and configuring software. The levdes.vim file contains instructions for Vim configuration but the tutorial doesn't mention this, perhaps these instructions should just be included in introduction.txt.

mumra wrote:To get all this initial information I had to jump around in the document quite a bit. Somewhere along the way, Vim is mentioned - this should probably be right at the start in a "Tools you might find useful" section. You don't want to get part-way through the instructions then have to go off and start installing and configuring software. The levdes.vim file contains instructions for Vim configuration but the tutorial doesn't mention this, perhaps these instructions should just be included in introduction.txt.

I think the part about Vim bears repeating.

Yes. Maybe a short tutorial on Vim would be nice as well. I've spent a lot of time with vi so was fine; but it's a pretty technical editor for anyone to get into who's not used to it!

I agree that starting up front with a step-by-step list of how to add a little vault is good:

1. Open a .des file (for example source/dat/des/variable/mini_features.des) in an editor of your choice.2. If you are able to use vi (or vim or gvim), you get the bonus of [levdes file]3. Copy an existing vault and rename it (change the string after NAME).4. Save and run Crawl. If you get an error, your new name was already used. Take a different one.5. Apply changes to the vault. See below for what the various symbols in the MAP and the keywords mean.6. For testing, use & to enter wizmode. This makes it easier to test vaults (press &? for help).7. To make sure your vault occurs in the game, either use the wizmode command &L which asks for a string (it suffices to enter a substring of your vault's name that uniquely matches it). Or add a PLACE: D:1 which will make the level builder use that vault on the first dungeon level.8. If you get errors (i.e. the game wouldn't start), check the indicated line. Very often, it is useful to comment out some lines of your code (by adding an # in front of the line).

What do you think? I am not sure about a list of monsters.... these lists are outdated very soon. By the way, there's the same issue with lists of colours, traps, clouds and tiles. Not sure how to indicate these.

dpeg wrote:8. If you get errors (i.e. the game wouldn't start), check the indicated line. Very often, it is useful to comment out some lines of your code (by adding an # in front of the line).

When I had errors Crawl just bombed, it didn't display any errors or indicate any line numbers. I think one specific problem that caused this was I had omitted ENDMAP. Took me a while to figure out!

dpeg wrote:What do you think? I am not sure about a list of monsters.... these lists are outdated very soon. By the way, there's the same issue with lists of colours, traps, clouds and tiles. Not sure how to indicate these.

If each of those are in a specific header file it might be best to just reference them all. The handy thing would be to list the URLs of the those files in the online Git browser, for easy access (are there permalinks that will always go to latest version of the file?) This would avoid having to update your local repository (or even needing the entire source code at all).

Mumra - I had the same problem with tiles just closing with no errors. However, when I opened up console version I got a line number. So if you're like me and use the installer and thus have both console and tiles, you can use that.

I just realised I probably should've mentioned it in my post - it would be nice if tiles could display the error rather than closing angrily.

This is awesome. Designing the vault was the easy part, especially when directed to the more important declarations. The hard part was getting it to test. First, I only played online before, so it took me a minute to understand what people were talking about. (Playing offline, made me realize how slow webtiles is though and how barebones its interface is too) Second, the .des file forced me to think for a bit, I ended up editing it in notepad and then had to adjust all the file properties to get access to save it. Also, I had to add CHANCE: 100%. I'm not the most sophisticated computer user, so this stuff wasn't obvious to me. All in all, it still only took a little over an hour to write it and then see it in action. Now what I want to know is where do we post vaults to get a thumbs up/down for them to be accepted and put in to webtiles? And what type of vaults are most needed? Minis? Stuff for upcoming project like spider?

Oh and here's the vault - I felt like hobgoblins seem so lonely and unloved and that some of them may be capable of having a nice little home with a few friends and pets and some clean water. Also, I figured I could expand this to make a unique "Harry the hairy hobgoblin" at some point. Not sure if uniques are kosher though, I know it's probably pretty touchy to add a new one. I think I do want to add a dialogue line for when you open the door at least to make it more obvious that you are intruding.

Guppyfry wrote: And what type of vaults are most needed? Minis? Stuff for upcoming project like spider?

What's needed most are Spider vaults, although all types of vault are usually welcome. But Spider is really lacking in any unique content right now: entry, welcome, floating and branch end. There's the new web trap to use in them as well. The relevant Mantis item is: https://crawl.develz.org/mantis/view.php?id=4453 - although there's still some uncertainty about what the branch end will contain, it can't do any harm to start experimenting with designs - you'll be able to use it somewhere.

Guppyfry wrote:Also, I figured I could expand this to make a unique "Harry the hairy hobgoblin" at some point. Not sure if uniques are kosher though, I know it's probably pretty touchy to add a new one.

Named monsters should be used extremely sparingly; occasionally they can be appropriate. Have a look through existing des files to see some examples of when name functions are used.

By the way, have a look at the updated vault documentation on the dev wiki: https://crawl.develz.org/wiki/doku.php?id=dcss:help:maps - a number of things have been fixed which were out of date in the old docs. And of course if you notice anything that needs fixing, you can go ahead and edit it

I'm getting used to wizard mode now for testing. I had two problems come up though. When I tried to create a portal for "spider" it said there was no such thing, so these are three spider minivaults (each roughly 12x12 with 8 random spiders) that I couldn't see in the setting of an actual spider level.

I also created a sewer map for kicks when I saw the thread mentioning that mites, roaches and geckos can all cling now, but when I was prompted for which sewer to use (after entering the wizard mode portal) and put in my map name it said there was none with that name. When I used "L" to just drop it in D:1 it worked though. I'm not sure if I'm missing something to make it function as an actual sewer portal. I had put it in the bottom of the sewer.des file.

The spider maps also didn't quite feel "natural", but this was set in D:1 and I'm still totally unused to seeing a map I drew pop up. The only other thing I noticed is that wolf spiders are much tougher than I remembered. The sewer map was kind of boring, but the sewer is always kind of boring. I thought about putting in a baby alligator, but they seem a little too tough.

My only other problem was a feeling of aimlessness. The vaults are below and any feedback about what makes a new vault functional and worthwhile would help.

Guppyfry wrote:When I tried to create a portal for "spider" it said there was no such thing, so these are three spider minivaults (each roughly 12x12 with 8 random spiders) that I couldn't see in the setting of an actual spider level.

Yeah, the &P command is a bit tricky to figure out. You need to give it the dst value of the portal which you can find in dat/des/portals/*.des. For spiders, the name is spiders_nest. It doesn't do partial match but it turns spaces into underscores. It creates a reusable wizard portal. If you want a real one, you need to use &L and place a portal entry map (portal_spiders_nest_entry_a).

<+Grunt> You dereference an invalid pointer! Ouch! That really hurt! The game dies...

Guppyfry wrote:I'm getting used to wizard mode now for testing. I had two problems come up though. When I tried to create a portal for "spider" it said there was no such thing, so these are three spider minivaults (each roughly 12x12 with 8 random spiders) that I couldn't see in the setting of an actual spider level.

It depends on which version you're using - if you're using 0.10 (trunk) then Spider is now a full branch, you can go there by typing: &~N1

It's recommended to use trunk anyway for designing vaults, since that's the version they'll end up in, it makes more sense to design and test them against it (you can also see how webs will affect your vault).

I also created a sewer map for kicks when I saw the thread mentioning that mites, roaches and geckos can all cling now, but when I was prompted for which sewer to use (after entering the wizard mode portal) and put in my map name it said there was none with that name. When I used "L" to just drop it in D:1 it worked though. I'm not sure if I'm missing something to make it function as an actual sewer portal. I had put it in the bottom of the sewer.des file.

The only thing possibly missing from the map definition is a WEIGHT line; not sure if that would cause the game to just not recognise it tho. What could be the problem is that Crawl pre-compiles all the map files the first time it starts up; maybe it hasn't recognised your changes and recompiled. The map compilation files are somewhere in your saves directory, you could try deleting them to retrigger compilation.

The spider maps also didn't quite feel "natural", but this was set in D:1 and I'm still totally unused to seeing a map I drew pop up. The only other thing I noticed is that wolf spiders are much tougher than I remembered. The sewer map was kind of boring, but the sewer is always kind of boring. I thought about putting in a baby alligator, but they seem a little too tough.

My only other problem was a feeling of aimlessness. The vaults are below and any feedback about what makes a new vault functional and worthwhile would help.

Not all vaults need an obvious theme or point, they're just little bits of less random architecture that pop up here and there to offset the randomly generated bits of the dungeon. Sometimes it's nice to make things with a bit more direction, but if every vault was like that it'd be too much. Also, as you make more you'll get a better idea of how to create an interesting tactical encounter out of even a very small, simple vault. Looking through existing designs and reading the comments can help with this. In general, simple little maps (they don't even have to have any monsters; the level generator can supply those anyway) can be placed much more naturally into a level than big, complex ones.

I downloaded trunk. The spider branch looks great with all those webs. The mini vaults fit in much better in the branch since the branch levels are much more open. Roxanne showed up on spider:2 when I was testing, which caught me off guard though.

Still can only get my sewer map to load as a vault (&L) and not as a chosen sewer map when entering a the wizard portal. I didn't see any saves directory, but I am ctrl-Q all of these wizard characters and have not played otherwise, so there may not be any saves.

Before I get started, do you accept edited documents and can you do a proper document comparison?

There is a lot of bulk (not erroneous) text.

Once I start reading, I plan to edit any sentences that appear overly wordy to smooth them, and will hand you the edited document(s).

I have 0.10-a0-602. Should I start with the next revision instead?

"Be aware that a lot of people on this forum, such as mageykun and XuaXua, have a habit of making things up." - minmay a.k.a. duvessaDid I make a lame complaint? Check for Bingo!Totally gracious CSDC Season 2 Division 4 Champeen!

As the comment says, it is a hobgoblin kitchen with a "tough" cook inside and two normal hobgoblins hanging around outside the front door. The cook is not particular nice to his kinsmen though since he is hiding the good stuff from them.

omndra wrote:While what is already in place Works i think that a video tutorial would be very much welcome.Also i've brought this up before but it instantly got shot down (for some reason?)Alot of games have level editing side programs. Why can't Crawl have one for people to make their own Dungeon Sprints/Zot defense maps?

Duh. Because it's a lot of work to code one. And there's already so much things to do on the game itself. If someone wants to contribute...

I have written a simple visual vault editor. It is an Java applet an is currently at http://infiniplix.ca/applets/vault_editor.html. I have visual images for each tile ("borrowed" from DCSS Tiles of course). You can enter your vault as tiles and copy it out as text. Or copy in a vault as tiles. There is also a Preview command that will eventually show you what your vault looks like with SHUFFLE, SUBST, and NSUBST commands. I am not finished the program yet, so NSUBST currently does nothing. However, I thought I could post it anyway.

I am not sure if this is where I should post this. Possibly it should have its own thread. Or something else. I can provide the source code if desired, but as of yet is is kind of disorganized and entirely undocumented.

On another note, there are ambiguities in the syntax.txt file. Those I have found so far are:1. SHUFFLE: xc/mx - do existing 'x's become 'm's or 'c's - ditto SHUFFLE: xx/cm2. When exactly do SUBST: lines resolve as weights and when as characters? - what is the meaning of SUBST: c = m x:20b - what about SUBST: c = m xb:203. SUBST: a = : b c - Does this replace all 'a's with a random one of ':', 'b', or 'c' - Or are all 'a's and all '='s replaced with the same one of 'b' or 'c'4. NSUBST with '/' characters is just explained

I'll jave to disable java to try that out (or get a browser that supports it first) but I want to thank you for making an editor. Any kind of editor that simplifies the process of making vaults, even if it does not include every feature, will vastly improve the quantity of vaults and nudge people closer to learning how to "code" then from scratch. You see this with the portal 2 community test chambers: valve released a very simple portal editor that lacks many features, yet has enough support that a good hand can make some very impressive stuff.

Minmay, I haven't submitted any vaults yet (still learning how to utilize every modifier) however I have made a few dozen so far and none of them were done without using your maps as a reference. So thank you as well. I think video tutorials are a great thing, and something I have experience doing having run a successful youtube account. This is something I'd seriously consider when I have vault creation down on the same level as the regular contributors.

seattle washington. friends for life. mods hate on me and devs ignore my posts. creater of exoelfs and dc:pt

5. The layout_BAR tags are unclear. When I saw them, I assumed that they would correspond to the layouts in builder.des. However, this is empirically not the case. They actually use some sort of different system that is not documented in the syntax file. Attempting to use the layouts in builder.des (e.g. layout_forbidden_doughnut) just makes the vault not appear.

This sounds like a great project, but I would make one suggestion: the easiest way to test a vault is to reuse game code, i.e. develop an in-game vault editor system instead of building a separate application. This will mean as well as solving your problems with SHUFFLE, SUBST, etc. you can also test LUA without having to reimplement a huge chunk of the game API (and think of the maintenance nightmare if you want to keep up-to-date with trunk, which happens to be the version that most serious vault development is done against).

I did a bit of testing to check some of these but I might still be wrong:

1. Say my map is:MAPxxxx.ccc.mmENDMAP

SHUFFLE: xc/mxIf the shuffling happens (of course %50 of the time it does nothing) I get mmmm.xxx.xx - x > m, c > x, m > x. My impression is that we run through the declaration in order: x>m then c>x then m>x then x>c, changing each in turn, but never changing a tile that we've already changed (so we don't get m's changing to x's and then to c's).

SHUFFLE: xx/cmIn this case when the shuffling occurs I get cccc.xxx.xx; x > c, c > x, m > x. This fits with the above, since we first change all the x's to c's, leaving the second x to do nothing.

2. It seems to only get counted as a weight (and not crash) if you put a space, one character, a colon, the weight number, and then another space.SUBST: c = m x:20b gives me a crash, presumably because the game tries to interpret 20b as a number.SUBST: c = m xb:20 gets interpreted as just a string of characters so you get :'s and 0's getting laid down, for example.

3. SUBST: a = : b c replaces each individual a randomly with {:bc}, and doesn't touch ='s. SUBST: am = : b c messes with both a's and m's and doesn't touch ='s.SUBST: a= = : b c replaces each individual a randomly with {=:bc}. Still doesn't touch ='s.Thus it seems like it grabs the first = or : (after the first character, for cases like SUBST: = = ab) and uses that as the operator.

4. The / means something like "then," soNSUBST: ! = 3:x / 10:cb / *: m a:20 Gwill do this: First, replace 3 !'s with x's.Then, replace 10 of the remaining !'s with a mix of c's and b's.Then, replace all the remaining !'s with a mix of m's, a's, and G's, with a's being twice as common as the others.

Actually, I posted them ambiguities in the syntax.des file because I thought that it would be easier for people to make vaults if these were clear in the instruction file. Thank you for the answers anyway, ontoclasm, it is nice to know.

I got started vault editing by reading, in order:1. Section G. Glyphs in syntax.txt2. A complete branch specification (I think it was Lair, but it was a while ago)3. The rest of syntax.txtThis actually worked pretty well for me (I still haven't read all of introduction.txt). From this, I judge that your information is already pretty good. On the other hand, I have Asperger's Syndrome and already know 2 programming languages, so I may not be a good test case. I hope this is helpful.