Rubble is a general purpose mod installer and creation tool. Mod installation is done with an easy to use HTML GUI or a basic CLI front end. Mod creation is facilitated by a powerful template and scripting system that allows automation of many common modding tasks.
Users of Rubble can install many unrelated mods (called "addons") simply by selecting them in the web UI and generating (which takes only a few seconds). Addons are designed to install quickly and cleanly with a minimum of effort on the part of the user.
Rubble is specifically designed to make it easy to have several worlds with radically different
settings playable at the same time. You can even have things like per-world population cap settings
(via addon:Util/Pop Cap) or switching tilesets on worlds in progress (perfect for trying
that new tileset you found or changing the tileset of a world you got from a buddy). Tileset switching
even works on worlds who's raws were not generated by Rubble!
For modders Rubble automates many common tasks allowing you to create mods in a small fraction of the time using standard methods would take, plus users of your mod can use it together with many other addons, making your mod much more user friendly and easier to install.
Rubble has been in continuous development since mid 2013, and many changes and improvements have been made since the first version (which was a simple Blast clone). All of my mods have been made to use it, so I have extensive experience with Rubble modding and along the way fixed most of the bugs and streamlined things as much as possible both for modders and users.
For modders Rubble cuts down repetition and encourages compatibility, for users it gives easy flexibility and simple customization. In short Rubble is the most powerful and easiest to use modding utility and mod manager ever made for Dwarf Fortress. Enjoy!
All documentation is in the "other" directory, this includes tutorials, template documentation, script documentation, and basic documentation of Rubble's internals.
If you want to view the documentation as it was designed to be viewed start the web UI and visit the documentation page.
General users have no need to read anything except this readme! Everything most users need to know (aside from things like how to install Rubble, which can be found in this document) can be found in the web UI addon description pages.
Most of the documentation assumes you know what you are doing as far as general DF modding goes, please do not read documentation that is above your level and then complain that "Rubble is too hard".
I do assume that modders will have at least some knowledge of programming (I apologize for this, as I know that not everyone does). If you do not know anything about programming most of the scripting stuff will be hard (if not impossible) to follow, but if you stick to using templates you will be fine (scripting is only needed for advanced stuff anyway, most people will never need it).
For examples of what all is possible with Rubble see the included addons, they cover a broad range of possibilities. Sadly comments explaining what is being done and why are often lacking, so if you cannot figure out why something was done a certain way just ask.
Modders will want to read the following (in most-important-first order):
- The Tutorials - Read as many as you can, some are advanced and/or are for something not of general interest.
- Rubble Base Templates - The template documentation for the
addon:Libs/Baseaddon, this stuff is VERY important! - Rubble Basics - Lots of stuff about addons and Rubble in general, some of this stuff is kinda advanced, but there is a lot of good basic information here.
- The included addons - A little short on comments but full of great examples.
Some file paths in this readme use the syntax used by the AXIS Virtual File System. These paths take
the form location/directory/some.file, for example addons/addonlist.ini points to a file
named addonlist.ini in your addons directory. For details see the section about AXIS paths in
Rubble Basics.
If you have anything in your Dwarf Fortress directory that you want to keep back it up! Rubble will
delete all your existing raw files, including creature graphics and the DFHack onLoad.init and
init.lua files (and many other things)!
Anything outside of your data/init and raw directories should be safe, but back it all up just
in case...
- Delete or otherwise remove any old Rubble version you may have.
- Extract the new Rubble to
<DF Directory>/rubble.- If you are running Linux or OSX then unpack
<DF Directory>/rubble/other/Linux and OSX Installer.tarand run the install script. This script must be run in the<DF Directory>/rubble/otherdirectory!
- If you are running Linux or OSX then unpack
- Install any custom addons you may have to
<DF Directory>/rubble/addons. - See the appropriate "Running Rubble" section below.
Now you are good to go!
Do not extract a new Rubble version over an old one! This can cause all sorts of hard to find problems!
I include 64 bit binaries for OSX and Linux. The install script should choose the proper binary and install it into the proper directory. For more help (and manual instalation instructions) see the "Rubble OS Specific Information" section in Rubble Basics.
A basic Rubble installation is fine for most users, but If you want to make use of some of Rubble's advanced features you may want to do some additional steps. All of the things listed here are optional. If you will not be using the features these steps enable then do not bother with them.
If you will be installing a bunch of extra addons it may be a good idea to add an extra addons directory so that it is easier to upgrade to a new Rubble version. To do this simply create a directory (name it "My Addons" or some such) and then create a file named "rubble.ini" in the directory where you installed Rubble. Add the following lines to "rubble.ini":
# If your custom addons directory is not in the rubble directory or is not named "My Addons"
# then you will need to change this. The path given here may be an AXIS path (only the "rubble",
# "df", and "out" locations work) or an OS path (which may be relative or absolute).
addonsdir=rubble/My Addons
# You should list your custom directory first so Rubble uses it for any downloaded addons.
addonsdir=rubble/addons
From now on Rubble will load addons from both the default addons directory and your custom directory.
If you commonly set certain configuration variables when you generate you may want to create a "userconfig.ini" file. To do this the easy way simply generate a set of raws with the options you want, then copy "genconfig.ini" from your raw directory to your Rubble directory and rename it to "userconfig.ini".
Once you have the file in place edit it to remove any options you don't care about, and from then on Rubble will use your settings as the defaults (you can still change them from the web UI as normal).
If you have favorite sets of addons it is possible to save them for later. Simply create a directory named "presets" in your Rubble directory. Whenever you generate a set of raws where you want to save the addon activation state for later simply copy the "addonlist.ini" file from the raw directory to your "presets" directory and name it something descriptive (keeping the ini extension). The only name limitation is that you may not use "Default", as it is reserved for the default settings.
To use these "presets" simply select them from the drop-down list at the bottom of the "select addons" page in the web UI (this control will not be shown unless you have at least one preset installed). This will set the addon activation state to match the state listed in the preset file.
The web UI is simple, functional, and easy to use.
This operation mode is the recommended way of running Rubble, as it always has full support for the latest ways of doing things.
To use the web UI all you need to do is start the server (just run the universal interface with no command
line options, web is the default mode), it should automatically open your web browser to the web UI main
page. Linux and OSX users will have to configure a browser startup script for this to work, see the "Rubble
Web UI Customization" section in Rubble Basics.
The web UI does not support everything Rubble can do, for some rare advanced actions you will need to use more advanced manual interface modes. Generally if you find something that the universal interface CLI modes allow but the web UI does not you should stop and ask yourself, "do I really want to do this?"
The UI's look and feel can be customized, see the "Rubble Web UI Customization" section in Rubble Basics.
It is highly recommended that you use the Web UI. It is generally much faster then doing everything by hand (plus you don't have to mess around with the command prompt, if you dislike that kind of thing)
For basic documentation on each option run rubble help or rubble help <mode>.
The Rubble universal interface uses a set of generic command line options who's exact meaning changes based on the operation mode. These modes are not actually part of the interface program itself, but are compiled in from external libraries. There may be more modes available than mentioned here, it depends on the Rubble version and how the interface was compiled.
Generally the universal interface defaults to launching the web UI server, but by changing the mode it is possible to access much more advanced functionality.
Common Tasks:
To activate or deactivate a Rubble addon manually you may set it's entry in addons/addonlist.ini
to true or false. If you just installed an addon it will not have an entry until Rubble has run
at least once (after the addon was installed).
If you want to run Rubble without generating anything (so as to update the addon list file) just run
rubble refresh.
To generate with the last used addons (aka the settings in addons/addonlist.ini) just run
rubble generate with no other arguments.
Here are a few example command lines to generate various configurations:
Vanilla (ignoring the addon list, but not rubble.ini):
rubble generate -addons="Base"
Vanilla with Vanilla creature graphics (plus anything you have in rubble.ini):
rubble generate -addons="Base;Graphics/Vanilla"
Some addons may allow additional configuration via "config variables", these are generally for
advanced users and may be specified with the -config command line option.
Example (vanilla with 10 dummy reactions):
rubble generate -addons="Base;Dev/Dummy" -config="DEV_DUMMY_REACTION_COUNT=10"
To switch tilesets on a world in progress use:
rubble tset -region="<region name>" -addons="<name of tileset addon>"
When specifying a region you may use "raw" to refer to the main raw directory.
Some addons may be applied to a world in progress. These addons are fairly rare, but sometimes handy.
To do this you use "iapply" (independent apply) mode:
rubble iapply -region="<region name>" -addons="<name of tileset addon>"
This is mechanically very similar to applying a tileset, but it carries out a different set of actions.
It is generally possible to regenerate the raws for a world, but this is a task fraught with peril, do not attempt unless you know what you are doing!
The first step is to change the addonlist.ini file that is in the world's raw directory, make sure
not to change it too much or you can mess up your world!
If you wish you can change genconfig.ini as well, but that is usually a bad idea.
Now for regenerating the raws, what follows is an example command line to do that for the save "region1":
rubble generate -addons="df/data/save/region1/raw/addonlist.ini" -config="df/data/save/region1/raw/genconfig.ini" -outputdir="df/data/save/region1/raw"
Note that if you have any addon or config settings in rubble.ini this will probably fail horribly (or
silently, which is worse).
There are also some extra tools that may be useful, run rubble help for a full list of all
the modes that are currently installed.
Please report issues on github.
When making an error report please post the full log file! Posting just a few lines tells me almost nothing about the problem, after all I made Rubble write all that stuff for a reason :)
I cannot stress this enough! With Rubble the actual error message is only a small part of the information I need for tracking an error down! In particular the list of active addons is very important (and it tends to get cut from most reports because it is near the start of the log).
If at all possible when reporting a bug in a template provide a test that demonstrates the bug. This will make reproducing the bug much easier.
If any of the documentation is not 100% clear just ask. I know everything there is to know about how Rubble works and so I tend to forget to put "obvious" stuff in the docs. A reminder that I forgot something is more a help than a hindrance.
In the event that I cannot be contacted on the Bay12 forums (user name "milo christiansen"), my email address is:
milo.christiansen (at) gmail (dot) com