Character classes

File conventions

• The character set is always UTF-8.
• All integers are written using Unicode codepoints DIGIT ZERO - DIGIT NINE (and prefixed with HYPHEN-MINUS if negative)

Notations:

• "foo" is literal string foo as Unicode code points.
• () denote grouping.
• <space> is any space character (see section on spaces below)
• <linefeed> is any linefeed character (see section on linefeeds below)
• something* is something repeated zero or more times
• something+ is something repeated one or more times
• something? is something or empty.
• $foo denotes Metasyntactic variable.
• $foo... denotes Metasyntactic variable that may span multiple components.
• Space means either concatenation (in raw strings) or component split (in stuff that is component-encoded)
• <start-of-line> is special zero-length string at beginning of line.
• <end-of-line> is special zero-length string at end of line.

Spaces

• Codepoints 0x20 (SPACE) and 0x09 (TAB)
• Codepoints 0x1680, 0x180E, 0x2028, 0x205F and 0x3000
• Codepoints 0x2000-0x200A.

Line feeds

• codepoint 0x0A
• codepoint 0x0D
• codepoint 0x1C-0x1E
• codepoint 0x85
• codepoint 0x2029

File structure

Magic

Blank lines

Starting section

Section line

Ending section

End of file

Line (component) format

• <start-of-line>: Initialize depth counter to 0. Initialize current token to "", initialize array to empty.
• <space>: If current token is not empty string, append token to array and reset token to "".
• "(" and depth counter is 0: Increment depth counter to 1 and behave like <space> was read.
• "(" and depth counter is >0: Increment depth counter and append literal '(' to token.
• ")" and depth counter is >1: Decrement depth counter and append literal ')' to token.
• ")" and depth counter is 1: Decrement depth counter to 0 and behave like <space> was read.
• ")" and depth counter is 0: Parse error.
• "\" (backslash) followed by <end-of-line>: Parse error.
• "\" (backslash) followed by some character: Read next character and append it to token as-is. Don't process the next character further.
• <end of line> and depth counter is >0: Parse error.
• <end of line> and depth counter is 0: Behave like <space> was read. If the resulting array is empty, ignore the whole line. Otherwise the array is the parse result.
• anything else: Append character literally to current token.

Sections

"header" section

• "PROJECTID" $opaque:
  • Multiplicity: 1
  • Meaning: Project ID is $opaque. Project ID is used for keeping track if newly loaded savestate is from the same movie (for purposes of keeping rerecord count and not erroring out the load if it would result cross-movie rewind).
• "SAVESTATEID" $opaque:
  • Multiplicity: 0-1
  • Meaning if present: This is either savestate or movie starting from savestate. The $opaque must equal to ID of one of the savestate events in event section.
  • Meaning if absent: This is movie starting from poweron.
• "RERECORDS" $count:
  • Multiplicity: 1
  • Meaning: Movie rerecord count is $count. $count must be nonnegative integer.
• "AUTHORS" $author...:
  • Multiplicity: 0-(infinity)
  • Meaning: Gives authors (real names) of run. Each component of $author... gives new author. The names listed are presumed to be real names.
• "AUTHORNICKS" $nick...:
  • Multiplicity: 0-(infinity)
  • Added in: R10.9.
  • Meaning: Gives authors (nicknames) of run. Each component of $nick... gives new author. The authors listed are assumed to be nicknames and do not have real names.
• "AUTHORFULL" $fullname $nickname:
  • Multiplicity: 0-(infinity)
  • Added in R10.9.
  • Meaning: Run has author with full name of $fullname and nickname of $nickname.
• "COMMENT" $opaque...:
  • Multiplicity: 0-(infinity)
  • Meaning: Comment. Not parsed by emulator.
• "SYSTEM" $system:
  • Multiplicity: 0-1
  • Added in R10.14.
  • Meaning if absent: Ignored.
  • Meaning if present: If $system is anything else than "PC-JPC-RR-r10" or "PC-JPC-RR-r11.3" (starting from r11.3), causes savestate/movie load error (as incompatible movie).
• "INITIALSTATE" $opaque:
  • Multiplicity: 0-(infinity)
  • Meaning: Denotes that "initialization-"$opaque is a valid initialization section to choose. If this is not present, "initialization" is assumed. If present, SYSTEM should be set to "PC-JPC-RR-r11.3".

"initialization" section

• "BIOS" $id: BIOS image ID is $id.
• "VGABIOS" $id: VGA BIOS image ID is $id.
• "INITIALTIME" $time: Number of milliseconds since Unix epoch when system is first powered on. $time must be integer 0-4 102 444 799 999.
• "CPUDIVIDER" $divider: Divide 1GHz by $divider to get CPU clock rate. $divider must be integer 1-256.
• "MEMORYSIZE" $pages: Number of 4KiB pages of memory present is $pages. $pages must be integer 256-262 144.
• "BOOT" $device: $device must be one of "FLOPPY", "HDD" or "CDROM". Sets the boot device. If $device is "CDROM", HDC must not be present. If $device is "HDD", HDA must be present.

• "HDA" $id: HDA image ID is $id.
• "HDB" $id: HDB image ID is $id.
• "HDC" $id: HDC image ID is $id.
• "HDD" $id: HDD image ID is $id.
• "FDA" $num: Upon poweron disk number $num is put into FDA. The specified disk must be of floppy type.
• "FDB" $num: Upon poweron disk number $num is put into FDB (the disk with same number must not be put into FDA too). The specified disk must be of floppy type.
• "CDROM" $num: Upon poweron disk number $num is put into CD-ROM drive. Mutually exclusive with HDC. The specified disk must be of cd-rom type.
• "IOPORTDELAY": Signals that I/O delay emulation is enabled.
• "VGAHRETRACE": Signals that VGA horizontal retrace emulation is enabled.
• "FLUSHONMODIFY": Signals that pipeline is to be flushed on detected code self-modification.
• "VGATIMINGMETHOD" $method: $method is either "0" or "1". If "0", classical force-60fps VGA timings are used. If "1", real VGA timings in accordance with timing registers are used.
• "SVGATYPE" $type: $type is either "0" or "1". If "0", emulated SVGA card is revision 2 BGA. If "1", emulated SVGA card is revision 5 BGA.

• "DISK" $num $id: ID of image in image slot $num is $id. $num must be nonnegative integer. Only one entry for each $num may be present.
• "DISKNAME" $num $name: Set name of image in image slot $num to $name. The image slot must be defined before setting its name by DISK line.
• "LOADMODULEA" $module $parameters: Load module named $module, passing $parameters to it.
• "LOADMODULE" $module: Load module $module.
• "FPU" $class: Set FPU emulator class to $class. Obsolete but still supported.

"savestate" and "manifest" sections

"events" section

• Class "SAVESTATE":
  • $opaque $rerecords: Savestate with identifier $opaque. $rerecords gives the rerecord count at point of saving (must be nonnegative integer).
• Class "OPTION":
  • "RELATIVE": Further timestamps will be relative to last timestamp.
  • "ABSOLUTE": Further timestamps will be relative to initial poweron (warning: buggy in versions R10.7 and before).
• Class "org.jpc.emulator.peripheral.Keyboard"
  • "KEYEDGE" $keynumber: Specified key pressed or released (initially all keys are released). The $keynumber must be from ranges 1-83, 85-95, 129-197 or 199-233. Timestamp of event must be divisible by keyboard time unit (66 666ns), and there must not have been any keyboard events within certain number of units^[1]
  • "PAUSE": Pause is hit. The timing restrictions are the same as in KEYEDGE case.
  • "MOUSEBUTTON" $button: Specified mouse button is pressed or released (initially all buttons are released). $button must be one of 0, 1, 2, 3 or 4.
  • "XMOUSEMOTION" $motion: Specifies that mouse has moved by $motion mickeys (must be integer -255 - 255) in X direction (positive is right).
  • "YMOUSEMOTION" $motion: Similar to XMOUSEMOTION, but gives motion in Y direction (positive is up).
  • "ZMOUSEMOTION" $motion: Gives scrollwheel motion (positive is down?). $motion must be integer in range -7 - 7.
• Class "org.jpc.modules.Joystick" (joystick module required to use these):
  • "BUTTONA" $state: Set joystick #1 button A state to $state ("0" if released, "1" if pressed).
  • "BUTTONB" $state: The same as BUTTONA but for Joystick #1 button B.
  • "BUTTONC" $state: The same as BUTTONA but for Joystick #2 button A.
  • "BUTTOND" $state: The same as BUTTONA but for Joystick #2 button B.
  • "AXISA" $hold: Set joystick #1 X axis monostable multivibrator hold time to $hold nanoseconds (must be positive integer).
• "AXISB" $hold: The same as AXISA, but for joystick #1 Y axis.
• "AXISC" $hold: The same as AXISA, but for joystick #2 X axis.
• "AXISD" $hold: The same as AXISA, but for joystick #2 Y axis.
• "org.jpc.emulator.PC$ResetButton":
  • (none): Reboot the PC.
• "org.jpc.emulator.PC$DiskChanger":
  • "FDA" $num: $num must be integer at least -1. If $num is "-1", disk in FDA is ejected (FDA must contain disk). Otherwise disk number $num is inserted into FDA (it must be valid disk number for disk of floppy type that's not already in FDB and FDA must be empty).
  • "FDB" $num: Same as FDA, but roles of FDA and FDB swapped.
  • "CDROM" $num: Similar to FDA but for CD-ROM drive (obivously images must be of CD-ROM type and such disks can't be in FDA or FDB). HDC may not be present.
  • "WRITEPROTECT $num: Turn on write protect of disk number $num (must be valid image slot of floppy type and must not be inserted in either fda or fdb).
  • "WRITEUNPROTECT" $num: Same as WRITEPROTECT, but turn off the write protect instead of on.

"diskinfo-<id>" sections

• TYPE FLOPPY: This is floppy disk image
• TYPE HDD: This is HD image.
• TYPE CDROM: This is CDROM image (.iso)
• TYPE BIOS: This is BIOS image
• TYPE UNKNOWN: WTF???
• IMAGELENGTH $length: Raw image length is $length.
• IMAGEMD5: Raw image MD5.
• TOTALSECTORS: Total sectors in image.
• TRACKS: Tracks (cylinders) on disk (per side)
• SIDES: Sides on disk.
• SECTORS: Sectors per track on disk.
• COMMENT: Line from image comments.

"output-info" section

• AUDIO $outputname: $outputname is audio output.
• VIDEO: Video output.