SCRYDOSBox-XReferenceReadscreen_map_findAlso in MAME

DOSBox-XRead

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 Bricks, the game this repository builds, stopped on its play screen with the game's own map loaded, as in the example of screen_map_write below.
Ask

Which screen is the game showing?

Call
screen_map_find()
Reply 5 of 8 fields
{
  "summary": "screen_map_find: play (file), 1 control",
  "matched": true,
  "screen": "play",
  "layer": "file",
  "controls": [
    {"name": "court", "rect": [200, 80, 80, 40], "centre": [240, 100]}
  ]
}

The game shows play, a screen of the loaded file (layer file). Its area court is the rectangle at 200, 80, with its centre at 240, 100.

The whole reply
JSON
{
  "summary": "screen_map_find: play (file), 1 control",
  "status": "ok",
  "matched": true,
  "screen": "play",
  "layer": "file",
  "kind": "pixel",
  "size": [320, 200],
  "controls": [
    {"name": "court", "rect": [200, 80, 80, 40], "centre": [240, 100]}
  ]
}

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 10 reply fields
  • controls (array)
  • kind (string)
  • layer (string)
  • matched (boolean)
  • 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 areas of the matched screen are what send_mouse(target=) clicks by name. The click acts on the screen this tool last matched, and what is drawn is not compared again. After anything that may have changed the screen, call it again at a stop.

A screen added with cells index is compared by palette index, not by colour.

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