From 58e6ef6524ca984d4acbaf8e613a8cc86d06b081 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 4 Nov 2015 23:13:52 +1100 Subject: [PATCH 01/18] De-alias migrants-now --- scripts/devel/migrants-now.lua | 9 --------- scripts/migrants-now.lua | 11 ++++++++--- 2 files changed, 8 insertions(+), 12 deletions(-) delete mode 100644 scripts/devel/migrants-now.lua diff --git a/scripts/devel/migrants-now.lua b/scripts/devel/migrants-now.lua deleted file mode 100644 index 8eb4b0c8f..000000000 --- a/scripts/devel/migrants-now.lua +++ /dev/null @@ -1,9 +0,0 @@ --- Force a migrants event in next 10 ticks. - -df.global.timed_events:insert('#',{ - new = true, - type = df.timed_event_type.Migrants, - season = df.global.cur_season, - season_ticks = df.global.cur_season_tick+1, - entity = df.historical_entity.find(df.global.ui.civ_id) -}) diff --git a/scripts/migrants-now.lua b/scripts/migrants-now.lua index b2f08e9f9..b38e38115 100644 --- a/scripts/migrants-now.lua +++ b/scripts/migrants-now.lua @@ -1,11 +1,16 @@ -- Force a migrant wave (only works after hardcoded waves) ---@alias = 'devel/migrants-now' --[[=begin migrants-now ============ Forces an immediate migrant wave. Only works after migrants have -arrived naturally. Alias for ``devel/migrants-now``; equivalent to -`modtools/force` ``-eventType migrants`` +arrived naturally. Equivalent to `modtools/force` ``-eventType migrants`` =end]] +df.global.timed_events:insert('#',{ + new = true, + type = df.timed_event_type.Migrants, + season = df.global.cur_season, + season_ticks = df.global.cur_season_tick+1, + entity = df.historical_entity.find(df.global.ui.civ_id) +}) From 5018af9a9e2644f951d7281644ee422d79e6dae4 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 4 Nov 2015 23:14:10 +1100 Subject: [PATCH 02/18] Document devel scripts --- scripts/devel/about.txt | 8 +++++-- scripts/devel/all-bob.lua | 10 +++++++- scripts/devel/cmptiles.lua | 10 +++++++- scripts/devel/export-dt-ini.lua | 7 ++++++ scripts/devel/find-offsets.lua | 38 +++++++++++++++++++++++------- scripts/devel/inject-raws.lua | 28 +++++++++++++++------- scripts/devel/inspect-screen.lua | 7 ++++++ scripts/devel/light.lua | 13 +++++++++- scripts/devel/list-filters.lua | 10 ++++++-- scripts/devel/lsmem.lua | 7 ++++++ scripts/devel/lua-example.lua | 6 ----- scripts/devel/nuke-items.lua | 10 ++++++-- scripts/devel/pop-screen.lua | 7 ++++++ scripts/devel/prepare-save.lua | 12 ++++++++++ scripts/devel/print-args.lua | 9 ++++++- scripts/devel/print-args2.lua | 9 ++++++- scripts/devel/scanitemother.rb | 8 ++++++- scripts/devel/spawn-unit-helper.rb | 22 ++++++++++------- scripts/devel/test-perlin.lua | 9 +++++++ scripts/devel/unforbidall.rb | 7 ++++++ scripts/devel/unit-path.lua | 7 ++++++ scripts/devel/watch-minecarts.lua | 9 +++++++ 22 files changed, 210 insertions(+), 43 deletions(-) delete mode 100644 scripts/devel/lua-example.lua diff --git a/scripts/devel/about.txt b/scripts/devel/about.txt index cd97a8809..12b1f1853 100644 --- a/scripts/devel/about.txt +++ b/scripts/devel/about.txt @@ -1,2 +1,6 @@ -``devel/*`` scripts are intended for developers, or still substantially unfinished. -If you don't already know what they do, best to leave them alone. +``devel/*`` scripts are intended for developer use, but many may +be of interest to anyone investigating odd phenomema or just messing +around. They are documented to encourage such inquiry. + +Some can PERMANENTLY DAMAGE YOUR SAVE if misused, so please be careful. +The warnings are real; if in doubt make backups before running the command. diff --git a/scripts/devel/all-bob.lua b/scripts/devel/all-bob.lua index 65c1ea2d6..08ab19fbb 100644 --- a/scripts/devel/all-bob.lua +++ b/scripts/devel/all-bob.lua @@ -1,6 +1,14 @@ --all-bob.lua --author expwnent ---names all units bob. Useful for testing interaction trigger events +-- +--[[=begin + +devel/all-bob +============= +Changes the first name of all units to "Bob". +Useful for testing `modtools/interaction-trigger` events. + +=end]] for _,v in ipairs(df.global.world.units.all) do v.name.first_name = "Bob" diff --git a/scripts/devel/cmptiles.lua b/scripts/devel/cmptiles.lua index 8421038eb..bb0871051 100644 --- a/scripts/devel/cmptiles.lua +++ b/scripts/devel/cmptiles.lua @@ -1,5 +1,13 @@ -- Lists and/or compares two tiletype material groups. --- Usage: devel/cmptiles material1 [material2] +--[[=begin + +devel/cmptiles +============== +Lists and/or compares two tiletype material groups. + +Usage: ``devel/cmptiles material1 [material2]`` + +=end]] local nmat1,nmat2=... local mat1 = df.tiletype_material[nmat1] diff --git a/scripts/devel/export-dt-ini.lua b/scripts/devel/export-dt-ini.lua index 41a2457ce..1d99b2d55 100644 --- a/scripts/devel/export-dt-ini.lua +++ b/scripts/devel/export-dt-ini.lua @@ -1,4 +1,11 @@ -- Exports an ini file for Dwarf Therapist. +--[[=begin + +devel/export-dt-ini +=================== +Exports an ini file containing memory addresses for Dwarf Therapist. + +=end]] local utils = require 'utils' local ms = require 'memscan' diff --git a/scripts/devel/find-offsets.lua b/scripts/devel/find-offsets.lua index ae99adbca..17bc4f6f9 100644 --- a/scripts/devel/find-offsets.lua +++ b/scripts/devel/find-offsets.lua @@ -1,19 +1,39 @@ -- Find some offsets for linux. +--[[=begin -local utils = require 'utils' -local ms = require 'memscan' -local gui = require 'gui' +devel/find-offsets +================== +WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS. + +Running this script on a new DF version will NOT +MAKE IT RUN CORRECTLY if any data structures +changed, thus possibly leading to CRASHES AND/OR +PERMANENT SAVE CORRUPTION. + +Finding the first few globals requires this script to be +started immediately after loading the game, WITHOUT +first loading a world. The rest expect a loaded save, +not a fresh embark. Finding current_weather requires +a special save previously processed with `devel/prepare-save` +on a DF version with working dfhack. ---[[ +The script expects vanilla game configuration, without +any custom tilesets or init file changes. Never unpause +the game unless instructed. When done, quit the game +without saving using 'die'. Arguments: - * global names to force finding them - * 'all' to force all globals - * 'nofeed' to block automated fake input searches - * 'nozoom' to disable neighboring object heuristics +* global names to force finding them +* ``all`` to force all globals +* ``nofeed`` to block automated fake input searches +* ``nozoom`` to disable neighboring object heuristics -]] +=end]] + +local utils = require 'utils' +local ms = require 'memscan' +local gui = require 'gui' local is_known = dfhack.internal.getAddress diff --git a/scripts/devel/inject-raws.lua b/scripts/devel/inject-raws.lua index 1450d1179..cea69eb61 100644 --- a/scripts/devel/inject-raws.lua +++ b/scripts/devel/inject-raws.lua @@ -1,14 +1,26 @@ -- Injects new reaction, item and building defs into the world. +--[[=begin --- The savegame contains a list of the relevant definition tokens in --- the right order, but all details are read from raws every time. --- This allows just adding stub definitions, and simply saving and --- reloading the game. +devel/inject-raws +================= +WARNING: THIS SCRIPT CAN PERMANENLY DAMAGE YOUR SAVE. --- Usage example: ---[[ -devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER -]] +This script attempts to inject new raw objects into your +world. If the injected references do not match the actual +edited raws, your save will refuse to load, or load but crash. + +The savegame contains a list of the relevant definition tokens in +the right order, but all details are read from raws every time. +This allows just adding stub definitions, and simply saving and +reloading the game. + +This is useful enough for modders and some users to justify the danger. + +Usage example:: + + devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER + +=end]] local utils = require 'utils' diff --git a/scripts/devel/inspect-screen.lua b/scripts/devel/inspect-screen.lua index ae8334ad7..9de6b2532 100644 --- a/scripts/devel/inspect-screen.lua +++ b/scripts/devel/inspect-screen.lua @@ -1,4 +1,11 @@ -- Read the tiles from the screen and display info about them. +--[[=begin + +devel/inspect-screen +==================== +Read the tiles from the screen and display info about them. + +=end]] local utils = require 'utils' local gui = require 'gui' diff --git a/scripts/devel/light.lua b/scripts/devel/light.lua index 532a3a4f5..e19591e11 100644 --- a/scripts/devel/light.lua +++ b/scripts/devel/light.lua @@ -1,4 +1,15 @@ --- an experimental lighting engine for df. param: "static" to not recalc when in game. press "~" to recalculate. "`" to exit +-- an experimental lighting engine +--[[=begin + +devel/light +=========== +An experimental lighting engine for DF, using the `rendermax` plugin. + +Call ``devel/light static`` to not recalculate lighting when in game. +Press :kbd:`~` to recalculate lighting. Press :kbd:`\`` to exit. + +=end]] + local gui = require 'gui' local guidm = require 'gui.dwarfmode' local render = require 'plugins.rendermax' diff --git a/scripts/devel/list-filters.lua b/scripts/devel/list-filters.lua index 87b9f24b1..5666315fc 100644 --- a/scripts/devel/list-filters.lua +++ b/scripts/devel/list-filters.lua @@ -1,6 +1,12 @@ -- List input items for the building currently being built. --- --- This is where the filters in lua/dfhack/buildings.lua come from. +--[[=begin + +devel/list-filters +================== +List input items for the building currently being built. +This is where the filters in lua/dfhack/buildings.lua come from. + +=end]] local dumper = require 'dumper' local utils = require 'utils' diff --git a/scripts/devel/lsmem.lua b/scripts/devel/lsmem.lua index 75586324d..b390adc5c 100644 --- a/scripts/devel/lsmem.lua +++ b/scripts/devel/lsmem.lua @@ -1,4 +1,11 @@ -- Prints memory ranges of the process. +--[[=begin + +devel/lsmem +=========== +Prints memory ranges of the process. + +=end]] for _,v in ipairs(dfhack.internal.getMemRanges()) do local access = { '-', '-', '-', 'p' } diff --git a/scripts/devel/lua-example.lua b/scripts/devel/lua-example.lua deleted file mode 100644 index 044849ed7..000000000 --- a/scripts/devel/lua-example.lua +++ /dev/null @@ -1,6 +0,0 @@ --- Example of a lua script. - -run_count = (run_count or 0) + 1 - -print('Arguments: ',...) -print('Command called '..run_count..' times.') diff --git a/scripts/devel/nuke-items.lua b/scripts/devel/nuke-items.lua index aa3f5b840..d98901142 100644 --- a/scripts/devel/nuke-items.lua +++ b/scripts/devel/nuke-items.lua @@ -1,6 +1,12 @@ -- Deletes ALL items not held by units, buildings or jobs. --- --- Intended solely for lag investigation. +--[[=begin + +devel/nuke-items +================ +Deletes ALL items not held by units, buildings or jobs. +Intended solely for lag investigation. + +=end]] local count = 0 diff --git a/scripts/devel/pop-screen.lua b/scripts/devel/pop-screen.lua index f1ee072c5..8bc5e45c6 100644 --- a/scripts/devel/pop-screen.lua +++ b/scripts/devel/pop-screen.lua @@ -1,3 +1,10 @@ -- For killing bugged out gui script screens. +--[[=begin + +devel/pop-screen +================ +For killing bugged out gui script screens. + +=end]] dfhack.screen.dismiss(dfhack.gui.getCurViewscreen()) diff --git a/scripts/devel/prepare-save.lua b/scripts/devel/prepare-save.lua index c282c8a43..dd1f81e45 100644 --- a/scripts/devel/prepare-save.lua +++ b/scripts/devel/prepare-save.lua @@ -1,4 +1,16 @@ -- Prepare the current save for use with devel/find-offsets. +--[[=begin + +devel/prepare-save +================== +WARNING: THIS SCRIPT IS STRICTLY FOR DFHACK DEVELOPERS. + +This script prepares the current savegame to be used +with `devel/find-offsets`. It CHANGES THE GAME STATE +to predefined values, and initiates an immediate +`quicksave`, thus PERMANENTLY MODIFYING the save. + +=end]] local utils = require 'utils' diff --git a/scripts/devel/print-args.lua b/scripts/devel/print-args.lua index 199a20e7f..46024eaa4 100644 --- a/scripts/devel/print-args.lua +++ b/scripts/devel/print-args.lua @@ -1,6 +1,13 @@ --print-args.lua --author expwnent ---prints all the arguments on their own line. useful for debugging +--[[=begin + +devel/print-args +================ +Prints all the arguments you supply to the script on their own line. +Useful for debugging other scripts. + +=end]] local args = {...} for _,arg in ipairs(args) do diff --git a/scripts/devel/print-args2.lua b/scripts/devel/print-args2.lua index 873b40311..ad870623d 100644 --- a/scripts/devel/print-args2.lua +++ b/scripts/devel/print-args2.lua @@ -1,6 +1,13 @@ --print-args2.lua --author expwnent ---prints all the arguments on their own line with quotes around them. useful for debugging +--[[=begin + +devel/print-args2 +================= +Prints all the arguments you supply to the script on their own line +with quotes around them. + +=end]] local args = {...} print("print-args") diff --git a/scripts/devel/scanitemother.rb b/scripts/devel/scanitemother.rb index 00b093a28..1f130603f 100644 --- a/scripts/devel/scanitemother.rb +++ b/scripts/devel/scanitemother.rb @@ -1,5 +1,11 @@ -# list indexes in world.item.other[] where current selected item appears +# list indices in world.item.other[] where current selected item appears +=begin +devel/scanitemother +=================== +List indices in ``world.item.other[]`` where current selected item appears. + +=end tg = df.item_find raise 'select an item' if not tg diff --git a/scripts/devel/spawn-unit-helper.rb b/scripts/devel/spawn-unit-helper.rb index a7d4f610d..437eb81db 100644 --- a/scripts/devel/spawn-unit-helper.rb +++ b/scripts/devel/spawn-unit-helper.rb @@ -13,17 +13,23 @@ df.world.raws.creatures.all.length.times { |r_idx| df.world.arena_spawn.creature_cnt[df.world.arena_spawn.race.length-1] = 0 puts < Date: Thu, 5 Nov 2015 00:23:45 +1100 Subject: [PATCH 03/18] Linting: improve script docs check, work off Travis Expands coverage of scripts linting, and improves checks for a correct title. Various fixes to make 'python travis/all.py' work for offline users; when the TRAVIS envvar is not set it now fails without an error. Minor cleanup in conf.py --- conf.py | 49 +++++++------------------------------- travis/lint.py | 5 +++- travis/script-in-readme.py | 43 +++++++++++++++++---------------- travis/script-syntax.py | 23 +++++++++++------- 4 files changed, 50 insertions(+), 70 deletions(-) diff --git a/conf.py b/conf.py index 81cfb78ef..5eb2c8177 100644 --- a/conf.py +++ b/conf.py @@ -1,8 +1,7 @@ #!/usr/bin/env python3 # -*- coding: utf-8 -*- # -# DFHack documentation build configuration file, created by -# sphinx-quickstart on Tue Sep 22 17:34:54 2015. +# DFHack documentation build configuration file # # This file is execfile()d with the current directory set to its # containing dir. @@ -18,25 +17,24 @@ from io import open import os import shlex import sys -import shutil +# -- Autodoc for DFhack scripts ------------------------------------------- + def doc_dir(dirname, files): """Yield (command, includepath) for each script in the directory.""" sdir = os.path.relpath(dirname, '.').replace('\\', '/').replace('../', '') for f in files: - if f[-3:] not in {'lua', '.rb'}: + if f[-3:] not in ('lua', '.rb'): continue with open(os.path.join(dirname, f), 'r', encoding='utf8') as fstream: text = [l.rstrip() for l in fstream.readlines() if l.strip()] command = None for line in text: - if line == len(line) * '=': - if command is not None: - yield command, sdir + '/' + f + if command and line == len(line) * '=': + yield command, sdir + '/' + f break command = line - # later, print an error for missing docs here def document_scripts(): @@ -89,11 +87,6 @@ def document_scripts(): document_scripts() -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) - # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -115,15 +108,12 @@ extlinks = { 'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s', 'Bug ') } -# some aliases for link directives -extlinks['forum'] = extlinks['forums'] # Add any paths that contain templates here, relative to this directory. templates_path = [] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The encoding of source files. @@ -145,7 +135,7 @@ def get_version(): """Return the DFHack version string, from CMakeLists.txt""" version = release = '' try: - with open('../CMakeLists.txt') as f: + with open('CMakeLists.txt') as f: for s in f.readlines(): if fnmatch.fnmatch(s.upper(), 'SET(DF_VERSION "?.??.??")\n'): version = s.upper().replace('SET(DF_VERSION "', '') @@ -179,19 +169,9 @@ exclude_patterns = ['docs/_build/*', 'depends/*', 'scripts/3rdparty/*'] # documents. default_role = 'ref' -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' -# If true, keep warnings as "system message" paragraphs in the built documents. -#keep_warnings = False - # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -245,7 +225,7 @@ html_static_path = ['docs/styles'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = '%Y-%m-%d' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. @@ -288,19 +268,6 @@ html_use_index = False # base URL from which the finished HTML is served. #html_use_opensearch = '' -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' -#html_search_language = 'en' - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - # Output file base name for HTML help builder. htmlhelp_basename = 'DFHackdoc' diff --git a/travis/lint.py b/travis/lint.py index ce28f4be3..9b39f0149 100644 --- a/travis/lint.py +++ b/travis/lint.py @@ -65,8 +65,11 @@ class Linter(object): class NewlineLinter(Linter): msg = 'Contains DOS-style newlines' + def __init__(self): + # git supports newline conversion. Catch in CI, ignore on Windows. + self.ignore = sys.platform == 'win32' and not os.environ.get('TRAVIS') def check_line(self, line): - return '\r' not in line + return self.ignore or '\r' not in line def fix_line(self, line): return line.replace('\r', '') diff --git a/travis/script-in-readme.py b/travis/script-in-readme.py index b7d0577f3..a6804fb00 100644 --- a/travis/script-in-readme.py +++ b/travis/script-in-readme.py @@ -1,17 +1,19 @@ from io import open import os +from os.path import basename, dirname, join, splitext import sys -scriptdirs = ( - 'scripts', - #'scripts/devel', # devel scripts don't have to be documented - 'scripts/fix', - 'scripts/gui', - 'scripts/modtools') + +def expected_cmd(path): + """Get the command from the name of a script.""" + dname, fname = basename(dirname(path)), splitext(basename(path))[0] + if dname in ('devel', 'fix', 'gui', 'modtools'): + return dname + '/' + fname + return fname def check_file(fname): - doclines = [] + errors, doclines = 0, [] with open(fname, errors='ignore') as f: for l in f.readlines(): if doclines or l.strip().endswith('=begin'): @@ -27,23 +29,24 @@ def check_file(fname): title, underline = doclines[2], doclines[3] if underline != '=' * len(title): print('Error: title/underline mismatch:', fname, title, underline) - return 1 - start = fname.split('/')[-2] - if start != 'scripts' and not title.startswith(start): - print('Error: title is missing start string: {} {} {}'.format(fname, start, title)) - return 1 - return 0 + errors += 1 + if title != expected_cmd(fname): + print('Warning: expected script title {}, got {}'.format( + expected_cmd(fname), title)) + errors += 1 + return errors def main(): """Check that all DFHack scripts include documentation (not 3rdparty)""" - errors = 0 - for path in scriptdirs: - for f in os.listdir(path): - f = path + '/' + f - if os.path.isfile(f) and f[-3:] in {'.rb', 'lua'}: - errors += check_file(f) - return errors + err = 0 + for root, _, files in os.walk('scripts'): + for f in files: + # TODO: remove 3rdparty exemptions from checks + # Requires reading their CMakeLists to only apply to used scripts + if f[-3:] in {'.rb', 'lua'} and '3rdparty' not in root: + err += check_file(join(root, f)) + return err if __name__ == '__main__': diff --git a/travis/script-syntax.py b/travis/script-syntax.py index 984ff1755..0b977f59d 100644 --- a/travis/script-syntax.py +++ b/travis/script-syntax.py @@ -1,15 +1,12 @@ -import argparse, os, sys, subprocess +import argparse +import os +import subprocess +import sys -parser = argparse.ArgumentParser() -parser.add_argument('--path', default='.', help='Root directory') -parser.add_argument('--ext', help='Script extension', required=True) -parser.add_argument('--cmd', help='Command', required=True) -args = parser.parse_args() def main(): root_path = os.path.abspath(args.path) cmd = args.cmd.split(' ') - ext = '.' + args.ext if not os.path.exists(root_path): print('Nonexistent path: %s' % root_path) sys.exit(2) @@ -19,14 +16,24 @@ def main(): if '.git' in parts or 'depends' in parts: continue for filename in filenames: - if not filename.endswith(ext): + if not filename.endswith(args.ext): continue full_path = os.path.join(cur, filename) try: subprocess.check_output(cmd + [full_path]) except subprocess.CalledProcessError: err = True + except IOError: + # catch error if not in Travis and Lua/Ruby is not available + if os.environ.get('TRAVIS', False): + raise sys.exit(int(err)) + if __name__ == '__main__': + parser = argparse.ArgumentParser() + parser.add_argument('--path', default='.', help='Root directory') + parser.add_argument('--ext', help='Script extension', required=True) + parser.add_argument('--cmd', help='Command', required=True) + args = parser.parse_args() main() From 8aafcec0c8292fc27edeb40b000e4759ca7c2f16 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 11:56:42 +1100 Subject: [PATCH 04/18] Add unacknowledged contributors Mostly authors of scripts which have been added. --- docs/Authors.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/Authors.rst b/docs/Authors.rst index 5661e6132..05997b3d6 100644 --- a/docs/Authors.rst +++ b/docs/Authors.rst @@ -21,15 +21,18 @@ Caldfir caldfir Chris Dombroski cdombroski Clayton Hughes David Corbett dscorbett +Deon DoctorVanGogh DoctorVanGogh Donald Ruegsegger hashaash doomchild doomchild +enjia2000 Eric Wald eswald Erik Youngren Artanis Espen Wiborg expwnent expwnent Feng Harlan Playford playfordh +IndigoFenix James Logsdon jlogsdon Japa JapaMala Jared Adams @@ -40,11 +43,14 @@ Jonas Ask kane-t kane-t Kelly Martin ab9rf Kris Parker kaypy +Kurik Amudnil Lethosor lethosor Mason11987 Mason11987 Matthew Cline Max maxthyme Max^TM melkor217 melkor217 +Meneth32 +Meph Michon van Dooren MaienM miffedmap miffedmap Mike Stewart thewonderidiot @@ -53,6 +59,7 @@ MithrilTuxedo MithrilTuxedo mizipzor mizipzor Neil Little nmlittle Nick Rart nickrart comestible +Omniclasm PeridexisErrant PeridexisErrant Petr Mrázek peterix potato @@ -64,6 +71,7 @@ rampaging-poet Raoul van Putten Raoul XQ raoulxq reverb +Raidau Raidau Rinin Rinin Robert Heinrich rh73 rofl0r rofl0r @@ -78,6 +86,7 @@ scamtank scamtank Seth Woodworth sethwoodworth simon Simon Jackson sizeak +Tacomagic Tim Walberg twalberg Timothy Collett danaris Tom Prince From 4fbf9ce233f26f94dbd9ca4e09062b1441d36eeb Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 13:01:06 +1100 Subject: [PATCH 05/18] Clarify LICENSE.rst, deduplicate, add links A simple list of components with the full text each time is not particularly useful, or required. The table lists components in alphabetical order (except DFhack, first), with license and copyright. Component names are hyperlinked to the source project, which was not the case previously. Licenses which are required to be included are, but once only - an improvement over four zlib, 3 BSD and five (!) MIT blocks. This and the table satisfies the requirements while remaining readable. --- LICENSE.rst | 380 +++++++++++----------------------------------------- 1 file changed, 78 insertions(+), 302 deletions(-) diff --git a/LICENSE.rst b/LICENSE.rst index 490b07a6e..782c77bf5 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -4,14 +4,53 @@ Licenses ######## -DFHack is distributed under a range of permissive and weakly copyleft licenses. - -The core uses the ZLib license; the others are described below. - -License of DFHack -================= -https://github.com/peterix/dfhack -Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com) +DFHack is distributed under the Zlib license, with some MIT- +and BSD-licensed components. These licenses protect your right +to use DFhack for any purpose, distribute copies, and so on. + +The core, plugins, scripts, and other DFHack code all use the +ZLib license unless noted otherwise. By contributing to DFHack, +authors release the contributed work under this license. + +DFHack also draws on several external packages. +Their licenses are summarised here and reproduced below. + +=============== ============= ================================================= +Component License Copyright +=============== ============= ================================================= +DFHack_ Zlib (c) 2009-2012, Petr Mrázek +clsocket_ BSD 3-clause (c) 2007-2009, CarrierLabs, LLC. +dirent_ MIT (c) 2006, Toni Ronkko +JSON.lua_ CC-BY-SA_ (c) 2010-2014, Jeffrey Friedl +jsoncpp_ MIT (c) 2007-2010, Baptiste Lepilleur +linenoise_ BSD 2-clause (c) 2010, Salvatore Sanfilippo & Pieter Noordhuis +lua_ MIT (c) 1994-2008, Lua.org, PUC-Rio. +luafilesystem_ MIT (c) 2003-2014, Kepler Project +protobuf_ BSD 3-clause (c) 2008, Google Inc. +tinythread_ Zlib (c) 2010, Marcus Geelnard +tinyxml_ Zlib (c) 2000-2006, Lee Thomason +UTF-8-decoder_ MIT (c) 2008-2010, Bjoern Hoehrmann +=============== ============= ================================================= + +.. _DFHack: https://github.com/DFHack/dfhack +.. _clsocket: https://github.com/DFHack/clsocket +.. _dirent: https://github.com/tronkko/dirent +.. _JSON.lua: http://regex.info/blog/lua/json +.. _jsoncpp: https://github.com/open-source-parsers/jsoncpp +.. _linenoise: http://github.com/antirez/linenoise +.. _lua: http://www.lua.org +.. _luafilesystem: https://github.com/keplerproject/luafilesystem +.. _protobuf: https://github.com/google/protobuf +.. _tinythread: http://tinythreadpp.bitsnbites.eu/ +.. _tinyxml: http://www.sourceforge.net/projects/tinyxml +.. _UTF-8-decoder: http://bjoern.hoehrmann.de/utf-8/decoder/dfa + +.. _CC-BY-SA: http://creativecommons.org/licenses/by/3.0/deed.en_US + + +Zlib License +============ +See https://en.wikipedia.org/wiki/Zlib_License :: This software is provided 'as-is', without any express or implied @@ -23,206 +62,21 @@ Copyright (c) 2009-2012 Petr Mrázek (peterix@gmail.com) redistribute it freely, subject to the following restrictions: 1. The origin of this software must not be misrepresented; you must - not claim that you wrote the original software. If you use this - software in a product, an acknowledgment in the product documentation - would be appreciated but is not required. + not claim that you wrote the original software. If you use this + software in a product, an acknowledgment in the product + documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and - must not be misrepresented as being the original software. + must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source - distribution. - -clsocket license -================ -:: - - Copyright (c) 2007-2009 CarrierLabs, LLC. All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the distribution. - 3. The name of the author may not be used to endorse or promote products - derived from this software without specific prior written permission. - - 4. The name "CarrierLabs" must not be used to - endorse or promote products derived from this software without - prior written permission. For written permission, please contact - mark@carrierlabs.com. - - THIS SOFTWARE IS PROVIDED BY MARK CARRIER ``AS IS'' AND ANY - EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR - PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL MARK CARRIER OR - ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT - NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, - STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED - OF THE POSSIBILITY OF SUCH DAMAGE. - -Lua license +MIT License =========== - -Lua is licensed under the terms of the MIT license reproduced below. -This means that Lua is free software and can be used for both academic -and commercial purposes at absolutely no cost. - -For details and rationale, see http://www.lua.org/license.html . - -:: - - Copyright (C) 1994-2008 Lua.org, PUC-Rio. - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in - all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN - THE SOFTWARE. - -Protobuf license -================ -:: - - Copyright 2008, Google Inc. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are - met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following disclaimer - in the documentation and/or other materials provided with the - distribution. - * Neither the name of Google Inc. nor the names of its - contributors may be used to endorse or promote products derived from - this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - Code generated by the Protocol Buffer compiler is owned by the owner - of the input file used when generating it. This code is not - standalone and requires a support library to be linked with it. This - support library is itself covered by the above license. - - -License of tinyxml (XML reader library) -======================================= -http://www.sourceforge.net/projects/tinyxml - -Original code, 2.0 and earlier, copyright 2000-2006 Lee Thomason (http://www.grinninglizard.com) -:: - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any - damages arising from the use of this software. - - Permission is granted to anyone to use this software for any - purpose, including commercial applications, and to alter it and - redistribute it freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must - not claim that you wrote the original software. If you use this - software in a product, an acknowledgment in the product documentation - would be appreciated but is not required. - - 2. Altered source versions must be plainly marked as such, and - must not be misrepresented as being the original software. - - 3. This notice may not be removed or altered from any source - distribution. - -tinythread license -================== -:: - - Copyright (c) 2010 Marcus Geelnard - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - - 3. This notice may not be removed or altered from any source - distribution. - -zlib license -============ - -:: - - Copyright (C) 1995-2010 Jean-loup Gailly and Mark Adler - - This software is provided 'as-is', without any express or implied - warranty. In no event will the authors be held liable for any damages - arising from the use of this software. - - Permission is granted to anyone to use this software for any purpose, - including commercial applications, and to alter it and redistribute it - freely, subject to the following restrictions: - - 1. The origin of this software must not be misrepresented; you must not - claim that you wrote the original software. If you use this software - in a product, an acknowledgment in the product documentation would be - appreciated but is not required. - 2. Altered source versions must be plainly marked as such, and must not be - misrepresented as being the original software. - 3. This notice may not be removed or altered from any source distribution. - - -dirent.h - dirent API for Microsoft Visual Studio -================================================= +See https://en.wikipedia.org/wiki/MIT_License :: - Copyright (C) 2006 Toni Ronkko - Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including @@ -237,35 +91,27 @@ dirent.h - dirent API for Microsoft Visual Studio THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. - IN NO EVENT SHALL TONI RONKKO BE LIABLE FOR ANY CLAIM, DAMAGES OR - OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, - ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - OTHER DEALINGS IN THE SOFTWARE. - - -linenoise.c -=========== -Parts of dfhack are based on linenoise: a line editing library against the -idea that a line editing lib needs to be 20,000 lines of C code. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -You can find the latest source code at http://github.com/antirez/linenoise +BSD Licenses +============ +See https://en.wikipedia.org/wiki/BSD_licenses :: - Copyright (c) 2010, Salvatore Sanfilippo - Copyright (c) 2010, Pieter Noordhuis - - All rights reserved. - Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright + 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in the - documentation and/or other materials provided with the distribution. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT @@ -279,91 +125,21 @@ You can find the latest source code at http://github.com/antirez/linenoise (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +``linenoise`` adds no further clauses. -UTF-8 Decoder -============= -See http://bjoern.hoehrmann.de/utf-8/decoder/dfa/ for details. -:: - - Copyright (c) 2008-2010 Bjoern Hoehrmann - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all - copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, - WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - -luafilesystem -============= -Parts of dfhack are based on luafilesystem: -:: - - Copyright (c) 2003-2014 Kepler Project. - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, copy, - modify, merge, publish, distribute, sublicense, and/or sell copies - of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. - -jsoncpp -======== -:: - - Copyright (c) 2007-2010 Baptiste Lepilleur - - Permission is hereby granted, free of charge, to any person - obtaining a copy of this software and associated documentation - files (the "Software"), to deal in the Software without - restriction, including without limitation the rights to use, copy, - modify, merge, publish, distribute, sublicense, and/or sell copies - of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be - included in all copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS - BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN - CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE. +``protobuf`` adds the following clause:: + 3. Neither the name of Google Inc. nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. -JSON.lua -======== -Copyright 2010-2014 Jeffrey Friedl, http://regex.info/blog/ +``clsocket`` adds the following clauses:: -Latest version: http://regex.info/blog/lua/json + 3. The name of the author may not be used to endorse or promote + products derived from this software without specific prior + written permission. -This code is released under a Creative Commons CC-BY "Attribution" License: -http://creativecommons.org/licenses/by/3.0/deed.en_US + 4. The name "CarrierLabs" must not be used to endorse or promote + products derived from this software without prior written + permission. For written permission, please contact + mark@carrierlabs.com From 3d9ba5712195d91de870bdd56975deead3fa5f6f Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Thu, 5 Nov 2015 21:40:09 +1100 Subject: [PATCH 06/18] Tidy and update Compile.rst Eg removed workarounds for closed OSX bug, etc. --- docs/Compile.rst | 142 +++++++++++++++++++++-------------------------- 1 file changed, 64 insertions(+), 78 deletions(-) diff --git a/docs/Compile.rst b/docs/Compile.rst index a55c2d44d..4a72f0dc4 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -2,14 +2,15 @@ Compiling DFHack ################ -.. important:: - You don't need to compile DFHack unless you're developing plugins or working on the core. - For users, modders, and authors of scripts it's better to download the latest release instead. +You don't need to compile DFHack unless you're developing plugins or working on the core. + +For users, modders, and authors of scripts it's better to download +and `install the latest release instead `. .. contents:: - :depth: 2 + :depth: 2 + -=================== How to get the code =================== DFHack doesn't have any kind of system of code snapshots in place, so you will have to @@ -33,22 +34,16 @@ To get the code:: If your version of git does not support the ``--recursive`` flag, you will need to omit it and run ``git submodule update --init`` after entering the dfhack directory. -If you just want to compile DFHack or work on it by contributing patches, it's quite -enough to clone from the read-only address instead:: - - git clone --recursive git://github.com/DFHack/dfhack.git - cd dfhack - If you want to get really involved with the development, create an account on Github, make a clone there and then use that as your remote repository instead. Detailed instructions are beyond the scope of this document. If you need help, join us on IRC (#dfhack channel on freenode). -=========== + Build types =========== -``cmake`` allows you to pick a build type by changing this -variable: ``CMAKE_BUILD_TYPE`` :: +``cmake`` allows you to pick a build type by changing the +``CMAKE_BUILD_TYPE`` environment variable:: cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE @@ -58,19 +53,19 @@ Without specifying a build type or 'None', cmake uses the Valid and useful build types include 'Release', 'Debug' and 'RelWithDebInfo'. 'Debug' is not available on Windows. -===== + Linux ===== On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD. Dependencies -============ +------------ DFHack is meant to be installed into an existing DF folder, so get one ready. For building, you need a 32-bit version of GCC. For example, to build DFHack on a 64-bit distribution like Arch, you'll need the multilib development tools and libraries. Alternatively, you might be able to use ``lxc`` to -`create a virtual 32-bit environment `_. +:forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. Before you can build anything, you'll also need ``cmake``. It is advisable to also get ``ccmake`` on distributions that split the cmake package into multiple parts. @@ -81,11 +76,13 @@ You should be able to find them in your distro repositories (on Arch linux To build Stonesense, you'll also need OpenGL headers. -Some additional dependencies for other distros are listed on the -`wiki `_. +On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. +On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. +Debian-derived distros should have similar requirements. + Build -===== +----- Building is fairly straightforward. Enter the ``build`` folder (or create an empty folder in the DFHack directory to use instead) and start the build like this:: @@ -108,9 +105,9 @@ extra options. You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui program. -Fixing the libstdc++ version bug -================================ +The libstdc++ version bug +~~~~~~~~~~~~~~~~~~~~~~~~~ When compiling dfhack yourself, it builds against your system libc. When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which comes from GCC 4.5 and is incompatible with code compiled with newer GCC versions. @@ -127,66 +124,69 @@ to your system lib and everything will work fine:: Alternatively, this issue can be avoided by compiling DFHack with GCC 4.5. -======== + Mac OS X ======== - DFHack functions similarly on OS X and Linux, and the majority of the information above regarding the build process (cmake and make) applies here as well. -* If you are building on 10.6, please read the subsection below titled "Snow Leopard Changes" FIRST. -* If you are building on 10.10+, read the "Yosemite Changes" subsection before building. +If you have issues building on OS X Yosemite (or above), try definining the +following environment variable:: -1. Download and unpack a copy of the latest DF -2. Install Xcode from Mac App Store -3. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools. -4. Install dependencies + export MACOSX_DEPLOYMENT_TARGET=10.9 + +#. Download and unpack a copy of the latest DF +#. Install Xcode from Mac App Store +#. Open Xcode, go to Preferences > Downloads, and install the Command Line Tools. +#. Install dependencies - Option 1: Using Homebrew: + Using `Homebrew `_:: - * `Install Homebrew `_ and run: - * ``brew tap homebrew/versions`` - * ``brew install git`` - * ``brew install cmake`` - * ``brew install gcc45`` + brew tap homebrew/versions + brew install git + brew install cmake + brew install gcc45 - Option 2: Using MacPorts: + Using `MacPorts `_:: - * `Install MacPorts `_ - * Run ``sudo port install gcc45 +universal cmake +universal git-core +universal`` - This will take some time—maybe hours, depending on your machine. + sudo port install gcc45 +universal cmake +universal git-core +universal - At some point during this process, it may ask you to install a Java environment; let it do so. + Macports will take some time - maybe hours. At some point it may ask + you to install a Java environment; let it do so. -5. Install perl dependencies +#. Install perl dependencies 1. ``sudo cpan`` If this is the first time you've run cpan, you will need to go through the setup process. Just stick with the defaults for everything and you'll be fine. + If you are running Snow Leopard or later, open a separate Terminal window and run:: + + sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml + 2. ``install XML::LibXML`` 3. ``install XML::LibXSLT`` -6. Get the dfhack source:: +#. Get the dfhack source:: git clone --recursive https://github.com/DFHack/dfhack.git cd dfhack -7. Set environment variables: +#. Set environment variables: - Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``):: + Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``):: export CC=/usr/local/bin/gcc-4.5 export CXX=/usr/local/bin/g++-4.5 - Macports:: + Macports:: export CC=/opt/local/bin/gcc-mp-4.5 export CXX=/opt/local/bin/g++-mp-4.5 -8. Build dfhack:: +#. Build dfhack:: mkdir build-osx cd build-osx @@ -195,34 +195,14 @@ as well. make install -Snow Leopard Changes -==================== - -1. Add a step 6.2a (before Install XML::LibXSLT):: - In a separate Terminal window or tab, run: - ``sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml`` - -2. Add a step 7a (before building):: - In /library/LuaTypes.cpp, change line 467 to - ``int len = strlen((char*)ptr);`` - -Yosemite Changes -================ - -If you have issues building on OS X Yosemite (or above), try definining the -following environment variable:: - - export MACOSX_DEPLOYMENT_TARGET=10.9 - -======= Windows ======= On Windows, DFHack replaces the SDL library distributed with DF. Dependencies -============ -First, you need ``cmake``. Get the win32 installer version from the official -site: http://www.cmake.org/cmake/resources/software.html +------------ +First, you need ``cmake``. Get the win32 installer version from +`the official site `_. It has the usual installer wizard. Make sure you let it add its binary folder to your binary search PATH so the tool can be later run from anywhere. @@ -241,24 +221,30 @@ install libxml and libxslt for it instead. Strawberry perl works though and has all the required packages. Build -===== -There are several different batch files in the ``build`` folder along with a script that's used for picking the DF path. +----- +There are several different batch files in the ``build`` folder along +with a script that's used for picking the DF path. -First, run set_df_path.vbs and point the dialog that pops up at your DF folder that you want to use for development. +First, run set_df_path.vbs and point the dialog that pops up at your +DF folder that you want to use for development. Next, run one of the scripts with ``generate`` prefix. These create the MSVC solution file(s): * ``all`` will create a solution with everything enabled (and the kitchen sink). -* ``gui`` will pop up the cmake gui and let you pick and choose what to build. This is probably what you want most of the time. Set the options you are interested in, then hit configure, then generate. More options can appear after the configure step. -* ``minimal`` will create a minimal solution with just the bare necessities - the main library and standard plugins. +* ``gui`` will pop up the cmake gui and let you pick and choose what to build. + This is probably what you want most of the time. Set the options you are interested + in, then hit configure, then generate. More options can appear after the configure step. +* ``minimal`` will create a minimal solution with just the bare necessities - + the main library and standard plugins. Then you can either open the solution with MSVC or use one of the msbuild scripts: -* Scripts with ``build`` prefix will only build. +* Scripts with ``build`` prefix will only build DFHack. * Scripts with ``install`` prefix will build DFHack and install it to the previously selected DF path. * Scripts with ``package`` prefix will build and create a .zip package of DFHack. When you open the solution in MSVC, make sure you never use the Debug builds. Those aren't binary-compatible with DF. If you try to use a debug build with DF, you'll only get crashes. -So pick either Release or RelWithDebInfo build and build the INSTALL target. -The ``debug`` scripts actually do RelWithDebInfo builds. +For this reason the Windows "debug" scripts actually do RelWithDebInfo builds, +so pick either Release or RelWithDebInfo build and build the INSTALL target. + From 0ba6f73dcd5944dd7f9d80252b9e2a4d4a01466c Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 00:58:18 +1100 Subject: [PATCH 07/18] Add Introduction.rst, list builtins in Core.rst The Introduction is the first page to read, and thus explains what DFHack is, installation, basic use, and troubleshooting. This frees up Core.rst for a detailed list of builtin commands (meant to be complete, but I might have missed some), some other key commands, and a discussion of init files. I also put the random notes that don't fit anywhere at the bottom of this file. --- docs/Core.rst | 529 ++++++++++++++++++++++++------------------ docs/Introduction.rst | 107 +++++++++ 2 files changed, 414 insertions(+), 222 deletions(-) create mode 100644 docs/Introduction.rst diff --git a/docs/Core.rst b/docs/Core.rst index 2ad51db70..fda08b676 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -1,152 +1,197 @@ +.. _dfhack-core: + ########### DFHack Core ########### +DFHack commands can be implemented in three ways, all of which +are used in the same way: + +:builtin: commands are implemented by the core of DFHack, and quite rare. + +:plugins: are stored in ``hack/plugins/`` and must be compiled with the + same version of DFHack. They are less flexible than scripts, + but used for complex or ongoing tasks becasue they run faster. + +:scripts: are Ruby or Lua scripts stored in ``hack/scripts/``. + Because they don't need to be compiled, scripts are + more flexible about versions, and easier to distribute. + Most third-party DFHack addons are scripts. + + .. contents:: -============== -Getting DFHack -============== -The project is currently hosted at http://www.github.com/ +Built-in Commands +================= +The following commands are provided by the 'core' components +of DFhack, rather than plugins or scripts. + + +.. _cls: + +cls +--- +Clear the terminal. Does not delete command history. + + +.. _die: + +die +--- +Instantly kills DF without saving. + + +.. _disable: + +.. _enable: + +enable +------ +Many plugins can be in a distinct enabled or disabled state. Some of +them activate and deactivate automatically depending on the contents +of the world raws. Others store their state in world data. However a +number of them have to be enabled globally, and the init file is the +right place to do it. + +Most such plugins or scripts support the built-in ``enable`` and ``disable`` +commands. Calling them at any time without arguments prints a list +of enabled and disabled plugins, and shows whether that can be changed +through the same commands. -Recent releases are available in source and binary formats `on the releases -page`_, while the binaries for releases 0.40.15-r1 to 0.34.11-r4 are on DFFD_. -Even older versions are available here_. +To enable or disable plugins that support this, use their names as +arguments for the command:: -.. _`on the releases page`: http://github.com/DFHack/dfhack/releases -.. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15 -.. _here: http://dethware.org/dfhack/download + enable manipulator search -All new releases are announced in `the bay12 forums thread`_, which is also a -good place for discussion and questions. -.. _`the Bay12 DFHack thread`: -.. _`the bay12 forums thread`: http://www.bay12forums.com/smf/index.php?topic=139553 +.. _fpause: -If this sounds too complicated, you might prefer to `get a Starter Pack`_. -These are packages for new players or those who don't want to set up everything -themselves, and are available - with DFHack configured - for all OSes. +fpause +------ +Forces DF to pause. This is useful when your FPS drops below 1 and you lose +control of the game. -.. _`get a Starter Pack`: http://dwarffortresswiki.org/index.php/Utility:Lazy_Newb_Pack -Compatibility -============= -DFHack is available for Windows (XP or later), Linux (any modern distribution), -or OS X (10.6.8 to 10.9). +.. _help: -Most releases only support the version of DF mentioned in their title - for -example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases -support earlier DF versions as well. Wherever possible, use the latest version -built for the target version of DF. +help +---- +Most commands support using the ``help `` built-in command +to retrieve further help without having to look at this document. +``? `` and ``man `` are aliases. -On Windows, DFHack is compatible with the SDL version of DF, but not the legacy version. +Some commands (including many scripts) instead take ``help`` or ``?`` +as an option on their command line - ie `` help``. -It is also possible to use the Windows DFHack with Wine under Linux and OS X. -Installation/Removal -==================== -Installing DFhack involves copying files into your DF folder. -Copy the files from a release archive so that: +.. _hide: -* On Windows, ``SDL.dll`` is replaced -* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script +hide +---- +Hides the DFHack terminal window. Only available on Windows. -Uninstalling is basically the same, in reverse: -* On Windows, first delete ``SDL.dll`` and rename ``SDLreal.dll`` to ``SDL.dll``, - then remove the other DFHack files -* On Linux, remove the DFHack files. +.. _keybinding: -The stonesense plugin might require some additional libraries on Linux. +keybinding +---------- +To set keybindings, use the built-in ``keybinding`` command. Like any other +command it can be used at any time from the console, but bindings are not +remembered between runs of the game unless re-created in `dfhack.init`. -If any of the plugins or dfhack itself refuses to load, check the ``stderr.log`` -file created in your DF folder. +Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported. +Possible ways to call the command: -=============== -Getting started -=============== -If DFHack is installed correctly, it will automatically pop up a console -window once DF is started as usual on windows. Linux and Mac OS X require -running the dfhack script from the terminal, and will use that terminal for -the console. +``keybinding list `` + List bindings active for the key combination. +``keybinding clear ...`` + Remove bindings for the specified keys. +``keybinding add "cmdline" "cmdline"...`` + Add bindings for the specified key. +``keybinding set "cmdline" "cmdline"...`` + Clear, and then add bindings for the specified key. -**NOTE**: The ``dfhack-run`` executable is there for calling DFHack commands in -an already running DF+DFHack instance from external OS scripts and programs, -and is *not* the way how you use DFHack normally. +The ```` parameter above has the following *case-sensitive* syntax:: -DFHack has a lot of features, which can be accessed by typing commands in the -console, or by mapping them to keyboard shortcuts. Most of the newer and more -user-friendly tools are designed to be at least partially used via the latter -way. + [Ctrl-][Alt-][Shift-]KEY[@context[|context...]] -In order to set keybindings, you have to create a text configuration file -called ``dfhack.init``; the installation comes with an example version called -``dfhack.init-example``, which is fully functional, covers all of the recent -features and can be simply renamed to ``dfhack.init``. You are encouraged to look -through it to learn which features it makes available under which key combinations. +where the *KEY* part can be any recognized key and [] denote optional parts. -Using DFHack -============ -DFHack basically extends what DF can do with something similar to the drop-down -console found in Quake engine games. On Windows, this is a separate command line -window. On Linux, the terminal used to launch the dfhack script is taken over -(so, make sure you start from a terminal). Basic interaction with dfhack -involves entering commands into the console. For some basic instructions, -use the ``help`` command. To list all possible commands, use the ``ls`` command. -Many commands have their own help or detailed description. You can use -``command help`` or ``command ?`` to show that. +When multiple commands are bound to the same key combination, DFHack selects +the first applicable one. Later ``add`` commands, and earlier entries within one +``add`` command have priority. Commands that are not specifically intended for use +as a hotkey are always considered applicable. -The command line has some nice line editing capabilities, including history -that's preserved between different runs of DF (use up/down keys to go through -the history). +The ``context`` part in the key specifier above can be used to explicitly restrict +the UI state where the binding would be applicable. If called without parameters, +the ``keybinding`` command among other things prints the current context string. -The second way to interact with DFHack is to bind the available commands -to in-game hotkeys. The old way to do this is via the hotkey/zoom menu (normally -opened with the ``h`` key). Binding the commands is done by assigning a command as -a hotkey name (with ``n``). +Only bindings with a ``context`` tag that either matches the current context fully, +or is a prefix ending at a ``/`` boundary would be considered for execution, i.e. +when in context ``foo/bar/baz``, keybindings restricted to any of ``@foo/bar/baz``, +``@foo/bar``, ``@foo`` or none will be active. -A new and more flexible way is the keybinding command in the dfhack console. -However, bindings created this way are not automatically remembered between runs -of the game, so it becomes necessary to use the dfhack.init file to ensure that -they are re-created every time it is loaded. +Multiple contexts can be specified by separating them with a +pipe (``|``) - for example, ``@foo|bar|baz/foo`` would match +anything under ``@foo``, ``@bar``, or ``@baz/foo``. Interactive commands like `liquids` cannot be used as hotkeys. -Many commands come from plugins, which are stored in ``hack/plugins/`` -and must be compiled with the same version of DFHack. Others come -from scripts, which are stored in ``hack/scripts``. Scripts are much -more flexible about versions, and easier to distribute - so most third-party -DFHack addons are scripts. -Something doesn't work, help! -============================= -First, don't panic :) +.. _kill-lua: -Second, dfhack keeps a few log files in DF's folder (``stderr.log`` and -``stdout.log``). Looking at these might help you solve the problem. -If it doesn't, you can ask for help in the forum thread or on IRC. +kill-lua +-------- +Stops any currently-running Lua scripts. By default, scripts can +only be interrupted every 256 instructions. Use ``kill-lua force`` +to interrupt the next instruction. -If you found a bug, you can report it in `the Bay12 DFHack thread`_, -`the issues tracker on github `_, -or visit `the #dfhack IRC channel on freenode -`_. -============= -Core Commands -============= -DFHack command syntax consists of a command name, followed by arguments separated -by whitespace. To include whitespace in an argument, quote it in double quotes. -To include a double quote character, use ``\"`` inside double quotes. +.. _load: +.. _unload: +.. _reload: -If the first non-whitespace character of a line is ``#``, the line is treated -as a comment, i.e. a silent no-op command. +load +---- +``load``, ``unload``, and ``reload`` control whether a plugin is loaded +into memory - note that plugins are loaded but disabled unless you do +something. Usage:: -When reading commands from dfhack.init or with the ``script`` command, if the final -character on a line is a backslash then the next uncommented line is considered a -continuation of that line, with the backslash deleted. Commented lines are skipped, -so it is possible to comment out parts of a command with the ``#`` character. + load|unload|reload PLUGIN|all + +Allows dealing with plugins individually by name, or all at once. + + +.. _ls: + +ls +-- +``ls`` does not list files like the Unix command, but rather +available commands - first built in commands, then plugins, +and scripts at the end. Usage: + +:ls -a: Also list scripts in subdirectories of ``hack/scripts/``, + which are generally not intended for direct use. +:ls : List subcommands for the given plugin. + + +.. _plug: + +plug +---- +Lists available plugins (*not* commands implemented by plugins). + +``plug [PLUGIN|v]`` - list plugin state and detailed description. + + +.. _rb_eval: + +rb_eval +------- +Evaluate the following arguments as a ruby string. Best used as +``:rb_eval [string]``, for the special parsing mode: If the first non-whitespace character is ``:``, the command is parsed in a special alternative mode: first, non-whitespace characters immediately following the ``:`` @@ -157,160 +202,200 @@ The following two command lines are exactly equivalent:: :foo a b "c d" e f foo "a b \"c d\" e f" -This is intended for commands like ``rb_eval`` that evaluate script language statements. -Almost all the commands support using the ``help `` built-in command -to retrieve further help without having to look at this document. Alternatively, -some accept a ``help`` or ``?`` as an option on their command line. +.. _sc-script: -.. note:: +sc-script +--------- +Allows additional scripts to be run when certain events occur +(similar to onLoad*.init scripts) - Some tools work by displaying dialogs or overlays in the game window. - In order to avoid confusion, these tools display the word "DFHack" while active. If they - merely add keybinding hints to existing screens, they use red instead of green for the key. +.. _script: +script +------ +Reads a text file, and runs each line as a DFHack command +as if it had been typed in by the user - treating the +input like `an init file `. -Init files -========== -DFHack allows users to automatically run commonly-used DFHack commands when DF is first -loaded, when a game is loaded, and when a game is unloaded. +Some other tools, such as `autobutcher` and `workflow`, export +their settings as the commands to create them - which are later +loaded with ``script`` -Init scripts function the same way they would if the user manually typed in their contents, -but are much more convenient. If your DF folder contains at least one file with a name -following the format ``dfhack*.init`` where ``*`` is a placeholder for any string (including -the empty string), then all such files are executed in alphabetical order as init scripts when -DF is first loaded. -If your DF folder does not contain any such files, then DFHack will execute ``dfhack.init-example`` -as an example of useful commands to be run automatically. If you want DFHack to do nothing on -its own, then create an empty ``dfhack.init`` file in the main DF directory, or delete ``dfhack.init-example``. +.. _show: -The file ``dfhack.init-example`` is included as an example for users to follow if they need DFHack -command executed automatically. We recommend modifying or deleting ``dfhack.init-example`` as -its settings will not be optimal for all players. +show +---- +Shows the terminal window after it has been `hidden `. +Only available on Windows. You'll need to use it from a +`keybinding` set beforehand, or the in-game `command-prompt`. -In order to facilitate savegave portability, mod merging, and general organization of init files, -DFHack supports multiple init files both in the main DF directory and save-specific init files in -the save folders. -DFHack looks for init files in three places. -It will look for them in the main DF directory, and in ``data/save/_____/raw`` and -``data/save/_____/raw/objects`` where ``_____`` is the name of the current savegame. +.. important-commands: -When a game is loaded, DFHack looks for files of the form ``onLoad*.init``, where -``*`` can be any string, including the empty string. +Other Important Commands +======================== -When a game is unloaded, DFHack looks for files of the form ``onUnload*.init``. Again, -these files may be in any of the above three places. All matching init files will be -executed in alphebetical order. +.. _command-prompt: -Setting keybindings -=================== -To set keybindings, use the built-in ``keybinding`` command. Like any other -command it can be used at any time from the console, but it is most useful -in the DFHack init file. +command-prompt +-------------- +An in-game DFHack terminal, where you can enter other commands. +Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. -Currently, any combinations of Ctrl/Alt/Shift with A-Z, 0-9, or F1-F12 are supported. +Usage: ``command-prompt [entry]`` -Possible ways to call the command: +If called with an entry, it starts with that text filled in. +Most useful for developers, who can set a keybinding to open +a laungage interpreter for lua or Ruby by starting with the +`:lua ` or `:rb_eval ` commands. -``keybinding list `` - List bindings active for the key combination. -``keybinding clear ...`` - Remove bindings for the specified keys. -``keybinding add "cmdline" "cmdline"...`` - Add bindings for the specified key. -``keybinding set "cmdline" "cmdline"...`` - Clear, and then add bindings for the specified key. +Otherwise somewhat similar to `gui/quickcmd`. -The ```` parameter above has the following *case-sensitive* syntax:: +.. image:: images/command-prompt.png - [Ctrl-][Alt-][Shift-]KEY[@context[|context...]] -where the *KEY* part can be any recognized key and [] denote optional parts. +.. _hotkeys: -When multiple commands are bound to the same key combination, DFHack selects -the first applicable one. Later ``add`` commands, and earlier entries within one -``add`` command have priority. Commands that are not specifically intended for use -as a hotkey are always considered applicable. +hotkeys +------- +Opens an in-game screen showing which DFHack keybindings are +active in the current context. -The ``context`` part in the key specifier above can be used to explicitly restrict -the UI state where the binding would be applicable. If called without parameters, -the ``keybinding`` command among other things prints the current context string. -Only bindings with a ``context`` tag that either matches the current context fully, -or is a prefix ending at a ``/`` boundary would be considered for execution, i.e. -for context ``foo/bar/baz``, possible matches are any of ``@foo/bar/baz``, ``@foo/bar``, -``@foo`` or none. Multiple contexts can be specified by separating them with a -pipe (``|``) - for example, ``@foo|bar|baz/foo``. +.. image:: images/hotkeys.png -Hotkeys -======= -Opens an in-game screen showing DFHack keybindings that are active in the current context. +Type ``hotkeys`` into the DFHack console to open the screen, +or bind the command to a globally active hotkey. The default +keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. -.. image:: images/hotkeys.png +lua +--- +The `lua` script provides an interactive interpreter, allows +loading and saving of lua files, or runs a single line of code. -Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a -globally active hotkey. The default keybinding is ``Ctrl-F1``. +multicmd +-------- +The `multicmd` script calls many commands in one line. -.. _command-prompt: +.. _nopause: -In-game command prompt -====================== -The ``command-prompt`` plugin adds an in-game DFHack terminal, where you -can enter other commands. It's default keybinding is Ctrl-Shift-P. +nopause +------- +Disables pausing (both manual and automatic) with the exception of pause forced +by `reveal` ``hell``. This is nice for digging under rivers. -A one line command prompt in df. Same as entering command into dfhack console. Best -used as a keybinding. Can be called with optional "entry" that will start prompt with -that pre-filled. +quicksave +--------- +The `quicksave` script saves the game immediately without exiting. -.. image:: images/command-prompt.png +repeat +------ +The `repeat` script sets a command to be called regularly. -Enabling plugins -================ -Many plugins can be in a distinct enabled or disabled state. Some of -them activate and deactivate automatically depending on the contents -of the world raws. Others store their state in world data. However a -number of them have to be enabled globally, and the init file is the -right place to do it. -Most such plugins or scripts support the built-in ``enable`` and ``disable`` -commands. Calling them at any time without arguments prints a list -of enabled and disabled plugins, and shows whether that can be changed -through the same commands. +.. _init-files: -To enable or disable plugins that support this, use their names as -arguments for the command:: +Init Files +========== +DFHack allows users to automatically run commonly-used DFHack commands +when DF is first loaded, when a game is loaded, and when a game is unloaded. - enable manipulator search +Init scripts function the same way they would if the user manually typed +in their contents, but are much more convenient. In order to facilitate +savegave portability, mod merging, and general organization of init files, +DFHack supports multiple init files both in the main DF directory and +save-specific init files in the save folders. +DFHack looks for init files in three places each time they could be run: -Game progress -============= +#. The main DF directory +#. :file:`data/save/{world}/raw`, where ``world`` is the current save, and +#. :file:`data/save/{world}/raw/objects` -die ---- -Instantly kills DF without saving. +When reading commands from dfhack.init or with the `script` command, if the final +character on a line is a backslash then the next uncommented line is considered a +continuation of that line, with the backslash deleted. Commented lines are skipped, +so it is possible to comment out parts of a command with the ``#`` character. -quicksave ---------- -Save immediately, without exiting. Only available in fortress mode. -forcepause ----------- -Forces DF to pause. This is useful when your FPS drops below 1 and you lose -control of the game. Activate with ``forcepause 1``; deactivate with ``forcepause 0``. +.. _dfhack.init: -.. _`hide, show`: +dfhack*.init +------------ +If your DF folder contains at least one file named ``dfhack*.init`` +(where ``*`` is a placeholder for any string), then all such files +are executed in alphabetical order when DF is first started. -hide / show ------------ -Hides or shows the DFHack terminal window, respectively. To use ``show``, use -the in-game console (default keybinding ``Ctrl-Shift-P``). Only available on Windows. +DFHack is distributed with :download:`/dfhack.init-example` as an example +with an up-to-date collection of basic commands; mostly setting standard +keybindings and `enabling ` plugins. You are encouraged to look +through this file to learn which features it makes available under which +key combinations. You may also customise it and rename it to ``dfhack.init``. -nopause -------- -Disables pausing (both manual and automatic) with the exception of pause forced -by 'reveal hell'. This is nice for digging under rivers. +If your DF folder does not contain any ``dfhack*.init`` files, the example +will be run as a fallback. + +These files are best used for keybindings and enabling persistent plugins +which do not require a world to be loaded. + + +.. _onLoad.init: + +onLoad*.init +------------ +When a world is loaded, DFHack looks for files of the form ``onLoad*.init``, +where ``*`` can be any string, including the empty string. + +All matching init files will be executed in alphebetical order. +A world being loaded can mean a fortress, an adventurer, or legends mode. + +These files are best used for non-persistent commands, such as setting +a `fix ` script to run on `repeat`. + + +.. _onUnload.init: + +onUnload*.init +-------------- +When a world is unloaded, DFHack looks for files of the form ``onUnload*.init``. +Again, these files may be in any of the above three places. +All matching init files will be executed in alphebetical order. + +Modders often use such scripts to disable tools which should not affect +an unmodded save. + + +Other init files +---------------- +* Any lua script named ``raw/init.d/*.lua``, in the save or main DF + directory, will be run when any world or that save is loaded. + + +Miscellaneous Notes +=================== +This section is for odd but important notes that don't fit anywhere else. + +* The ``dfhack-run`` executable is there for calling DFHack commands in + an already running DF+DFHack instance from external OS scripts and programs, + and is *not* the way how you use DFHack normally. + +* If a DF hotkey (:kbd:`H`) is named with a DFHack command, pressing + the corresponding :kbd:`Fx` button will run that command, instead of + zooming to the set location. + +* The command line has some nice line editing capabilities, including history + that's preserved between different runs of DF (use up/down keys to go through + the history). + +* To include whitespace in the argument/s to some command, quote it in + double quotes. To include a double quote character, use ``\"``. + +* The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_. + Older versions are available here_. + + .. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000 + .. _here: http://dethware.org/dfhack/download diff --git a/docs/Introduction.rst b/docs/Introduction.rst new file mode 100644 index 000000000..f0fc0a0bf --- /dev/null +++ b/docs/Introduction.rst @@ -0,0 +1,107 @@ +.. _introduction: + +######################### +Introduction and Overview +######################### + +DFHack is a Dwarf Fortress memory access library, distributed with +a wide variety of useful scripts and plugins. + +The project is currently hosted at https://www.github.com/DFHack/dfhack, +and can be downloaded from `the releases page +`_. + +All new releases are announced in :forums:`the bay12 forums thread <139553>`, +which is also a good place for discussion and questions. + +For users, it provides a significant suite of bugfixes and interface +enhancements by default, and more can be enabled. There are also many tools +(such as `workflow` or `autodump`) which can make life easier. +You can even add third-party scripts and plugins to do almost anything! + +For modders, DFHack makes many things possible. Custom reactions, new +interactions, magic creature abilities, and more can be set through `modtools` +and custom raws. Non-standard DFHack scripts and inits can be stored in the +raw directory, making raws or saves fully self-contained for distribution - +or for coexistence in a single DF install, even with incompatible components. + +For developers, DFHack unites the various ways tools access DF memory and +allows easier development of new tools. As an open-source project under +`various copyleft licences `, contributions are welcome. + + +.. contents:: + + +.. _installing: + +Installing DFHack +================= +New players are encouraged to :wiki:`get a pack with DFHack preinstalled +`. + +DFHack is available for the SDL version of Dwarf Frtress on Windows, +any modern Linux distribution, and OS X (10.6.8 to 10.9). +It is possible to use Windows DF+DFHack under Wine on Linux or OS X. + +Most releases only support the version of DF mentioned in their title - for +example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases +support earlier DF versions as well. Wherever possible, use the latest version +of DFHack built for the target version of DF. + +Installing DFhack involves copying files from a release archive +into your DF folder, so that: + +* On Windows, ``SDL.dll`` is replaced +* On Linux or OSX, the ``dfhack`` script is placed in the same folder as the ``df`` script + +Uninstalling is basically the same, in reverse: + +* On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files. +* On Linux or OSX, remove the DFHack files. + + +Getting started +=============== +DFHack basically extends DF with something similar to the +console found in many PC games. + +If DFHack is installed correctly, it will automatically pop up a console +window once DF is started as usual on Windows. Linux and Mac OS X require +running the dfhack script from the terminal, and will use that terminal for +the console. + +* Basic interaction with dfhack involves entering commands into the console. + To learn what commands are available, you can keep reading this documentation + or skip ahead and use the `ls` and `help` commands. + +* Another way to interact with DFHack is to set in-game `keybindings ` + for certain commands. Many of the newer and user-friendly tools are designed + to be used this way. + +* Commands can also run at startup via `init files `, + on in batches at other times with the `script` command. + +* Finally, some commands are persistent once enabled, and will sit in the + background managing or changing some aspect of the game if you `enable` them. + + +.. _troubleshooting: + +Troubleshooting +=============== +Don't panic! Even if you need this section, it'll be OK :) + +If something goes wrong, check the log files in DF's folder +(``stderr.log`` and ``stdout.log``). Looking at these might help you - +or someone else - solve the problem. Take screenshots of any weird +error messages, and take notes on what you did to cause them. + +If the search function in this documentation isn't enough and +:wiki:`the DF Wiki <>` hasn't helped, try asking in: + +- the `#dfhack IRC channel on freenode `_ +- the :forums:`Bay12 DFHack thread <139553>` +- the `/r/dwarffortress `_ questions thread +- the thread for the mod or Starter Pack you're using (if any) + From 3cc0b34d73d280f1bdef2cb45a642e40adc858f5 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 00:59:48 +1100 Subject: [PATCH 08/18] Clean up other docs to match Some deduplication in Scripts and Plugins, links in NEWS, add content and link to files in index. --- NEWS.rst | 4 ++-- docs/Plugins.rst | 8 ++------ docs/Scripts.rst | 16 +++------------- index.rst | 13 +++++++++++-- 4 files changed, 18 insertions(+), 23 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index e966eda6a..53be4c149 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -197,8 +197,8 @@ Lua New Internal Commands --------------------- -- `hide, show`: hide and show the console on Windows -- sc-script: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts) +- `hide`, `show`: hide and show the console on Windows +- `sc-script`: Allows additional scripts to be run when certain events occur (similar to onLoad*.init scripts) New Plugins ----------- diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 842367283..192bbb36d 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -6,7 +6,8 @@ DFHack plugins are the commands, that are compiled with a specific version. They can provide anything from a small keybinding, to a complete overhaul of game subsystems or the entire renderer. -Most are listed here, hopefully organised in a way you will find useful. +Most commands offered by plugins are listed here, +hopefully organised in a way you will find useful. .. contents:: :depth: 4 @@ -351,11 +352,6 @@ UI Upgrades When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key. -.. _hotkeys: - -hotkeys -======= -Shows the DFHack keybindings active on the current screen. .. _manipulator: diff --git a/docs/Scripts.rst b/docs/Scripts.rst index 87eeaf666..0e6ef415c 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -2,20 +2,10 @@ DFHack Scripts ############## -Lua or ruby scripts placed in the ``hack/scripts/`` directory are considered for -execution as if they were native DFHack commands. They are listed at the end -of the ``ls`` command output. +Lua or ruby scripts placed in the :file:`hack/scripts/` directory +are considered for execution as if they were native DFHack commands. -Note: scripts in subdirectories of hack/scripts/ can still be called, but will -only be listed by ls if called as ``ls -a``. This is intended as a way to hide -scripts that are obscure, developer-oriented, or should be used as keybindings -or from the init file. See the page for each type for details. - -``kill-lua`` stops any currently-running Lua scripts. By default, scripts can -only be interrupted every 256 instructions. Use ``kill-lua force`` to interrupt -the next instruction. - -The following pages document all the standard DFHack scripts. +The following pages document all the scripts in the DFHack standard library. .. toctree:: :maxdepth: 2 diff --git a/index.rst b/index.rst index a93660db3..7f3e815a3 100644 --- a/index.rst +++ b/index.rst @@ -4,8 +4,15 @@ Welcome to DFHack's documentation! Introduction ============ -DFHack is a Dwarf Fortress memory access library, distributed with scripts -and plugins implementing a wide variety of useful functions and tools. +DFHack is a Dwarf Fortress memory access library, distributed with +a wide variety of useful scripts and plugins. + +The project is currently hosted at https://www.github.com/DFHack/dfhack, +and can be downloaded from `the releases page +`_. + +All new releases are announced in :forums:`the bay12 forums thread <139553>`, +which is also a good place for discussion and questions. For users, it provides a significant suite of bugfixes and interface enhancements by default, and more can be enabled. There are also many tools @@ -29,6 +36,7 @@ User Manual .. toctree:: :maxdepth: 2 + docs/Introduction docs/Core docs/Plugins docs/Scripts @@ -53,4 +61,5 @@ For Developers docs/Compile docs/Lua API library/xml/SYNTAX + library/xml/how-to-update docs/Binpatches From 18a921baef41f4addd205572a287c8029ed2da8b Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 11:44:43 +1100 Subject: [PATCH 09/18] Further clarify Core; move plugins out; other fixes - Fix formatting of (c) in license - Avoid possible issues with script linting - Move plugin docs out of Core.rst - Fix some builtin docs, tweak other bits --- .travis.yml | 4 +- LICENSE.rst | 24 +++++------ docs/Core.rst | 110 +++++++++++++---------------------------------- docs/Plugins.rst | 61 +++++++++++++++++++++++++- 4 files changed, 104 insertions(+), 95 deletions(-) diff --git a/.travis.yml b/.travis.yml index 1863835f1..058a95a18 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,8 +17,8 @@ script: - python travis/pr-check-base.py - python travis/lint.py - python travis/script-in-readme.py -- python travis/script-syntax.py --ext=lua --cmd="luac5.2 -p" -- python travis/script-syntax.py --ext=rb --cmd="ruby -c" +- python travis/script-syntax.py --ext=.lua --cmd="luac5.2 -p" +- python travis/script-syntax.py --ext=.rb --cmd="ruby -c" - mkdir build-travis - cd build-travis - cmake .. && make -j3 diff --git a/LICENSE.rst b/LICENSE.rst index 782c77bf5..e6a643e3d 100644 --- a/LICENSE.rst +++ b/LICENSE.rst @@ -18,18 +18,18 @@ Their licenses are summarised here and reproduced below. =============== ============= ================================================= Component License Copyright =============== ============= ================================================= -DFHack_ Zlib (c) 2009-2012, Petr Mrázek -clsocket_ BSD 3-clause (c) 2007-2009, CarrierLabs, LLC. -dirent_ MIT (c) 2006, Toni Ronkko -JSON.lua_ CC-BY-SA_ (c) 2010-2014, Jeffrey Friedl -jsoncpp_ MIT (c) 2007-2010, Baptiste Lepilleur -linenoise_ BSD 2-clause (c) 2010, Salvatore Sanfilippo & Pieter Noordhuis -lua_ MIT (c) 1994-2008, Lua.org, PUC-Rio. -luafilesystem_ MIT (c) 2003-2014, Kepler Project -protobuf_ BSD 3-clause (c) 2008, Google Inc. -tinythread_ Zlib (c) 2010, Marcus Geelnard -tinyxml_ Zlib (c) 2000-2006, Lee Thomason -UTF-8-decoder_ MIT (c) 2008-2010, Bjoern Hoehrmann +DFHack_ Zlib \(c\) 2009-2012, Petr Mrázek +clsocket_ BSD 3-clause \(c\) 2007-2009, CarrierLabs, LLC. +dirent_ MIT \(c\) 2006, Toni Ronkko +JSON.lua_ CC-BY-SA_ \(c\) 2010-2014, Jeffrey Friedl +jsoncpp_ MIT \(c\) 2007-2010, Baptiste Lepilleur +linenoise_ BSD 2-clause \(c\) 2010, Salvatore Sanfilippo & Pieter Noordhuis +lua_ MIT \(c\) 1994-2008, Lua.org, PUC-Rio. +luafilesystem_ MIT \(c\) 2003-2014, Kepler Project +protobuf_ BSD 3-clause \(c\) 2008, Google Inc. +tinythread_ Zlib \(c\) 2010, Marcus Geelnard +tinyxml_ Zlib \(c\) 2000-2006, Lee Thomason +UTF-8-decoder_ MIT \(c\) 2008-2010, Bjoern Hoehrmann =============== ============= ================================================= .. _DFHack: https://github.com/DFHack/dfhack diff --git a/docs/Core.rst b/docs/Core.rst index fda08b676..6ff1c8935 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -7,7 +7,9 @@ DFHack Core DFHack commands can be implemented in three ways, all of which are used in the same way: -:builtin: commands are implemented by the core of DFHack, and quite rare. +:builtin: commands are implemented by the core of DFHack. They manage + other DFhack tools, interpret commands, and control basic + aspects of DF (force pause or quit). :plugins: are stored in ``hack/plugins/`` and must be compiled with the same version of DFHack. They are less flexible than scripts, @@ -159,7 +161,7 @@ load into memory - note that plugins are loaded but disabled unless you do something. Usage:: - load|unload|reload PLUGIN|all + load|unload|reload PLUGIN|(-a|--all) Allows dealing with plugins individually by name, or all at once. @@ -181,26 +183,13 @@ and scripts at the end. Usage: plug ---- -Lists available plugins (*not* commands implemented by plugins). +Lists available plugins, including their state and detailed description. -``plug [PLUGIN|v]`` - list plugin state and detailed description. - - -.. _rb_eval: - -rb_eval -------- -Evaluate the following arguments as a ruby string. Best used as -``:rb_eval [string]``, for the special parsing mode: - -If the first non-whitespace character is ``:``, the command is parsed in a special -alternative mode: first, non-whitespace characters immediately following the ``:`` -are used as the command name; the remaining part of the line, starting with the first -non-whitespace character *after* the command name, is used verbatim as the first argument. -The following two command lines are exactly equivalent:: - - :foo a b "c d" e f - foo "a b \"c d\" e f" +``plug`` + Lists available plugins (*not* commands implemented by plugins) +``plug [PLUGIN] [PLUGIN] ...`` + List state and detailed description of the given plugins, + including commands implemented by the plugin. .. _sc-script: @@ -232,68 +221,24 @@ Shows the terminal window after it has been `hidden `. Only available on Windows. You'll need to use it from a `keybinding` set beforehand, or the in-game `command-prompt`. +.. _type: +type +---- +``type command`` shows where ``command`` is implemented. -.. important-commands: - -Other Important Commands -======================== - -.. _command-prompt: - -command-prompt +Other Commands -------------- -An in-game DFHack terminal, where you can enter other commands. -Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. - -Usage: ``command-prompt [entry]`` - -If called with an entry, it starts with that text filled in. -Most useful for developers, who can set a keybinding to open -a laungage interpreter for lua or Ruby by starting with the -`:lua ` or `:rb_eval ` commands. - -Otherwise somewhat similar to `gui/quickcmd`. - -.. image:: images/command-prompt.png - - -.. _hotkeys: +The following commands are *not* built-in, but offer similarly useful functions. -hotkeys -------- -Opens an in-game screen showing which DFHack keybindings are -active in the current context. - -.. image:: images/hotkeys.png - -Type ``hotkeys`` into the DFHack console to open the screen, -or bind the command to a globally active hotkey. The default -keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. - -lua ---- -The `lua` script provides an interactive interpreter, allows -loading and saving of lua files, or runs a single line of code. - -multicmd --------- -The `multicmd` script calls many commands in one line. - -.. _nopause: - -nopause -------- -Disables pausing (both manual and automatic) with the exception of pause forced -by `reveal` ``hell``. This is nice for digging under rivers. - -quicksave ---------- -The `quicksave` script saves the game immediately without exiting. - -repeat ------- -The `repeat` script sets a command to be called regularly. +* `command-prompt` +* `hotkeys` +* `lua` +* `multicmd` +* `nopause` +* `quicksave` +* `rb_eval` +* `repeat` .. _init-files: @@ -370,6 +315,11 @@ an unmodded save. Other init files ---------------- + +* ``onMapLoad*.init`` and ``onMapUnload*.init`` are run when a map, + distinct from a world, is loaded. This is good for map-affecting + commands (eg `clean`), or avoiding issues in Legends mode. + * Any lua script named ``raw/init.d/*.lua``, in the save or main DF directory, will be run when any world or that save is loaded. @@ -382,7 +332,7 @@ This section is for odd but important notes that don't fit anywhere else. an already running DF+DFHack instance from external OS scripts and programs, and is *not* the way how you use DFHack normally. -* If a DF hotkey (:kbd:`H`) is named with a DFHack command, pressing +* If a DF :kbd:`H` hotkey is named with a DFHack command, pressing the corresponding :kbd:`Fx` button will run that command, instead of zooming to the set location. diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 192bbb36d..ddb60316b 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -346,13 +346,65 @@ UI Upgrades .. note:: - In order to avoid user confusion, as a matter of policy all these tools + In order to avoid user confusion, as a matter of policy all GUI tools display the word :guilabel:`DFHack` on the screen somewhere while active. When that is not appropriate because they merely add keybinding hints to existing DF screens, they deliberately use red instead of green for the key. +DFHack Interface +================ + +.. _command-prompt: + +command-prompt +-------------- +An in-game DFHack terminal, where you can enter other commands. +Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. + +Usage: ``command-prompt [entry]`` + +If called with an entry, it starts with that text filled in. +Most useful for developers, who can set a keybinding to open +a laungage interpreter for lua or Ruby by starting with the +`:lua ` or `:rb_eval ` commands. + +Otherwise somewhat similar to `gui/quickcmd`. + +.. image:: images/command-prompt.png + + +.. _hotkeys: + +hotkeys +------- +Opens an in-game screen showing which DFHack keybindings are +active in the current context. + +.. image:: images/hotkeys.png + +Type ``hotkeys`` into the DFHack console to open the screen, +or bind the command to a globally active hotkey. The default +keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. + +.. _rb_eval: + +rb_eval +------- +Evaluate the following arguments as a ruby string. Best used as +``:rb_eval [string]``, for the special parsing mode: + +If the first non-whitespace character is ``:``, the command is parsed in a special +alternative mode: first, non-whitespace characters immediately following the ``:`` +are used as the command name; the remaining part of the line, starting with the first +non-whitespace character *after* the command name, is used verbatim as the first argument. +The following two command lines are exactly equivalent:: + + :foo a b "c d" e f + foo "a b \"c d\" e f" + + .. _manipulator: manipulator @@ -450,6 +502,13 @@ using Permit Fats again while the list is filtered. Game interface ============== +.. _nopause: + +nopause +------- +Disables pausing (both manual and automatic) with the exception of pause forced +by `reveal` ``hell``. This is nice for digging under rivers. + .. _embark-tools: embark-tools From bc91928f8d35236bf9962955453f8e6db3110223 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 11:58:33 +1100 Subject: [PATCH 10/18] Explain ":foo" parsing mode in Core notes --- docs/Core.rst | 16 +++++++++++++--- docs/Plugins.rst | 12 +----------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/Core.rst b/docs/Core.rst index 6ff1c8935..17b6d3174 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -340,12 +340,22 @@ This section is for odd but important notes that don't fit anywhere else. that's preserved between different runs of DF (use up/down keys to go through the history). -* To include whitespace in the argument/s to some command, quote it in - double quotes. To include a double quote character, use ``\"``. - * The binaries for 0.40.15-r1 to 0.34.11-r4 are on DFFD_. Older versions are available here_. .. _DFFD: http://dffd.bay12games.com/search.php?string=DFHack&id=15&limit=1000 .. _here: http://dethware.org/dfhack/download +* To include whitespace in the argument/s to some command, quote it in + double quotes. To include a double quote character, use ``\"``. + +* If the first non-whitespace character is ``:``, the command is parsed in + an alternative mode which is very useful for the `lua` and `rb_eval` commands. + The following two command lines are exactly equivalent:: + + :foo a b "c d" e f + foo "a b \"c d\" e f" + + * non-whitespace characters following the ``:`` are the command name + * the remaining part of the line is used verbatim as the first argument + diff --git a/docs/Plugins.rst b/docs/Plugins.rst index ddb60316b..4486d11cb 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -393,17 +393,7 @@ keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. rb_eval ------- Evaluate the following arguments as a ruby string. Best used as -``:rb_eval [string]``, for the special parsing mode: - -If the first non-whitespace character is ``:``, the command is parsed in a special -alternative mode: first, non-whitespace characters immediately following the ``:`` -are used as the command name; the remaining part of the line, starting with the first -non-whitespace character *after* the command name, is used verbatim as the first argument. -The following two command lines are exactly equivalent:: - - :foo a b "c d" e f - foo "a b \"c d\" e f" - +``:rb_eval [string]``, for the special parsing mode. .. _manipulator: From 193e71793a3a0bf3e72b936a65059eec17c3f669 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 16:58:58 +1100 Subject: [PATCH 11/18] Fix compile, intro, scripts - script-syntax.py now exits with 1 instead of silently catching the error if lua or ruby are missing - index paths are absolute (from the repo root) - less strong suggestion for third-party packs - re-added lua-example and test-perlin doc - corrected and clarified Compile some more --- docs/Compile.rst | 69 +++++++++++++++-------------------- docs/Introduction.rst | 6 +-- index.rst | 26 ++++++------- scripts/devel/lua-example.lua | 14 +++++++ scripts/devel/test-perlin.lua | 2 - travis/script-syntax.py | 6 +-- 6 files changed, 62 insertions(+), 61 deletions(-) create mode 100644 scripts/devel/lua-example.lua diff --git a/docs/Compile.rst b/docs/Compile.rst index 4a72f0dc4..752b9b5fd 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -14,17 +14,8 @@ and `install the latest release instead `. How to get the code =================== DFHack doesn't have any kind of system of code snapshots in place, so you will have to -get code from the github repository using git. -The code resides at https://github.com/DFHack/dfhack - -On Linux and OS X, having a ``git`` package installed is the minimal requirement (see below for OS X instructions), -but some sort of git gui or git integration for your favorite text editor/IDE will certainly help. - -On Windows, you will need some sort of Windows port of git, or a GUI. Some examples: - - * http://msysgit.github.io - this is a command line version of git for windows. - Most tutorials on git usage will apply. - * http://code.google.com/p/tortoisegit - this puts a pretty, graphical face on top of msysgit +get code from the github repository using git. How to get git is described under +the instructions for each platform. To get the code:: @@ -34,16 +25,14 @@ To get the code:: If your version of git does not support the ``--recursive`` flag, you will need to omit it and run ``git submodule update --init`` after entering the dfhack directory. -If you want to get really involved with the development, create an account on +If you want to get involved with the development, create an account on Github, make a clone there and then use that as your remote repository instead. -Detailed instructions are beyond the scope of this document. If you need help, -join us on IRC (#dfhack channel on freenode). +We'd love that; join us on IRC (#dfhack channel on freenode) if you need help. Build types =========== -``cmake`` allows you to pick a build type by changing the -``CMAKE_BUILD_TYPE`` environment variable:: +``cmake`` allows you to pick a build type by changing the ``CMAKE_BUILD_TYPE`` variable:: cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE @@ -62,23 +51,25 @@ Dependencies ------------ DFHack is meant to be installed into an existing DF folder, so get one ready. -For building, you need a 32-bit version of GCC. For example, to build DFHack on -a 64-bit distribution like Arch, you'll need the multilib development tools and libraries. -Alternatively, you might be able to use ``lxc`` to +We assume that any Linux platform will have ``git`` available. + +To build DFHack you need a 32-bit version of GCC. On 64-bit distributions +(which is most of them), this means you'll need the multilib development tools +and libraries. Alternatively, you might be able to use ``lxc`` to :forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. Before you can build anything, you'll also need ``cmake``. It is advisable to also get ``ccmake`` on distributions that split the cmake package into multiple parts. You also need perl and the XML::LibXML and XML::LibXSLT perl packages (for the code generation parts). -You should be able to find them in your distro repositories (on Arch linux -``perl-xml-libxml`` and ``perl-xml-libxslt``) or through ``cpan``. +You should be able to find them in your distro repositories. -To build Stonesense, you'll also need OpenGL headers. +* On Arch linux, ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``) +* On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. +* On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. +* Debian-derived distros should have similar requirements. -On 64-bit Ubuntu, ``apt-get install zlib1g-dev:i386 libxml-libxml-perl libxml-libxslt-perl``. -On 32-bit Ubuntu, ``apt-get install zlib1g-dev libxml-libxml-perl libxml-libxslt-perl``. -Debian-derived distros should have similar requirements. +To build Stonesense, you'll also need OpenGL headers. Build @@ -100,14 +91,12 @@ Alternatively, you can use ccmake instead of cmake:: make install This will show a curses-based interface that lets you set all of the -extra options. +extra options. You can also use a cmake-friendly IDE like KDevelop 4 +or the cmake-gui program. -You can also use a cmake-friendly IDE like KDevelop 4 or the cmake-gui -program. - -The libstdc++ version bug -~~~~~~~~~~~~~~~~~~~~~~~~~ +Incompatible libstdc++ +~~~~~~~~~~~~~~~~~~~~~~ When compiling dfhack yourself, it builds against your system libc. When Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which comes from GCC 4.5 and is incompatible with code compiled with newer GCC versions. @@ -116,14 +105,12 @@ This manifests itself with the error message:: ./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version `GLIBCXX_3.4.15' not found (required by ./hack/libdfhack.so) -To fix this, simply remove the libstdc++ shipped with DF, it will fall back -to your system lib and everything will work fine:: +To fix this, you can compile DFHack with GCC 4.5 - or simply remove the +libstdc++ shipped with DF, and it will fall back to your system lib:: cd /path/to/DF/ rm libs/libstdc++.so.6 -Alternatively, this issue can be avoided by compiling DFHack with GCC 4.5. - Mac OS X ======== @@ -201,16 +188,18 @@ On Windows, DFHack replaces the SDL library distributed with DF. Dependencies ------------ -First, you need ``cmake``. Get the win32 installer version from -`the official site `_. +You will need some sort of Windows port of git, or a GUI. Some examples: +* `Git for Windows `_ (command-line and GUI) +* `tortoisegit `_ (GUI and File Explorer integration) + +You need ``cmake``. Get the win32 installer version from +`the official site `_. It has the usual installer wizard. Make sure you let it add its binary folder to your binary search PATH so the tool can be later run from anywhere. You'll need a copy of Microsoft Visual C++ 2010. The Express version is sufficient. -Grab it from Microsoft's site. - -You'll also need the Visual Studio 2010 SP1 update. +Grab it from Microsoft's site. You'll also need the Visual Studio 2010 SP1 update. For the code generation parts, you'll need perl with XML::LibXML and XML::LibXSLT. `Strawberry Perl `_ works nicely for this. diff --git a/docs/Introduction.rst b/docs/Introduction.rst index f0fc0a0bf..8a82e0f10 100644 --- a/docs/Introduction.rst +++ b/docs/Introduction.rst @@ -37,9 +37,6 @@ allows easier development of new tools. As an open-source project under Installing DFHack ================= -New players are encouraged to :wiki:`get a pack with DFHack preinstalled -`. - DFHack is available for the SDL version of Dwarf Frtress on Windows, any modern Linux distribution, and OS X (10.6.8 to 10.9). It is possible to use Windows DF+DFHack under Wine on Linux or OS X. @@ -60,6 +57,9 @@ Uninstalling is basically the same, in reverse: * On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files. * On Linux or OSX, remove the DFHack files. +New players may wish to :wiki:`get a pack ` +with DFHack preinstalled. + Getting started =============== diff --git a/index.rst b/index.rst index 7f3e815a3..de587e95a 100644 --- a/index.rst +++ b/index.rst @@ -36,10 +36,10 @@ User Manual .. toctree:: :maxdepth: 2 - docs/Introduction - docs/Core - docs/Plugins - docs/Scripts + /docs/Introduction + /docs/Core + /docs/Plugins + /docs/Scripts Other Contents ============== @@ -47,9 +47,9 @@ Other Contents .. toctree:: :maxdepth: 1 - docs/Authors - LICENSE - NEWS + /docs/Authors + /LICENSE + /NEWS For Developers ============== @@ -57,9 +57,9 @@ For Developers .. toctree:: :maxdepth: 1 - docs/Contributing - docs/Compile - docs/Lua API - library/xml/SYNTAX - library/xml/how-to-update - docs/Binpatches + /docs/Contributing + /docs/Compile + /docs/Lua API + /library/xml/SYNTAX + /library/xml/how-to-update + /docs/Binpatches diff --git a/scripts/devel/lua-example.lua b/scripts/devel/lua-example.lua new file mode 100644 index 000000000..bbdb04ed6 --- /dev/null +++ b/scripts/devel/lua-example.lua @@ -0,0 +1,14 @@ +-- Example of a lua script. +--[[=begin + +devel/lua-example +================= +An example lua script, which reports the number of times it has +been called. Useful for testing environment persistence. + +=end]] + +run_count = (run_count or 0) + 1 + +print('Arguments: ',...) +print('Command called '..run_count..' times.') diff --git a/scripts/devel/test-perlin.lua b/scripts/devel/test-perlin.lua index 2759d7085..3b3a6a11a 100644 --- a/scripts/devel/test-perlin.lua +++ b/scripts/devel/test-perlin.lua @@ -5,8 +5,6 @@ devel/test-perlin ================= Generates an image using multiple octaves of perlin noise. -Used by `3dveins`? - =end]] local args = {...} diff --git a/travis/script-syntax.py b/travis/script-syntax.py index 0b977f59d..c4454d7be 100644 --- a/travis/script-syntax.py +++ b/travis/script-syntax.py @@ -24,9 +24,9 @@ def main(): except subprocess.CalledProcessError: err = True except IOError: - # catch error if not in Travis and Lua/Ruby is not available - if os.environ.get('TRAVIS', False): - raise + if not err: + print('Warning: cannot check %s script syntax' % args.ext) + err = True sys.exit(int(err)) From 5826b49d09f12ebc16cc6937234b1e56aa39a559 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 6 Nov 2015 17:09:56 +1100 Subject: [PATCH 12/18] Move index.rst to docs directory Having the docs index in the repo root was a holdover from when it was the README file. Now that it's not much use without being built, it's better to leave the root to README, NEWS, and LICENSE - especially when one is a html shortcut to the docs index. --- CMakeLists.txt | 2 +- README.html | 6 +++--- conf.py | 2 +- index.rst => docs/index.rst | 0 4 files changed, 5 insertions(+), 5 deletions(-) rename index.rst => docs/index.rst (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index fb6dd52bb..c7ab44fd5 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -214,7 +214,7 @@ if (BUILD_DOCS) "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.lua" "${CMAKE_CURRENT_SOURCE_DIR}/scripts/*.rb" ) - set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst index.rst) + set(SPHINX_DEPS ${SPHINX_DEPS} ${SPHINX_SCRIPT_DEPS} LICENSE.rst NEWS.rst) set(SPHINX_OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/docs/html/.buildinfo") set_source_files_properties(${SPHINX_OUTPUT} PROPERTIES GENERATED TRUE) diff --git a/README.html b/README.html index 325cd66f6..660ea2b5b 100644 --- a/README.html +++ b/README.html @@ -4,13 +4,13 @@ - + Page Redirection - Follow this link to the documentation. + Follow this link to the documentation. \ No newline at end of file diff --git a/conf.py b/conf.py index 5eb2c8177..7b0a7c4c5 100644 --- a/conf.py +++ b/conf.py @@ -120,7 +120,7 @@ source_suffix = '.rst' #source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'index' +master_doc = 'docs/index' # General information about the project. project = 'DFHack' diff --git a/index.rst b/docs/index.rst similarity index 100% rename from index.rst rename to docs/index.rst From 7f212178ca756922d28d8e9e17a2db68fa5c047b Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 10:13:21 +1100 Subject: [PATCH 13/18] Move unused docs to plugin source files This way they can easily be restored when the plugins are reactivated, but don't confuse users until then. --- docs/Plugins.rst | 80 +++++------------------------ plugins/advtools.cpp | 11 ++++ plugins/dwarfexport/dwarfexport.cpp | 5 ++ plugins/mapexport/mapexport.cpp | 6 +++ plugins/misery.cpp | 15 ++++++ plugins/treefarm.cpp | 18 +++++++ 6 files changed, 69 insertions(+), 66 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 4486d11cb..baa336cbd 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -10,7 +10,7 @@ Most commands offered by plugins are listed here, hopefully organised in a way you will find useful. .. contents:: - :depth: 4 + :depth: 3 =========================== Visualizers and data export @@ -37,15 +37,6 @@ For detailed information, see the `stonesense readme`_, the :wiki:`wiki page .. _`stonesense readme`: https://github.com/DFHack/stonesense/blob/master/README.md -mapexport -========= -Export the current loaded map as a file. This was used by visualizers for -DF 0.34.11, but is now basically obsolete. - -dwarfexport -=========== -Export dwarves to RuneSmith-compatible XML; also unused by modern tools. - .. _blueprint: blueprint @@ -1689,48 +1680,6 @@ cycle runs once every in game day. If you add ``enable getplants`` to your dfhack.init there will be a hotkey to open the dashboard from the chop designation menu. -treefarm --------- -Automatically manages special burrows and regularly schedules tree chopping -and digging when appropriate. - -Every time the plugin runs, it checks for burrows with a name containing the -string ``"treefarm"``. For each such burrow, it checks every tile in it for -fully-grown trees and for diggable walls. For each fully-grown tree it finds, -it designates the tree to be chopped, and for each natural wall it finds, it -designates the wall to be dug. - -Usage: - -:treefarm: Enables treefarm monitoring, starting next frame -:treefarm n: Enables treefarm monitoring, starting next frame, and sets - interval to n frames. If n is less than one, disables monitoring. - - -============== -Adventure mode -============== - -adv-bodyswap -============ -This allows taking control over your followers and other creatures in adventure -mode. For example, you can make them pick up new arms and armor and equip them -properly. - -Usage: - -* When viewing unit details, body-swaps into that unit. -* In the main adventure mode screen, reverts transient swap. - -advtools -======== -A package of different adventure mode tools. Usage: - -:list-equipped [all]: List armor and weapons equipped by your companions. - If all is specified, also lists non-metal clothing. -:metal-detector [all-types] [non-trader]: - Reveal metal armor and weapons in shops. The options - disable the checks on item type and being in shop. ================ Map modification @@ -2162,6 +2111,19 @@ or 'snow', with those words as commands (eg ``weather rain``). Mods and Cheating ================= +.. _adv-bodyswap: + +adv-bodyswap +============ +This allows taking control over your followers and other creatures in adventure +mode. For example, you can make them pick up new arms and armor and equip them +properly. + +Usage: + +* When viewing unit details, body-swaps into that unit. +* In the main adventure mode screen, reverts transient swap. + .. _catsplosion: catsplosion @@ -2243,20 +2205,6 @@ Options: :lair: Mark the map as monster lair :lair reset: Mark the map as ordinary (not lair) -misery -====== -When enabled, every new negative dwarven thought will be multiplied by a factor (2 by default). - -Usage: - -:misery enable n: enable misery with optional magnitude n. If specified, n must be positive. -:misery n: same as "misery enable n" -:misery enable: same as "misery enable 2" -:misery disable: stop adding new negative thoughts. This will not remove existing - duplicated thoughts. Equivalent to "misery 1" -:misery clear: remove fake thoughts added in this session of DF. Saving makes them - permanent! Does not change factor. - mode ==== This command lets you see and change the game mode directly. diff --git a/plugins/advtools.cpp b/plugins/advtools.cpp index 8f613d1cc..77cc02934 100644 --- a/plugins/advtools.cpp +++ b/plugins/advtools.cpp @@ -41,6 +41,17 @@ using df::nemesis_record; using df::historical_figure; using namespace DFHack::Translation; +/* +advtools +======== +A package of different adventure mode tools. Usage: + +:list-equipped [all]: List armor and weapons equipped by your companions. + If all is specified, also lists non-metal clothing. +:metal-detector [all-types] [non-trader]: + Reveal metal armor and weapons in shops. The options + disable the checks on item type and being in shop. +*/ DFHACK_PLUGIN("advtools"); REQUIRE_GLOBAL(world); diff --git a/plugins/dwarfexport/dwarfexport.cpp b/plugins/dwarfexport/dwarfexport.cpp index 8355573be..666601b79 100644 --- a/plugins/dwarfexport/dwarfexport.cpp +++ b/plugins/dwarfexport/dwarfexport.cpp @@ -20,6 +20,11 @@ using namespace std; #include #include #include +/* +dwarfexport +=========== +Export dwarves to RuneSmith-compatible XML; also unused by modern tools. +*/ using namespace DFHack; using df::global::ui; diff --git a/plugins/mapexport/mapexport.cpp b/plugins/mapexport/mapexport.cpp index 0c69eeb68..ceb03196a 100644 --- a/plugins/mapexport/mapexport.cpp +++ b/plugins/mapexport/mapexport.cpp @@ -21,6 +21,12 @@ using namespace google::protobuf::io; using namespace DFHack; using df::global::world; +/* +mapexport +========= +Export the current loaded map as a file. This was used by visualizers for +DF 0.34.11, but is now basically obsolete. +*/ typedef std::vector PlantList; diff --git a/plugins/misery.cpp b/plugins/misery.cpp index 00c844f1d..a4468079c 100644 --- a/plugins/misery.cpp +++ b/plugins/misery.cpp @@ -14,6 +14,21 @@ using namespace std; using namespace DFHack; +/* +misery +====== +When enabled, every new negative dwarven thought will be multiplied by a factor (2 by default). + +Usage: + +:misery enable n: enable misery with optional magnitude n. If specified, n must be positive. +:misery n: same as "misery enable n" +:misery enable: same as "misery enable 2" +:misery disable: stop adding new negative thoughts. This will not remove existing + duplicated thoughts. Equivalent to "misery 1" +:misery clear: remove fake thoughts added in this session of DF. Saving makes them + permanent! Does not change factor. +*/ DFHACK_PLUGIN("misery"); DFHACK_PLUGIN_IS_ENABLED(is_enabled); diff --git a/plugins/treefarm.cpp b/plugins/treefarm.cpp index 68429dd93..0e24ad28f 100644 --- a/plugins/treefarm.cpp +++ b/plugins/treefarm.cpp @@ -20,6 +20,24 @@ //#include "df/world.h" using namespace DFHack; +/* +treefarm +======== +Automatically manages special burrows and regularly schedules tree chopping +and digging when appropriate. + +Every time the plugin runs, it checks for burrows with a name containing the +string ``"treefarm"``. For each such burrow, it checks every tile in it for +fully-grown trees and for diggable walls. For each fully-grown tree it finds, +it designates the tree to be chopped, and for each natural wall it finds, it +designates the wall to be dug. + +Usage: + +:treefarm: Enables treefarm monitoring, starting next frame +:treefarm n: Enables treefarm monitoring, starting next frame, and sets + interval to n frames. If n is less than one, disables monitoring. +*/ DFHACK_PLUGIN("treefarm"); DFHACK_PLUGIN_IS_ENABLED(enabled); From 35069214479dc9074b0a9227aef87020bf365232 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 10:53:12 +1100 Subject: [PATCH 14/18] Add cross-links for similar commands --- docs/Plugins.rst | 9 ++++++--- scripts/source.rb | 1 + 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index baa336cbd..8e36de861 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -206,7 +206,7 @@ allowing them to make trade agreements. This was the default behaviour in fix-unit-occupancy ================== -This plugin fixes issues with unit occupancy, notably issues with phantom +This plugin fixes issues with unit occupancy, notably phantom "unit blocking tile" messages (:bug:`3499`). It can be run manually, or periodically when enabled with the built-in enable/disable commands: @@ -1913,7 +1913,10 @@ See also `this issue. `_ Settings will be remembered until you quit DF. You can call `liquids-here` to execute the last configured action, which is useful in combination with keybindings. -Usage: point the DF cursor at a tile you want to modify and use the commands +Usage: point the DF cursor at a tile you want to modify and use the commands. + +If you only want to add or remove water or magma from one tile, +`source` may be easier to use. Commands -------- @@ -1971,7 +1974,7 @@ Intended to be used as keybinding. Requires an active in-game cursor. tiletypes ========= Can be used for painting map tiles and is an interactive command, much like -`liquids`. +`liquids`. If something goes wrong, `fixveins` may help. The tool works with two set of options and a brush. The brush determines which tiles will be processed. First set of options is the filter, which can exclude diff --git a/scripts/source.rb b/scripts/source.rb index 647fc960a..92f1a47a6 100644 --- a/scripts/source.rb +++ b/scripts/source.rb @@ -4,6 +4,7 @@ source ====== Create an infinite magma or water source or drain on a tile. +For more complex commands, try the `liquids` plugin. This script registers a map tile as a liquid source, and every 12 game ticks that tile receives or remove 1 new unit of flow based on the configuration. From a1110b36e8015a78a58130c727de67b850d40acc Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 11:35:44 +1100 Subject: [PATCH 15/18] Add shortlink for issues, update links Also moved search above local table of contents in sidebar, which can get very long. --- conf.py | 5 +++-- docs/Binpatches.rst | 13 +++++-------- docs/Compile.rst | 7 ++++--- docs/Contributing.rst | 24 ++++++++++++++---------- docs/Plugins.rst | 9 ++++----- 5 files changed, 30 insertions(+), 28 deletions(-) diff --git a/conf.py b/conf.py index 7b0a7c4c5..6c4f768db 100644 --- a/conf.py +++ b/conf.py @@ -106,7 +106,8 @@ extlinks = { 'Bay12 forums thread '), 'dffd': ('http://dffd.bay12games.com/file.php?id=%s', 'DFFD file '), 'bug': ('http://www.bay12games.com/dwarves/mantisbt/view.php?id=%s', - 'Bug ') + 'Bug '), + 'issue': ('https://github.com/DFHack/dfhack/issues/%s', 'Issue '), } # Add any paths that contain templates here, relative to this directory. @@ -235,9 +236,9 @@ html_last_updated_fmt = '%Y-%m-%d' html_sidebars = { '**': [ 'about.html', - 'localtoc.html', 'relations.html', 'searchbox.html', + 'localtoc.html', ] } diff --git a/docs/Binpatches.rst b/docs/Binpatches.rst index 145dead89..e1ae1c0ef 100644 --- a/docs/Binpatches.rst +++ b/docs/Binpatches.rst @@ -32,8 +32,7 @@ decent skill in `memory research `. * 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. +* :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. @@ -56,7 +55,7 @@ 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. As with many other commands, users -can simply add it to ``dfhack.init`` to reapply the patch every time DF is run. +can simply add it to `dfhack.init` to reapply the patch every time DF is run. Patching on disk @@ -152,8 +151,8 @@ 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. +Bind to a key (the example config uses :kbd:`P`), and activate when viewing a weapon +rack in the :kbd:`q` mode. .. image:: images/assign-rack.png @@ -166,9 +165,7 @@ work again. The existing issues are: * 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 + and has not been updated since 0.34.11. See :bug:`1445` for more info. * Haulers still take equipment stored in the armory away to the stockpiles, unless `fix-armory` is used. diff --git a/docs/Compile.rst b/docs/Compile.rst index 752b9b5fd..e140c6b28 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -135,7 +135,7 @@ following environment variable:: brew install cmake brew install gcc45 - Using `MacPorts `_:: + Using `MacPorts `_:: sudo port install gcc45 +universal cmake +universal git-core +universal @@ -149,7 +149,8 @@ following environment variable:: If this is the first time you've run cpan, you will need to go through the setup process. Just stick with the defaults for everything and you'll be fine. - If you are running Snow Leopard or later, open a separate Terminal window and run:: + If you are running Snow Leopard (ie 10.6 or earlier), good luck! + You'll need to open a separate Terminal window and run:: sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml @@ -214,7 +215,7 @@ Build There are several different batch files in the ``build`` folder along with a script that's used for picking the DF path. -First, run set_df_path.vbs and point the dialog that pops up at your +First, run ``set_df_path.vbs`` and point the dialog that pops up at your DF folder that you want to use for development. Next, run one of the scripts with ``generate`` prefix. These create the MSVC solution file(s): diff --git a/docs/Contributing.rst b/docs/Contributing.rst index 5691fbcc0..cd2495922 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -11,7 +11,6 @@ Several things should be kept in mind when contributing code to DFHack. Code Format ----------- - * Four space indents for C++. Never use tabs for indentation in any language. * LF (Unix style) line terminators * Avoid trailing whitespace @@ -25,14 +24,18 @@ Code Format How to get new code into DFHack ------------------------------- - -* Submit pull requests to the ``develop`` branch, not the master branch. The master branch always points at the most recent release. -* Use new branches for each feature/fix so that your changes can be merged independently (i.e. not the master or develop branch of your fork). +* Submit pull requests to the ``develop`` branch, not the ``master`` branch. + (The ``master`` branch always points at the most recent release) +* Use a new branch for each feature or bugfix so that your changes can be merged independently + (i.e. not the master or develop branch of your fork). * If possible, compile on multiple platforms when changing anything that compiles -* Update ``NEWS`` and ``docs/Authors.rst`` when applicable +* It must pass CI - run ``python travis/all.py`` to check this. +* Update ``NEWS.rst`` and ``docs/Authors.rst`` when applicable. * Create a GitHub pull request once finished -* Work done against GitHub issues tagged "bug" get priority -* Submit ideas and bug reports as issues on GitHub. Posts in the forum thread can easily get missed or forgotten. +* Submit ideas and bug reports as :issue:`issues on GitHub <>`. + Posts in the forum thread can easily get missed or forgotten. +* Work on :issue:`reported problems ` + will take priority over ideas or suggestions. .. _contributing-memory-research: @@ -62,7 +65,8 @@ All the plugins can be found in the 'plugins' folder. There's no in-depth docume on how to write one yet, but it should be easy enough to copy one and just follow the pattern. ``plugins/skeleton/skeleton.cpp`` is provided for this purpose. -Other than through plugins, it is possible to use DFHack via remote access interface, or by writing Lua scripts. +Other than through plugins, it is possible to use DFHack via remote access interface, +or by writing scripts in Lua or Ruby. There are plenty of examples in the scripts folder. The most important parts of DFHack are the Core, Console, Modules and Plugins. @@ -164,10 +168,10 @@ text. Use double-backticks to put commands in monospaced font, like this:: You can use ``cleanowned scattered x`` to dump tattered or abandoned items. If the command takes more than three arguments, format the list as a table -called Options. The table *only* lists arguments, not full commands. +called Usage. The table *only* lists arguments, not full commands. Input values are specified in angle brackets. Example:: - Options: + Usage: :arg1: A simple argument. :arg2 : Does something based on the input value. diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 8e36de861..3434233fd 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -217,6 +217,8 @@ periodically when enabled with the built-in enable/disable commands: The default is 1200 ticks, or 1 day. Ticks are only counted when the game is unpaused. +.. _fixveins: + fixveins ======== Removes invalid references to mineral inclusions and restores missing ones. @@ -1890,8 +1892,7 @@ Usage: ``infiniteSky enable/disable`` Enables/disables monitoring of constructions. If you build anything in the second to highest z-level, it will allocate one more sky level. This is so you can continue to build stairs upward. -`Sometimes `_ -new z-levels disappear and cause cave-ins. +:issue:`Sometimes <254>` new z-levels disappear and cause cave-ins. Saving and loading after creating new z-levels should fix the problem. .. _liquids: @@ -1901,9 +1902,7 @@ liquids Allows adding magma, water and obsidian to the game. It replaces the normal dfhack command line and can't be used from a hotkey. Settings will be remembered as long as dfhack runs. Intended for use in combination with the command -``liquids-here`` (which can be bound to a hotkey). - -See also `this issue. `_ +``liquids-here`` (which can be bound to a hotkey). See also :issue:`80`. .. note:: From 1c25f8f1a366789d1740316a93ac81da392ca101 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 13:03:17 +1100 Subject: [PATCH 16/18] Unify docs for designation and map-mod plugins Plus some cleanup and flattening of the behaviour mod plugin docs --- docs/Plugins.rst | 576 +++++++++++++++++------------------- scripts/gui/power-meter.lua | 9 + 2 files changed, 287 insertions(+), 298 deletions(-) diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 3434233fd..91835cd35 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -718,232 +718,6 @@ materials that color the light etc... .. image:: images/rendermax.png -Designations -============ - -burrow ------- -Miscellaneous burrow control. Allows manipulating burrows and automated burrow -expansion while digging. - -Options: - -:enable feature ...: - Enable features of the plugin. -:disable feature ...: - Disable features of the plugin. -:clear-unit burrow burrow ...: - Remove all units from the burrows. -:clear-tiles burrow burrow ...: - Remove all tiles from the burrows. -:set-units target-burrow src-burrow ...: - Clear target, and adds units from source burrows. -:add-units target-burrow src-burrow ...: - Add units from the source burrows to the target. -:remove-units target-burrow src-burrow ...: - Remove units in source burrows from the target. -:set-tiles target-burrow src-burrow ...: - Clear target and adds tiles from the source burrows. -:add-tiles target-burrow src-burrow ...: - Add tiles from the source burrows to the target. -:remove-tiles target-burrow src-burrow ...: - Remove tiles in source burrows from the target. - - For these three options, in place of a source burrow it is - possible to use one of the following keywords: ABOVE_GROUND, - SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED - -Features: - -:auto-grow: When a wall inside a burrow with a name ending in '+' is dug - out, the burrow is extended to newly-revealed adjacent walls. - This final '+' may be omitted in burrow name args of commands above. - Digging 1-wide corridors with the miner inside the burrow is SLOW. - -dig ---- -This plugin makes many automated or complicated dig patterns easy. - -Basic commands: - -:digv: Designate all of the selected vein for digging. -:digvx: Also cross z-levels, digging stairs as needed. Alias for ``digv x``. -:digl: Like ``digv``, for layer stone. Also supports an ``undo`` option - to remove designations, for if you accidentally set 50 levels at once. -:diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. - -digexp -~~~~~~ -This command is for :wiki:`exploratory mining `. - -There are two variables that can be set: pattern and filter. - -Patterns: - -:diag5: diagonals separated by 5 tiles -:diag5r: diag5 rotated 90 degrees -:ladder: A 'ladder' pattern -:ladderr: ladder rotated 90 degrees -:clear: Just remove all dig designations -:cross: A cross, exactly in the middle of the map. - -Filters: - -:all: designate whole z-level -:hidden: designate only hidden tiles of z-level (default) -:designated: Take current designation and apply pattern to it. - -After you have a pattern set, you can use ``expdig`` to apply it again. - -Examples: - -``expdig diag5 hidden`` - Designate the diagonal 5 patter over all hidden tiles -``expdig`` - Apply last used pattern and filter -``expdig ladder designated`` - Take current designations and replace them with the ladder pattern - -digcircle -~~~~~~~~~ -A command for easy designation of filled and hollow circles. -It has several types of options. - -Shape: - -:hollow: Set the circle to hollow (default) -:filled: Set the circle to filled -:#: Diameter in tiles (default = 0, does nothing) - -Action: - -:set: Set designation (default) -:unset: Unset current designation -:invert: Invert designations already present - -Designation types: - -:dig: Normal digging designation (default) -:ramp: Ramp digging -:ustair: Staircase up -:dstair: Staircase down -:xstair: Staircase up/down -:chan: Dig channel - -After you have set the options, the command called with no options -repeats with the last selected parameters. - -Examples: - -``digcircle filled 3`` - Dig a filled circle with diameter = 3. -``digcircle`` - Do it again. - -digtype -~~~~~~~ -For every tile on the map of the same vein type as the selected tile, -this command designates it to have the same designation as the -selected tile. If the selected tile has no designation, they will be -dig designated. -If an argument is given, the designation of the selected tile is -ignored, and all appropriate tiles are set to the specified -designation. - -Options: - -:dig: -:channel: -:ramp: -:updown: up/down stairs -:up: up stairs -:down: down stairs -:clear: clear designation - -digFlood --------- -Automatically digs out specified veins as they are discovered. It runs once -every time a dwarf finishes a dig job. It will only dig out appropriate tiles -that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. -This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` -to disable, then remove, then re-enable. - -Usage: - -:help digflood: detailed help message -:digFlood 0: disable the plugin -:digFlood 1: enable the plugin -:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: - disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin -:digFlood CLEAR: remove all inorganics from monitoring -:digFlood digAll1: ignore the monitor list and dig any vein -:digFlood digAll0: disable digAll mode - -filltraffic ------------ -Set traffic designations using flood-fill starting at the cursor. - -Traffic Type Codes: - -:H: High Traffic -:N: Normal Traffic -:L: Low Traffic -:R: Restricted Traffic - -Other Options: - -:X: Fill across z-levels. -:B: Include buildings and stockpiles. -:P: Include empty space. - -Example: - -``filltraffic H`` - When used in a room with doors, it will set traffic to HIGH in just that room. - -alltraffic ----------- -Set traffic designations for every single tile of the map (useful for resetting traffic designations). - -Traffic Type Codes: - -:H: High Traffic -:N: Normal Traffic -:L: Low Traffic -:R: Restricted Traffic - -Example: - -``alltraffic N`` - Set traffic to 'normal' for all tiles. - -restrictliquid --------------- -Restrict traffic on all visible tiles with liquid. - -restrictice ------------ -Restrict traffic on all tiles on top of visible ice. - -getplants ---------- -This tool allows plant gathering and tree cutting by RAW ID. Specify the types -of trees to cut down and/or shrubs to gather by their plant names, separated -by spaces. - -Options: - -:-t: Select trees only (exclude shrubs) -:-s: Select shrubs only (exclude trees) -:-c: Clear designations instead of setting them -:-x: Apply selected action to all plants except those specified (invert - selection) -:-a: Select every type of plant (obeys ``-t``/``-s``) - -Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified, -all valid plant IDs will be listed. - - =========================== Job and Fortress management =========================== @@ -1006,7 +780,7 @@ Advanced usage: :autolabor list: List current status of all labors. :autolabor status: Show basic status information. -See `autolabor-artisans` for a differently-tunde setup. +See `autolabor-artisans` for a differently-tuned setup. Examples: @@ -1704,6 +1478,62 @@ if vein mass shifts between Z layers. The only undo option is to restore your save from backup. +.. _alltraffic: + +alltraffic +========== +Set traffic designations for every single tile of the map - useful for resetting +traffic designations. See also `filltraffic`, `restrictice`, and `restrictliquid`. + +Options: + +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic + +.. _burrow: + +burrow +====== +Miscellaneous burrow control. Allows manipulating burrows and automated burrow +expansion while digging. + +Options: + +:enable feature ...: + Enable features of the plugin. +:disable feature ...: + Disable features of the plugin. +:clear-unit burrow burrow ...: + Remove all units from the burrows. +:clear-tiles burrow burrow ...: + Remove all tiles from the burrows. +:set-units target-burrow src-burrow ...: + Clear target, and adds units from source burrows. +:add-units target-burrow src-burrow ...: + Add units from the source burrows to the target. +:remove-units target-burrow src-burrow ...: + Remove units in source burrows from the target. +:set-tiles target-burrow src-burrow ...: + Clear target and adds tiles from the source burrows. +:add-tiles target-burrow src-burrow ...: + Add tiles from the source burrows to the target. +:remove-tiles target-burrow src-burrow ...: + Remove tiles in source burrows from the target. + + For these three options, in place of a source burrow it is + possible to use one of the following keywords: ABOVE_GROUND, + SUBTERRANEAN, INSIDE, OUTSIDE, LIGHT, DARK, HIDDEN, REVEALED + +Features: + +:auto-grow: When a wall inside a burrow with a name ending in '+' is dug + out, the burrow is extended to newly-revealed adjacent walls. + This final '+' may be omitted in burrow name args of commands above. + Digging 1-wide corridors with the miner inside the burrow is SLOW. + + changelayer =========== Changes material of the geology layer under cursor to the specified inorganic @@ -1829,6 +1659,129 @@ replicating the old channel digging designation. It also removes any and all 'down ramps' that can remain after a cave-in (you don't have to designate anything for that to happen). +.. _dig: + +dig +=== +This plugin makes many automated or complicated dig patterns easy. + +Basic commands: + +:digv: Designate all of the selected vein for digging. +:digvx: Also cross z-levels, digging stairs as needed. Alias for ``digv x``. +:digl: Like ``digv``, for layer stone. Also supports an ``undo`` option + to remove designations, for if you accidentally set 50 levels at once. +:diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. + +digexp +------ +This command is for :wiki:`exploratory mining `. + +There are two variables that can be set: pattern and filter. + +Patterns: + +:diag5: diagonals separated by 5 tiles +:diag5r: diag5 rotated 90 degrees +:ladder: A 'ladder' pattern +:ladderr: ladder rotated 90 degrees +:clear: Just remove all dig designations +:cross: A cross, exactly in the middle of the map. + +Filters: + +:all: designate whole z-level +:hidden: designate only hidden tiles of z-level (default) +:designated: Take current designation and apply pattern to it. + +After you have a pattern set, you can use ``expdig`` to apply it again. + +Examples: + +``expdig diag5 hidden`` + Designate the diagonal 5 patter over all hidden tiles +``expdig`` + Apply last used pattern and filter +``expdig ladder designated`` + Take current designations and replace them with the ladder pattern + +digcircle +--------- +A command for easy designation of filled and hollow circles. +It has several types of options. + +Shape: + +:hollow: Set the circle to hollow (default) +:filled: Set the circle to filled +:#: Diameter in tiles (default = 0, does nothing) + +Action: + +:set: Set designation (default) +:unset: Unset current designation +:invert: Invert designations already present + +Designation types: + +:dig: Normal digging designation (default) +:ramp: Ramp digging +:ustair: Staircase up +:dstair: Staircase down +:xstair: Staircase up/down +:chan: Dig channel + +After you have set the options, the command called with no options +repeats with the last selected parameters. + +Examples: + +``digcircle filled 3`` + Dig a filled circle with diameter = 3. +``digcircle`` + Do it again. + +digtype +------- +For every tile on the map of the same vein type as the selected tile, +this command designates it to have the same designation as the +selected tile. If the selected tile has no designation, they will be +dig designated. +If an argument is given, the designation of the selected tile is +ignored, and all appropriate tiles are set to the specified +designation. + +Options: + +:dig: +:channel: +:ramp: +:updown: up/down stairs +:up: up stairs +:down: down stairs +:clear: clear designation + +digFlood +======== +Automatically digs out specified veins as they are discovered. It runs once +every time a dwarf finishes a dig job. It will only dig out appropriate tiles +that are adjacent to the finished dig job. To add a vein type, use ``digFlood 1 [type]``. +This will also enable the plugin. To remove a vein type, use ``digFlood 0 [type] 1`` +to disable, then remove, then re-enable. + +Usage: + +:help digflood: detailed help message +:digFlood 0: disable the plugin +:digFlood 1: enable the plugin +:digFlood 0 MICROCLINE COAL_BITUMINOUS 1: + disable plugin, remove microcline and bituminous coal from monitoring, then re-enable the plugin +:digFlood CLEAR: remove all inorganics from monitoring +:digFlood digAll1: ignore the monitor list and dig any vein +:digFlood digAll0: disable digAll mode + +.. _feature: + feature ======= Enables management of map features. @@ -1844,6 +1797,26 @@ Options: :show X: Marks the selected map feature as discovered. :hide X: Marks the selected map feature as undiscovered. +.. _filltraffic: + +filltraffic +=========== +Set traffic designations using flood-fill starting at the cursor. +See also `alltraffic`, `restrictice`, and `restrictliquid`. Options: + +:H: High Traffic +:N: Normal Traffic +:L: Low Traffic +:R: Restricted Traffic +:X: Fill across z-levels. +:B: Include buildings and stockpiles. +:P: Include empty space. + +Example: + +``filltraffic H`` + When used in a room with doors, it will set traffic to HIGH in just that room. + .. _fortplan: fortplan @@ -1880,6 +1853,24 @@ All of the building designation uses `Planning Mode `, so you do n have the items available to construct all the buildings when you run fortplan with the .csv file. +getplants +========= +This tool allows plant gathering and tree cutting by RAW ID. Specify the types +of trees to cut down and/or shrubs to gather by their plant names, separated +by spaces. + +Options: + +:-t: Select trees only (exclude shrubs) +:-s: Select shrubs only (exclude trees) +:-c: Clear designations instead of setting them +:-x: Apply selected action to all plants except those specified (invert + selection) +:-a: Select every type of plant (obeys ``-t``/``-s``) + +Specifying both ``-t`` and ``-s`` will have no effect. If no plant IDs are specified, +all valid plant IDs will be listed. + infiniteSky =========== Automatically allocates new z-levels of sky at the top of the map as you build up, @@ -1968,6 +1959,43 @@ settings in liquids were made it paints a point of 7/7 magma by default). Intended to be used as keybinding. Requires an active in-game cursor. +plant +===== +A tool for creating shrubs, growing, or getting rid of them. + +Subcommands: + +:create: Creates a new sapling under the cursor. Takes a raw ID as argument + (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile. +:grow: Turns saplings into trees; under the cursor if a sapling is selected, + or every sapling on the map if the cursor is hidden. +:extirpate: Kills the tree or shrub under the cursor, instantly turning them to ashes. +:immolate: Sets the plants on fire instead. The fires can and *will* spread ;) + +For mass effects, use one of the additional options: + +:shrubs: affect all shrubs on the map +:trees: affect all trees on the map +:all: affect every plant! + +regrass +======= +Regrows all the grass. Not much to it ;) + +.. _restrictice: + +restrictice +=========== +Restrict traffic on all tiles on top of visible ice. +See also `alltraffic`, `filltraffic`, and `restrictliquid`. + +.. _restrictliquid: + +restrictliquid +============== +Restrict traffic on all visible tiles with liquid. +See also `alltraffic`, `filltraffic`, and `restrictice`. + .. _tiletypes: tiletypes @@ -2079,29 +2107,6 @@ Options: Beware that filling in hollow veins will trigger a demon invasion on top of your miner when you dig into the region that used to be hollow. -plant -===== -A tool for creating shrubs, growing, or getting rid of them. - -Subcommands: - -:create: Creates a new sapling under the cursor. Takes a raw ID as argument - (e.g. TOWER_CAP). The cursor must be located on a dirt or grass floor tile. -:grow: Turns saplings into trees; under the cursor if a sapling is selected, - or every sapling on the map if the cursor is hidden. -:extirpate: Kills the tree or shrub under the cursor, instantly turning them to ashes. -:immolate: Sets the plants on fire instead. The fires can and *will* spread ;) - -For mass effects, use one of the additional options: - -:shrubs: affect all shrubs on the map -:trees: affect all trees on the map -:all: affect every plant! - -regrass -======= -Regrows all the grass. Not much to it ;) - weather ======= Prints the current weather, and lets you change the weather to 'clear', 'rain' @@ -2252,49 +2257,32 @@ Options: Known limitations: if the selected unit is currently performing a job, the mood will not be started. - -Behavior Mods -============= -These plugins, when activated via configuration UI or by detecting certain -structures in RAWs, modify the game engine behavior concerning the target -objects to add features not otherwise present. - .. _siege-engine: siege-engine ------------- -Siege engines are a very interesting feature, but sadly almost useless in the current state -because they haven't been updated since 2D and can only aim in four directions. This is an -attempt to bring them more up to date until Toady has time to work on it. Actual improvements, -e.g. like making siegers bring their own, are something only Toady can do. +============ +Siege engines in DF haven't been updated since the game was 2D, and can +only aim in four directions. This plugin allows you to: -The siege-engine plugin enables siege engines to be linked to stockpiles, and -aimed at an arbitrary rectangular area across Z levels, instead of the original -four directions. Also, catapults can be ordered to load arbitrary objects, not -just stones. +* link siege engines to stockpiles +* load any object into a catapult, not just stones +* aim at a rectangular area in any direction, and across Z-levels -The configuration front-end to the plugin is implemented by `gui/siege-engine`. +The front-end is implemented by `gui/siege-engine`. .. _power-meter: power-meter ------------ +=========== The power-meter plugin implements a modified pressure plate that detects power being supplied to gear boxes built in the four adjacent N/S/W/E tiles. -The configuration front-end is implemented by `gui/power-meter`. Bind it to a -key (the example config uses :kbd:`Ctrl`:kbd:`Shift`:kbd:`M`) and activate after selecting Pressure Plate -in the build menu. - -.. image:: images/power-meter.png - -The script follows the general look and feel of the regular pressure plate build -configuration page, but configures parameters relevant to the modded power meter building. +The configuration front-end is implemented by `gui/power-meter`. .. _steam-engine: steam-engine ------------- +============ The steam-engine plugin detects custom workshops with STEAM_ENGINE in their token, and turns them into real steam engines. @@ -2303,34 +2291,29 @@ power, but windmills give relatively little power, and water wheels require flowing water, which must either be a real river and thus immovable and limited in supply, or actually flowing and thus laggy. -Steam engines are an alternative to water reactors that actually makes -sense, and hopefully doesn't lag. Also, unlike e.g. animal treadmills, -it can be done just by combining existing features of the game engine -in a new way with some glue code and a bit of custom logic. +Compared to the :wiki:`water reactor ` +exploit, steam engines make a lot of sense! Construction -~~~~~~~~~~~~ +------------ The workshop needs water as its input, which it takes via a passable floor tile below it, like usual magma workshops do. The magma version also needs magma. -Since this building is a machine, and machine collapse -code cannot be hooked, it would collapse over true open space. -As a loophole, down stairs provide support to machines, while -being passable, so use them. +Due to DFHack limits, the workshop will collapse over true open space. +However down stairs are passable but support machines, so you can use them. After constructing the building itself, machines can be connected to the edge tiles that look like gear boxes. Their exact position is extracted from the workshop raws. -Like with collapse above, part of the code involved in -machine connection cannot be hooked. As a result, the workshop +Like with collapse above, due to DFHack limits the workshop can only immediately connect to machine components built AFTER it. This also means that engines cannot be chained without intermediate axles built after both engines. Operation -~~~~~~~~~ +--------- In order to operate the engine, queue the Stoke Boiler job (optionally on repeat). A furnace operator will come, possibly bringing a bar of fuel, and perform it. As a result, a "boiling water" item will appear @@ -2364,7 +2347,7 @@ decrease it by further 4%, and also decrease the whole steam use rate by 10%. Explosions -~~~~~~~~~~ +---------- The engine must be constructed using barrel, pipe and piston from fire-safe, or in the magma version magma-safe metals. @@ -2374,7 +2357,7 @@ toppled during operation by a building destroyer, or a tantruming dwarf. Save files -~~~~~~~~~~ +---------- It should be safe to load and view engine-using fortresses from a DF version without DFHack installed, except that in such case the engines won't work. However actually making modifications @@ -2386,15 +2369,12 @@ being generated. .. _add-spatter: add-spatter ------------ +=========== This plugin makes reactions with names starting with ``SPATTER_ADD_`` produce contaminants on the items instead of improvements. The produced -contaminants are immune to being washed away by water or destroyed by -the `clean` ``items`` command. +contaminants are immune to being washed away by water or destroyed by `clean`. The plugin is intended to give some use to all those poisons that can -be bought from caravans. :) - -To be really useful this needs patches for :bug:`808`, ie `tweak` -``fix-dimensions`` and `tweak` ``advmode-contained``. +be bought from caravans. It's most useful when combined with +`tweak` ``fix-dimensions`` and ``advmode-contained`` to patch :bug:`808`. diff --git a/scripts/gui/power-meter.lua b/scripts/gui/power-meter.lua index 51908bd0f..ac10e5dc7 100644 --- a/scripts/gui/power-meter.lua +++ b/scripts/gui/power-meter.lua @@ -5,6 +5,15 @@ gui/power-meter =============== An in-game interface for `power-meter`. +Bind it to a key (default :kbd:`Ctrl`:kbd:`Shift`:kbd:`M`) and activate +after selecting Pressure Plate in the build menu. + +.. image:: /docs/images/power-meter.png + +The script follows the general look and feel of the regular pressure +plate build configuration page, but configures parameters relevant to +the modded power meter building. + =end]] local utils = require 'utils' local gui = require 'gui' From 3d801d45c6b2a1390271565c5acc775642e585fa Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 13:52:21 +1100 Subject: [PATCH 17/18] Flatten plugin documentation The obvious solution to not knowing how to categories plugins well is to do so a little less. This commit does not rearrange them though, since I thought that counterproductive without a better idea of what to do. - removed many headings that are not commands - fixed a few links and added some - clarified stockpiles plugins --- NEWS.rst | 20 ++--- docs/Plugins.rst | 205 +++++++++++++++++++++-------------------------- 2 files changed, 103 insertions(+), 122 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index 53be4c149..96412f671 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -103,7 +103,7 @@ Fixes - help: now recognizes built-in commands, like "help" - `manipulator`: fixed crash when selecting custom professions when none are found - `remotefortressreader`: fixed crash when attempting to send map info when no map was loaded -- `search`: fixed crash in unit list after cancelling a job; fixed crash when disabling stockpile category after searching in a subcategory +- `search-plugin`: fixed crash in unit list after cancelling a job; fixed crash when disabling stockpile category after searching in a subcategory - `stockpiles`: now checks/sanitizes filenames when saving - `stocks`: fixed a crash when right-clicking - `steam-engine`: fixed a crash on arena load; number keys (e.g. 2/8) take priority over cursor keys when applicable @@ -157,7 +157,7 @@ Misc Improvements - `prospect`: works from within command-prompt - `quicksave`: Restricted to fortress mode - `remotefortressreader`: Exposes more information -- `search`: +- `search-plugin`: - Supports noble suggestion screen (e.g. suggesting a baron) - Supports fortress mode loo[k] menu @@ -470,8 +470,8 @@ Misc Improvements - `EventManager`: deals with frame_counter getting reset properly now. - `modtools/item-trigger`: fixed equip/unequip bug and corrected minor documentation error - `teleport`: Updated with proper argument handling and proper unit-at-destination handling. -- `autotrade `: Removed the newly obsolete :guilabel:`Mark all` functionality. -- `search`: Adapts to the new trade screen column width +- `autotrade`: Removed the newly obsolete :guilabel:`Mark all` functionality. +- `search-plugin`: Adapts to the new trade screen column width - `tweak fast-trade `: Switching the fast-trade keybinding to Shift-Up/Shift-Down, due to Select All conflict @@ -486,8 +486,8 @@ Fixes ----- - Stopped duplicate load/unload events when unloading a world - Stopped ``-e`` from being echoed when DFHack quits on Linux -- `automelt `: now uses a faster method to locate items -- `autotrade `: "Mark all" no longer double-marks bin contents +- `automelt`: now uses a faster method to locate items +- `autotrade`: "Mark all" no longer double-marks bin contents - `drain-aquifer`: new script replaces the buggy plugin - `embark-tools`: no longer conflicts with keys on the notes screen - `fastdwarf`: Fixed problems with combat/attacks @@ -537,18 +537,18 @@ Internals New Plugins ----------- - `hotkeys`: Shows ingame viewscreen with all dfhack keybindings active in current mode. -- `automelt `: allows marking stockpiles so any items placed in them will be designated for melting +- `automelt`: allows marking stockpiles so any items placed in them will be designated for melting Fixes ----- - possible crash fixed for `gui/hack-wish` -- `search`: updated to not conflict with BUILDJOB_SUSPEND +- `search-plugin`: updated to not conflict with BUILDJOB_SUSPEND - `workflow`: job_material_category -> dfhack_material_category Misc Improvements ----------------- - now you can use ``@`` to print things in interactive Lua with subtley different semantics -- optimizations for stockpiles for `autotrade ` and `stockflow` +- optimizations for stockpiles for `autotrade` and `stockflow` - updated `exportlegends` to work with new maps, dfhack 40.11 r1+ @@ -561,7 +561,7 @@ Internals Fixes ----- - `3dveins`: should no longer hang/crash on specific maps -- `autotrade `, `search`: fixed some layout issues +- `autotrade`, `search-plugin`: fixed some layout issues - `deathcause`: updated - `gui/hack-wish`: should work now - `reveal`: no longer allocates data for nonexistent map blocks diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 91835cd35..7df79e625 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -12,9 +12,9 @@ hopefully organised in a way you will find useful. .. contents:: :depth: 3 -=========================== -Visualizers and data export -=========================== +=============================== +Data inspection and visualizers +=============================== .. _stonesense: @@ -64,10 +64,6 @@ An in-development plugin for realtime fortress visualisation. See :forums:`Armok Vision <146473>`. -============== -Map inspection -============== - cursecheck ========== Checks a single map tile or the whole map/world for cursed creatures (ghosts, @@ -346,13 +342,26 @@ UI Upgrades existing DF screens, they deliberately use red instead of green for the key. -DFHack Interface -================ +.. _automelt: + +automelt +======== +When automelt is enabled for a stockpile, any meltable items placed +in it will be designated to be melted. +This plugin adds an option to the :kbd:`q` menu when `enabled `. + +.. _autotrade: + +autotrade +========= +When autotrade is enabled for a stockpile, any items placed in it will be +designated to be taken to the Trade Depot whenever merchants are on the map. +This plugin adds an option to the :kbd:`q` menu when `enabled `. .. _command-prompt: command-prompt --------------- +============== An in-game DFHack terminal, where you can enter other commands. Best used from a keybinding; by default :kbd:`Ctrl`:kbd:`Shift`:kbd:`P`. @@ -371,7 +380,7 @@ Otherwise somewhat similar to `gui/quickcmd`. .. _hotkeys: hotkeys -------- +======= Opens an in-game screen showing which DFHack keybindings are active in the current context. @@ -384,7 +393,7 @@ keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. .. _rb_eval: rb_eval -------- +======= Evaluate the following arguments as a ruby string. Best used as ``:rb_eval [string]``, for the special parsing mode. @@ -443,6 +452,9 @@ The following mouse shortcuts are also available: Pressing :kbd:`Esc` normally returns to the unit screen, but :kbd:`Shift`:kbd:`Esc` would exit directly to the main dwarf mode screen. +.. comment - the link target "search" is reserved for the Sphinx search page +.. _search-plugin: + search ====== The search plugin adds search to the Stocks, Animals, Trading, Stockpile, @@ -482,20 +494,17 @@ only fat or tallow by forbidding fats, then searching for fat/tallow, and using Permit Fats again while the list is filtered. -Game interface -============== - .. _nopause: nopause -------- +======= Disables pausing (both manual and automatic) with the exception of pause forced by `reveal` ``hell``. This is nice for digging under rivers. .. _embark-tools: embark-tools ------------- +============ A collection of embark-related tools. Usage and available tools:: embark-tools enable/disable tool [tool]... @@ -508,7 +517,7 @@ A collection of embark-related tools. Usage and available tools:: :sticky: Maintains the selected local area while navigating the world map automaterial ------------- +============ This makes building constructions (walls, floors, fortifications, etc) a little bit easier by saving you from having to trawl through long lists of materials each time you place one. @@ -544,7 +553,7 @@ enabled materials, you should be able to place complex constructions more conven .. _buildingplan: buildingplan ------------- +============ When active (via ``enable buildingplan``), this plugin adds a planning mode for furniture placement. You can then place furniture and other buildings before the required materials are available, and the job will be unsuspended when @@ -558,7 +567,7 @@ with minimal space dedicated to stockpiles. .. _confirm: confirm -------- +======= Implements several confirmation dialogs for potentially destructive actions (for example, seizing goods from traders or deleting hauling routes). @@ -571,7 +580,7 @@ Usage: Enable (or disable) specific confirmation dialogues. follow ------- +====== Makes the game view follow the currently highlighted unit after you exit from the current menu or cursor mode. Handy for watching dwarves running around. Deactivated by moving the view manually. @@ -579,7 +588,7 @@ by moving the view manually. .. _mousequery: mousequery ----------- +========== Adds mouse controls to the DF interface, eg click-and-drag designations. Options: @@ -598,41 +607,38 @@ Usage:: .. _resume: resume ------- +====== Allows automatic resumption of suspended constructions, along with colored UI hints for construction status. tidlers -------- +======= Toggle between all possible positions where the idlers count can be placed. .. _trackstop: trackstop ---------- +========= Adds a :kbd:`q` menu for track stops, which is completely blank by default. This allows you to view and/or change the track stop's friction and dump direction settings, using the keybindings from the track stop building interface. twaterlvl ---------- +========= Toggle between displaying/not displaying liquid depth as numbers. .. _stocks: stocks ------- -An improved stocks screen. - -stockpile management --------------------- +====== +Replaces the DF stocks screen with an improved version. .. _stocksettings: .. _stockpiles: -import/export -~~~~~~~~~~~~~ -The following commands allow you to save and load stockpile settings. +stocksettings +============= +Offers the following commands to save and load stockpile settings. See `gui/stockpiles` for an in-game interface. :copystock: Copies the parameters of the currently highlighted stockpile to the custom @@ -656,27 +662,10 @@ Note that files are relative to the DF folder, so put your files there or in a subfolder for easy access. Filenames should not have spaces. Generated materials, divine metals, etc are not saved as they are different in every world. -.. _`Stockpile automation`: - -Stockpile automation -~~~~~~~~~~~~~~~~~~~~ - -Enable the autodump, automelt and autotrade plugins in your dfhack.init with:: - - enable autodump automelt autotrade - -When querying a stockpile, options will appear to toggle automation settings for this stockpile. - -When automelt is enabled for a stockpile, any meltable items placed in it will be designated -to be melted. When autotrade is enabled for a stockpile, any items placed in it will be -designated to be taken to the Trade Depot whenever merchants are on the map. -When autodump is enabled for a stockpile, any items placed in this stockpile will -automatically be designated to be dumped. - .. _rename: rename ------- +====== Allows renaming various things. Use `gui/rename` for an in-game interface. Options: @@ -698,10 +687,9 @@ Options: .. _rendermax: rendermax ---------- +========= A collection of renderer replacing/enhancing filters. For better effect try changing the -black color in palette to non totally black. For more info see -`the Bay12 Rendermax thread `_. +black color in palette to non totally black. See :forums:`128487` for more info. Options: @@ -798,7 +786,9 @@ Examples: .. _autohauler: autohauler ----------- +========== +Autohauler is an autolabor fork. + Rather than the all-of-the-above means of autolabor, autohauler will instead only manage hauling labors and leave skilled labors entirely to the user, who will probably use Dwarf Therapist to do so. @@ -817,13 +807,10 @@ being assigned when the skill is present. By default this is the unused ALCHEMIST labor but can be changed by the user. -Job management -============== - .. _job: job ---- +=== Command for general job query and manipulation. Options: @@ -839,8 +826,8 @@ Options: Replace the exact item type id in the job item. job-material ------------- -Alter the material of the selected job. +============ +Alter the material of the selected job. Similar to ``job item-material ...`` Invoked as:: @@ -855,19 +842,19 @@ Intended to be used as a keybinding: over the first available choice with the matching material. job-duplicate -------------- -Duplicate the selected job in a workshop: - -* In :kbd:`q` mode, when a job is highlighted within a workshop or furnace building, - instantly duplicates the job. +============= +In :kbd:`q` mode, when a job is highlighted within a workshop or furnace +building, calling ``job-duplicate`` instantly duplicates the job. .. _stockflow: stockflow ---------- +========= Allows the fortress bookkeeper to queue jobs through the manager, based on space or items available in stockpiles. +Inspired by `workflow`. + Usage: ``stockflow enable`` @@ -896,11 +883,9 @@ waiting for the bookkeeper. .. _workflow: workflow --------- -Manage control of repeat jobs. - -Check out `gui/workflow` for a simple front-end integrated -in the game UI. +======== +Manage control of repeat jobs. `gui/workflow` provides a simple +front-end integrated in the game UI. Usage: @@ -928,7 +913,7 @@ Usage: Delete all constraints. Function -~~~~~~~~ +-------- When the plugin is enabled, it protects all repeat jobs from removal. If they do disappear due to any cause, they are immediately re-added to their workshop and suspended. @@ -940,15 +925,14 @@ the amount has to drop before jobs are resumed; this is intended to reduce the frequency of jobs being toggled. Constraint format -~~~~~~~~~~~~~~~~~ +----------------- The constraint spec consists of 4 parts, separated with ``/`` characters:: ITEM[:SUBTYPE]/[GENERIC_MAT,...]/[SPECIFIC_MAT:...]/[LOCAL,] The first part is mandatory and specifies the item type and subtype, -using the raw tokens for items, in the same syntax you would e.g. use -for a custom reaction input. For more information, see -`this page. `_ +using the raw tokens for items (the same syntax used custom reaction inputs). +For more information, see :wiki:`this wiki page `. The subsequent parts are optional: @@ -967,7 +951,7 @@ The subsequent parts are optional: be used to ignore imported items or items below a certain quality. Constraint examples -~~~~~~~~~~~~~~~~~~~ +------------------- Keep metal bolts within 900-1000, and wood/bone within 150-200:: workflow amount AMMO:ITEM_AMMO_BOLTS/METAL 1000 100 @@ -1005,7 +989,7 @@ Make sure there are always 80-100 units of dimple dye:: .. note:: In order for this to work, you have to set the material of the PLANT input - on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the `job` ``item-material`` + on the Mill Plants job to MUSHROOM_CUP_DIMPLE using the `job item-material ` command. Otherwise the plugin won't be able to deduce the output material. Maintain 10-100 locally-made crafts of exceptional quality:: @@ -1013,13 +997,10 @@ Maintain 10-100 locally-made crafts of exceptional quality:: workflow count CRAFTS///LOCAL,EXCEPTIONAL 100 90 -Cleanup and garbage disposal -============================ - .. _clean: clean ------ +===== Cleans all the splatter that get scattered all over the map, items and creatures. In an old fortress, this can significantly reduce FPS lag. It can also spoil your !!FUN!!, so think before you use it. @@ -1036,15 +1017,19 @@ Extra options for ``map``: :snow: Also remove snow coverings. spotclean ---------- +========= Works like ``clean map snow mud``, but only for the tile under the cursor. Ideal if you want to keep that bloody entrance ``clean map`` would clean up. .. _autodump: autodump --------- -This utility lets you quickly move all items designated to be dumped. +======== +This plugin adds an option to the :kbd:`q` menu for stckpiles when `enabled `. +When autodump is enabled for a stockpile, any items placed in the stockpile will +automatically be designated to be dumped. + +ALternatively, you can use it to quickly move all items designated to be dumped. Items are instantly moved to the cursor position, the dump flag is unset, and the forbid flag is set, as if it had been dumped normally. Be aware that any active dump item tasks still point at the item. @@ -1054,18 +1039,17 @@ Cursor must be placed on a floor tile so the items can be dumped there. Options: :destroy: Destroy instead of dumping. Doesn't require a cursor. -:destroy-here: Destroy items only under the cursor. Alias ``autodump-destroy-here``, for keybindings. + If called again before the game is resumed, cancels destroy. +:destroy-here: As ``destroy``, but only the selected item in the :kbd:`k` list, + or inside a container. + Alias ``autodump-destroy-here``, for keybindings. :visible: Only process items that are not hidden. :hidden: Only process hidden items. :forbidden: Only process forbidden items (default: only unforbidden). -autodump-destroy-item -~~~~~~~~~~~~~~~~~~~~~ -Destroy the selected item. The item may be selected in the :kbd:`k` list, or inside -a container. If called again before the game is resumed, cancels destroy. cleanowned ----------- +========== Confiscates items owned by dwarfs. By default, owned food on the floor and rotten items are confistacted and dumped. @@ -1085,13 +1069,10 @@ Example: worn items with 'X' damage and above. -Fortress activity management -============================ - .. _dwarfmonitor: dwarfmonitor ------------- +============ Records dwarf activity to measure fort efficiency. Options: @@ -1164,13 +1145,13 @@ Some widgets support additional options: nothing will be displayed. workNow -------- +======= Force all dwarves to look for a job immediately, or as soon as the game is unpaused. .. _seedwatch: seedwatch ---------- +========= Watches the numbers of seeds available and enables/disables seed and plant cooking. Each plant type can be assigned a limit. If their number falls below that limit, @@ -1200,7 +1181,7 @@ Examples: .. _zone: zone ----- +==== Helps a bit with managing activity zones (pens, pastures and pits) and cages. Options: @@ -1256,7 +1237,7 @@ Filters: :milkable: Race is milkable. Negatable. Usage with single units -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- One convenient way to use the zone tool is to bind the command 'zone assign' to a hotkey, maybe also the command 'zone set'. Place the in-game cursor over a pen/pasture or pit, use 'zone set' to mark it. Then you can select units @@ -1265,7 +1246,7 @@ and use 'zone assign' to assign them to their new home. Allows pitting your own dwarves, by the way. Usage with filters -~~~~~~~~~~~~~~~~~~ +------------------ All filters can be used together with the 'assign' command. Restrictions: It's not possible to assign units who are inside built cages @@ -1286,14 +1267,14 @@ are not properly added to your own stocks; slaughtering them should work). Most filters can be negated (e.g. 'not grazer' -> race is not a grazer). Mass-renaming -~~~~~~~~~~~~~ +------------- Using the 'nick' command you can set the same nickname for multiple units. If used without 'assign', 'all' or 'count' it will rename all units in the current default target zone. Combined with 'assign', 'all' or 'count' (and further optional filters) it will rename units matching the filter conditions. Cage zones -~~~~~~~~~~ +---------- Using the 'tocages' command you can assign units to a set of cages, for example a room next to your butcher shop(s). They will be spread evenly among available cages to optimize hauling to and butchering from them. For this to work you need @@ -1304,7 +1285,7 @@ would make no sense, but can be used together with 'nick' or 'remnick' and all the usual filters. Examples -~~~~~~~~ +-------- ``zone assign all own ALPACA minage 3 maxage 10`` Assign all own alpacas who are between 3 and 10 years old to the selected pasture. @@ -1327,7 +1308,7 @@ Examples on the current default zone. autonestbox ------------ +=========== Assigns unpastured female egg-layers to nestbox zones. Requires that you create pen/pasture zones above nestboxes. If the pen is bigger than 1x1 the nestbox must be in the top left corner. Only 1 unit will be assigned per pen, regardless @@ -1349,7 +1330,7 @@ Options: .. _autobutcher: autobutcher ------------ +=========== Assigns lifestock for slaughter once it reaches a specific count. Requires that you add the target race(s) to a watch list. Only tame units will be processed. @@ -1441,7 +1422,7 @@ add some new races with 'watch'. If you simply want to stop it completely use autobutcher unwatch ALPACA CAT autochop ---------- +======== Automatically manage tree cutting designation to keep available logs withing given quotas. @@ -1674,7 +1655,7 @@ Basic commands: :diglx: Also cross z-levels, digging stairs as needed. Alias for ``digl x``. digexp ------- +====== This command is for :wiki:`exploratory mining `. There are two variables that can be set: pattern and filter. @@ -1706,7 +1687,7 @@ Examples: Take current designations and replace them with the ladder pattern digcircle ---------- +========= A command for easy designation of filled and hollow circles. It has several types of options. @@ -1742,7 +1723,7 @@ Examples: Do it again. digtype -------- +======= For every tile on the map of the same vein type as the selected tile, this command designates it to have the same designation as the selected tile. If the selected tile has no designation, they will be @@ -2291,7 +2272,7 @@ power, but windmills give relatively little power, and water wheels require flowing water, which must either be a real river and thus immovable and limited in supply, or actually flowing and thus laggy. -Compared to the :wiki:`water reactor ` +Compared to the :wiki:`water reactor ` exploit, steam engines make a lot of sense! Construction From 6dacbe3d9f4401e1b4affacd9403fca0f6fbcfc6 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Sat, 7 Nov 2015 16:59:11 +1100 Subject: [PATCH 18/18] Add docs for "sort" and "diggingInvaders" plugins I don't know how these were missed, but I've now checked everything listed by "plug" but not (previously) a heading in Plugins.rst --- docs/Core.rst | 4 +- docs/Plugins.rst | 101 ++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 85 insertions(+), 20 deletions(-) diff --git a/docs/Core.rst b/docs/Core.rst index 17b6d3174..51d0ec955 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -237,7 +237,7 @@ The following commands are *not* built-in, but offer similarly useful functions. * `multicmd` * `nopause` * `quicksave` -* `rb_eval` +* `rb` * `repeat` @@ -350,7 +350,7 @@ This section is for odd but important notes that don't fit anywhere else. double quotes. To include a double quote character, use ``\"``. * If the first non-whitespace character is ``:``, the command is parsed in - an alternative mode which is very useful for the `lua` and `rb_eval` commands. + an alternative mode which is very useful for the `lua` and `rb` commands. The following two command lines are exactly equivalent:: :foo a b "c d" e f diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 7df79e625..3b8b7d132 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -370,7 +370,7 @@ Usage: ``command-prompt [entry]`` If called with an entry, it starts with that text filled in. Most useful for developers, who can set a keybinding to open a laungage interpreter for lua or Ruby by starting with the -`:lua ` or `:rb_eval ` commands. +`:lua ` or `:rb ` commands. Otherwise somewhat similar to `gui/quickcmd`. @@ -390,12 +390,12 @@ Type ``hotkeys`` into the DFHack console to open the screen, or bind the command to a globally active hotkey. The default keybinding is :kbd:`Ctrl`:kbd:`F1`. See also `hotkey-notes`. -.. _rb_eval: +.. _rb: -rb_eval -======= -Evaluate the following arguments as a ruby string. Best used as -``:rb_eval [string]``, for the special parsing mode. +rb +== +Ruby language plugin, which evaluates the following arguments as a ruby string. +Best used as ``:rb [string]``, for the special parsing mode. Alias ``rb_eval``. .. _manipulator: @@ -627,6 +627,42 @@ twaterlvl ========= Toggle between displaying/not displaying liquid depth as numbers. +.. _sort-items: + +sort-items +========== +Sort the visible item list:: + + sort-items order [order...] + +Sort the item list using the given sequence of comparisons. +The ``<`` prefix for an order makes undefined values sort first. +The ``>`` prefix reverses the sort order for defined values. + +Item order examples:: + + description material wear type quality + +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` + +.. _sort-units: + +sort-units +========== +Sort the visible unit list:: + + sort-units order [order...] + +Sort the unit list using the given sequence of comparisons. +The ``<`` prefix for an order makes undefined values sort first. +The ``>`` prefix reverses the sort order for defined values. + +Unit order examples:: + + name age arrival squad squad_position profession + +The orderings are defined in ``hack/lua/plugins/sort/*.lua`` + .. _stocks: stocks @@ -2099,6 +2135,15 @@ or 'snow', with those words as commands (eg ``weather rain``). Mods and Cheating ================= +.. _add-spatter: + +add-spatter +=========== +This plugin makes reactions with names starting with ``SPATTER_ADD_`` +produce contaminants on the items instead of improvements. The plugin is +intended to give some use to all those poisons that can be bought from caravans, +so they're immune to being washed away by water or destroyed by `clean`. + .. _adv-bodyswap: adv-bodyswap @@ -2153,6 +2198,38 @@ Options: :building: Subsequent items will become part of the currently selected building. Good for loading traps; do not use with workshops (or deconstruct to use the item). +.. _diggingInvaders: + +diggingInvaders +=============== +Makes invaders dig or destroy constructions to get to your dwarves. + +To enable/disable the pluging, use: ``diggingInvaders (1|enable)|(0|disable)`` + +Basic usage: + +:add GOBLIN: registers the race GOBLIN as a digging invader. Case-sensitive. +:remove GOBLIN: unregisters the race GOBLIN as a digging invader. Case-sensitive. +:now: makes invaders try to dig now, if plugin is enabled +:clear: clears all digging invader races +:edgesPerTick n: makes the pathfinding algorithm work on at most n edges per tick. + Set to 0 or lower to make it unlimited. + +You can also use ``diggingInvaders setCost (race) (action) n`` to set the +pathing cost of particular action, or ``setDelay`` to set how long it takes. +Costs and delays are per-tile, and the table shows default values. + +============================== ======= ====== ================================= +Action Cost Delay Notes +============================== ======= ====== ================================= +``walk`` 1 0 base cost in the path algorithm +``destroyBuilding`` 2 1,000 delay adds to the job_completion_timer of destroy building jobs that are assigned to invaders +``dig`` 10,000 1,000 digging soil or natural stone +``destroyRoughConstruction`` 1,000 1,000 constructions made from boulders +``destroySmoothConstruction`` 100 100 constructions made from blocks or bars +============================== ======= ====== ================================= + + .. _fastdwarf: fastdwarf @@ -2347,15 +2424,3 @@ can easily result in inconsistent state once this plugin is available again. The effects may be as weird as negative power being generated. -.. _add-spatter: - -add-spatter -=========== -This plugin makes reactions with names starting with ``SPATTER_ADD_`` -produce contaminants on the items instead of improvements. The produced -contaminants are immune to being washed away by water or destroyed by `clean`. - -The plugin is intended to give some use to all those poisons that can -be bought from caravans. It's most useful when combined with -`tweak` ``fix-dimensions`` and ``advmode-contained`` to patch :bug:`808`. -