DF Storyteller

Give Dwarf Fortress Storyteller your Legends and we will tell the story. You can just sit back and enjoy.

DF Storyteller is an application that imports Dwarf Fortress legends files, stores them internally and makes them queryable using API's. DF Storyteller currently supports the parsing of:

• ...-legends.xml
• ...-legends_plus.xml
• ...-world_history.txt (planned)
• ...-world_site_and_pops.txt (planned)

DF Storyteller currently supports querying the data using:

• RESTfull API (read-only for now)
• GraphQL (Work in progress)

Why use DF Storyteller

In the past legends viewers had to implement their own legends parser to get the data from the files. Keeping them up-to-data takes valuable time away from making a nice interface. DF Storyteller changes that. We take care of all the complicated things. You can just ask for the exact data you need and we give it to you. All you have to do is visualize the data in unique ways.

DF Storyteller also combines all imported files so you have all data available to you. You can then choose which data you are interested in.

Documentation is important so we do our best to make all descriptions as as clear as possible. For our API's we have build in documentation that is automatically generated so all documentation is up-to-date.

Want to become a painter and create some beautiful visuals, look here.

Features

DF Storyteller is packed with features and more are planned, here are a few:

• Low memory usage: Application (+ PostgreSQL) < 100 MB RAM
  • Importing of files still needs to be optimized and will use MUCH more memory depending on the size of the legend files. But only has to be done once.
• Small binary: < 100 MB (and included most/all dependencies)
• RESTfull and GraphQL: interface to query the data.
• View you world in detail on a Map!: Planned feature, not available yet.
• Great documentation: API documentation, Developer documentation, build in documentation and other support documents.
• Best Effort Parsing: Should work for every version of Dwarf Fortress and DF Hack.
• Very stable and secure!: We ❤️ Rust, DF ST will always tell you what went wrong and has build in bug report creation.
• Privacy: We don't track you in any way! Look here for more info about privacy.

How does it work?

DF Storyteller takes the legend files from Dwarf Fortress and DFHack and imports them into a database. It then provides and API to view the data.

Install your own storyteller!

DF Storyteller is written to be used by other applications so it might be included in the visualizer you want to use. Look here for a list of visualizers (painters). To get started, download the executable from the release page.

Here you can find instructions on how to install it for your system. You can find a video with instructions here.

Command your storyteller

DF Storyteller is designed as a command line tool. This allows us to provide different functionalities depending on what the user wants. The commands can also be used by other applications to open the application in different ways.

Get started

To get started with the command line you can use the help flag in the command line like this:

# Get the general help from the app
./df_storyteller --help
# For windows this changes to:
./df_storyteller.exe --help

The first subcommands you might want to use are guide, import and start. For example:

./df_storyteller guide
./df_storyteller import -w 1 ./region4-00125-01-01-legends.xml
./df_storyteller start -w 1

You can then open http://localhost:20350 to find more info. The start command will print the exact url in the terminal, like this:

INFO :launch - 🚀 Rocket has launched from http://127.0.0.1:20350

For more commands and more info look at this page.

Documentation

Every instance of DF Storyteller comes with its own build in documentation. But we also provide documentation for the most recent build here.

Become a Painter

Do you want to visualize legends data yourself! You are in the right place. We will get you started in no time. Just take a look over here.

Need help?

Join us on Discord or bay12forums.

System Requirements & Supported

DF Storyteller has very minimal system requirements that highly depend on the files that you want to import.

[^1]: This highly depends on files you want to import using the import subcommand. The start subcommand uses very little RAM should will work on all modern systems.

For information about what versions of Dwarf Fortress, DFHack and mods we support look here

Want to contribute?

• Contribution guidelines for this project.
• Create your own application using DF Storyteller.
• I want to help, but not a programmer, can I still help? Yes! Look here for more info.

Our Code of Conduct.

Other info

• Security
• Privacy
• Technical info

License

This project is licensed under the AGPL-3.0-or-later license.

All documentation[^2] is also licensed under GNU FDL, MIT license and/or Creative Commons Attribution-ShareAlike 3.0 Unported license

This makes the documentation both compatible with the Dwarf Fortress Wiki and Wikipedia.

All contributions to this project will be similarly licensed.

[^2]: This includes all Rust Doc, API documentation and other info in this codebase.