Idea for the system DFMon V0.

9 User Guide

This tool is designed to replace viewing the in game alerts… A lot of the alerts are not given high
enough priority and get lost in a wash of job cancellation spam. Other messages are simply not
useful and can be removed. There are also messages which I think people would like to pause and/or
zoom to but can’t currently without also pausing and zooming to a whole bunch of other useless
messages.

System Overview
DFMon works by monitoring the gamelog.txt file for changes and then using text parsing to
determine how/if new lines should be displayed/handled.

You can choose precisely which messages are displayed and how these are handled. You can group
these messages into different display windows and disable enable them, choosing things like how
often messages should be displayed and for how long. What font sizes, styles and colours should be
used as well as setting them to ONLY be displayed in the big monitor or also in the mini one as well.

Terminology
Filter Category – The groups filters are divided into for display/grouping purposes. Default is Alerts
and Combat.

Filter – The collection of words/wordsets which will be matched in a gamelog.txt entry to display a
row of text in the AlertMonitor/Mini Monitor.

Filter Exception – Lines of text which will be IGNORED when a given filter is matched. Ie
“UristMcSpammer cancels job” will match the Cancel filter, but if you add “UristMcSpammer” to the
Filter Exceptions then only cancellations from other dwarfs would be displayed.

Alert Monitor – The large main window alerts are displayed in

Alert mini Monitor – The small window alerts are displayed in which sits on top of your dwarf
fortress window.

Starting Up
Run the .exe or launch from the lazy newb pack. The monitor will open in the background with the
dwarf fortress window in front. Click on the homescreen and make sure it is using your correct
gamelog.txt file as well as detecting the correct dwarf fortress process. You can then click “Start
Monitor” and optionally tick the box to try and bypass the homescreen in future (now that you have
set gamelog). The monitor will not start if no dwarf fortress process is detected.
 1. The start button

2. Enables autostart in future, so you don’t have to look at the home screen (Requires a
settings save before the system will remember that you’ve ticked/unticked this)

3. Click Detect/Change game log to select where your gamelog is in relation to your DFMon
install. The monitor won’t run until you have a valid file selected.

4. This button should be clicked if you have opened the monitor before opening dwarf fortress.
It will detect your game window. It only opens the first dwarf fortress copy it finds so it can
be tricky to get onto the right window if you have several copies of dwarf fortress open
(but why would you do that to your poor poor processor!)

The Main Screen

 1. Each new message will appear here on the mini monitor. You can have several categories
active at once and the messages will display concurrently… this gets messy if you have more
than two or three open though (unless you have a giant wide screen). Messages are
replaced when a new message arrives, so mini monitor only displays one message at a time
for each filter category you have enabled.

2. This handy icon allows you to quickly jump into filter exception mode and edit the current
line of text for the current alert. THIS IS THE BUTTON YOU WILL PROBABLY USE MOST, see
futher documentation below.

3. The spanner icon opens the settings menu

4. The down arrow is a minimize button

5. The X closes this part of the program. You can run just the mini or main alerts. If you only
have one window open this will terminate the application.

6. This triangle is called a gripper and lets you resize the mini monitor window. If you don’t
often resize your dwarf fortress window you should only have to do this once… but it is
IMPORTANT to get it in the right position then save your settings… This will make you
enjoy using the monitor a lot more (get it pixel perfect then save settings). You can also
click and drag anywhere else on the mini monitor to move it around. The program
remembers its position relative to the dwarf fortress window and will move it accordingly
when you move dwarf fortress.

7. This is the header of the main monitor. Here is where all the categories are displayed. Click a
category to see it’s corresponding filters.

8. Here is where messages will be displayed, similar to the in game monitor.

The Settings Menu

Number of announcements – The number of messages that will be displayed in the main monitor
for each category BEFORE they are deleted. Set it as high or as low as you like.

Display New Alerts Above Previous – Lets you choose to have new messages appear at the TOP or
bottom of the alert screen.

Background Colour – Change the monitor to be any colour you like (Currently a lot of text is WHITE
though, so I don’t suggest picking that)….

Hide Menu Bar – Makes the DFMon windows look nice, I don’t recommend turning this off

Transparent Window – Makes the DFMon windows look even nicer. I don’t recommend turning this
off.

Tweak Rel Pos X – Changes the Left hand position of the monitor relative to the edge of the dwarf
fortress window. A negative value will place it to the right of dwarf fortress, a positive value to the
left. (This value is overwritten if you manually click and drag the monitor)

Tweak Rel Pos Y – Changes the bottom position of the monitor relative to the bottom edge of the
dwarf fortress window. A negative value will place the monitor ABOVE the bottom edge, A positive
value will place it below. (This value is overwritten if you manually click and drag the monitor)

Tweak Rel Width – Changes the width of the monitor relative to the dwarf fortress window width. If
dwarf fortress is 1000 pixels wide then a relative width of -300 will make the alert monitor 700 pixels
wide. (This value is overwritten if you manually resize the monitor)

Tweak Height – Changes the height of the mini monitor. (This value is overwritten if you manually
resize the monitor)

Font Size – Changes the font size for displayed alerts. Eventually this may be moved so that you can
have different font sizes for different filters.

Font Style – Changes the style of the messages being displayed. Windings is an obvious choice.
Eventually this may be moved so you can have different styles for different filters.

Persist Time – This determines the length of time a message will be displayed on the mini monitor
for, unless another message is received. It is set in miliseconds but in actuality is only accurate to the
nearest second. (1000 miliseconds = 1 second. Default value is 10 seconds)

Spam Stop Time – This determines how often any particular message will be displayed. If you get the
same message 10 times in a row within the given set time (default is 5 seconds) then only one
message will be displayed. Currently this keeps track of every message over the length of time so be
wary of memory issues if you set the value very very high and receive lots of messages.

Load Settings – You can load separate settings files. Can be handy if you have one per fort.
Eventually I’d like to have DFMon detect which save file you are currently playing and load a settings
file from it’s save folder if one is found.

Save Settings – You can save individual settings files… You may want different exclusions per fortress
or you may want to make a backup of your settings before messing around with the filters too much.

Apply Changes – Many changes, such as changing how things are displayed or adding new filter
categories requires a restart of the program. Apply changes does this. Currently this isn’t very
intuitive for some things and I will look to make this better in a future version.
Reset Settings To Defaults – Defaults to the settings saved to \Settings\default.xml. If you save over
this file you can get the original defaults by deleting the file and then clicking this button. A new
default file will be generated.

Search GameLog for missed filters – This is a very useful button. It parses through your whole game
log and produces a text file showing you all lines of gamelog text which WOULDN’T be captured by
your current filters (FILTER EXCEPTIONS ARE NOT TAKEN INTO ACCOUNT SO DON’T WORRY ABOUT
THOSE). Basically this lets you see if your current settings are going to miss anything critical that you
are interested in. The best filter sets should produce blank/near blank results with only useless (or
currently adventure mode) stuff left.

The Settings Filter Categories Menu

This section of the settings lets you create/edit/delete filter categories. These determine how many
tabs you have on the Alert Monitor and how many columns are on the Mini Monitor.

Active checkbox - determines if the filter category is being used. If set to not active NO tab will
appear in the alert monitor and all filters grouped under that filter category will be ignored.

Mini mon checkbox – determines if the filter category is being displayed on the mini monitor. By
Default only the main alerts is displayed, but the above screenshot shows you what two columns
would look like (you can have as many as you like….)

The Settings Filter Menu

1. Here you can edit the filters – Which control what messages from gamelog.txt are used by the
program.

2. Unticking this box will stop messages from being displayed! This can be confusing if you have also
disabled having a category active. Make sure to enable both the filters AND the category they
correspond to

3. Here you can edit the exceptions – Which messages should be ignored?

4. This dropdown list lets you change which tab of the monitor messages will appear in for this alert

5. Filters can have multiple words to match. See examples below.

6. The add new filter button is at the top.

Creating Filters
Creating filters is simple once you get the hang of it. First you need to setup what text from
gamelog.txt you want to display. Below are some pretend example gamelog.txt lines:

1. Urst McExample cancels coding AlertMonitor: Drinking beer

2. Urst McExample cancels coding AlertMonitor: Drinking wine

3. Urst McExample cancels coding AlertMonitor: Drinking whisky

If you setup a filter called “drinking” containing “cancels” it would catch all these messages.

However we could make it more explicit by having it catch only coding messages, “cancels coding”.

Okay so great that catches all three… but it doesn’t let us handle them separately! Instead let’s make
three filters, “cancels”+”beer”, “cancels”+”wine”, “cancels”+”whisky”. Now I can set the first one to
pause the game and the third one to zoom. This allows us to be very specific in pausing/zooming
when certain things occur, while being generic enough to display everything.
Finally let’s say that Urst McExample cancels coding ALL the damn time due to wine drinking… but
we really want to know when he is drinking our precious precious whisky…. We can add a Filter
Exception containing the word wine. This means that any lines of gamelog.txt which MATCH our
filter but ALSO contain the word wine will be ignored.

Links
http://www.bay12games.com/support.html – Do you want to reward me for spending HOURS
coding this program? You can do this by instead donating money to Toady, the maker of
dwarf fortress at the above link. Feel free to give me some kudos in your message to
him.

http://dffd.wimbli.com/file.php?id=7946 – Here you can rate the program (0- stars) as

well as quickly see if newer versions are available for download

http://www.bay12forums.com/smf/index.php?topic=130590.0 – Here you can leave me feed-

back on the program, suggest improvements and just generally talk about DFMon

ChangeLog V0.1 -> V0.5

Bugs fixed:
- masterpiece filter now works
- link to masterpiece text file now works
- fixed bug where mini monitor would not always resize to dwarf fortress upon open
- fixed an annoying bug where monitor would sometimes lock onto dfhack window
instead of df window (a real pain to fix!)
- Monitor now only stays on top of dwarf fortress, rather than ALL windows.
- Special characters now display correctly

Changes Made:
- Error handing added. Errors are logged to errors folder in root directory
- A lot more efficient (less memory and cpu cycles consumed)
- Filters are now dynamic, have as many or as little as you like. (Just create new text
files or use settings UI)
- QuickButton in mini monitor lets you filter text items more efficiently as they appear
and annoy you.
- Removed settings option to have monitor "always on top"
- removed the need for the program to full screen dwarf fortress when opening.
- You can now have as many/few monitors as you like and take full control of them.
- You can now pause the game when an alert occurs
- you can now (attempt) to zoom the game when an alert occurs. This is buggy and
often fails. (it opens up the alerts and tries to zoom last message, which isn't always
right/isn't always zoomable)
- New filter categories let you group filters together and quickly turn them on or off AND
view them in separate screens
- You can now save/load to several settings files (I suggest one per fortress if you are
heavily customising things)
- Now supports relative paths for gamelog.txt

ChangeLog V0.5 -> V0.9

Bugs fixed:

- Some code simplification now reduces amount of text parsing when extreme amounts of messages
are being reported quickly.
- Several crashes now don't happen
- Settings files can no longer cause crashes
- Optimised start up time for speed, PLUS Lazy newb pack auto loading support
- Removed some UI bugs
- fixed bugs where messages/filters/exceptions were SOMETIMES case sensitive
- fixed a bug where all messages were being displayed in lower case.
- fixed a bug where restarting the monitor could cause a crash if dwarf fortress had been closed
- Fixed a bug where long lists of filters caused the filter/exception editing pages to overflow off the
screen.

Changes Made:

- Settings window is now brought to foreground if you try and open it when it is already open in the
background.
- New home screen for launching the monitor... Lets you edit settings without running the program
and also means you can open it when dwarf fortress is closed!
- Added a second donation button and a personal reference.
- Default colours fixed (for all except "discovery" and "artifact" which I have left as gold. Not
bothered to tie this to data/init/colors.txt yet.
Red - #ff0000, Light Blue - #32befa, blue - #3296ff, Grey - #b4aa96 , yellow/orange - #ffc800, Purple -
#e632e6, Green - #8cff32
- You can now choose how long messages are displayed for on the mini monitor (minimum one
second, and doesn't work in real-time, so
- you won't always get your message to disappear in XXXX milliseconds... but it is close enough).
- You can now choose how often to display repeated messages in terms of time. Setting a SPAM
TIME of 30000 milliseconds will only show you any one unique message at most once every 30
seconds. Value can be set in milliseconds with a maximum value of 60000 ms(60 seconds) to keep
memory overhead down. Default value is 1 second, but I'd increase this!
- Added detection/display of gamelog/df window to home screen instead of on monitor launch and
removed closing if not found. Status display now instead. Detection happens when you try and start
the monitor, but also optional buttons to manually do it.
- When mini monitor is moved, it's location is saved to current settings so that resizing/moving dwarf
fortress doesn't cause it to jump back to it's original location. (requires a settings save to save for
future sessions)
- Default width no longer obscures happiness counter.
- When mini monitor is resized, it's width is saved to current settings so that resizing/moving dwarf
fortress doesn't cause it to jump back to it's original width.
- You can bypass the homescreen by using the tickbox on it
- Help documentation now available.
- Added a default filter to pause and zoom when one of your dwarfs is attacked by a ghost