game-lua-injection

game-lua-injection

A DSH skill + gate kit for injecting Lua/Luau into Unity + XLua games and reading runtime state without touching process memory.

Instead of scanning memory for values (fragile, offset-dependent, often blocked), this approach replaces the Lua bytecode package the game loads anyway. Your code then runs inside the game's own Lua VM and reads the game's own authoritative values.

The trade-off: you must obey the game's bytecode rules exactly. Most of this repo is those rules and what violating them costs you.

What's in here

SKILL.md                        the skill itself: iron rules, workflow, methodology
references/
  workflow.md                   injection chain, gates, iteration rhythm
  opcode-remap.md               remapping theory, the four forbidden opcodes, AUX traps
  xlua-reflection.md            what XLua reflection can and cannot do
  attribution-patterns.md       attributing value changes to a source, cross-validation
  pitfalls.md                   14 classes of crash / hang / silent failure
  case-study.md                 a complete abstracted walk-through (placeholders)
scripts/
  gate.py                       one CLI: lint / compile / remap / forbidden / bootstrap / structure / all
  luau_bc.py                    Luau bytecode parser (AUX-aware instruction walk)
  bc_remap.py                   opcode remapping (flags + numbering shift) with selftest
  lint_payload_src.py           source pre-flight (forbidden constructs, bootstrap requires, BOM)
  doctor.py                     environment self-check (compiler / payload / staging / gates)
  gate.example.json             config template

Install

cp -r game-lua-injection ~/.dsh/skills/

Then the skill is available by name. Alternatively just read SKILL.md — nothing here is DSH-specific except the install path.

The six rules that matter

1. No .., no {}, no for-in in the payload. They compile to CONCAT / NEWTABLE / FORGLOOP, whose encodings differ on the game side → wrong values or a black screen.
2. Reproduce the bootstrap require(...) chain of the segment you replace. Miss one and every later module gets nil.
3. Never rewrite the .lua source wholesale (especially with PowerShell). ANSI/UTF-8 mismatch mangles non-ASCII and swallows newlines, silently commenting out require and local lines. It still compiles.
4. Never use # on a C# array exposed through XLua. It recurses into a stack overflow that pcall cannot catch.
5. Don't call Debug.Log per line. Each call appends a full C# stack trace; per-frame logging exhausts the allocator and the client hangs.
6. Run the gates every time. They exist because each of the above has burned a full build cycle.

Quick start

python scripts/doctor.py --root <your project root>

cp scripts/gate.example.json <your project>/gate.json
# edit paths, remap numbers, bootstrap module names
python scripts/gate.py all --config <your project>/gate.json

Every step aborts the chain on failure and prints do not ship this payload.

Calibration is mandatory

luau_bc.py's OPNAMES table matches one specific Luau version, and the remap shift is derived empirically. After a compiler or game update, re-calibrate:

• gate.py structure <file> --game-numbering → any unknown opcodes means the table or shift is wrong
• bc_remap.py --selftest (with GATE_SELFTEST_PKG, GATE_SELFTEST_TMP, GATE_COMPILER set) compares our output against a block the game itself compiled

Acceptance criterion: same source, compiled by us vs by the game, must be byte-identical after remapping. Anything less is luck.

Scope

This is for single-player, offline, or self-hosted setups and for research on your own copy of a game. Using it against live online services to gain an advantage generally violates those services' terms and may be unlawful where you live — that's on you, not on this repo.

The skill contains no game assets, no proprietary code, and no credentials. All example identifiers are placeholders.

Acknowledgements

• The Luau bytecode format and VM are by Roblox Corporation (MIT). luau_bc.py is an independent parser for that format.
• Nothing here is affiliated with or endorsed by any game developer or publisher.

License

MIT — see LICENSE.