SCRYMAMEReferenceReadscreen_map_findAlso in DOSBox-X

MAMERead

screen_map_find

Name the screen your program is showing, from its screen map: a file of the program's screens and the named areas of each.

screen_map_find()

Try it

On Gridlee, a free ROM from mamedev.org, stopped on the level card the game shows after START, just after the example of screen_map_write below added that screen.
Ask

Which screen of the map is the game showing?

Call
screen_map_find()
Reply 5 of 23 fields
{
  "summary": "screen_map_find: level_card (session), 1 control",
  "matched": true,
  "screen": "level_card",
  "layer": "session",
  "controls": [
    {"name": "level", "rect": [88, 152, 72, 8], "centre": [124, 156]}
  ]
}

The game shows level_card, one of the screens added this session (layer session). Its area level is the rectangle at 88, 152, with its centre at 124, 156.

The whole reply
JSON
{
  "summary": "screen_map_find: level_card (session), 1 control",
  "status": "ok",
  "matched": true,
  "screen": "level_card",
  "layer": "session",
  "kind": "pixel",
  "size": [256, 240],
  "controls": [
    {"name": "level", "rect": [88, 152, 72, 8], "centre": [124, 156]}
  ],
  "evaluated_by": "one step",
  "lines_ahead": 0,
  "thread_errors": 0,
  "console_reruns": 0,
  "call": "MAME_MCP_LUA_END#21",
  "pc_before": "0x0000a631",
  "cause": "screen_map_find: one step",
  "stop_seq": 27,
  "pc": "0x0000a633",
  "cpu": ":maincpu",
  "frame": 702,
  "regs": {
    "A": "0x00",
    "B": "0x99",
    "D": "0x0099",
    "X": "0x0014",
    "Y": "0xf2e6",
    "U": "0x4071",
    "PC": "0xa633",
    "S": "0x0800",
    "CC": "0x84",
    "DP": "0x00"
  },
  "instruction": {"address": "A633", "bytes": "24FC", "text": "BCC    $A631", "symbol": "wait_frame", "delta": 2},
  "following": ["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", "A640: 7E F0 00 JMP    $F000", "... 6 more"],
  "errorlog": "<volatile>"
}

Arguments

Takes no argument.

What comes back

matched
true when a screen of the map is the one showing.
screen
The name of the screen that matched.
controls
The matched screen's named areas, each with name, rect and centre, in the program's own units.
layer
Where the screen was found: session for a screen added in this session, file for one of the loaded map.
screens_mapped
When nothing matched: how many screens the map holds. screens_tried says how many had the right kind and size.
view_fits
false when the picture's size cannot be the map's, seen through the scale and margin it was loaded with.
All 27 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)
  • call (string)
  • controls (array)
  • evaluated_by (string)
  • kind (string)
  • layer (string)
  • lines_ahead (integer)
  • matched (boolean)
  • pc_before (string)
  • reader_steps (integer)
  • screen (string)
  • screens_mapped (integer)
  • screens_tried (integer)
  • screens_unjudged (integer)
  • size (array)
  • view_fits (boolean)

What it refuses

Why it works this way

A screen matches when its kind and size are the ones showing and each of its regions has the fingerprint the map recorded. Screens added this session are tried first, then the loaded file's.

The screen is captured once for the whole map, and sizes are compared before any fingerprint: a capture is a round trip through MAME's Lua console.

A screen added with cells index is compared by palette index, not by colour. Capturing the indices costs MAME more, so it happens only when the map holds such a screen.

The contract your client receives
Text
Which mapped screen the machine shows. Reply: `matched`, `kind` and `size`; when matched,
`screen`, `layer`, `controls` (`name`, `rect`, `centre`), in the program's units; when not,
`screens_mapped` and, if the view fits the map, `screens_tried` and `screens_unjudged`
(signed by index on a screen whose pens cannot be read), else `view_fits` false. None mapped:
`needs_call`.

Reference: REFERENCE.md, Screen maps.
Tools