Skip to content

devel/datamine: runtime data mining tool - #1635

Open
Alistair-Afton wants to merge 1 commit into
DFHack:masterfrom
Alistair-Afton:devel-datamine
Open

Alistair-Afton wants to merge 1 commit into
DFHack:masterfrom
Alistair-Afton:devel-datamine

Conversation

@Alistair-Afton

Copy link
Copy Markdown

Summary

  • Adds devel/datamine, a developer tool for observing live game state when writing scripts or reverse-engineering structures.
  • watch [-n name] [-i frames] <expr>: polls a Lua expression each frame and prints old -> new to the DFHack console when it changes. Watches persist across invocations (script env), run via repeat-util, and are cleared on world unload.
  • snap <name> <expr> / diff <name>: records a deep snapshot of every field reachable from the expression's result, then reports which paths changed -- the classic "do X, see what moved" workflow.
  • find <expr> <substring>: prints paths of fields whose name or value matches.
  • All walks are depth-capped (5), per-container capped (200 elements), leaf-capped (20000), cycle-safe via object addresses, and every field access is pcall-guarded.
  • Nothing runs unless a command is invoked; nothing is enabled by default.

Test plan

  • watch registers, polls per-frame even while paused, prints on change, unwatch/unwatch all stop it
  • snap on unit.name (19 fields), unit.status (2638 fields), units.active (20011 fields, leaf-capped)
  • diff catches a written field (.nickname -> ZZTEST) and a stress write (.souls[0].personality.stress: 13486 -> 99999)
  • find matches field-name substrings and value substrings, descends into containers
  • error paths: bad expression at watch time, nonexistent watch name, unknown subcommand
  • devel/datamine help renders the embedded doc

A runtime data mining tool for script development and reverse
engineering:

- watch: poll a lua expression each frame and print when its value
  changes
- snap/diff: deep-record a structure's fields, then report which
  paths changed after doing something in-game
- find: list field paths whose name or value matches a substring

Walks are depth-, length-, and leaf-capped, cycle-safe, and all field
access is guarded. Watches run via repeat-util on frame timeouts and
are cleared on world unload.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant