Document devel scripts

scripts/devel/about.txt

@@ -1,2 +1,6 @@
-``devel/*`` scripts are intended for developers, or still substantially unfinished.
+``devel/*`` scripts are intended for developer use, but many may
-If you don't already know what they do, best to leave them alone.
+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.

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"

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]

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'

scripts/devel/find-offsets.lua

@@ -1,19 +1,39 @@
 -- Find some offsets for linux.
+--[[=begin
 
-local utils = require 'utils'
+devel/find-offsets
-local ms = require 'memscan'
+==================
-local gui = require 'gui'
+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
+* global names to force finding them
-    * 'all' to force all globals
+* ``all`` to force all globals
-    * 'nofeed' to block automated fake input searches
+* ``nofeed`` to block automated fake input searches
-    * 'nozoom' to disable neighboring object heuristics
+* ``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
 

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
+devel/inject-raws
--- the right order, but all details are read from raws every time.
+=================
--- This allows just adding stub definitions, and simply saving and
+WARNING: THIS SCRIPT CAN PERMANENLY DAMAGE YOUR SAVE.
--- reloading the game.
 
--- Usage example:
+This script attempts to inject new raw objects into your
---[[
+world. If the injected references do not match the actual
-devel/inject-raws trapcomp ITEM_TRAPCOMP_STEAM_PISTON workshop STEAM_ENGINE MAGMA_STEAM_ENGINE reaction STOKE_BOILER
+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'
 

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'

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'

scripts/devel/list-filters.lua

@@ -1,6 +1,12 @@
 -- List input items for the building currently being built.
---
+--[[=begin
--- This is where the filters in lua/dfhack/buildings.lua come from.
+
+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'

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' }

scripts/devel/lua-example.lua

@@ -1,6 +0,0 @@
--- Example of a lua script.
-
-run_count = (run_count or 0) + 1
-
-print('Arguments: ',...)
-print('Command called '..run_count..' times.')

scripts/devel/nuke-items.lua

@@ -1,6 +1,12 @@
 -- Deletes ALL items not held by units, buildings or jobs.
---
+--[[=begin
--- Intended solely for lag investigation.
+
+devel/nuke-items
+================
+Deletes ALL items not held by units, buildings or jobs.
+Intended solely for lag investigation.
+
+=end]]
 
 local count = 0
 

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())

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'
 

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

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")

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
 

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 <<EOS
-Arena spawn data initialized.
+=begin
 
-Now enter the 'k' menu, change mode using:
+devel/spawn-unit-helper
-  rb_eval df.gametype = :DWARF_ARENA
+=======================
+Setup stuff to allow arena creature spawn after a mode change.
 
-spawn creatures ('c' ingame),
+With Arena spawn data initialized:
 
-revert to game mode using:
+- enter the :kbd:`k` menu and change mode using
-  rb_eval df.gametype = #{df.gametype.inspect}
+  ``rb_eval df.gametype = :DWARF_ARENA``
 
-To convert spawned creatures to livestock, select each one with the 'v' menu, and enter:
+- spawn creatures (:kbd:`c` ingame)
-  rb_eval df.unit_find.civ_id = df.ui.civ_id
 
+- revert to game mode using ``rb_eval df.gametype = #{df.gametype.inspect}``
+
+- To convert spawned creatures to livestock, select each one with
+  the :kbd:`v` menu, and enter ``rb_eval df.unit_find.civ_id = df.ui.civ_id``
+
+=end
 EOS

scripts/devel/test-perlin.lua

@@ -1,4 +1,13 @@
 -- Generates an image using multiple octaves of perlin noise.
+--[[=begin
+
+devel/test-perlin
+=================
+Generates an image using multiple octaves of perlin noise.
+
+Used by `3dveins`?
+
+=end]]
 
 local args = {...}
 local rng = dfhack.random.new(3)

scripts/devel/unforbidall.rb

@@ -1,3 +1,10 @@
 # unforbid all items
+=begin
+
+devel/unforbidall
+=================
+Unforbid all items.
+
+=end
 
 df.world.items.all.each { |i| i.flags.forbid = false }

scripts/devel/unit-path.lua

@@ -1,4 +1,11 @@
 -- Show the internal path a unit is currently following.
+--[[=begin
+
+devel/unit-path
+===============
+Show the internal path a unit is currently following.
+
+=end]]
 
 local utils = require 'utils'
 local gui = require 'gui'

scripts/devel/watch-minecarts.lua

@@ -1,4 +1,13 @@
 -- Logs minecart coordinates and speeds to console.
+--[[=begin
+
+devel/watch-minecarts
+=====================
+Logs minecart coordinates and speeds to console.
+
+Usage:  ``devel/watch-minecarts start|stop``
+
+=end]]
 
 last_stats = last_stats or {}