From 5018af9a9e2644f951d7281644ee422d79e6dae4 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Wed, 4 Nov 2015 23:14:10 +1100 Subject: [PATCH] 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 <