diff --git a/README.rst b/README.rst index b75320a98..97ac6b36e 100644 --- a/README.rst +++ b/README.rst @@ -56,3 +56,4 @@ For Developers: docs/Compile docs/Lua API library/xml/SYNTAX + docs/Binpatches diff --git a/docs/Binpatches.rst b/docs/Binpatches.rst new file mode 100644 index 000000000..994957b1b --- /dev/null +++ b/docs/Binpatches.rst @@ -0,0 +1,179 @@ +.. _binpatches: + +###################### +Patching the DF binary +###################### + +Writing scripts and plugins for DFHack is not the only way to modify Dwarf +Fortress. Before DFHack, it was common for tools to manually patch the +binary to change behaviour, and DFHack still contains tools to do this via +the `scripts/binpatch` command. + +.. warning:: + + We recommend using a script or plugin instead of a raw patch if + at all possible - that way your work will work for many versions + across multiple operating systems. There's a reason nobody has + written patches since ``0.34.11``! + +.. contents:: + + +Getting a patch +=============== +There are no binary patches available for Dwarf Fortress versions after 0.34.11 + +This system is kept for the chance that someone will find it useful, so some +hints on how to write your own follow. This will require disassembly and +decent skill in `memory research `. + +* The patches are expected to be encoded in text format used by IDA. + +* See `this commit `_, + when the 0.34.11 patches were discarded, for example patches. + +* `Issue #546 `_ is about the + future of the binpatches, and may be useful reading. + +If you want to write a patch, the armory patches discussed here and documented +below would probably be the best place to start. + + +Using a patch +============= +There are two methods to apply a patch. + +Patching at runtime +------------------- +The `scripts/binpatch` script checks, applies or removes binary patches +directly in memory at runtime:: + + binpatch [check|apply|remove] + +If the name of the patch has no extension or directory separators, the +script uses ``hack/patches//.dif``, thus auto-selecting +the version appropriate for the currently loaded executable. + +This is the preferred method; it's easier to debug, does not cause persistent +problems, and leaves file checksums alone. + + +Patching on disk +---------------- + +.. warning:: + + This method of patching is deprecated, and may be removed without notice. + You should use the runtime patching option above. + +DFHack includes a small stand-alone utility for applying and removing +binary patches from the game executable. Use it from the regular operating +system console: + +``binpatch check "Dwarf Fortress.exe" patch.dif`` + Checks and prints if the patch is currently applied. + +``binpatch apply "Dwarf Fortress.exe" patch.dif`` + Applies the patch, unless it is already applied or in conflict. + +``binpatch remove "Dwarf Fortress.exe" patch.dif`` + Removes the patch, unless it is already removed. + +If you use a permanent patch under OSX or Linux, you must update +``symbols.xml`` with the new checksum of the executable. Find the relevant +section, and add a new line:: + + + +In order to find the correct value of the hash, look into stderr.log; +DFHack prints an error there if it does not recognize the hash. + +.. _binpatches/needs-patch: + +Tools reliant on binpatches +=========================== +Some DFHack tools require the game to be patched to work. As no patches +are currently available, the full description of each is included here. + +fix-armory +---------- +Enables a fix for storage of squad equipment in barracks. + +Specifically, it prevents your haulers from moving squad equipment +to stockpiles, and instead queues jobs to store it on weapon racks, +armor stands, and in containers. + +.. note:: + + In order to actually be used, weapon racks have to be patched and + manually assigned to a squad. See `scripts/gui/assign-rack`. + +Note that the buildings in the armory are used as follows: + +* Weapon racks (when patched) are used to store any assigned weapons. + Each rack belongs to a specific squad, and can store up to 5 weapons. + +* Armor stands belong to specific squad members and are used for + armor and shields. + +* Cabinets are used to store assigned clothing for a specific squad member. + They are **never** used to store owned clothing. + +* Chests (boxes, etc) are used for a flask, backpack or quiver assigned + to the squad member. Due to a probable bug, food is dropped out of the + backpack when it is stored. + +.. warning:: + + Although armor stands, cabinets and chests properly belong only to one + squad member, the owner of the building used to create the barracks will + randomly use any containers inside the room. Thus, it is recommended to + always create the armory from a weapon rack. + +Contrary to the common misconception, all these uses are controlled by the +*Individual Equipment* usage flag. The *Squad Equipment* flag is actually +intended for ammo, but the game does even less in that area than for armor +and weapons. This plugin implements the following rules almost from scratch: + +* Combat ammo is stored in chests inside rooms with Squad Equipment enabled. + +* If a chest is assigned to a squad member due to Individual Equipment also + being set, it is only used for that squad's ammo; otherwise, any squads + with Squad Equipment on the room will use all of the chests at random. + +* Training ammo is stored in chests inside archery ranges designated from + archery targets, and controlled by the same Train flag as archery training + itself. This is inspired by some defunct code for weapon racks. + +There are some minor traces in the game code to suggest that the first of +these rules is intended by Toady; the rest are invented by this plugin. + + +gui/assign-rack +--------------- +Bind to a key (the example config uses P), and activate when viewing a weapon +rack in the ``q`` mode. + +.. image:: images/assign-rack.png + +This script is part of a group of related fixes to make the armory storage +work again. The existing issues are: + +* Weapon racks have to each be assigned to a specific squad, like with + beds/boxes/armor stands and individual squad members, but nothing in + the game does this. This issue is what this script addresses. + +* Even if assigned by the script, **the game will unassign the racks again + without a binary patch**. This patch is called ``weaponrack-unassign``, + and has not been updated since 0.34.11. See `the bug report`_ for more info. + +.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 + +* Haulers still take equipment stored in the armory away to the stockpiles, + unless `plugins/fix-armory` is used. + +The script interface simply lets you designate one of the squads that +are assigned to the barracks/armory containing the selected stand as +the intended user. In order to aid in the choice, it shows the number +of currently assigned racks for every valid squad. + diff --git a/docs/Contributing.rst b/docs/Contributing.rst index 3c7f99ec1..6599f680c 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -101,6 +101,8 @@ How to get new code into DFHack * Work done against Github issues tagged "bug report" get priority * Submit ideas and bug reports as issues on Github. Posts in the forum thread can easily get missed or forgotten. +.. _contributing-memory-research: + Memory research --------------- If you want to do memory research, you'll need some tools and some knowledge. diff --git a/docs/Core.rst b/docs/Core.rst index 91d2fdb96..4e2080311 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -304,31 +304,3 @@ nopause Disables pausing (both manual and automatic) with the exception of pause forced by 'reveal hell'. This is nice for digging under rivers. -Patched binaries -================ -As an alternative to permanently modifying the binary, you can use the -``binpatch`` dfhack command to apply patches live in memory during a DF session. - -In this case, updating symbols.xml is not necessary - otherwise Linux and OSX -users of patched binaries may have to find the relevant section in ``symbols.xml``, -and add a new line with the checksum of their executable:: - - - -In order to find the correct value of the hash, look into stderr.log; -DFHack prints an error there if it does not recognize the hash. - -DFHack includes a small stand-alone utility for applying and removing -binary patches from the game executable. Use it from the regular operating -system console: - -``binpatch check "Dwarf Fortress.exe" patch.dif`` - Checks and prints if the patch is currently applied. - -``binpatch apply "Dwarf Fortress.exe" patch.dif`` - Applies the patch, unless it is already applied or in conflict. - -``binpatch remove "Dwarf Fortress.exe" patch.dif`` - Removes the patch, unless it is already removed. - -The patches are expected to be encoded in text format used by IDA. diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 5cb16dfd3..656df680d 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -332,56 +332,8 @@ Subcommands that persist until disabled or DF quits: fix-armory ========== -Enables a fix for storage of squad equipment in barracks. - -Specifically, it prevents your haulers from moving squad equipment -to stockpiles, and instead queues jobs to store it on weapon racks, -armor stands, and in containers. - -.. note:: - - In order to actually be used, weapon racks have to be patched and - manually assigned to a squad. See `scripts/gui/assign-rack`. - -Note that the buildings in the armory are used as follows: - -* Weapon racks (when patched) are used to store any assigned weapons. - Each rack belongs to a specific squad, and can store up to 5 weapons. - -* Armor stands belong to specific squad members and are used for - armor and shields. - -* Cabinets are used to store assigned clothing for a specific squad member. - They are **never** used to store owned clothing. - -* Chests (boxes, etc) are used for a flask, backpack or quiver assigned - to the squad member. Due to a probable bug, food is dropped out of the - backpack when it is stored. - -.. warning:: - - Although armor stands, cabinets and chests properly belong only to one - squad member, the owner of the building used to create the barracks will - randomly use any containers inside the room. Thus, it is recommended to - always create the armory from a weapon rack. - -Contrary to the common misconception, all these uses are controlled by the -*Individual Equipment* usage flag. The *Squad Equipment* flag is actually -intended for ammo, but the game does even less in that area than for armor -and weapons. This plugin implements the following rules almost from scratch: - -* Combat ammo is stored in chests inside rooms with Squad Equipment enabled. - -* If a chest is assigned to a squad member due to Individual Equipment also - being set, it is only used for that squad's ammo; otherwise, any squads - with Squad Equipment on the room will use all of the chests at random. - -* Training ammo is stored in chests inside archery ranges designated from - archery targets, and controlled by the same Train flag as archery training - itself. This is inspired by some defunct code for weapon racks. - -There are some minor traces in the game code to suggest that the first of -these rules is intended by Toady; the rest are invented by this plugin. +`This plugin requires a binpatch `, which has not +been available since DF 0.34.11 =========== diff --git a/docs/Scripts.rst b/docs/Scripts.rst index e7203694c..d28914c47 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -143,31 +143,8 @@ Does something with items in adventure mode jobs. gui/assign-rack =============== -Bind to a key (the example config uses P), and activate when viewing a weapon -rack in the 'q' mode. - -.. image:: images/assign-rack.png - -This script is part of a group of related fixes to make the armory storage -work again. The existing issues are: - -* Weapon racks have to each be assigned to a specific squad, like with - beds/boxes/armor stands and individual squad members, but nothing in - the game does this. This issue is what this script addresses. - -* Even if assigned by the script, **the game will unassign the racks again without a binary patch**. - This patch is called ``weaponrack-unassign``, and can be applied via - the binpatch program, or the matching script. See `the bug report`_ for more info. - -.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 - -* Haulers still take equipment stored in the armory away to the stockpiles, - unless `plugins/fix-armory` is used. - -The script interface simply lets you designate one of the squads that -are assigned to the barracks/armory containing the selected stand as -the intended user. In order to aid in the choice, it shows the number -of currently assigned racks for every valid squad. +`This script requires a binpatch `, which has not +been available since DF 0.34.11 gui/autobutcher =============== @@ -681,15 +658,11 @@ A more convenient way to ban cooking various categories of foods than the kitchen interface. Usage: ``ban-cooking ``. Valid types are ``booze``, ``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds). +.. _scripts/binpatch: + binpatch ======== -Checks, applies or removes binary patches directly in memory at runtime:: - - binpatch check/apply/remove - -If the name of the patch has no extension or directory separators, the -script uses ``hack/patches//.dif``, thus auto-selecting -the version appropriate for the currently loaded executable. +Implements functions for in-memory binpatches. See `binpatches`. .. _scripts/brainwash: