v50 Steam/Premium information for editors
  • v50 information can now be added to pages in the main namespace. v0.47 information can still be found in the DF2014 namespace. See here for more details on the new versioning policy.
  • Use this page to report any issues related to the migration.
This notice may be cached—the current version can be found here.

Difference between revisions of "v0.34:Macros and keymaps"

From Dwarf Fortress Wiki
Jump to navigation Jump to search
(Created page with "=== Macros and Keymaps === In this context the macro is mean a set of keystrokes / input from the player. Keymap is a set of special key combinations to get special function, or...")
 
 
(37 intermediate revisions by 20 users not shown)
Line 1: Line 1:
=== Macros and Keymaps ===
+
{{Quality|Exceptional|14:18, 4 April 2011 (UTC)}}
 +
{{av}}
 +
Playing Dwarf Fortress means lots of typing. The game has an internal macro/keymap system. Using it or any external program can save you a great deal of time when dumping, rewalling, designating, and so forth.
  
In this context the macro is mean a set of keystrokes / input from the player. Keymap is a set of special key combinations to get special function, or shorten input.
+
== DF macros ==
 +
=== Creating macros ===
 +
The controls for creating macros within DF are as follows:
  
What this is good for?
+
*{{k|Ctrl}}+{{k|r}} = record (and finish recording)
Did you had a migrants of 20 or more, and you were in trouble of make enough accommodations for them, before they got unhappy thoughts? Were you bored, by the repetitive creation of of a big bedroom? Not to worry anymore, it's possible to break down the task into much less interaction, and to speed up things.
+
*{{k|Ctrl}}+{{k|s}} = save
 +
*{{k|Ctrl}}+{{k|l}} = load
 +
*{{k|Ctrl}}+{{k|u}}+number = set to repeat [number] of times
 +
*{{k|Ctrl}}+{{k|p}} = play
  
What you need:
+
To create a macro, press {{k|Ctrl}}+{{k|r}} to begin recording your actions.  When you have recorded all the actions that you want, stop recording by hitting {{k|Ctrl}}+{{k|r}} again and save ({{k|Ctrl}}+{{k|s}}) the macro.  The macro is then added to your macro list.  To load a macro from the list just press {{k|Ctrl}}+{{k|l}}.  You can then play the macro by pressing {{k|Ctrl}}+{{k|p}} whenever you want.  You can also set a macro to repeat by pressing {{k|Ctrl}}+{{k|u}}, typing a two digit number, and then pressing {{k|Ctrl}}+{{k|p}} to begin the playback session. Moving your mouse from the playing window, or otherwise losing focus on Dwarf Fortress, is <s>an annoying way</s> a good way to interrupt a macro session from continuing (also the only known method anyway).
under linux:
 
  * fluxbox (or your steady window manager, or shortcut editor)
 
* xvkbd (or anything, that allows you to type something into an active window / program, as came from stdin)
 
winder windows:
 
*a good (free) program, that can do the same, and supports special characters
 
  
=== Fluxbox ===
+
There is a directory data/init/macros for them. The macros are saved in .mak format.  The first line of the macro file must match the filename, or the file will not be recognized as a valid macro.  Even a recorded file for a simple macro - for example to create a 3 tiles wide ramp - may already consist of up to 50 commands listed. This is because every possible [[Key_bindings|binding of the key pressed]] is included in the macro and put in a block (and {{k|r}} for ramp has many by default).
 +
<pre>
 +
pressing_enter_recorded
 +
SELECT
 +
CLOSE_MEGA_ANNOUNCEMENT
 +
WORLD_PARAM_ENTER_VALUE
 +
SETUPGAME_SAVE_PROFILE_GO
 +
D_BURROWS_DEFINE
 +
D_MILITARY_ALERTS_SET
 +
End of group
 +
CUSTOM_CTRL_R
 +
End of group
 +
End of macro
 +
</pre>
 +
For this example the recording was started, enter was pressed and the recording was stopped. When using this macro every underlying command in the file will be called, if possible. If you are in the designation menu, it will react as a select, the other commands will be ignored. If you are in the burrow menu, it will work like pressing enter there. The macro alway ends with a block containing the end of its recording. But executing macros seems to ignore this command. If you have changed your key bindings you'll get another result, because the underlying commands are recorded, not the keys pressed.<br />
 +
When creating or editing your own macros it is a good idea to use only those commands you really want.
 +
<pre>
 +
ramping_created
 +
DESIGNATE_RAMP
 +
End of group
 +
CURSOR_DOWN_Z
 +
End of group
 +
SELECT
 +
End of group
 +
CURSOR_RIGHT
 +
End of group
 +
CURSOR_RIGHT
 +
End of group
 +
SELECT
 +
End of group
 +
CURSOR_LEFT
 +
End of group
 +
CURSOR_LEFT
 +
End of group
 +
CURSOR_UP
 +
End of group
 +
End of macro
 +
</pre>
 +
This selfmade example will designate a 3 tiles wide ramp one z-level below and place the cursor to make the next execution of the macro continue the way down. The first line has to be the name of the file. You can see that there are grouping tags for every single keypress. These are important for a working macro.<br />
 +
It is unknown if there is the possibility of creationg loops/iterations, other programming features or comments.<br />
  
Fluxbox is a tiny window manager, that allows a lot of powerful customization. If you don't want to install fluxbox just for this, you should look for other solutions in your distro (KDE / Gnome). If you use / successfully setup fluxbox [[http://fluxbox.org/help]] you only need to edit .fluxbox/keys files. This contains the keyboard shortcuts.
+
Removing macros in-game can be done by pressing {{k|Esc}} and then selecting Keybindings > Macros. Press {{k|Backspace}} on the macros you want to delete, then press {{k|Esc}} and select "Save and Exit". This will also delete the corresponding macro file permanently. Otherwise, you can delete the corresponding .mak file from the init/macros/ folder, although that will only take effect the next time DF is run.
  
Mod1 Mod4 m None d b :ExecCommand xvkbd -text "\D2r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r"
+
Changing macros while the game is running uses a counter-intuitive process.  After editing the macro file, create a backup of it and remove the macro as described earlier. However, before saving the changes, place the backup file on the init/macros/ folder. Then save the changes and reload the macro with {{k|Ctrl}}+{{k|l}}.
  
Mod1 means windows / command funciton key (If you use keychains, the order of the modificators seems important :( )
+
Adding macros is also possible, resorting to the macro changing process. A "dummy" macro would be recorded and saved, then deleted. The macro that would be added would replace the dummy file.
Mod4 means alt
+
<pre>
m is for the key m (so this will be windows + alt + m (special enough not to used in any other application
+
macroscreen
(this is important, because if fluxbox is intercepting a hotkey, it not pass along to the active application!))
+
OPTIONS
None the following combinations are not using modifications keys (Important: use your last key in keychain as
+
End of group
non-modified key, or a big enough delay, or else your macro input will be applied to the modifier, you currently
+
STANDARDSCROLL_DOWN
pressing (see below))
+
CURSOR_DOWN
d is for key D (like Dwarf Fortress)
+
End of group
b is for key B (as bedroom)
+
STANDARDSCROLL_DOWN
: means, that this is the end of key combinations, and from here the command to apply.
+
CURSOR_DOWN
 +
End of group
 +
SELECT
 +
End of group
 +
SELECT
 +
End of group
 +
End of macro
 +
</pre>
  
So, to start this particular keychain (hotkey), '''(windows + alt + m) d b'''
+
=== Tuning macros ===
 +
The fewer commands a macro consists of, the faster it runs. This means you should avoid unnecessary steps by optimizing the "path" of your designations.
  
:ExecCommand  tells fluxbox, to execute the followings
+
The second and most effective way to increase speed is to remove all unnecessary commands DF recorded. These may be found in the init/macros folder and edited with any basic text editing program. The extra commands are ignored by the game but they still take time to be processed. To move a cursor 3 (up/down) or 4 (right/left) commands are recorded, most other keys are bound to more commands. Pressing {{k|d}} for example records more than 30 commands.
  
xvkbd this the virtual keyboard we will use
+
For example the code below is a simple macro that selects the digging designation, moves one square to the right, and then designates that tile to be dug.
-text tells xvkbd to don't display the virtual keyboard, just get the input from command line
+
<pre>
(there's file input is available, but it does not support special keys so easily)
+
example
"\D2r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r" This is the input, we will pass to
+
OPTION4
Dwarf Fortress (which will press r, and gives 12 + and a final enter)
+
CUSTOM_D
The begining '''\D2''' commands xvkbd to wait 2*100ms. You might want to play with this, but I found,
+
WORLD_PARAM_DELETE
that I need this, because the first input key is not passed always otherwise.
+
LEGENDS_EXPORT_DETAILED_MAP
 +
A_COMBAT_DODGE
 +
A_STATUS_DESC
 +
A_SLEEP_DAWN
 +
A_INV_DROP
 +
SETUP_NOTES_DELETE_NOTE
 +
BUILDJOB_TARGET_RIGHT
 +
BUILDJOB_BED_DORMITORY
 +
BUILDJOB_FARM_WINTER
 +
BUILDJOB_RACKSTAND_KILL2
 +
HOTKEY_BUILDING_DOOR
 +
HOTKEY_BUILDING_CONSTRUCTION_STAIR_DOWN
 +
HOTKEY_BUILDING_WORKSHOP_DYER
 +
BUILDING_ORIENT_RIGHT
 +
BUILDING_ADVANCE_STAGE
 +
BUILDING_TRIGGER_MAX_SIZE_DOWN
 +
BUILDING_TRACK_STOP_DUMP
 +
HOTKEY_GLASS_DOOR
 +
HOTKEY_CARPENTER_DOOR
 +
HOTKEY_MASON_DOOR
 +
HOTKEY_TRAP_DOOR
 +
BUILDJOB_STOCKPILE_DELETE_CHILD
 +
STOCKPILE_ARMOR
 +
STOCKPILE_SETTINGS_DISABLE
 +
STORES_DUMP
 +
ORDERS_DYED_CLOTH
 +
ORDERS_ZONE_DRINKING
 +
D_DESIGNATE
 +
D_HAULING_STOP_LC_DIR
 +
D_BURROWS_DELETE
 +
D_NOTE_DELETE
 +
D_NOTE_ROUTE_DELETE
 +
D_BITEM_DUMP
 +
D_LOOK_DUMP
 +
ARENA_CREATURE_SIDE_UP
 +
ASSIGNTRADE_SORT
 +
DESIGNATE_DUMP
 +
DESIGNATE_DIG
 +
ITEM_DUMP
 +
D_MILITARY_DISBAND_SQUAD
 +
D_MILITARY_ALERTS_DELETE
 +
D_MILITARY_AMMUNITION_REMOVE_ITEM
 +
D_MILITARY_DELETE_UNIFORM
 +
STRING_A100
 +
End of group
 +
STANDARDSCROLL_RIGHT
 +
CURSOR_RIGHT
 +
WORLD_PARAM_INCREASE
 +
A_MOVE_E
 +
End of group
 +
SELECT
 +
CLOSE_MEGA_ANNOUNCEMENT
 +
WORLD_PARAM_ENTER_VALUE
 +
SETUPGAME_SAVE_PROFILE_GO
 +
D_BURROWS_DEFINE
 +
D_MILITARY_ALERTS_SET
 +
End of group
 +
SELECT
 +
CLOSE_MEGA_ANNOUNCEMENT
 +
WORLD_PARAM_ENTER_VALUE
 +
SETUPGAME_SAVE_PROFILE_GO
 +
D_BURROWS_DEFINE
 +
D_MILITARY_ALERTS_SET
 +
End of group
 +
CUSTOM_CTRL_R
 +
End of group
 +
End of macro
 +
</pre>
 +
Here is the same code but optimized through removal of all the excess commands. Each macro also contains an addition CUSTOM_CTRL_R command at the end that may be removed as well.
 +
<pre>
 +
example
 +
DESIGNATE_DIG
 +
End of group
 +
CURSOR_RIGHT
 +
End of group
 +
SELECT
 +
End of group
 +
SELECT
 +
End of group
 +
End of macro
 +
</pre>
  
The + is used on keypad under DF, we access this by \[]. The enter is also a special character, used by \r. You might want to take a peek into the xvkbd's man page for some special keys.
 
  
So what this macro does at all:
+
The third way to increase the speed of macros is to change settings in the init-files. In the [[init.txt|base init file (data/init/init.txt)]] you will find the follow lines:
if you press: if you have large bedroom, and you don't want to make the boring task to create a large bedroom for all the beds, you can manage the bed by '''q''' (task and preferences in DF), and then press '''(windows + alt + m) d b''', which will give the order of '''r''' ++++++++++++ and an enter.
+
<pre>
 +
If you set KEY_REPEAT_ACCEL_LIMIT above one, then after KEY_REPEAT_ACCEL_START repetitions
 +
the repetition delay will smoothly decrease until repetition is this number of times faster
 +
than at the start.
  
=== Important mistakes ===
+
[KEY_REPEAT_ACCEL_LIMIT:8]
 +
[KEY_REPEAT_ACCEL_START:10]
  
* My first characters are missing from the input
+
This controls the number of milliseconds between macro instructions.
** - You have most probably insufficient delay at the start of the text. Try a bigger number, or a delay at all ('''\D2''')
 
* My macro fails / I cannot get it work at, and not even prints into a textbox.
 
** - You might have a last keychain key with a modifier.
 
  '''Mod1 Mod4 b :ExecCommand xvkbd -text "Hello World"'''
 
  This will most probably not give you any output, or even worst, start a few other applications. This is because the
 
  keyboard interface is behaving additively. This means, if you plug 2 keyboards, and press a key on one of them, and
 
  press another on the other one, the OS will see as both of them pressed. So, if you press on your keyboard Mod1 + Mod4,
 
  and sending a stream of keys on the other, they will add up, and you will end up, as you typed the '''Hellow World'''
 
  with Mod1 + Mod4 pressed (Windows + Alt).
 
  Solutions:
 
  **Set a big enough delay at the beginning of your string ('''\D5Hello World'''), so you can release them.
 
  '''Mod1 Mod4 b :ExecCommand xvkbd -text "\D5Hello World"'''
 
  **Set the hotkey to a keychain that ends with a non-modified key
 
  '''Mod1 Mod4 m None b :ExecCommand xvkbd -text "Hello World"'''
 
  
=== Some useful macros with a short description ===
+
[MACRO_MS:15]
  
* Quick resizes a (bed)room (from the 'q' and set into cursored the bed)
+
</pre>
'''Mod1 Mod4 m None d b :ExecCommand xvkbd -text "\D2r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r"'''
 
'''Windows + Alt + m d b'''
 
  
* Quick resizes 6 (bed)room, that are inline to the right with a distance of 2 title.
+
* The <code>MACRO_MS</code> setting is the number of milliseconds between macro instructions (the default, 15, allows 1000/15 instructions per second, or about 66). Decreasing this makes macros run '''faster''', although decreasing it too far can make the game unresponsive while the macro is running.
'''Mod1 Mod4 m None d v :ExecCommand xvkbd -text "\D2r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r\[Right]\[Right]\[Right]r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r\[Right]\[Right]\[Right]r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r\[Right]\[Right]\[Right]r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r\[Right]\[Right]\[Right]r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r\[Right]\[Right]\[Right]r\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\[+]\r\[Right]\[Right]\[Right]"'''
+
* The <code>KEY_REPEAT_ACCEL_START</code> and <code>KEY_REPEAT_ACCEL_LIMIT</code> settings are unrelated to macros (except while recording). See [[Technical tricks#Keyboard|Technical tricks]] for more information.
'''Windows + Alt + m d v'''
 
b  b  b  b  b  b  x (and the cursor will be stopped at the next item)
 
  
* Quick select items at the trading depot. If you hate to sell the bins too (or trading with elves).
+
== External utilities ==
'''Mod1 Mod4 m None d t :ExecCommand xvkbd -text "\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]\r\[Down]"'''
 
'''Windows + Alt + m d t'''
 
Warning, if you sell ~20 finished goods bins' contents, then you may expect that
 
the merchants will pack up for a while (probably for a few months).
 
  
* Quick macro to build a repeating pattern. For example, you want to build a bedroom, where the dwarf's items are 2 titles apart (6 of them). Will select the first available item, so if there's something, you don't want to used, forbid them (coffers / bags).
+
=== [http://joelpt.net/quickfort/ QuickFort] ===
'''Mod1 Mod4 m None d 3 :ExecCommand xvkbd -text "\r\r\r\[Right]\[Right]\[Right]\r\r\r\[Right]\[Right]\[Right]\r\r\r\[Right]\[Right]\[Right]\r\r\r\[Right]\[Right]\[Right]\r\r\r\[Right]\[Right]\[Right]"'''
+
A spreadsheet-driven construction tool for Dwarf Fortress. Converts CSV files containing a "graphical" (or at least two-dimensional) representation of what you want to build into efficient DF macros. Comes with a number of scripts to get you started, some of them quite complex.
Build menu, and select the item, you want to build (with /*-+, not the keycode!, otherwise you end up
 
one wanted item, and 5 other armor stands) '''Windows + Alt + m d 3'''
 
  
Feel free, to add your own macros.
+
=== AutoHotKey ===
 +
AutoHotKey is a powerful easy-to-use scripting language that can simulate keystrokes. (among other functions)
 +
 
 +
To started:
 +
#  Go to the [http://www.autohotkey.com/ AutoHotKey website] and download AutoHotKey.  Installation is simple and the program uses very little system resources.
 +
#  Read through their [http://www.autohotkey.com/docs/Tutorial.htm quick-start guide] and start write your macro scripts (file type .ahk), which may contain any number of commands.  You activate scripts by double-clicking .ahk files or by assigning hotkeys to your macros.  Both of these can be done at any time - even right in the middle of a game.  AutoHotKey also allows for automated activation of scripts.
 +
 
 +
=== Fluxbox + xvkbd ===
 +
For linux, it's a quite cool solution. It's possible to create macros with outside tools, like fluxbox (linux window manager) + xvkbd (linux virtual keyboard for kiosks, with some macro capabilities). See the documentation [[Fluxbox_macros|here]].
 +
 
 +
Pros:
 +
*Faster execution
 +
*Easier script writing
 +
*Portable code
 +
Cons:
 +
*Sometime needs timing
 +
*Need xvkbd (Linux at least)
 +
*Need some special key reservation
 +
 
 +
'''Please see also the [[40d:Macros and Keymaps|40d macros page]], as much of what is there works perfectly fine. If you can verify it works, please move it to this page.'''
 +
 
 +
== Useful Macro Ideas ==
 +
 
 +
The following are macro ideas that other players have found useful, and may make management of your fort easier. For most macros it's highly recommended to '''pause the game''' before hitting the play button to avoid your dwarves causing unexpected behavior, i.e. a dwarf giving birth or anything else that auto-zooms to a different location.
 +
 
 +
=== Large Bedrooms ===
 +
 
 +
Bedrooms, especially larger ones or large blocks of identical ones, involve a lot of designations and build orders. These macros are designed to streamline the process. For all of these mass-building macros you may wish to temporarily forbid any of your artifact or masterwork furniture, to avoid giving overly-valuable items to your dwarf peasantry.
 +
 
 +
==== Placing Beds ====
 +
 
 +
So you've recorded a macro to dig out a series of bedrooms, and now you have to fill them. Bring up the {{k|b}}uild menu, select {{k|b}}ed, and go the first position you want to place a bed in.
 +
 
 +
Start a new macro ({{k|Ctrl}}+{{k|r}}) and place the bed (selecting the first bed from the list), then move to the next bedroom in sequence. Repeat this until you reach the end of the row. If you are placing beds into multiple long rows of bedrooms, move the cursor to the first bed in the next row to make things faster. Turn off macro recording ({{k|Ctrl}}+{{k|r}}), but don't exit the build menu. You can then save your macro if you wish, though it's not necessary. Play the macro ({{k|Ctrl}}+{{k|p}}), and you have just laid out another row. Repeat until you have enough bedrooms or you run out of beds.
 +
 
 +
==== Placing Coffers ====
 +
 
 +
Placing coffers (but ''not'' bags) requires an extra step. Pause the game (you ''did'' remember to pause before playing macros, didn't you?) and go to the Stocks menu. Forbid all bags, regardless of what's inside them or what they're being used for (this is temporary). Exit to main screen and repeat the steps above, this time placing containers in your rooms. You will end up placing only chests / coffers / boxes, ignoring any bags. Repeat and play back for the rest of your bedrooms, then un-forbid your bags before un-pausing the game.
 +
 
 +
==== Resizing Rooms ====
 +
 
 +
If the bedroom is finished (at least all the beds are hauled to place), you may want to create a new macro to designate each room as a bedroom. {{k|q}}uery the building and select the first bed. Start a new macro and press {{k|r}} to designate it as a bedroom, then press + a few times to fill the available space. If you are fine with the size of the bedroom you can press enter, move on to the next bed, and repeat this for the whole row. If you want bedrooms that fill all the room and not all your bedrooms are the same size, you may have to press + a bit more or less for the larger cases. Repeat this for the rest of the rows as above.
 +
 
 +
=== Mass Selector ===
 +
 
 +
With this macro you can select a lot of things at once. Extremely helpful if you want to sell a lot of junk to the caravans. Record {{k|enter}}, then {{k|down}} about 10-25 times in a row. (For some menus you may wish to use {{k|enter}}, then {{k|+}}) When the caravan arrives, your dwarves haul all the bins to your Trade Depot for sale as normal. At the trade menu, load the macro and play it as many times as you like. The macro will select all the items in your "for sale" list, saving the bins you carried them in for later use. Be sure to at least browse through the final list once you're done to avoid selling items you didn't wish to sell, i.e. items that were in the same bin as your trade goods that you wish to keep, or wood items if you're trading with the Elves.
 +
 
 +
=== Mass Trap Builder ===
 +
 
 +
It's basically just the same as building items in bedrooms, but for traps. Useful for populating entire hallways with weapon or stone-fall traps.
 +
 
 +
=== Custom Uniforms ===
 +
 
 +
Since custom uniforms are not saved from one fortress to another, it can be tedious to remake them after each new embark. Instead, you can record a few macros to create each of your custom uniforms (Axedwarves with full armor, Wrestlers with light armor, Archers, Civilians, etc.) It is recommended to start recording each macro from the main window, before entering the (m)ilitary screen, and to avoid naming the uniform as part of the macro.  Because of the way the uniform menu is set up, you should also be careful not to move the cursor back into the uniform list during the recording of your macro, or problems may arise. As always, pause the game before you start recording or playback.
 +
 
 +
=== Digging in Odd Directions/Shapes ===
 +
 
 +
While it is very simple and fast to designate mining in any of the 6 possible linear directions (North, East, South, West, Up, and Down) in very long sections, specialized mining, such as diagonal hallways, circular rooms, etc., are more difficult.  It may be worth, for example, recording 4 macros that dig a short section of 3-tile wide hallway in non-standard directions (NE, NW, SW, and SE).  This way, when you want a hallway dug at a 45 degree angle you just load the appropriate macro and keep playing it until the hallway is the desired length.
 +
 
 +
=== Downshafts ===
 +
 
 +
Simple up/down stairs are easy to do, but if your standard fort layout includes stairs with empty spaces around them, like so...
 +
<pre>
 +
      (rooms)
 +
 
 +
        %%..%%
 +
        %....%
 +
(more  ..XX.. (still
 +
rooms) ..XX..  more
 +
        %....%  rooms)
 +
        %%..%%
 +
 
 +
      (etc...)
 +
</pre>
 +
...it can be cumbersome to designate all of that for multiple Z-levels at once. Instead, create a macro from one reference point (say, the top-left staircase of the 2x2 shaft or some such) and hit record, then designate the staircase area as you see fit. Move the cursor back to your reference point and move down one Z-level, then stop recording. You can now load it up and play it wherever you need it.
 +
 
 +
For added awesomeness, trim out the extra commands in a text editor as described above. Then highlight the whole macro and copy/paste it into a new file, copying the commands 5 times or as many as you want. Then save the new macro as a separate file (be sure to rename it at the top of the macro text as well). In this way you can have easy-to-use macros for digging your own standard stairwell. Separate macros for 1 level, 5 levels, and 20 levels seem to work well.
 +
 
 +
== Troubleshooting Scripts ==
 +
Users may experience some issues in getting external scripts to work, particularly when using looping scripts when experiencing low frame-rates.
 +
* If experiencing low frame-rates, try adding delays ("Sleep 100" to pause for 100 milliseconds for example) within macros to allow the interface to keep up. If there are nested loops, sometimes adding a pause at the end of an inner loop is all that is needed to flush the keyboard buffer.
 +
* Another way to add delay during and after each simulated key press is to put <B>SetKeyDelay, 40, 40</B> at the start of the macro.
 +
* Make sure that Dwarf Fortress maintains focus. IM windows are the enemy! Who needs friends anyhow? You've got Dwarf Fortress.
 +
* This may go without saying, but most macros assume standard key-mappings. If you're using non-standard ones, you may have to edit the macro to get it to work.
 +
* Visiting liaisons can bring up screens that eat keystrokes, throwing a long-looping script out-of-phase with where it expects the game to be.  Wait for the farewell screen before running a long script, or just pause the game beforehand.
 +
* The <B>SendPlay</B> function supports keys that the <B>Send</B> function does not, for example {{key|Shift-Enter}}.  According to the AutoHotKey documentation, <B>SendPlay</B> may also be better at preventing dropped keystrokes.
 +
 
 +
=== General Fortress Mode Hotkeys Script ===
 +
An attempt at speeding up various designations. Includes an up/down stair builder, a fast move up/down, and some select-and-advance keys. Please see [[user:DDR#Dwarf_Fortress_General_AHK_Script]].

Latest revision as of 14:45, 9 August 2018

This article is about an older version of DF.

Playing Dwarf Fortress means lots of typing. The game has an internal macro/keymap system. Using it or any external program can save you a great deal of time when dumping, rewalling, designating, and so forth.

DF macros[edit]

Creating macros[edit]

The controls for creating macros within DF are as follows:

  • Ctrl+r = record (and finish recording)
  • Ctrl+s = save
  • Ctrl+l = load
  • Ctrl+u+number = set to repeat [number] of times
  • Ctrl+p = play

To create a macro, press Ctrl+r to begin recording your actions. When you have recorded all the actions that you want, stop recording by hitting Ctrl+r again and save (Ctrl+s) the macro. The macro is then added to your macro list. To load a macro from the list just press Ctrl+l. You can then play the macro by pressing Ctrl+p whenever you want. You can also set a macro to repeat by pressing Ctrl+u, typing a two digit number, and then pressing Ctrl+p to begin the playback session. Moving your mouse from the playing window, or otherwise losing focus on Dwarf Fortress, is an annoying way a good way to interrupt a macro session from continuing (also the only known method anyway).

There is a directory data/init/macros for them. The macros are saved in .mak format. The first line of the macro file must match the filename, or the file will not be recognized as a valid macro. Even a recorded file for a simple macro - for example to create a 3 tiles wide ramp - may already consist of up to 50 commands listed. This is because every possible binding of the key pressed is included in the macro and put in a block (and r for ramp has many by default).

pressing_enter_recorded
		SELECT
		CLOSE_MEGA_ANNOUNCEMENT
		WORLD_PARAM_ENTER_VALUE
		SETUPGAME_SAVE_PROFILE_GO
		D_BURROWS_DEFINE
		D_MILITARY_ALERTS_SET
	End of group
		CUSTOM_CTRL_R
	End of group
End of macro

For this example the recording was started, enter was pressed and the recording was stopped. When using this macro every underlying command in the file will be called, if possible. If you are in the designation menu, it will react as a select, the other commands will be ignored. If you are in the burrow menu, it will work like pressing enter there. The macro alway ends with a block containing the end of its recording. But executing macros seems to ignore this command. If you have changed your key bindings you'll get another result, because the underlying commands are recorded, not the keys pressed.
When creating or editing your own macros it is a good idea to use only those commands you really want.

ramping_created
		DESIGNATE_RAMP
	End of group
		CURSOR_DOWN_Z
	End of group
		SELECT
	End of group
		CURSOR_RIGHT
	End of group
		CURSOR_RIGHT
	End of group
		SELECT
	End of group
		CURSOR_LEFT
	End of group
		CURSOR_LEFT
	End of group
		CURSOR_UP
	End of group
End of macro

This selfmade example will designate a 3 tiles wide ramp one z-level below and place the cursor to make the next execution of the macro continue the way down. The first line has to be the name of the file. You can see that there are grouping tags for every single keypress. These are important for a working macro.
It is unknown if there is the possibility of creationg loops/iterations, other programming features or comments.

Removing macros in-game can be done by pressing Esc and then selecting Keybindings > Macros. Press Backspace on the macros you want to delete, then press Esc and select "Save and Exit". This will also delete the corresponding macro file permanently. Otherwise, you can delete the corresponding .mak file from the init/macros/ folder, although that will only take effect the next time DF is run.

Changing macros while the game is running uses a counter-intuitive process. After editing the macro file, create a backup of it and remove the macro as described earlier. However, before saving the changes, place the backup file on the init/macros/ folder. Then save the changes and reload the macro with Ctrl+l.

Adding macros is also possible, resorting to the macro changing process. A "dummy" macro would be recorded and saved, then deleted. The macro that would be added would replace the dummy file.

macroscreen
		OPTIONS
	End of group
		STANDARDSCROLL_DOWN
		CURSOR_DOWN
	End of group
		STANDARDSCROLL_DOWN
		CURSOR_DOWN
	End of group
		SELECT
	End of group
		SELECT
	End of group
End of macro

Tuning macros[edit]

The fewer commands a macro consists of, the faster it runs. This means you should avoid unnecessary steps by optimizing the "path" of your designations.

The second and most effective way to increase speed is to remove all unnecessary commands DF recorded. These may be found in the init/macros folder and edited with any basic text editing program. The extra commands are ignored by the game but they still take time to be processed. To move a cursor 3 (up/down) or 4 (right/left) commands are recorded, most other keys are bound to more commands. Pressing d for example records more than 30 commands.

For example the code below is a simple macro that selects the digging designation, moves one square to the right, and then designates that tile to be dug.

example
		OPTION4
		CUSTOM_D
		WORLD_PARAM_DELETE
		LEGENDS_EXPORT_DETAILED_MAP
		A_COMBAT_DODGE
		A_STATUS_DESC
		A_SLEEP_DAWN
		A_INV_DROP
		SETUP_NOTES_DELETE_NOTE
		BUILDJOB_TARGET_RIGHT
		BUILDJOB_BED_DORMITORY
		BUILDJOB_FARM_WINTER
		BUILDJOB_RACKSTAND_KILL2
		HOTKEY_BUILDING_DOOR
		HOTKEY_BUILDING_CONSTRUCTION_STAIR_DOWN
		HOTKEY_BUILDING_WORKSHOP_DYER
		BUILDING_ORIENT_RIGHT
		BUILDING_ADVANCE_STAGE
		BUILDING_TRIGGER_MAX_SIZE_DOWN
		BUILDING_TRACK_STOP_DUMP
		HOTKEY_GLASS_DOOR
		HOTKEY_CARPENTER_DOOR
		HOTKEY_MASON_DOOR
		HOTKEY_TRAP_DOOR
		BUILDJOB_STOCKPILE_DELETE_CHILD
		STOCKPILE_ARMOR
		STOCKPILE_SETTINGS_DISABLE
		STORES_DUMP
		ORDERS_DYED_CLOTH
		ORDERS_ZONE_DRINKING
		D_DESIGNATE
		D_HAULING_STOP_LC_DIR
		D_BURROWS_DELETE
		D_NOTE_DELETE
		D_NOTE_ROUTE_DELETE
		D_BITEM_DUMP
		D_LOOK_DUMP
		ARENA_CREATURE_SIDE_UP
		ASSIGNTRADE_SORT
		DESIGNATE_DUMP
		DESIGNATE_DIG
		ITEM_DUMP
		D_MILITARY_DISBAND_SQUAD
		D_MILITARY_ALERTS_DELETE
		D_MILITARY_AMMUNITION_REMOVE_ITEM
		D_MILITARY_DELETE_UNIFORM
		STRING_A100
	End of group
		STANDARDSCROLL_RIGHT
		CURSOR_RIGHT
		WORLD_PARAM_INCREASE
		A_MOVE_E
	End of group
		SELECT
		CLOSE_MEGA_ANNOUNCEMENT
		WORLD_PARAM_ENTER_VALUE
		SETUPGAME_SAVE_PROFILE_GO
		D_BURROWS_DEFINE
		D_MILITARY_ALERTS_SET
	End of group
		SELECT
		CLOSE_MEGA_ANNOUNCEMENT
		WORLD_PARAM_ENTER_VALUE
		SETUPGAME_SAVE_PROFILE_GO
		D_BURROWS_DEFINE
		D_MILITARY_ALERTS_SET
	End of group
		CUSTOM_CTRL_R
	End of group
End of macro

Here is the same code but optimized through removal of all the excess commands. Each macro also contains an addition CUSTOM_CTRL_R command at the end that may be removed as well.

example
		DESIGNATE_DIG
	End of group
		CURSOR_RIGHT
	End of group
		SELECT
	End of group
		SELECT
	End of group
End of macro


The third way to increase the speed of macros is to change settings in the init-files. In the base init file (data/init/init.txt) you will find the follow lines:

If you set KEY_REPEAT_ACCEL_LIMIT above one, then after KEY_REPEAT_ACCEL_START repetitions 
the repetition delay will smoothly decrease until repetition is this number of times faster 
than at the start.

[KEY_REPEAT_ACCEL_LIMIT:8]
[KEY_REPEAT_ACCEL_START:10]

This controls the number of milliseconds between macro instructions.

[MACRO_MS:15]

  • The MACRO_MS setting is the number of milliseconds between macro instructions (the default, 15, allows 1000/15 instructions per second, or about 66). Decreasing this makes macros run faster, although decreasing it too far can make the game unresponsive while the macro is running.
  • The KEY_REPEAT_ACCEL_START and KEY_REPEAT_ACCEL_LIMIT settings are unrelated to macros (except while recording). See Technical tricks for more information.

External utilities[edit]

QuickFort[edit]

A spreadsheet-driven construction tool for Dwarf Fortress. Converts CSV files containing a "graphical" (or at least two-dimensional) representation of what you want to build into efficient DF macros. Comes with a number of scripts to get you started, some of them quite complex.

AutoHotKey[edit]

AutoHotKey is a powerful easy-to-use scripting language that can simulate keystrokes. (among other functions)

To started:

  1. Go to the AutoHotKey website and download AutoHotKey. Installation is simple and the program uses very little system resources.
  2. Read through their quick-start guide and start write your macro scripts (file type .ahk), which may contain any number of commands. You activate scripts by double-clicking .ahk files or by assigning hotkeys to your macros. Both of these can be done at any time - even right in the middle of a game. AutoHotKey also allows for automated activation of scripts.

Fluxbox + xvkbd[edit]

For linux, it's a quite cool solution. It's possible to create macros with outside tools, like fluxbox (linux window manager) + xvkbd (linux virtual keyboard for kiosks, with some macro capabilities). See the documentation here.

Pros:

  • Faster execution
  • Easier script writing
  • Portable code

Cons:

  • Sometime needs timing
  • Need xvkbd (Linux at least)
  • Need some special key reservation

Please see also the 40d macros page, as much of what is there works perfectly fine. If you can verify it works, please move it to this page.

Useful Macro Ideas[edit]

The following are macro ideas that other players have found useful, and may make management of your fort easier. For most macros it's highly recommended to pause the game before hitting the play button to avoid your dwarves causing unexpected behavior, i.e. a dwarf giving birth or anything else that auto-zooms to a different location.

Large Bedrooms[edit]

Bedrooms, especially larger ones or large blocks of identical ones, involve a lot of designations and build orders. These macros are designed to streamline the process. For all of these mass-building macros you may wish to temporarily forbid any of your artifact or masterwork furniture, to avoid giving overly-valuable items to your dwarf peasantry.

Placing Beds[edit]

So you've recorded a macro to dig out a series of bedrooms, and now you have to fill them. Bring up the build menu, select bed, and go the first position you want to place a bed in.

Start a new macro (Ctrl+r) and place the bed (selecting the first bed from the list), then move to the next bedroom in sequence. Repeat this until you reach the end of the row. If you are placing beds into multiple long rows of bedrooms, move the cursor to the first bed in the next row to make things faster. Turn off macro recording (Ctrl+r), but don't exit the build menu. You can then save your macro if you wish, though it's not necessary. Play the macro (Ctrl+p), and you have just laid out another row. Repeat until you have enough bedrooms or you run out of beds.

Placing Coffers[edit]

Placing coffers (but not bags) requires an extra step. Pause the game (you did remember to pause before playing macros, didn't you?) and go to the Stocks menu. Forbid all bags, regardless of what's inside them or what they're being used for (this is temporary). Exit to main screen and repeat the steps above, this time placing containers in your rooms. You will end up placing only chests / coffers / boxes, ignoring any bags. Repeat and play back for the rest of your bedrooms, then un-forbid your bags before un-pausing the game.

Resizing Rooms[edit]

If the bedroom is finished (at least all the beds are hauled to place), you may want to create a new macro to designate each room as a bedroom. query the building and select the first bed. Start a new macro and press r to designate it as a bedroom, then press + a few times to fill the available space. If you are fine with the size of the bedroom you can press enter, move on to the next bed, and repeat this for the whole row. If you want bedrooms that fill all the room and not all your bedrooms are the same size, you may have to press + a bit more or less for the larger cases. Repeat this for the rest of the rows as above.

Mass Selector[edit]

With this macro you can select a lot of things at once. Extremely helpful if you want to sell a lot of junk to the caravans. Record enter, then down about 10-25 times in a row. (For some menus you may wish to use enter, then +) When the caravan arrives, your dwarves haul all the bins to your Trade Depot for sale as normal. At the trade menu, load the macro and play it as many times as you like. The macro will select all the items in your "for sale" list, saving the bins you carried them in for later use. Be sure to at least browse through the final list once you're done to avoid selling items you didn't wish to sell, i.e. items that were in the same bin as your trade goods that you wish to keep, or wood items if you're trading with the Elves.

Mass Trap Builder[edit]

It's basically just the same as building items in bedrooms, but for traps. Useful for populating entire hallways with weapon or stone-fall traps.

Custom Uniforms[edit]

Since custom uniforms are not saved from one fortress to another, it can be tedious to remake them after each new embark. Instead, you can record a few macros to create each of your custom uniforms (Axedwarves with full armor, Wrestlers with light armor, Archers, Civilians, etc.) It is recommended to start recording each macro from the main window, before entering the (m)ilitary screen, and to avoid naming the uniform as part of the macro. Because of the way the uniform menu is set up, you should also be careful not to move the cursor back into the uniform list during the recording of your macro, or problems may arise. As always, pause the game before you start recording or playback.

Digging in Odd Directions/Shapes[edit]

While it is very simple and fast to designate mining in any of the 6 possible linear directions (North, East, South, West, Up, and Down) in very long sections, specialized mining, such as diagonal hallways, circular rooms, etc., are more difficult. It may be worth, for example, recording 4 macros that dig a short section of 3-tile wide hallway in non-standard directions (NE, NW, SW, and SE). This way, when you want a hallway dug at a 45 degree angle you just load the appropriate macro and keep playing it until the hallway is the desired length.

Downshafts[edit]

Simple up/down stairs are easy to do, but if your standard fort layout includes stairs with empty spaces around them, like so...

       (rooms)

        %%..%%
        %....%
(more   ..XX.. (still
 rooms) ..XX..  more
        %....%  rooms)
        %%..%%

       (etc...)

...it can be cumbersome to designate all of that for multiple Z-levels at once. Instead, create a macro from one reference point (say, the top-left staircase of the 2x2 shaft or some such) and hit record, then designate the staircase area as you see fit. Move the cursor back to your reference point and move down one Z-level, then stop recording. You can now load it up and play it wherever you need it.

For added awesomeness, trim out the extra commands in a text editor as described above. Then highlight the whole macro and copy/paste it into a new file, copying the commands 5 times or as many as you want. Then save the new macro as a separate file (be sure to rename it at the top of the macro text as well). In this way you can have easy-to-use macros for digging your own standard stairwell. Separate macros for 1 level, 5 levels, and 20 levels seem to work well.

Troubleshooting Scripts[edit]

Users may experience some issues in getting external scripts to work, particularly when using looping scripts when experiencing low frame-rates.

  • If experiencing low frame-rates, try adding delays ("Sleep 100" to pause for 100 milliseconds for example) within macros to allow the interface to keep up. If there are nested loops, sometimes adding a pause at the end of an inner loop is all that is needed to flush the keyboard buffer.
  • Another way to add delay during and after each simulated key press is to put SetKeyDelay, 40, 40 at the start of the macro.
  • Make sure that Dwarf Fortress maintains focus. IM windows are the enemy! Who needs friends anyhow? You've got Dwarf Fortress.
  • This may go without saying, but most macros assume standard key-mappings. If you're using non-standard ones, you may have to edit the macro to get it to work.
  • Visiting liaisons can bring up screens that eat keystrokes, throwing a long-looping script out-of-phase with where it expects the game to be. Wait for the farewell screen before running a long script, or just pause the game beforehand.
  • The SendPlay function supports keys that the Send function does not, for example Shift-Enter. According to the AutoHotKey documentation, SendPlay may also be better at preventing dropped keystrokes.

General Fortress Mode Hotkeys Script[edit]

An attempt at speeding up various designations. Includes an up/down stair builder, a fast move up/down, and some select-and-advance keys. Please see user:DDR#Dwarf_Fortress_General_AHK_Script.