initial commit

CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing gamedata
+
+Most functions are derived automatically. When source2rosetta *can't* locate one — a newly
+interesting function, or one whose signature drifted past the model — you can contribute its
+locator directly. A contribution is just **a name + how to find it, dated to the build you
+saw it on.** The derive merges it into the catalogue, validates it against a live server, and
+tracks it forward across future builds like any first-party entry.
+
+## Add a contribution
+
+Drop a JSON file into the folder for your game:
+
+```
+mappings/contributions/<game_key>/<anything>.json      csgo  → CS2
+                                                        dota  → Dota 2
+```
+
+Every file is a JSON array of entries:
+
+```json
+[
+  {
+    "name": "CCSPlayer_WeaponServices::BumpWeapon",
+    "kind": "vtable-offset",
+    "value": "27",
+    "date": "2026-07-09"
+  },
+  {
+    "name": "CTakeDamageInfo::CTakeDamageInfo",
+    "kind": "signature",
+    "value": "49 BB ? ? ? ? ? ? ? ? 55",
+    "date": "2026-07-09"
+  }
+]
+```
+
+| field | meaning |
+|---|---|
+| `name` | the function, `Class::Method` for a virtual, a bare name otherwise. |
+| `kind` | `"signature"` (a non-virtual, located by bytes) or `"vtable-offset"` (a virtual, located by slot). |
+| `value` | for a signature, a space-separated byte pattern with `?` wildcards; for an offset, the vtable slot index as a string. |
+| `date` | the build you observed it on, `YYYY-MM-DD`. This anchors the observation so the derive can chain the offset / re-locate the signature forward from there. |
+
+All four fields are required. Files are merged in sorted filename order; a malformed entry is
+skipped with a warning (it never breaks the build), so keep one logical group per file.
+
+## What happens to it
+
+1. **Merge** — the derive folds your entries into the catalogue for that game (contributions
+   are never written into the historical corpus model — they live only in this folder).
+2. **Validate** — `produce` launches a vanilla server and checks your locator against live
+   memory: a signature must resolve to executable code, an offset must land on a real vtable
+   slot, and a representative call must return cleanly. Passing entries ship; failing ones are
+   reported, not silently dropped.
+3. **Track forward** — because the entry is dated, later builds re-locate it automatically
+   (offset chaining / string-anchor backfill), so one contribution keeps paying off across
+   updates instead of needing a re-submit each patch.
+
+## Getting the value
+
+- **vtable-offset** — the slot index of a virtual method. Read it off a class's RTTI vtable
+  with any Source-2 class dumper, or from an existing entry for a neighbouring method on the
+  same class.
+- **signature** — a unique byte pattern at the function's prologue. Keep wildcards (`?`) on
+  relative offsets / addresses so the pattern survives minor recompiles.
+
+Then let the tool check it for you: add the entry, run `produce` against the current build
+(omit `--game-dir` for a fast offline check), and look for your name in the output. It lands in
+`core` if it resolved, or in `unresolved` with a reason if it did not — every catalogue entry is
+accounted for in one of the tiers, so a contribution never disappears silently.
+
+Prefer an **offset** over a signature when the function is virtual — it's RTTI-derived and far
+more stable across builds.
+
+## Show it holds across builds (optional)
+
+A one-build entry is fine; one that has held for hundreds of builds is stronger. For a
+**vtable-offset**, `backfill` chains your slot back through the shipped model's alignment history —
+no build binaries needed, just the model file:
+
+```json
+// mine.json
+[{ "name": "CCSPlayer_WeaponServices::BumpWeapon", "class": "CCSPlayer_WeaponServices", "slot": 27 }]
+```
+
+```
+source2rosetta --game cs2 backfill --corpus-model model-cs2.json --names mine.json --out history.json
+```
+
+```
+backfill: 1 names over 0 corpus builds / 343 model builds
+  graduates: 1 DEEP first-class (>=50% coverage, >=0.9 consistent)
+```
+
+`history.json` then lists the slot at every build the class appears in, plus a consistency score. A
+deep, consistent timeline is a strong signal the entry is solid — it's exactly what promotes a name
+to first-class regardless of how it was first found. (A **signature** can be back-filled too, but
+that half re-locates the anchor string in every raw build, so it needs the full build corpus the
+maintainers keep — the offset half above works from the published model alone.)