Utility:For Each Tile

This is a module for Gibbed's Dwarf Fortress Tweak utility that can conditionally alter tiles of the map. By supplying a condition and a set of operations, the program is able to evaluate the condition for each tile, and if the condition is true, then the operations are executed, altering that particular tile is some fashion. This flexibility potentially provides numerous uses. This utility was originally designed to be a smarter version of Reveal, but grew to become much more. Not only can this utility show or hide tiles, but it can change whether or not they are outside, inside, light, dark, subterranean, or above ground. It can alter water and magma levels, mining designations, and in some cases substantially alter tile types, such as when creating a river source tile.

Installation

Required Components

• Exponent.DwarfFortress.Tools.ForEachTile.zip (extract this into the tweak/plugins/ subfolder)
• Gibbed's Dwarf Fortress Tweak
• .NET 3.5 Runtime

Memory XML File Values

Below is a list of all the required and optional memory addresses and offsets for each version of Dwarf Fortress on which this utility has been tested. Most of them are not necessary for limited operation of the program, but certain functions will be unavailable if the needed memory locations are not available.

v0.28.181.40a

<address name="menu_state" value="0x01392268" />
<address name="view_state" value="0x009FB368" />
<address name="mouse_x" value="0x009FB294" />
<address name="mouse_y" value="0x009FB298" />
<address name="mouse_z" value="0x009FB29C" />
<address name="viewport_x" value="0x00D447FC" />
<address name="viewport_y" value="0x00D72870" />
<address name="viewport_z" value="0x00D7284C" />
<address name="window_grid_x" value="0x01704ECC" />
<address name="window_grid_y" value="0x01704ED0" />
<address name="map_data" value="0x015C3D60"/>
<address name="map_x_count" value="0x015C3D78"/>
<address name="map_y_count" value="0x015C3D7C"/>
<address name="map_z_count" value="0x015C3D80"/>
<offset name="map_data_type_offset" value="0x0062"/>
<offset name="map_data_designation_offset" value="0x0264"/>
<offset name="map_data_occupancy_offset" value="0x0664"/>
<offset name="map_data_temperature1_offset" value="0x1564"/>
<offset name="map_data_temperature2_offset" value="0x1764"/>

Dwarf Fortress v0.28.181.39f

<address name="menu_state" value="0x01386260" />
<address name="view_state" value="0x009EF368" />
<address name="mouse_x" value="0x009EF294" />
<address name="mouse_y" value="0x009EF298" />
<address name="mouse_z" value="0x009EF29C" />
<address name="viewport_x" value="0x00D387FC" />
<address name="viewport_y" value="0x00D66870" />
<address name="viewport_z" value="0x00D6684C" />
<address name="window_grid_x" value="0x016F8A7C" />
<address name="window_grid_y" value="0x016F8A80" />
<address name="map_data" value="0x015B7920"/>
<address name="map_x_count" value="0x015B7938"/>
<address name="map_y_count" value="0x015B793C"/>
<address name="map_z_count" value="0x015B7940"/>
<offset name="map_data_type_offset" value="0x0062"/>
<offset name="map_data_designation_offset" value="0x0264"/>
<offset name="map_data_occupancy_offset" value="0x0664"/>
<offset name="map_data_temperature1_offset" value="0x1564"/>
<offset name="map_data_temperature2_offset" value="0x1764"/>

Dwarf Fortress v0.28.181.39e

<address name="menu_state" value="0x0132FDB0" />
<address name="view_state" value="0x009E3358" />
<address name="mouse_x" value="0x009E3284" />
<address name="mouse_y" value="0x009E3288" />
<address name="mouse_z" value="0x009E328C" />
<address name="viewport_x" value="0x00CE23C4" />
<address name="viewport_y" value="0x00D103C0" />
<address name="viewport_z" value="0x00D1039C" />
<address name="map_data" value="0x01561470"/>
<address name="map_x_count" value="0x01561488"/>
<address name="map_y_count" value="0x0156148C"/>
<address name="map_z_count" value="0x01561490"/>
<offset name="map_data_type_offset" value="0x0062"/>
<offset name="map_data_designation_offset" value="0x0264"/>
<offset name="map_data_occupancy_offset" value="0x0664"/>
<offset name="map_data_temperature1_offset" value="0x1564"/>
<offset name="map_data_temperature2_offset" value="0x1764"/>

Change Log

Version 0.6 Beta (2008/08/18 21:32 CST)

• added bodily fluid functions (blood, pus, ichor, goo, slime) in the Occupancy categories, along with related constants in the Constants category
• renamed is_vomit to has_vomit, and moved it and set_vomit to the Occupancy categories
• renamed is_snow_covered to has_snow, and set_snow_covered to set_snow, and moved them to the Occupancy categories
• added support for the string type, including a to_string function and the concatenation operator (+)
• added print and print_line functions for writing to the output panel
• added the is_allocated function
• added a new Experimental category, including functions for reading/writing type, matgloss id, and biome id
• provided a variation for most query functions to accept specific x, y, z coordinates, instaed of just defaulting to the current tile's x, y, z coordinates
• fixed various bugs with the functions in the Raw category, and added mask_and_set_ versions of each
• various small improvements to the interface
• updated viewport calculation code to properly handle changes in the latest DF version (0.28.181.40a)

Version 0.5 Beta (2008/08/15 18:18 CST)

• set_liquid_type_to_water was not working, now it is

Version 0.4 Beta (2008/08/15 16:29 CST)

• general interface improvements
• fixed undo bug, when the maximum undo/redo depth was infinite
• added z_distance_to_surface
• renamed is_ramp to is_upward_ramp
• added is_ramp, is_downward_ramp, is_above_upward_ramp and make_downward_ramp
• renamed is_lava to is_magma_source, and make_lava to make_magma_source
• added traffic designation queries, which had erroneously been left out
• added a few additional example operation sets to the included file

Usage

General

Menus and Toolbar Buttons

File

Items under the file menu are used to work with files that contain operation sets. A file can contain any number of operation sets. Generally, you will only need to keep one file, and a default is provided with some basic operation sets already defined. The standard actions of saving, opening, or creating a new file exist, as well as the option to refresh from the current file. This is for situations where the file that is currently open within the utility was edited by an external program, and you wish to bring these changes in without having to go through the Open File dialog.

Edit

The items in the edit menu allow you to work with the list of operation sets for the file that is currently open. Creating a new operation set will add a blank item at the bottom of the list and select it, so that you can edit its details in the text boxes below. Duplicating an item will make a copy of the selected item immediately below that item. Deleting the selected item will remove that item from the list completely.

Items can also be rearranged, so that you can place more frequently used operation sets near the top, and less frequently used ones near the bottom. Moving the selected item up or down will simply cause it to swap locations with the item that is immediately above or below it, respectively.

Expressions

Expressions use standard in-fix notation, complete with parentheses, operator precedence, and so forth. Individual items in an expression fall under one of five categories: constants, operators, general functions, queries, and modifiers. A description of each of these categories, along with some basic examples, are given below.

Constants

Constants are just specific values that are given an easy-to-remember name. Some of them are boolean, which means that they are either true or false, and some are doubles, which means that they represent real numbers.

Boolean Constants

While the two boolean values are represented internally as 0 (false) or 1 (true), you will use the actual text "false" or "true" in order to use these values in the program.

Double Constants

Some common mathematical constants are available, as well as some constants specific either to the Dwarf Fortress universe or to some particular function in this program. Standard mathematical constants are those such as pi and e. Constants specific to Dwarf Fortress are those such as water_freezing_temperature and water_boiling_temperature, which refer to Dwarf Fortress-specific temperature values. Finally, constants such as euclidean_distance and manhattan_distance are used by certain functions to indicate how they should function. These two in particular are used to tell certain functions how to calculate distances between pairs of tiles.

Operators

Basic mathematical, boolean, and comparison operators are available, as well as parentheses to control the order of evaluation. Boolean operators do not use symbols, but rather use the text "and", "or", and "not". All arguments to a boolean operator ("and" and "or" expect two arguments, "not" expects one) must be boolean, and the result is also boolean. Mathematical operators require doubles, and return doubles. Comparison operators require doubles (except for equal (=) and not-equal (!=), which can take either booleans or doubles) and return booleans.

General Functions

Some general functions are available for performing various generic tasks. Standard mathematical functions exist, such as the trigonometric sin(), cos(), and tan(), as well as the power/exponents functions sqrt(), pow() and log(). Random values are also available with random_bool() and random_double(). Other functions exist as well, which I will describe in the advanced section below.

Queries

Queries are functions that ask something about the current state of the game, and return some result as the answer. There are a variety of subcategories that queries fall under. For example, map queries ask something about the map: How big it is, which tile is currently being tested/modified, where the viewport is located, or where the cursor is located. Property queries ask something about basic properties of the current tile: if it is light or dark, above ground or subterranean, muddy or not, and so on. Other categories include physical, occupancy, designation, and area queries.

Modifiers

Modifiers are functions that alter the current tile in some way, and do not return any value (which is often indicated by saying that they return void). All modifiers have corresponding queries, though not all queries have corresponding modifiers. For example, you cannot modify the viewport width even though you can query it. Technical limitations also prevent many physical queries from having matching modifiers, modifying a tile to become a tree, for example.

There is still a lot that can be modified, however. The light/dark, inside/outside/ above ground/subterranean values mentioned above can all be changed. The level and type of liquid in a tile can be changed. Digging designations can be altered. And even certain physical states can be modified, such as turning a tile into a river source or a bottomless pit.

Operation Sets

The function portion of an operation set consists of a condition expression, and one or more operation statements. A statement is merely an expression that has its return value ignored, if it has one. When an operation set is executed, the condition is evaluated for each tile, and if the condition is true, then the operations are executed, one at a time. If the condition is false, no operations are executed.

Basic Examples

Reveal

The most straightforward example is an unconditional reveal, which performs precisely the same function as Rick's basic reveal module. It applies to every tile regardless of each tile's state, and modifies each tile to be shown. In this program, it would therefore look like:

Condition:

true

Operations:

show();

The semicolon at the end of the operation is optional. If you were to have more than one operation, as I will show later, then you would need a semicolon between each statement.