SCRYMAMEReferenceScreengfx_draft

MAMEScreen

gfx_draft

Write a draft gfx.yaml from what this session's gfx_locate answers and your picks proved, with a report of every figure beside it.

gfx_draft(dest="", choose=null)

Try it

On Gridlee, a free ROM from mamedev.org, after the gfx_sweep and gfx_locate calls shown on this page. The pick of s1c1 is recorded as the example session's.
Ask

Write down what we worked out about Gridlee's sprite format as a draft manifest, and record that the tour picked candidate s1c1.

Call
gfx_draft(dest="./tmp/demos/tour/gridlee-gfx-draft.yaml",
    choose={"candidate": "s1c1", "chosen_by": "the tour"})
Reply 5 of 11 fields
{
  "summary": "gfx_draft ./tmp/demos/tour/gridlee-gfx-draft.yaml: 1 format  ... (105 characters)",
  "formats": {"tiles_8x16x4": "human"},
  "evidence": {"locates": 1, "sweeps": 1, "choices": 1, "correlations": 0},
  "not_proved": [
    ":gfx1: s1c1 matched only windows that prove no layout (faile ... (70 characters)",
    ":gfx1: no asset for tiles_8x16x4, chosen under no palette"
  ],
  "chose": {"candidate": "s1c1", "chosen_by": "the tour"}
}

The one format written is the recorded pick, marked human: not_proved says the match found here proves no layout. No asset is written, since the pick was made under no palette.

The whole reply
JSON
{
  "summary": "gfx_draft ./tmp/demos/tour/gridlee-gfx-draft.yaml: 1 format (1 human), 0 assets, 0 commands; 2 not proved",
  "status": "ok",
  "manifest": {
    "path": "./tmp/demos/tour/gridlee-gfx-draft.yaml",
    "sha256": "227b32e68e59f87c84a0ed70236c92d935c8c42bb20b8f66a6a3269c8aca106d"
  },
  "report": {
    "path": "./tmp/demos/tour/gridlee-gfx-draft-report.json",
    "sha256": "251286b45bd5632f5e776e4346eae0e9bb22403970fc20f99da27d415469142d"
  },
  "formats": {"tiles_8x16x4": "human"},
  "asset_names": [],
  "command_fields": {},
  "evidence": {"locates": 1, "sweeps": 1, "choices": 1, "correlations": 0},
  "not_proved": [":gfx1: s1c1 matched only windows that prove no layout (failed: rarest)", ":gfx1: no asset for tiles_8x16x4, chosen under no palette"],
  "confirm": "the owner confirms the draft by deleting its first line; `gfx_load` loads it before that and says `draft: true`",
  "chose": {"candidate": "s1c1", "chosen_by": "the tour"}
}

Arguments

dest string, default ""
An absolute .yaml path in an existing folder, where only an earlier draft is replaced. Left empty, the session's temporary folder.
choose object, optional
Records a person's pick from a gfx_sweep sheet before drafting: {"candidate": "s1c3", "chosen_by": "<who>"}.

What comes back

manifest
The draft: its path and sha256. report gives the same two for the JSON report.
formats
Each format written, by name, with its status: proved or human.
not_proved
The first 8 things the session could not settle, in words. not_proved_more counts the rest.
evidence
What the draft was worked out from: how many locates, sweeps, choices and correlations.
chose
With choose, the pick recorded: candidate and chosen_by.
confirm
How the draft becomes a manifest: delete its first line.
All 12 reply fields
  • asset_names (array)
  • chose (object)
  • command_fields (object)
  • confirm (string)
  • draft (string)
  • evidence (object)
  • formats (object)
  • manifest (object)
  • marker (string)
  • not_proved (array)
  • not_proved_more (integer)
  • report (object)

What it refuses

Why it works this way

The draft holds only what the session's record establishes: every gfx_locate answer, every gfx_sweep sheet and every pick, kept until close or the next start. Each entry is written with its status and what proved it. What the record cannot settle is listed in not_proved.

A format is proved by a match whose window varies along both axes and whose rarest pen covers the tile's longer side. No other block may match those pixels on the same frame, since a pixel has one origin. A dot or a line is found by chance among hundreds of tiles.

The draft's first line marks it as a draft, and deleting that line confirms it. gfx_load takes it before that and says draft: true, so a draw command the draft found can be tried with gfx_blits first.

More on why

A match is only as strong as the search is wide, and you set the width. A patch cut to one window matches once whenever it matches, so the number of windows tried says nothing; the rarest pen does. At three planes or more, a layout's only match in a search of every tile also proves it.

Two layouts of one tile size that both matched are rivals. One is proved only when an answer that tried both saw it match a window the other missed; otherwise neither is written. Layouts of different sizes are not rivals.

A pick from a gfx_sweep sheet is written as human where nothing of its tile size is proved. A match that proves the same layout turns it into proved, and a match that proves another is reported as contradicting it.

An asset is written for each block and palette bank a format was drawn with; asset_names lists them. A format matched only through gfx_locate's pen table proves no bank, so it gets no asset.

A draw command comes from a capture watch (watch_add), paired with the answers whose matches all sit in one window. An answer of screen frame F pairs with the capture's row of frame F minus a lag. Each word of the block is tried as dest_x, dest_y and source_tile, with a sign and an add.

A capture whose callbacks raised is short of writes, so the draft proves no draw command from it and says why in not_proved.

A reading holds when it agrees on every paired answer, on enough of them, with a value that changes. The lag is the one at which both x and y hold; none or several settle nothing. A role that holds only at another lag is left out and named (elsewhere); command_fields lists what was written.

Every figure lives in the report, which the same record regenerates byte for byte, and the draft's source lines name the report's key. A choose is recorded once however often it is made, and not at all when the draft fails.

The contract your client receives
Text
Write a `gfx.yaml` draft from what this session proved, and a JSON report beside it with
every figure. Refused with no evidence.

`dest`: an absolute `.yaml` in an existing directory (empty: the scratch); an earlier draft
there is replaced, anything else is refused. `choose` `{"candidate": "s1c3", "chosen_by":
"<who>"}` records a person's pick first.

Reply: `manifest` and `report` (each `path`, `sha256`), `formats` (name to status),
`asset_names`, `command_fields`, `evidence`, `not_proved` (first 8),
`chose` (with `choose`), `confirm`.

Reference: REFERENCE.md, Input and the screen.
Tools