SCRYMAMEReferenceStatesstate_listAlso in DOSBox-X

MAMEStates

state_list

List the session's saved states, with the size of each and where it was saved.

state_list()

Try it

On Gridlee, a free ROM from mamedev.org, after a state was saved as two_credits. The example session gives start a state_dir of its own.
Ask

Which saved states does this session have?

Call
state_list()
Reply 3 of 4 fields
{
  "summary": "state_list: 1 state in ./tmp/demos/tour/gridlee-states/sta/gridlee",
  "status": "ok",
  "state_dir": "./tmp/demos/tour/gridlee-states/sta/gridlee"
}

The summary counts one state, and state_dir is the folder it is in: sta/gridlee under the state_dir given to start.

The whole reply
JSON
{
  "summary": "state_list: 1 state in ./tmp/demos/tour/gridlee-states/sta/gridlee",
  "status": "ok",
  "state_dir": "./tmp/demos/tour/gridlee-states/sta/gridlee",
  "states": [
    {
      "name": "two-credits",
      "path": "./tmp/demos/tour/gridlee-states/sta/gridlee/two-credits.sta",
      "bytes": "<volatile>",
      "frame": 543,
      "pc": "0x0000b502"
    }
  ]
}

Arguments

Takes no argument.

What comes back

state_dir
The folder the states are in: sta/<system> under the state_dir given to start, or under the session's temporary folder, which close deletes.
states
One row per .sta file: name, path, bytes, and the frame and pc it was saved at. A value not read is unavailable, with why.
All 2 reply fields
  • state_dir (string)
  • states (array)

Why it works this way

The list is read from the folder, not from the machine, so it answers while the program runs.

frame and pc are known only for a state this session saved. A .sta from an earlier session has them unavailable, as a load of it reports.

A .sta that is no regular file (a link to nothing, a directory, a FIFO) has bytes unavailable too, its why saying what is there. So has one under a name no load reads, such as Boss_1.sta where a state is boss-1: its why says to rename it.

The contract your client receives
Text
List the saved states of the session's state folder.

Reply: `state_dir`, `states` (each `name`, `path`, `bytes`, `frame`, `pc`; unavailable with
`why` when not read).

Reference: REFERENCE.md, Saved states.
Tools