morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 07:47:29 +00:00

[GH-ISSUE #2363] [Feature] Agent guidance for custom archives through user-installed QuickBMS #782

New issue

Open

opened 2026-10-15 18:28:18 +00:00 by bsakaguchi · 2 comments

bsakaguchi commented

2026-10-15 18:28:18 +00:00

Owner

Originally created by @dot-mike on GitHub (Oct 12, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2363

Before submitting

I searched the open and closed issues and pull requests for a related proposal.
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This request does not include credentials, private samples, or sensitive target data.

Area

Documentation

Current limitation

Many games and some applications keep their data in custom archives such as
.pak, .big, .arc, .tiger or .dat. No REA tool parses them. Today an
agent using REA has no guidance for these files. It either stops, or it writes
an ad hoc parser without the checks that tell a correct layout from one that
only runs.

QuickBMS is the common tool for these formats. A .bms script describes the
header, file table, names, offsets, sizes and compression, and QuickBMS lists,
extracts or repacks the entries. QuickBMS runs scripts as programs:
ComType EXECUTE and -S start external programs, and CallDLL loads native
code.

Use cases

List and extract a game archive whose layout is undocumented, for example a
Capcom RE Engine KPKA pak or a Crystal Dynamics TAFS (.tiger) archive.
Read a script someone else published and find out what it does before
running it.
Turn a layout found with REA's native analysis of the loader into a script
the user can run.

Desired outcome and success criteria

Documentation and skill guidance only. No new tool, provider or dependency.

The skill routes custom archives to a QuickBMS reference.
The agent identifies the file with REA first, looks for an existing script,
and otherwise works out the layout from the bytes and from the loader code.
The agent checks each field against the real file: the table ends where the
data starts, entries stay inside the file, and compressed entries inflate to
their declared size.
The agent reads any script it did not write and reports ComType EXECUTE,
CallDLL, Include, encryption commands and writes to real files before a
run, and asks for approval when a script starts other programs.
The report marks each field as observed, inferred or unknown.
User docs say QuickBMS is user-installed, and how to list, extract and
repack.

Expected interaction with targets

Read existing files or captured data, Inject instrumentation or run scripts/code, Write or change files/configuration

Target and scope details

REA does not ship, install or run QuickBMS. The user installs it and decides
where it runs. The agent may run the user's QuickBMS when its environment
allows that, or hand over the commands.
"Run scripts" is QuickBMS running a .bms script, which can start other
programs. The guidance requires reading the script first and asking before
running one that starts programs.
"Write files" is extraction into a new empty folder, and repacking into an
archive only when the user asks, on a backup copy.
Non-goals: decrypting archives, shipping keys or name lists, fetching the
Oodle library, or a QuickBMS provider or MCP tool.

Verification available so far

I have a prototype or observed results

Verification details

A branch ready for a draft PR adds references/quickbms.md to the skill and docs/quickbms.md.
Checks run locally on copies of games I own. No samples are shared.

Scripts written by agents following the guide, run in QuickBMS 0.12:
- RE2 re_chunk_000.pak.patch_001.pak: 331 entries, 1,338,018,368 bytes
  extracted, equal to the sums of the pak's own table.
- Tomb Raider (2013) jcontent.000.tiger: 177 entries, 17,801,867 bytes,
  equal to the table. Coverage is 23% because the file holds data the table
  does not point to. The guide covers that case.
- Heroes of Might and Magic III H3bitmap.lod: 2,008 entries,
  89,171,848 bytes, equal to the table.
Asked to run a published script that uses ComType EXECUTE, the agent did
not run it, named the external program and asked for approval.
npm run docs:check and npm run docs:build pass.

Alternatives considered

An REA archive reader per format. Each needs its own design and review, and
covers one format. This guidance covers the long tail and can sit beside
later readers.
A QuickBMS provider that REA runs. That is a larger execution-authority
question and is not proposed here.

Possible direction

.agents/skills/reverse-engineer-anything/references/quickbms.md: workflow,
script review, layout checks, common patterns (sector offsets, packed
offsets, hashed names, split archives, per-entry codecs), list, extract,
repack and limits.
One routing line and one guide link in the skill.
docs/quickbms.md, a ## QuickBMS section in docs/installation.md, a
README table row and a docs sidebar entry.

References

QuickBMS: https://aluigi.altervista.org/quickbms.htm (GPL-2.0)
QuickBMS manual, section 3 (reimport) and section 4 (script language), in
quickbms.txt inside the download

Originally created by @dot-mike on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2363 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related proposal. - [x] I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. - [x] This request does not include credentials, private samples, or sensitive target data. ### Area Documentation ### Current limitation Many games and some applications keep their data in custom archives such as `.pak`, `.big`, `.arc`, `.tiger` or `.dat`. No REA tool parses them. Today an agent using REA has no guidance for these files. It either stops, or it writes an ad hoc parser without the checks that tell a correct layout from one that only runs. QuickBMS is the common tool for these formats. A `.bms` script describes the header, file table, names, offsets, sizes and compression, and QuickBMS lists, extracts or repacks the entries. QuickBMS runs scripts as programs: `ComType EXECUTE` and `-S` start external programs, and `CallDLL` loads native code. ### Use cases - List and extract a game archive whose layout is undocumented, for example a Capcom RE Engine `KPKA` pak or a Crystal Dynamics `TAFS` (`.tiger`) archive. - Read a script someone else published and find out what it does before running it. - Turn a layout found with REA's native analysis of the loader into a script the user can run. ### Desired outcome and success criteria Documentation and skill guidance only. No new tool, provider or dependency. - The skill routes custom archives to a QuickBMS reference. - The agent identifies the file with REA first, looks for an existing script, and otherwise works out the layout from the bytes and from the loader code. - The agent checks each field against the real file: the table ends where the data starts, entries stay inside the file, and compressed entries inflate to their declared size. - The agent reads any script it did not write and reports `ComType EXECUTE`, `CallDLL`, `Include`, encryption commands and writes to real files before a run, and asks for approval when a script starts other programs. - The report marks each field as observed, inferred or unknown. - User docs say QuickBMS is user-installed, and how to list, extract and repack. ### Expected interaction with targets Read existing files or captured data, Inject instrumentation or run scripts/code, Write or change files/configuration ### Target and scope details - REA does not ship, install or run QuickBMS. The user installs it and decides where it runs. The agent may run the user's QuickBMS when its environment allows that, or hand over the commands. - "Run scripts" is QuickBMS running a `.bms` script, which can start other programs. The guidance requires reading the script first and asking before running one that starts programs. - "Write files" is extraction into a new empty folder, and repacking into an archive only when the user asks, on a backup copy. - Non-goals: decrypting archives, shipping keys or name lists, fetching the Oodle library, or a QuickBMS provider or MCP tool. ### Verification available so far I have a prototype or observed results ### Verification details A branch ready for a draft PR adds `references/quickbms.md` to the skill and `docs/quickbms.md`. Checks run locally on copies of games I own. No samples are shared. - Scripts written by agents following the guide, run in QuickBMS 0.12: - RE2 `re_chunk_000.pak.patch_001.pak`: 331 entries, 1,338,018,368 bytes extracted, equal to the sums of the pak's own table. - Tomb Raider (2013) `jcontent.000.tiger`: 177 entries, 17,801,867 bytes, equal to the table. Coverage is 23% because the file holds data the table does not point to. The guide covers that case. - Heroes of Might and Magic III `H3bitmap.lod`: 2,008 entries, 89,171,848 bytes, equal to the table. - Asked to run a published script that uses `ComType EXECUTE`, the agent did not run it, named the external program and asked for approval. - `npm run docs:check` and `npm run docs:build` pass. ### Alternatives considered - An REA archive reader per format. Each needs its own design and review, and covers one format. This guidance covers the long tail and can sit beside later readers. - A QuickBMS provider that REA runs. That is a larger execution-authority question and is not proposed here. ### Possible direction - `.agents/skills/reverse-engineer-anything/references/quickbms.md`: workflow, script review, layout checks, common patterns (sector offsets, packed offsets, hashed names, split archives, per-entry codecs), list, extract, repack and limits. - One routing line and one guide link in the skill. - `docs/quickbms.md`, a `## QuickBMS` section in `docs/installation.md`, a README table row and a docs sidebar entry. ### References - QuickBMS: https://aluigi.altervista.org/quickbms.htm (GPL-2.0) - QuickBMS manual, section 3 (reimport) and section 4 (script language), in `quickbms.txt` inside the download

bsakaguchi added the

area: providers

P3: low

enhancement

labels

2026-10-15 18:28:18 +00:00

bsakaguchi commented

2026-10-15 18:28:19 +00:00

Author

Owner

@matbrgz commented on GitHub (Oct 12, 2026):

The proposed approach of treating QuickBMS strictly as agent documentation/skill guidance—without bundling binary distributions, executing arbitrary scripts silently, or exposing an unvetted runner tool—is well aligned with REA's contribution boundaries and bring-your-own philosophy.

PR #2367 carries this implementation. Note that once #2403 (canonical documentation reorganization) lands on main, the documentation path for this guide should follow the reorganized structure under docs/guides/quickbms.md (or the corresponding category) to preserve the public route mapping.

@matbrgz commented on GitHub (Oct 12, 2026): The proposed approach of treating QuickBMS strictly as agent documentation/skill guidance—without bundling binary distributions, executing arbitrary scripts silently, or exposing an unvetted runner tool—is well aligned with REA's contribution boundaries and bring-your-own philosophy. PR #2367 carries this implementation. Note that once #2403 (canonical documentation reorganization) lands on `main`, the documentation path for this guide should follow the reorganized structure under `docs/guides/quickbms.md` (or the corresponding category) to preserve the public route mapping.

bsakaguchi commented

2026-10-15 18:28:20 +00:00

Author

Owner

@dot-mike commented on GitHub (Oct 13, 2026):

Unfortunately, my PR implementation got denied. I think having access to QuickBMS or having code in place to detect arbitrary data formats should still be in the code base. Given it's nature.

@dot-mike commented on GitHub (Oct 13, 2026): Unfortunately, my PR implementation got denied. I think having access to QuickBMS or having code in place to detect arbitrary data formats should still be in the code base. Given it's nature.

bsakaguchi referenced this issue

2026-10-15 18:28:32 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-16 21:16:05 +00:00

[PR #782] [CLOSED] fix: recover serialized native NIB view hierarchy #2238

bsakaguchi referenced this issue

2026-10-16 21:16:27 +00:00

[PR #815] [MERGED] fix: integrate 24 reviewed browser/native/semantics corrections #2262

bsakaguchi added

enhancement

and removed