Bay 12 Games Forum

Please login or register.

Login with username, password and session length
Advanced search  

Author Topic: Expanded Documentation for DF Hack or tutorials?  (Read 2365 times)

Zerim

  • Bay Watcher
  • One man's past is another man's weapon
    • View Profile
Expanded Documentation for DF Hack or tutorials?
« on: November 22, 2016, 08:57:31 pm »

After spending quite a bit of time through the DF Hack user manual, I've been having a troubling time figuring out what I'm supposed to do with the tools given to me. I can see it has mod tools, but it just give me a set of standard functions and not much else. It seems strange to me that the program encourages users to make use of its advanced features, but do nothing more than tell them to figure it out on their own?

That's what I never understood about DF's modding community. It appears that almost everyone is self-taught in some way, and the only in-depth and meaningful tutorial that I've been able to find is on the wiki. I have done extensive searching and have found absolutely no meaningful or helpful tutorials on utilizing DF Hack, and that's incredibly strange to me. Surely, with all the time DF Hack has been out, no one has thought to write up even a brief tutorial for new modders?

How am I to make use of these functions and scripts and plugins? How do I make custom raws? How do I make custom syndromes and announcements? It seems that the only way to figure these things out, is to indeed do intense research through both the documentation and the files provided in DF Hack. I found that looking through Deon's Fallout Mod was an interesting way to see how things worked, but there needs to be a a more comprehensive and in-depth guide for making such modifications.


If there are any in-depth guides for creating mods that take advantage of DF Hack's features, please let me know.
Logged

Warmist

  • Bay Watcher
  • Master of unfinished jobs
    • View Profile
Re: Expanded Documentation for DF Hack or tutorials?
« Reply #1 on: November 23, 2016, 08:11:51 am »

After spending quite a bit of time through the DF Hack user manual, I've been having a troubling time figuring out what I'm supposed to do with the tools given to me. I can see it has mod tools, but it just give me a set of standard functions and not much else. It seems strange to me that the program encourages users to make use of its advanced features, but do nothing more than tell them to figure it out on their own?

That's what I never understood about DF's modding community. It appears that almost everyone is self-taught in some way, and the only in-depth and meaningful tutorial that I've been able to find is on the wiki. I have done extensive searching and have found absolutely no meaningful or helpful tutorials on utilizing DF Hack, and that's incredibly strange to me. Surely, with all the time DF Hack has been out, no one has thought to write up even a brief tutorial for new modders?

How am I to make use of these functions and scripts and plugins? How do I make custom raws? How do I make custom syndromes and announcements? It seems that the only way to figure these things out, is to indeed do intense research through both the documentation and the files provided in DF Hack. I found that looking through Deon's Fallout Mod was an interesting way to see how things worked, but there needs to be a a more comprehensive and in-depth guide for making such modifications.


If there are any in-depth guides for creating mods that take advantage of DF Hack's features, please let me know.

What most people don't understand is that dfhack is not as popular as it looks. Sure there might be thousands of users but developers are very few and far (in a sense that they touch only some part of dfhack) apart. Sure even i had few ideas about tutorials but they would be in some (probably not very useful to you) part of dfhack. And dfhack is very big- almost as big as df (well maybe not that big, but you get the idea).

There are few ways to use dfhack to mod: write plugins (c++), write scripts (lua/ruby), and df raws that call scripts/plugins. Mostly used is the last one. It depends on the first two but is closest to df raw modding. Also it's the one i least understand (and it looks the most complicated to me).

jaked122

  • Bay Watcher
  • [PREFSTRING:Lurker tendancies]
    • View Profile
Re: Expanded Documentation for DF Hack or tutorials?
« Reply #2 on: January 08, 2017, 09:14:03 pm »

After spending quite a bit of time through the DF Hack user manual, I've been having a troubling time figuring out what I'm supposed to do with the tools given to me. I can see it has mod tools, but it just give me a set of standard functions and not much else. It seems strange to me that the program encourages users to make use of its advanced features, but do nothing more than tell them to figure it out on their own?

That's what I never understood about DF's modding community. It appears that almost everyone is self-taught in some way, and the only in-depth and meaningful tutorial that I've been able to find is on the wiki. I have done extensive searching and have found absolutely no meaningful or helpful tutorials on utilizing DF Hack, and that's incredibly strange to me. Surely, with all the time DF Hack has been out, no one has thought to write up even a brief tutorial for new modders?

How am I to make use of these functions and scripts and plugins? How do I make custom raws? How do I make custom syndromes and announcements? It seems that the only way to figure these things out, is to indeed do intense research through both the documentation and the files provided in DF Hack. I found that looking through Deon's Fallout Mod was an interesting way to see how things worked, but there needs to be a a more comprehensive and in-depth guide for making such modifications.


If there are any in-depth guides for creating mods that take advantage of DF Hack's features, please let me know.


The best option would be to learn how to read the source code, which is something I'm not terribly sure of my own ability to do, or at least follow along.


Unfortunately, the project is very big and complex because it needs to interfere in a very complex process whose internals aren't as well understood as I'd like, which is Dwarf Fortress.
Sure, Toady could tell them about it, but he's busy building the game, and he's reticent about this for various reasons (though I think I remember him talking about a plan to give the dfhack developers memory maps for the various structures in the next release).
Nobody seems like they are in a position to write a tutorial about all of it, partly because the potential of the exposed features isn't exactly quantified either as there still seems to be a surprising amount of innovation going on in some of the scripts, but really, the best people to write the docs for the features are the ones who wrote them, and since they seem to be a bit behind on that, not that it's easy to balance writing the code and the documentation, it's hard to get started.

Nagidal

  • Bay Watcher
    • View Profile
    • My gaming channel
Re: Expanded Documentation for DF Hack or tutorials?
« Reply #3 on: January 19, 2017, 02:50:34 am »

dfhack is not as popular as it looks. Sure there might be thousands of users ...

I'd say there is tens of thousands of users and it is extremely popular. Anyone which uses PeridexisErrant's PyLNP uses DFHack. Sure, the amount of those who actually enter some console commands is minimal, but DFHack does a ton of good stuff out of the box, e.g. the search functions, job priority tweaks, easier trading (culling on mandates), it makes Dwarf Therapist possible, etc.
Logged
I stream most of my DF sessions: gaming.youtube/nagidal146, they are archived on my youtube channel. (Dwarf Fortress Tutorials)

Ygvir

  • Bay Watcher
    • View Profile
Re: Expanded Documentation for DF Hack or tutorials?
« Reply #4 on: January 19, 2017, 01:47:55 pm »

Having written only one script so far and doing a tiny bit of troubleshooting with lethosor and a couple of other developers, I can tell you that there simply isn't the resources. Writing the documentation for my simple and still somewhat poorly documented lua script probably took about half the time it took me to write the script itself. Given that each release of DF requires a great deal of painstaking memory mapping and code testing, it is a lot to ask of the few dedicated developers that they dive into other peoples code and figure out how to write documentation.

What I can tell you is that everyone in the DFHack community is incredibly helpful and welcoming. If someone were willing to step forward and start submitting documentation, of ANY type, I'm certain it would be well received. If you want to see this type of documentation, my suggestion is to start writing. Ask questions when you don't understand something and I'm certain you will get help.

I know that isn't the answer that anyone wants to hear but I think most of us would rather have DFHack work well (not crash and kill DF) than for it to be better documented. By the way, almost every script does have a help text that can be accessed, usually with "help [command]" in DFHack. Good Luck!
« Last Edit: January 19, 2017, 04:03:14 pm by Ygvir »
Logged