SCRYMAMEReferenceReadscreen_map_writeAlso in DOSBox-X
screen_map_write
Build the screen map, the file that names your program's screens and their areas: add the screen showing, load a file, or save one.
screen_map_write(method, screen="", match=null, controls=null, cells="", anchor="", path="", scale=null, margin=null, dest="", overwrite=null)
Try it
Add this screen to the map as level_card, known by its title, with the level number as an area named level.
screen_map_write(method="add", screen="level_card", match=[[24, 104, 208, 16]],
controls=[{"name": "level", "rect": [88, 152, 72, 8]}]){
"summary": "screen_map_write add: level_card (pixel 256x240), 1 region, 1 control",
"screen": "level_card",
"size": [256, 240],
"match": [
{"crop": [24, 104, 208, 16], "signature": "5733a1938b03c102"}
],
"controls": 1,
"replaced": false
}The screen is recorded as level_card, 256 by 240 pixels, with one named area. Its one region has the fingerprint 5733a1938b03c102 (signature), which is what later identifies it.
The whole reply
{
"summary": "screen_map_write add: level_card (pixel 256x240), 1 region, 1 control",
"status": "ok",
"screen": "level_card",
"kind": "pixel",
"size": [256, 240],
"cells": "rgb",
"match": [
{"crop": [24, 104, 208, 16], "signature": "5733a1938b03c102"}
],
"controls": 1,
"replaced": false,
"shadows_file": false,
"evaluated_by": "one step",
"lines_ahead": 0,
"thread_errors": 0,
"console_reruns": 0,
"call": "MAME_MCP_LUA_END#20",
"pc_before": "0x0000a633",
"cause": "screen_map_write add: one step",
"stop_seq": 26,
"pc": "0x0000a631",
"cpu": ":maincpu",
"frame": 702,
"regs": {
"A": "0x00",
"B": "0x99",
"D": "0x0099",
"X": "0x0014",
"Y": "0xf2e6",
"U": "0x4071",
"PC": "0xa631",
"S": "0x0800",
"CC": "0x84",
"DP": "0x00"
},
"instruction": {"address": "A631", "bytes": "04B4", "text": "LSR <$B4", "symbol": "wait_frame", "delta": 0},
"following": ["A633: 24 FC BCC $A631", "A635: B7 93 80 STA $9380", "A638: B6 97 00 LDA $9700", "A63B: 43 COMA", "A63C: 85 20 BITA #$20", "A63E: 27 03 BEQ $A643", "... 7 more"],
"errorlog": "<volatile>",
"kept": "3 saved for `promote`; maps/gridlee, perform/two-coins, start/gridlee: nothing this session read names its repository: promote(dry_run=true, root=<the repository>) lists what an approval would create"
}The three methods
| method | what it does |
|---|---|
add |
Records the screen showing now under a name, with the regions that identify it and its named areas. Needs the program stopped. |
load |
Reads a map file; nothing is written to disk. Works while the program runs. |
save |
Writes the loaded map and the screens added since as one file, which becomes the loaded map. Works while the program runs. |
Arguments
- method one of
"add","load","save", required add,loadorsave, as above.- screen string, default
"" - For
add: the name the screen is recorded under. - match array of array of integer, optional
- For
add: 1 to 16 rectangles[x, y, width, height]that always look the same on this screen. They are what identifies it. - controls array of object, optional
- For
add: the screen's named areas, each{"name", "rect"}. Left out, none. - cells one of
"","rgb","index", default"" - For
add:indexcompares palette indices, not the colours shown, so one map serves a program shown through two palettes. Left out,rgb. - anchor string, default
"" - For
add: a symbol or an address the program reaches once the screen is fully drawn.run_to(screen=)runs to it. - path string, default
"" - For
load: the map file, named<application>-screen-map.json, as an absolute or~-led path. - scale integer, optional
- For
load: how many times larger this machine shows the program's picture, 1 to 8. Left out, 1. - margin array of integer, optional
- For
load:[x, y], the border in machine pixels on each side of the program's picture. Left out, none. - dest string, default
"" - For
save: the file to write, named<application>-screen-map.json, as an absolute or~-led path. - overwrite boolean, optional
- For
save:truereplaces a file already atdest. Left out, an existing file is refused.
What comes back
- match
add: each region as recorded, with itscropand itssignature, the fingerprint taken from the screen.- replaced
add:truewhen a screen of that name was already added this session.shadows_fileistruewhen the loaded file has one too.- kept
add: readsN saved for promoteonce the map is a candidate thatpromotecan write into your repository's.scry/folder.- screens
loadandsave: how many screens the map holds;controlscounts their named areas.- mode
loadandsave:verifiedwhen a screen is checked each time it is reached,consolidatedwhen it is trusted without a check.- promoted
save: the names of the screens added this session that the file now holds.
All 33 reply fields
console_reruns(integer)cpu(string)following(array of string)instruction(StopInstruction)errorlog(object)frame(integer)pc(string)regs(object)resent(integer)stop_seq(integer)thread_errors(integer)watches(array)anchor(string)application(string)cells(string)controls(integer)kind(string)kept(string)match(array)mode(string)path(string)pointer(object)promoted(array)replaced(boolean)screen(string)screens(integer)shadows_file(boolean)size(array)call(string)evaluated_by(string)lines_ahead(integer)pc_before(string)reader_steps(integer)
What it refuses
- An argument the method does not take.
- A name, rectangle, area or file that is not well formed, or a rectangle outside the screen (
bad_argument). - An
addwithoutanchorwhen the loaded map isconsolidated, or asaveof one holding a screen with none (bad_argument). cellsindexon a screen that has no palette (no_channel).- A
savewith nothing mapped (needs_call).
Why it works this way
A screen is recognised by a few regions that never change, not by the whole picture: a cursor or a moving ball would change a fingerprint of the whole screen.
The map has two layers. Screens you add live in the session and win over a loaded file's screen of the same name; save writes both as one file. A new start empties the session layer and keeps the file.
A map's mode says who keeps it true. In a verified map, run_to(screen=) checks the screen's regions on reaching it and refuses a map that no longer matches (stale_map). In a consolidated map the screen is trusted at its anchor, which lets one map serve two versions of a program whose pixels differ.
More on why
The mode is the file's own: save keeps the loaded map's, and writes verified when none was loaded. screen_map_find checks the regions in either mode.
Rectangles are in the program's pixels. With scale and margin, this machine's picture is the program's size times the scale, plus the margin on each side. A capture is sampled back to the program's size before it is compared.
A map file is kept in the program's repository, as .scry/maps/<application>-screen-map.json, and looks like this.
{"format": "scry-screen-map/1", "application": "circus", "mode": "verified",
"screens": [{"name": "attract", "kind": "pixel", "size": [248, 256],
"match": [{"crop": [0, 0, 248, 8], "signature": "<16 hex>"}],
"controls": [{"name": "high_score", "rect": [40, 112, 184, 8]}]}]}On an arcade board a named area is somewhere to read, never something to click: its inputs go in by port and field. A file may also say where the program keeps a mouse pointer; this server keeps that entry, writes it back on save and does nothing else with it.
In the replay test perform_export writes, load and add are replayed as steps and screen_map_find becomes a check of what it matched. A save is left out, since a replay would find its file there.
Related tools
The contract your client receives
The screen map: an application's screens, each known by the signatures of its stable regions, and their controls, in a session layer and a file layer.
`add`: the screen shown now as `screen` in the session layer, one capture signing each `match` crop ([x, y, width, height], 1..16), `controls` ([{"name", "rect"}]) naming its places to read; needs the machine stopped. Reply: `screen`, `kind`, `size`, `cells`, `match`, `controls`, `replaced`, `shadows_file`, `anchor` (when given), `kept` (a complete map is kept for `promote`).
`add`'s `cells` `index` (a pixel screen; default
`rgb`) signs the palette indices drawn, not the colours shown, so one map knows a program
shown through two palettes; a screen with no palette refuses it (`no_channel`).
`add`'s `anchor` (a symbol or an address, as `run_to`'s `ref`) is the place after which the screen is whole,
what `run_to(screen=)` runs to: a consolidated map refuses an `add` without one (`bad_argument`),
since it enters its screens by theirs.
`load`: `path` (`<application>-screen-map.json`, absolute or `~`-led) as the file layer, held by the
server; nothing is written to disk. `scale` (1..8) and `margin` [x, y] (machine pixels on
each side) say how the program's picture sits on this machine's screen; maps and `add`'s
crops are in the program's units. Reply: `path`, `application`, `mode`, `screens`, `controls`, `pointer`
(a map that declares the program's pointer).
`save`: both layers as one map to `dest`, refused there without `overwrite`, made the file
layer, in the loaded map's `mode` (`verified` when none was loaded). Reply: `path`,
`application`, `mode`, `screens`, `controls`, `promoted`.
Refused: an argument the method does not take; a misshapen name, crop, control, view or file; an `add` without an `anchor` to a consolidated map, and a save of one holding a screen with none (`bad_argument`); neither a screen nor a `pointer` to save (`needs_call`).
Reference: REFERENCE.md, Screen maps.