Setting up with an AI assistant
Most of what ByteMatch needs is in your repository already: objdiff's project file and the CI that builds it. This page has a prompt you can give a coding assistant (Claude Code, Cursor, Copilot and the like) so it does that wiring for you, and a description of how ByteMatch reads your units, which is what the assistant will be changing.
Registering the project on the site is still yours to do: sign in and add it under Manage, as in Getting started. The prompt covers the rest.
The prompt
Copy it whole, fill in the two lines at the top, and run it from your repository's root. It asks the assistant to look before it changes anything and to stop at what it can't check, so read what it reports before you merge.
Set this decompilation repository up for ByteMatch (https://bytematch.dev), a progress
tracker that reads objdiff progress reports from CI. Keep the changes small and in the
style of the repository; don't touch the decompiled code itself.
Repository: <owner>/<repo>
Game versions (e.g. SCES_509.16, GALE01): <versions>
1. Look first. Find how the project builds and whether it already has an objdiff project
file (objdiff.json, often generated by configure.py or a dtk-template setup) and a
GitHub Actions workflow. Tell me what you found before changing anything.
2. objdiff.json: every unit needs
- "name": a path-like name, folders separated by "/" (e.g. "game/player/move"). ByteMatch
draws units as a map grouped by these folders, so group them the way the source tree is.
- "target_path" (the original object) and "base_path" (the object built from our source).
- "metadata.source_path": the source file or folder it's built from, relative to the
repository root, so ByteMatch can show its code.
- "metadata.complete": true only when the unit is fully matched and linked from source.
- "metadata.progress_categories": ids from a top-level "progress_categories" list
([{"id": "game", "name": "Game code"}, ...]) if the project splits its progress
(game, engine, libraries...). Leave them out if it doesn't.
If the file is generated, change the generator, not the output.
3. CI: on pushes to the default branch, after the build, run
objdiff-cli report generate -o build/<VERSION>/report.json
and upload it with actions/upload-artifact as an artifact named <VERSION>_report, one per
version (a matrix is fine). The run must succeed for ByteMatch to read it. Don't add
secrets or tokens: ByteMatch downloads artifacts itself.
4. Optional, only if the repository keeps a list of functions written as working but
non-matching C: put a functional.json beside each report in the same artifact, as
{"functions": [{"name": "<function name>", "confidence": "high"|"medium"|"low"}]}.
5. README: add a progress badge,
[](https://bytematch.dev/<owner>/<repo>)
6. Check what you can: run the build and objdiff-cli report generate locally if the tools
are available, and validate the workflow's YAML. List anything you couldn't run.
How ByteMatch reads your units
ByteMatch shows what objdiff's report says; it doesn't build or diff anything itself. Each part
of the project page comes from one part of the report, and the report comes from objdiff.json.
| On the page | From the report | Set in objdiff.json |
|---|---|---|
| A unit's tile on the map | the unit, sized by its code bytes | one entry in units |
| Folders on the map | the unit's name, split on / | name |
| Function tiles inside a unit | the unit's functions | (objdiff finds them) |
| View source and function code | metadata.source_path | metadata.source_path |
| Fully linked | metadata.complete | metadata.complete |
Categories (sidebar, category=) | categories | progress_categories, top-level and per unit |
| Versions | one report per version | one artifact per version (or split versions) |
A few things that follow from this:
- Names are the layout.
game/player/moveandgame/player/jumpsit together in aplayerbox insidegame. Flat names (move,jump) give one flat map, which is hard to read for a big project. - A unit can be a folder. If
source_pathis a directory (projects that split one object into many files), View source lists its files and a function opens the file it's defined in. Files named after the address their code starts at (vendor_002CF2C0.c) are searched first. - Complete means linked. Matched code counts as matched either way;
completemarks units the build links from source, which is the fully linked figure. - Functions are found, not configured. objdiff reads them from the objects, so a missing function usually means a symbol problem in the build, not in ByteMatch.
After it's merged
Once a successful run on the default branch has the artifact, the project page fills in within the poll interval (15 minutes on bytematch.dev), or straight away with the GitHub App installed. If nothing shows, the project's manage page says why; Getting started has the details of each step.