SCRYMAMEReferenceCommentscomment_listAlso in DOSBox-X
comment_list
List every saved comment, or one cpu's, each with its address and whether MAME's disassembly shows it.
comment_list(cpu="")
Try it
Which comments are saved for this game?
comment_list(){
"summary": "comment_list: 1 comment",
"status": "ok",
"comments_total": 1,
"truncated": false,
"cpu": {"available": false, "why": "no cpu was named, so the rows are every cpu's"}
}One comment is saved, and truncated is false: the reply lists every one. No cpu was named, so the rows are every cpu's.
The whole reply
{
"summary": "comment_list: 1 comment",
"status": "ok",
"comments": [
{
"ref": "count_coin",
"by": "symbol",
"cpu": ":maincpu",
"created_at": "<volatile>",
"origin": "<volatile>",
"inherited": false,
"age_s": "<volatile>",
"text": "a coin: INC credits, then the BCD copy",
"addr": "0x0000b583",
"state": "armed"
}
],
"comments_total": 1,
"truncated": false,
"declarations": {"persistent": true, "path": "./tmp/demos/tour/gridlee-states/declarations.json"},
"cpu": {"available": false, "why": "no cpu was named, so the rows are every cpu's"}
}Arguments
- cpu string, default
"" - Lists this cpu's comments only. Left empty, every cpu's.
What comes back
- comments
- The comments this reply shows. Each row has
ref,text,addronce resolved,state, andwhywhen it is not shown. - comments_total
- How many comments are saved, listed or not.
- truncated
truewhen there are more comments than the reply lists.comment_write(method="save")writes them all.- declarations
- The saved breakpoints file the comments live in: its
path, andpersistent,falsewhen they last only this session.
All 5 reply fields
comments(array)comments_total(integer)cpu(string or object)declarations(object)truncated(boolean)
What it refuses
- A cpu the machine does not have (
unknown_ref).
Why it works this way
It reads the saved comments and asks the machine nothing, so it answers while the program runs.
MAME also ties a comment to a checksum of the instruction bytes under it. Code that moves in RAM hides its comment in MAME's disassembly, while the comment stays saved.
More on why
What state says of a comment:
-
armed: MAME's disassembly shows it. -
unarmable: saved but not shown.whysays the reason. -
unresolved: its symbol is not in this build. -
stale: a raw address saved over another build. -
Each row also carries
by,cpu,created_at,origin,inheritedandage_s, as a saved breakpoint's row does. -
A rebuild can bring several comments to one address. All are kept: MAME's disassembly shows the first it can, and each other reads
unarmable. -
A field with nothing to give is an object:
availableisfalseandwhysays the reason, ascpuwhen none was named. -
While the machine runs the reply adds
last_stop.
Related tools
The contract your client receives
Every comment of the store, or `cpu`'s. Answers on a running machine too.
Reply: `comments` (each `ref`, `text`, `addr`, `state`; at most 24),
`comments_total`, `truncated`, `declarations`, `cpu`.
Reference: REFERENCE.md, Breakpoints and watches.