Document devel scripts

develop
PeridexisErrant 2015-11-04 23:14:10 +11:00
parent 58e6ef6524
commit 5018af9a9e
22 changed files with 210 additions and 43 deletions

@ -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.

@ -1,6 +1,14 @@
--all-bob.lua --all-bob.lua
--author expwnent --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 for _,v in ipairs(df.global.world.units.all) do
v.name.first_name = "Bob" v.name.first_name = "Bob"

@ -1,5 +1,13 @@
-- Lists and/or compares two tiletype material groups. -- 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 nmat1,nmat2=...
local mat1 = df.tiletype_material[nmat1] local mat1 = df.tiletype_material[nmat1]

@ -1,4 +1,11 @@
-- Exports an ini file for Dwarf Therapist. -- 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 utils = require 'utils'
local ms = require 'memscan' local ms = require 'memscan'

@ -1,19 +1,39 @@
-- Find some offsets for linux. -- 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: 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 local is_known = dfhack.internal.getAddress

@ -1,14 +1,26 @@
-- Injects new reaction, item and building defs into the world. -- 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' local utils = require 'utils'

@ -1,4 +1,11 @@
-- Read the tiles from the screen and display info about them. -- 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 utils = require 'utils'
local gui = require 'gui' local gui = require 'gui'

@ -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 gui = require 'gui'
local guidm = require 'gui.dwarfmode' local guidm = require 'gui.dwarfmode'
local render = require 'plugins.rendermax' local render = require 'plugins.rendermax'

@ -1,6 +1,12 @@
-- List input items for the building currently being built. -- 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 dumper = require 'dumper'
local utils = require 'utils' local utils = require 'utils'

@ -1,4 +1,11 @@
-- Prints memory ranges of the process. -- Prints memory ranges of the process.
--[[=begin
devel/lsmem
===========
Prints memory ranges of the process.
=end]]
for _,v in ipairs(dfhack.internal.getMemRanges()) do for _,v in ipairs(dfhack.internal.getMemRanges()) do
local access = { '-', '-', '-', 'p' } local access = { '-', '-', '-', 'p' }

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

@ -1,6 +1,12 @@
-- Deletes ALL items not held by units, buildings or jobs. -- 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 local count = 0

@ -1,3 +1,10 @@
-- For killing bugged out gui script screens. -- 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()) dfhack.screen.dismiss(dfhack.gui.getCurViewscreen())

@ -1,4 +1,16 @@
-- Prepare the current save for use with devel/find-offsets. -- 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' local utils = require 'utils'

@ -1,6 +1,13 @@
--print-args.lua --print-args.lua
--author expwnent --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 = {...} local args = {...}
for _,arg in ipairs(args) do for _,arg in ipairs(args) do

@ -1,6 +1,13 @@
--print-args2.lua --print-args2.lua
--author expwnent --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 = {...} local args = {...}
print("print-args") print("print-args")

@ -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 tg = df.item_find
raise 'select an item' if not tg raise 'select an item' if not tg

@ -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 df.world.arena_spawn.creature_cnt[df.world.arena_spawn.race.length-1] = 0
puts <<EOS 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 EOS

@ -1,4 +1,13 @@
-- Generates an image using multiple octaves of perlin noise. -- 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 args = {...}
local rng = dfhack.random.new(3) local rng = dfhack.random.new(3)

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

@ -1,4 +1,11 @@
-- Show the internal path a unit is currently following. -- 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 utils = require 'utils'
local gui = require 'gui' local gui = require 'gui'

@ -1,4 +1,13 @@
-- Logs minecart coordinates and speeds to console. -- 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 {} last_stats = last_stats or {}