Request: Documentation for key modding items

Hi there

I’ve watched this from the sidelines for a long time and bit the bullet this past weekend and bought the game. I think you guys have done a fantastic job. I’m leaning more towards the Gnomoria/Dwarf Fortress type gameplay and thus promptly started to dig around in the game files.

I’m sure there are many others who would want things like random caves, more types of ores, building settlements into the mountain etc. and it would seem that the base game provides all that is needed.

What is not there is reasonably good documentation. I understand that you don’t want to document what you may yet change, but come’on, have a heart and give a guy or gal a hand!

I’ve tried to dig through the world gen code, the rivers mod and some of the archipelago mod but without some guidance on how everything hangs together, what order things get called in and why functions are there and done in one way and not another, it’s pretty hopeless (e.g. why 32x32 vs. 16x16 chunks vs blueprint vs ore scenarios vs underground maps, etc.

I think you see the point. I think the community would rapidly add to the depth of the game if you give us a hand. I simply wanted to create some caves and some new ores … I’m not talking about dungeons or events and I think that is something that should be fairly straight forward (not expecting I-depth hand-holding, but without some guidance on how things hang together this just seems like a waste of time to try).

Oh, and I also wonder if the map height (or rather, depth) can be changed - the slice tool seems to indicate it’s 64m. Is that hard coded or can we go deeper? If hard-coded … please change it (and while I’m on it, make the slice tool go by cube and put it on the scroll wheel … much more natural for those of us who want to dig … and fix the mining tools, PLEASE! :slightly_smiling_face:

Thank you!


I have asked this question of the devs repeatedly over the last two years or so. Their reasoning is that the API is still under development, and so, writing any documentation would be premature. I can’t say I disagree with this line of reasoning.

That said, I encourage you to keep reading through the game files. Team Radiant employs some masterful codewrights, their code is both self-documenting and generously commented. I’m a programmer of average skill, and I was able to work out the game’s systems enough to identify the parts that interested me. I’m sure if you have any aptitude for coding, you will also be able to navigate fairly easily through the code.


Thanks Moai - I’m sympathetic to the devs not wanting to invest a lot of time in documentation of stuff that will still change.

Yet - I’m not looking for a detailed, hand-holding type documentation and someone writing down a broad outline of how things hang together, what functions get called in which order, what is used and what is not used, and how, would probably take all of 30 minutes for the dev responsible for that bit of the codebase.

It’s really a small ask and would go a long way towards the community being able to enrich the game!

Unfortunately, not all of the devs who wrote the code are still with the team. In addition, if you haven’t had a look yet, there is a lot of code there. And that’s just in terms of lines of code, add to that the general architecture, overview of things like Campaigns and AI, etc etc etc… Formatting the documentation, proofreading it, keeping it updated, all of that takes time. And as it is, the community has already been fairly loud about feature updates being slow. They certainly don’t need the extra overhead.

As it stands, I think their level of documentation is more than adequate for an Alpha product. The comments alone are a godsend. At the end of the day, if you’ve dug around and still have no idea, just come to the forums and ask around, somebody will help you.

1 Like


(1) I did not ask for proper documentation - I asked for an outline that helps people understand what’s going and how the logic flows. That does not necessarily have to be kept up to date by the devs (they don’t seem to spend time on this part at the moment anyway).

(2) I’m not criticising the state of the documentation in relation to the version the game is at, I’m merely putting out a plea for someone to spend an hour and help the community out. I’m quite happy to do the work that enriches the game and ultimately makes it more valuable and more sell-able for the devs, which is good for them, but I have a demanding day job and it’s simply too demotivating having to dig through many files to understand the flow without there being even an outline of relevant concepts … an no, the code comments are not great (unless you’re a mindreader).

I have asked Bruno, who’s provided some helpful pointers - but it’s not really helpful for the community if that knowledge just sits in one or two people’s heads in my view. I’ve asked a private question but a post on the topic will help others.

There’s much to do - different types of rock, different ores (yes I know some mods have that already), terrain that is properly layered, has caves, etc. and I think the engine is pretty much in place for many things, the devs have limited capacity and really need to focus on fixing core stuff such as:

  • WTF is up with mining … it feels like someone purposefully made it difficult - the code shows that a lot of work has gone into combining mining zones, which is theoretically interesting but not necessary for the gameplay …
  • and why can’t I bind the scroll wheel to go through slices and CTRL-SCROLL to zoom, etc. … basic stuff even DF’s ASCII interface does well …
  • Why can’t I seem to remove a window that I put into a mountain wall via place object?
  • Do rooms dug out of the side of a mountain give hearthlings the same happiness as houses? Why shouldn’t they?
  • Why can’t I smooth dug-out walls or engrave them? Do I really need to mine an extra layer and build an interior wall? (Probably moddable)

… this game is currently basically only good if you want to build houses and hopefully that system will be fixed soon, and then they actually start looking after people wanting to hollow out mountains.

Anyway, I’d be surprised if I’m the only one who would like to be able to do these things. I wanted to make a start and people could use that start to build on it … but, as I said, with the little time I have, I can’t spend several evenings trying to second guess why the devs constructed, e.g. the world gen, the way they did.

Of course you might say that the devs have other things to do … for sure, it just seems that stuff like seeing appeal is nice to have but not essential when frigging basic mining doesn’t work properly.

In the end, devs dwaddling around with facial expression and not fixing the game to allow more than just building pretty houses cube by cube will mean that the game dies as people will leave … AND THAT WOULD BE A GREAT SHAME.

I imagine they probably have at least an AI flowchart or two from the redesign. I’d be all for some of that being released publicly if it’s not too hard to make presentable. They’ve released a couple documents on style standards for the models and icons, so showing these things could happen, but even if it does it probably won’t be for a while.