SCRYMAMEReferenceScanscanAlso in DOSBox-X
scan
Find the byte that holds a value nobody has named: start from a whole range and keep only what changes as the value does.
scan(method, ref="", length=null, cell_bytes=null, cpu="", operator=null, value=null, limit=null)
Try it
Find the byte where this game counts its credits: scan the first 2 KB and filter after each of three coins.
scan(method="start", ref="0x0", length=2048){
"summary": "scan start: 0x0, 2048 1-byte candidates on :maincpu",
"status": "ok",
"length": 2048,
"cell_bytes": 1,
"hits_total": 2048,
"cpu": ":maincpu"
}Then, after the third coin:
scan(method="filter", operator="=", value=3){
"summary": "scan filter: = 0x03, 3 left",
"status": "ok",
"iterations": 3,
"hits": [
{"addr": "0x000003ee", "value": "0x03"},
{"addr": "0x0000042b", "value": "0x03"},
{"addr": "0x0000042c", "value": "0x03"}
],
"hits_total": 3
}Three bytes still hold 3 after three coins. Two of them, 0x42b and 0x42c, are the credits, which the game keeps twice.
The two replies, whole
The first call's:
{
"summary": "scan start: 0x0, 2048 1-byte candidates on :maincpu",
"status": "ok",
"ref": "0x0",
"addr": "0x00000000",
"length": 2048,
"cell_bytes": 1,
"hits_total": 2048,
"cpu": ":maincpu",
"space": "program"
}The second call's:
{
"summary": "scan filter: = 0x03, 3 left",
"status": "ok",
"operator": "=",
"value": "0x03",
"iterations": 3,
"closed": false,
"hits": [
{"addr": "0x000003ee", "value": "0x03"},
{"addr": "0x0000042b", "value": "0x03"},
{"addr": "0x0000042c", "value": "0x03"}
],
"hits_total": 3,
"truncated": false,
"cpu": ":maincpu",
"space": "program"
}The three methods
| method | what it does |
|---|---|
start |
Opens a scan: every cell of the range is a candidate. |
filter |
Keeps the candidates whose value passes a comparison. |
clear |
Ends the scan. |
Arguments
- method one of
"start","filter","clear", required start,filterorclear, as above.- ref string, default
"" - Where the range begins, for
start: a0xaddress or a symbol. - length integer, optional
- How many bytes to scan, for
start: at most0x100000. - cell_bytes one of
1,2,4, optional - The size of each candidate: 1, 2 or 4 bytes. Left out, one byte.
- cpu string, default
"" - The cpu whose program memory is scanned. Left empty, the one the debugger is showing.
- operator one of
"=","!",">",">=","<","<=", optional - The comparison a
filtermakes. Left out,=. - value integer or string, optional
- What each candidate is compared with: an integer or a
0xstring. Left out, what it held atstart. - limit integer (>= 1, <= 400), optional
- How many of the candidates left the reply lists: 1 to 400. Left out, 40.
What comes back
- hits_total
- How many candidates are left.
- hits
- The first
limitof them, each with its address and its value now. - iterations
- How many filters this scan has taken.
- closed
truewhen a filter left no candidate, which ends the scan.- truncated
truewhen there are more candidates thanhitslists.
All 14 reply fields
addr(string)cell_bytes(integer)cleared(boolean)closed(boolean)cpu(string)hits(array)hits_total(integer)iterations(integer)length(integer)operator(string)ref(string)space(string)truncated(boolean)value(string or object)
What it refuses
- An argument the method does not take.
- A second
startwhile a scan is open, or afilterwith none (needs_call). - A range that runs past the cpu's program memory (
bad_argument).
Why it works this way
The scan reads memory the way the cpu does, through the board's own handlers, so it sees what MAME's cheat search cannot. It belongs to one cpu, because every filter must read the same memory.
One scan is open at a time, and nothing you do between filters ends it: running, writing, a reset or loading a saved state. That is what lets a coin go in between two filters.
Related tools
The contract your client receives
Value scan: find a variable no map names, in one cpu's program space only, no io
ports. One scan at a time; it outlives runs, writes, `reset` and state loads; `close`
ends it.
`start`: every cell of `cell_bytes` from `ref` on `cpu` is a candidate;
`length` counts bytes, at most 0x100000. Reply: `ref`, `addr`, `length`, `cell_bytes`,
`hits_total`, `cpu`, `space`.
`filter`: keep the cells whose value satisfies `operator` (`=` default) against
`value` (an integer or a `0x` string), or with no `value` against what each held at `start`; none left
closes the scan. Reply: `operator`, `value`, `iterations`, `closed`, `hits` (the first
`limit`, default 40), `hits_total`, `truncated`, `cpu`, `space`.
`clear`: end the scan. Reply: `cleared`, `note`.
Refused: an argument the method does not take; a second `start` or no scan open
(`needs_call`); a range past the cpu's program space (`bad_argument`).
Reference: REFERENCE.md, Reading and writing.