diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index cdea83c40..752444bf3 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ blank_issues_enabled: true contact_links: + - name: A fact about the 1.12.1 client that is missing or wrong + url: https://github.com/samwhosung/benilla-re/issues + about: The reverse engineering lives in benilla-re; a gap or an error in it is filed there. - name: Discord url: https://discord.gg/wJSJx467G4 about: Questions, ideas and chat. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 368962f62..043cb643d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,6 +4,6 @@ **What this changes** -**What 1.12.1 does, and how you know** (the client's behaviour, a DBC field, a FrameXML line, a capture) +**What 1.12.1 does, and how you know** (a benilla-re entry or client address, the client's behaviour, a DBC field, a FrameXML line, a capture) **How you checked it** (`scripts/check.sh` or `scripts/gates.sh`, and before and after) diff --git a/AGENTS.md b/AGENTS.md index a0b67e0de..cd0c1a10e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,11 @@ Read, in this order: touching anything. 3. `docs/CONTRIBUTING.md` — what gets in and how a change is judged. +What the real client does comes from [benilla-re](https://github.com/samwhosung/benilla-re), the +reverse engineering of 1.12.1, before you build: clone it beside this repo and grep it, or look an +address up at `https://samwhosung.github.io/benilla-re/?0x5e6853`. `docs/CONTRIBUTING.md`, "The +reference", says how to read it and what to do when it has a gap. + The rest of the root is code and data: `crates/` the workspace, `reference/` the 1.12 name catalogues the tests check against, `scripts/` the gates and instruments, `third_party/` vendored code. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index adbffd109..728ad3b91 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -48,6 +48,25 @@ Past `run_with` and that folder, benilla opens a piece of itself to such a crate 1.12.1 work creates that piece, never for the crate alone, and promises no stable API: a crate pins the benilla revision it builds on. What a crate cannot reach stays a fork's. +## The reference + +[benilla-re](https://github.com/samwhosung/benilla-re) is the reverse engineering of the 1.12.1 +client that benilla is built against, read at its bytes, and the place to find what 1.12.1 does +before you change benilla. Every client address a comment here cites is backed there, by a row +or a finding. + +- **Look it up.** The site, `https://samwhosung.github.io/benilla-re/`, has a page per function, + global and struct, per system, and per Lua function, event, CVar and opcode; + `?0x5e6853` goes to whatever holds an address. For an agent, a clone beside this repo is + quicker: grep `symbols/functions.tsv` (a row per function: name, meaning, confidence, the + finding behind it), `tables/` (opcodes, events, CVars, Lua bindings, messages) and the docs + under `systems/`. +- **Weigh it.** A row says how sure it is: `inferred` is a lead to check before you rest on it, + `verified` with proof `one` or `two` is one or two readings of the bytes. +- **When it has a gap or is wrong,** take that to benilla-re: an issue there with what you need to + know, or a pull request that adds the finding (its `CONTRIBUTING.md` says how a finding is + written and checked). Then cite the client address here, as the comments do. + ## How a change is judged 1. `scripts/gates.sh` is green: fmt, clippy with warnings denied, the workspace tests (once @@ -58,8 +77,8 @@ pins the benilla revision it builds on. What a crate cannot reach stays a fork's 2. The reference fact is stated: what 1.12.1 does, and where that is known from (an entry in [benilla-re](https://github.com/samwhosung/benilla-re) by client address, the client's behaviour you observed, a DBC field, a FrameXML line, a packet capture). The names and shapes - under `reference/` are the surface benilla tracks. A fact benilla-re does not have yet can be - added there first. + under `reference/` are the surface benilla tracks. A fact benilla-re does not have yet is + added there first ("The reference"). 3. A comment where it matters, one line, saying what the code does and the 1.12 fact behind it. No history. 4. The commit message says what changed, for a player or a developer, in one line. diff --git a/docs/METHOD.md b/docs/METHOD.md index 1bfabef91..de5f3d83b 100644 --- a/docs/METHOD.md +++ b/docs/METHOD.md @@ -20,7 +20,8 @@ crate of its own or a fork, and benilla opens a piece of itself to such a crate client before building: its code as [benilla-re](https://github.com/samwhosung/benilla-re) documents it by address, its behaviour, a DBC field, a FrameXML line, a packet capture. The names and shapes under - `reference/` are the surface benilla tracks. + `reference/` are the surface benilla tracks. A fact benilla-re lacks, or gets wrong, is + settled there, as an issue or a finding, and cited here by its client address. 2. **Build it idiomatically.** Modern Bevy and Rust, performance woven in from the start. Implement the mechanism well; do not ape a quirk that is a bug. 3. **Measure, never eyeball.** Timing, delay, ordering and feel are settled with instruments: