SCRYDOSBox-XReferenceStatesstate_listAlso in MAME

DOSBox-XStates

state_list

List the session's saved states, with what each file says of itself: program, machine, memory and time.

state_list()

Try it

On Bricks, the game this repository builds, after a state was saved as third-brick. 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 5 fields
{
  "summary": "state_list: 1 state in ./tmp/demos/tour/files/states",
  "status": "ok",
  "state_dir": "./tmp/demos/tour/files/states"
}

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

The whole reply
JSON
{
  "summary": "state_list: 1 state in ./tmp/demos/tour/files/states",
  "status": "ok",
  "state_dir": "./tmp/demos/tour/files/states",
  "states": [
    {
      "name": "third-brick",
      "path": "./tmp/demos/tour/files/states/third-brick.sav",
      "bytes": "<volatile>",
      "version": "<volatile>",
      "program": "BRICKS",
      "machine": "MCH_VGA",
      "memory_mb": 4096,
      "saved_at": "<volatile>"
    }
  ],
  "working_slot": {"available": false, "why": "the emulator's own numbered slot has not been written"}
}

Arguments

Takes no argument.

What comes back

state_dir
The folder the states are in: the state_dir given to start, or one in the session's temporary folder, which close deletes.
states
One row per named .sav file: name, path, bytes, version, program, machine, memory_mb and saved_at. A row that is no state carries a note.
working_slot
The emulator's own numbered slot file, as a row of its own because it is not a named state. Unavailable when it has not been written.
All 3 reply fields
  • state_dir (string)
  • states (array)
  • working_slot (object)

Why it works this way

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

A file that is not a state keeps its row, with a note and its values unavailable. So does a .sav that is no regular file: a link to nothing, a directory, a FIFO. A .sav under a name no load reads, such as Boss_1.sav where a state is boss-1, carries a note saying to rename it.

The contract your client receives
Text
List the session's saved states, read off each file without loading it.

Reply: `state_dir`, `states` (`name`, `path`, `version`, `program`, `machine`, `memory_mb`,
`saved_at`, `bytes`, `note`), `working_slot`.

Reference: REFERENCE.md, Saved states.
Tools