# decomp.fun

> decomp.fun is a directory and leaderboard of matching decompilation projects for video games: games being
> rewritten in C/C++ that compile back into the exact original binary. Progress is read automatically from each
> project's own CI. It is aimed at people (and their AI agents) decompiling games. Everything below is static and
> public; no key is needed.

## How progress is measured

- Each project's GitHub Actions publish an objdiff (https://github.com/encounter/objdiff) progress report as an
  artifact with "report" in its name, on the default branch. decomp.fun reads the newest one every hour.
  Projects built from dtk-template (https://github.com/encounter/dtk-template) already do this.
- Each artifact is one build (version), e.g. GALE01_report -> build GALE01. The first build listed is the default.
- decompiled_percent = matched code bytes / total code bytes. linked_percent = code in units that link fully.
  partly_percent also counts partly matched ("fuzzy") code. functions = matched / total functions.
- GitHub deletes artifacts after 90 days. A project with no CI run since then keeps its last numbers
  ("live": false means they come from the archived decomp.dev index).
- One project is listed per game (a "slot"). When several repositories work on the same game, the one listed is
  the leader; another takes the slot after leading by the takeover margin for several days in a row.

## Data (JSON, CORS open, regenerated every hour)

- https://decomp.fun/v1/index.json : machine-readable description of every endpoint and field.
- https://decomp.fun/v1/projects.json : every listed project.
  projects[]: owner, repo, name, url, api, repository, game_title, platform {key, name}, slot, leader (bool),
  listed_as, archived (GitHub repo archived), updated, versions[].
  versions[]: id, default, live, commit {sha, timestamp}, total_code, matched_code, decompiled_percent,
  linked_percent, partly_percent, functions {matched, total}, data {total, matched, linked} (if any), url.
- https://decomp.fun/v1/games.json : games.<slot> -> platform, game, identified, title, leader, decompiled_percent,
  url, others[], challengers {repo: since}, contesters[], contested_by[]. Slot keys are "platform:game-key", or
  "repo:owner/name" when the game could not be identified.
- https://decomp.fun/v1/systems.json : systems[]: key, name, short, maker, projects, games, games_known, url.
- https://decomp.fun/v1/OWNER/REPO.json : one project: the projects.json fields plus description, default_branch,
  stars, source, history (URL), badge (URL), others, contesters, contested_by; each version adds todo and units URLs.
  Use the owner/repo casing from projects.json (URLs are case-sensitive).
- https://decomp.fun/v1/OWNER/REPO/BUILD/todo.json : what to work on next in one build. units[] (up to 200): name,
  size (code bytes), percent (decompiled incl. partly), remaining (bytes left = (100 - percent) / 100 * size),
  linked; sorted by remaining, largest first. Also units_total and units_left. Unit-level only; functions are not
  included.
- https://decomp.fun/OWNER/REPO/history.json : progress over time for the default build. []: timestamp,
  commit_sha, commit_message, source (report | archive | readme), measures {matched_code_percent,
  complete_code_percent, fuzzy_match_percent, ...}.
- https://decomp.fun/OWNER/REPO/units.json (default build) and https://decomp.fun/OWNER/REPO/BUILD/units.json
  (other builds): every source unit. []: n (name), s (code bytes), p (percent incl. partly), l (linked),
  x, y, w, h (treemap cell).
- https://decomp.fun/v1/changes.json : the latest 200 progress changes across all projects, newest first.
  changes[]: owner, repo, name, platform, url, timestamp, commit_sha, commit_message, source,
  decompiled_percent, decompiled_delta, linked_percent, linked_delta.
- https://decomp.fun/feed.xml : the same changes as an Atom feed.
- https://decomp.fun/health.json : built (time), projects, live, fetch_failed.

## Pages

- https://decomp.fun/ : all games. /systems/ : by system. /OWNER/REPO/ : a project (default build).
  /OWNER/REPO/BUILD/ : another build. /OWNER/REPO/history/ : history chart. /submit/ : add a project.

## Add a project

Open https://decomp.fun/submit/ and sign in with GitHub (public profile only). Checks, all automatic:
- public GitHub repository whose Actions publish an objdiff report artifact ("report" in its name) on the default branch;
- at least 5% of the code decompiled;
- the game is identified from the repository (disc ID, serial, title ID or ROM hash). PC, DOS and Switch games:
  pick the system and give the game's exact published name;
- one project per game: if the game is listed, your repository must decompile the same executable, and it takes the
  slot once it leads on progress for long enough;
- the GitHub account is at least 30 days old; up to 3 submissions per account per day.
Results appear at https://decomp.fun/submit/ (and https://decomp.fun/submissions.json) within a few minutes.

## Refresh a project immediately from CI

Add this as the last step of the workflow that uploads the report artifact (after the upload):

    - name: Update decomp.fun
      if: github.event_name == 'push' && github.ref_name == github.event.repository.default_branch
      run: curl -fsS "https://decomp.fun/api/fresh?repo=${{ github.repository }}" || true

Or in any shell: curl -fsS "https://decomp.fun/api/fresh?repo=OWNER/REPO"
Response: {"status": "updating"} (a refresh started; the page updates in a few minutes), "current" (nothing newer
seen), "busy" (a refresh limit was reached; the hourly update will pick it up), "unknown" (not listed), "error".
It is rate-limited server-side (each project is checked at most once a minute, and refreshed up to 100 times a day), so
calling it on every push is fine. Only listed projects can be refreshed.

## Badge

    ![decomp.fun](https://img.shields.io/endpoint?url=https://decomp.fun/v1/badge/OWNER/REPO.json)

https://decomp.fun/v1/badge/OWNER/REPO.json is a shields.io endpoint: {"schemaVersion": 1, "label": "decomp.fun",
"message": "94.5%", "color": ...} for the default build's decompiled percent.

## Attribution

Game titles and identifiers come from No-Intro and Redump game lists as packaged by libretro-database
(CC BY-SA 4.0), MAME, titledb and Wikidata. Reuse of those fields must credit them and share alike.
Progress data are facts read from public repositories; credit for the decompilations belongs to their authors.
Site source: https://github.com/g-guthrie/decomp.fun