Bay 12 Games Forum

One question though, or suggestion for the documentation. I'm a definitely Python newbie, I've dabbled enough to know the syntax but I've never developed anything serious with it. I understand how to call scripts through manager.py well enough, so I think the documentation is great there, btw

Thanks so much for your interest!

Developing the scripts that come with PyDwarf was a lot of trial and error for me, too, though I like to think I usually got things right the first time. (I didn't.)

To test scripts, in a console located at PyDwarf's root directory I ran python, then import raws, pydwarf; df = pydwarf.df(raws) - that pydwarf.df command should load your settings from your configuration files, though you can also manually specify settings by passing them as arguments to that function. Then I'd call one of my scripts using syntax like this: print pydwarf.scripts.pineapple.noexotic(df), or maybe I'd just step through some code manually. (You can pass named arguments to your script when you run it that way, I should mention.) And then I'd print information to the console that ought to have been changed by the script so I could check up on how things were working. I could also run df.reset() and then run it all over again, perhaps after making some manual changes to the raws to see how the script contended with them. (But you'll have to restart the python console and start over again if you make changes to your script. As inconvenient as this is, I couldn't find another reliable way to reload modified scripts!)

For example, on one occasion that I was testing a script this way, my console looked something like this:

>>> import raws, pydwarf; df = pydwarf.df(raws)
>>> print df.getobj('CREATURE:TIGER').list(range=12, skip=False)
[CREATURE:TIGER]
    [DESCRIPTION:A huge, striped predator.  It is found in almost any climate on a lone hunt for its prey.]
    [NAME:tiger:tigers:tiger]
    [CASTE_NAME:tiger:tigers:tiger]
    [CHILD:3][GENERAL_CHILD_NAME:tiger cub:tiger cubs]
    [CREATURE_TILE:'T'][COLOR:6:0:1]
    [PETVALUE:200]
    [PET_EXOTIC]
    [MOUNT_EXOTIC]
    [TRAINABLE]
>>> print pydwarf.scripts.pineapple.noexotic(df)
SUCCESS: Replaced 303 PET_EXOTIC and 150 MOUNT_EXOTIC tokens.
>>> print len(df.all(value_in=['PET_EXOTIC', 'MOUNT_EXOTIC']))
0
>>> print df.getobj('CREATURE:TIGER').list(range=12, skip=False)
[CREATURE:TIGER]
    [DESCRIPTION:A huge, striped predator.  It is found in almost any climate on a lone hunt for its prey.]
    [NAME:tiger:tigers:tiger]
    [CASTE_NAME:tiger:tigers:tiger]
    [CHILD:3][GENERAL_CHILD_NAME:tiger cub:tiger cubs]
    [CREATURE_TILE:'T'][COLOR:6:0:1]
    [PETVALUE:200]
    [PET]
    [MOUNT]
    [TRAINABLE]

I turned this into a unit test. You can find that exact snippet, except for the top line with the imports and such, in docs/examples/scripts.pineapple.txt. You can make your own file in that directory containing unit tests for your own scripts, and then run all the tests in that directory using docs/bin/verify.py. I'm not sure whether I actually documented anywhere how this works, but I can summarize:

I copied that console text wholesale, save for the topmost line, and pasted it into that unit test file. Violà, it became an actual unit test where the commands are run and the output I verified here is compared to the output given after, say, I made some changes to the code or to the script. The verify.py script will helpfully let you know whether the test passed or failed and, if it failed, it will tell you where and why. I used this to do some test-driven development, as well as testing code that was already written.

There's some special formatting going on mainly so that the code snippets in these unit test files can also be used in the HTML documentation, but you won't need to worry about that much. It's the three lines you see above every unit test in those files. Your three lines will probably look like this - sans the comments.

# The name of the script you're testing goes here
pydwarf.scripts.pineapple.noexotic
# For thoroughness' sake I listed all the API commands I called here in case it was useful in the generated docs, but you can leave this line blank
raws.queryableobj.getobj raws.queryable.all raws.tokenlist.__len__ pydwarf.registrar.__getattr__
# Putting "reset" here, as opposed to a blank line, means the DF directory is reloaded so that the following test has a clean slate to work with. You probably want to do this for every test.
reset

I last worked with this code months ago and my memory is fuzzy and I can almost guarantee I've made some mistakes and terribly mislead you regarding how to best test your scripts. But I hope I've helped answer your question and put you on the right track, and I am more than happy to work with you if you run into any more obstacles.

Just a PSA that PyDwarf is 100% functional for DF 42.x. It's possible that some mods written for it may be incompatible with raws changes made, and mods depending on other utilities won't work until those have been updated - but PyDwarf itself requires no update.

All of the mods packaged with PyDwarf should work with DF 42.x without any changes, though some depend on DFHack or TWBT also being up-to-date.

PyDwarf v1.1.0: Chalcedony has been released!

Here's a step-by-step tutorial to guide you through your first time configuring and running PyDwarf, and here's another tutorial to help you get started creating your first mod. Also, here's a handy list of scripts with which PyDwarf comes packaged. And here's where all those scripts are actually located, in case you'd like to see what their innards look like.

Here's just a few examples of the mods included with this release of PyDwarf:

• Omniclasm's State of Decay.
  
• DragonDePlatino's Gemset.
  
• Umiman's Small Things.
  
• Stalhansch's Armoury Packs.
  

Normally you'd be bound to run into compatibility issues when trying to install so many of these mods at once, and you'd surely have to wait for authors to update their mods before reinstalling everything whenever Dwarf Fortress updates. Not so with PyDwarf. PyDwarf is highly capable of avoiding conflicts between mods, and it cares little about which version of Dwarf Fortress you're modifying. Not only does PyDwarf make it much easier for the player to install mods, it also makes it easier for the modder to craft something excellent. Instead of editing text files on your own, PyDwarf allows you to write scripts which edit them for you: What this means for you is an enormous reduction in tedium.

Haha, "soon".

This is going to be the last major release of PyDwarf so I'm spending a lot of time making the documentation as helpful as I can and hunting down any remaining bugs. How does it go, the last 10% of the code takes 90% of the development time? But this polish is important: I understand that PyDwarf can look like a confusing mess and that's why I'm working hard to make it as accessible and as easy to use as possible. For anyone with any programming experience who wants to get into modding I believe PyDwarf is their best option by far. Included with the next release will be several tutorials for various aspects of PyDwarf, thorough documentation on its more complicated parts, and summaries and example usages for as many functions and methods as I can cover.

Want to help PyDwarf to attain its final form? I can always use help discovering bugs, writing code examples, making sure everything actually makes sense to someone who isn't me.

Is the wolf in a penguin's clothing

PyDwarf 1.0.2: Magma Forge is released!

PyDwarf and Rubble both have mods that automatically handle exactly this, pineapple.orientation in the case of the former and User/Fix/Gays in the latter.

May I suggest using Pydwarf for helping to alleviate your modularity troubles? It sounds like it could be exactly what you need, and all that's necessary to write mods for it is a basic understanding of Python. And if you decide to try it then I'd be happy to help out where I can.