emulator.doc

=== Command-line switches ===

-D
  Use double buffering for the display.

-F
  Start in full screen mode. It will decide the appropriate screen size
  automatically if you do not specify the -w and -h switches. This does
  not imply -S but you may specify both switches.

-I
  Use a separate thread to read from stdin.

-J #
  Set joystick mode. See the below section about joystick for details.

-N
  Tells the window manager to omit the frame.

-O
  Emulate touch screen. (This is an experimental feature, and may be
  changed or removed in future.)

-Q
  Disable the mouse initially (it can still be enabled at run time).

-S
  Disallow the uxn program to change the screen size.

-T year.month.day.hours.minutes.seconds.wday.yday.yday.isdst
  Use a fixed value for the date/time, by numbers with dots in between. In
  this case, it will read the same values from the date/time device each
  time it is read. If you put less numbers than expected, then zero will
  be used for the remaining values; however, some programs will use these
  values to seed a random number generator and will not work correctly if
  they are zero. (Note that the month number is zero-based, while the day
  number is one-based.)

-T @unixtime
  Use a fixed value for the date/time like the other -T does, but treat
  the argument as UNIX time if the argument starts with a at sign; it will
  be converted to the corresponding date/time in the Gregorian calendar.
  In this case, the presence or absence of the -Z switch does matter,
  since it will convert it to local time if the -Z switch is not specified
  or to UTC if the -Z switch is specified.

-Y
  Enable file system access including writing.

-Z
  Use UTC instead of local time. (Has no effect in combination with -T,
  unless the UNIX time variant of -T is used.)

-a #
  Set audio. See the below section about audio for details. If both -a and
  -n switches are used, then audio data is written to stdout (it is signed
  16-bits big-endian).

-d
  Enable some debugging features. (Some will work even without this.)

-e #
  Execute another program (with "sh -c"), which will be connected to this
  one using the standard I/O. For example, it can be used with nc to make
  remote two players.

-h #
  Set default screen height.

-i
  Hide the system mouse cursor. (The Uxn program might still draw its own
  mouse cursor, which most do.)

-j
  Enable key repeat for joypad emulation.

-m #
  Specify memory writes and device writes to do before or after loading the
  file. See the "Memory/device scripts" section below for details.

-n
  Disable GUI. Either this switch or -I is required in order to read stdin.
  If neither -n nor -I is specified, then stdin cannot be read (although
  command-line arguments can still be read).

-p #
  Select the palette. Valid palette numbers are 0 to 7, where 7 is the
  default setting and means that the running Uxn program can set colours.
  If you follow the palette number by a equal sign and then RGB hex codes
  then it will define that palette. Specify eight RGB colours each of which
  is six hex digits, with commas in between.

-q
  Disable standard I/O.

-s #
  Define scroll amount.

-t #
  Set the frame rate, in milliseconds per frame.

-w #
  Set default screen width.

-x
  Enable nonstandard features.

-y
  Enable read-only file system access.

-z #
  Set zoom level.


=== Function keys ===

F1
  Advance one frame, even if paused.

F2
  Mute/unmute audio.

F3
  Toggle the mouse mode. When the mouse mode is disabled, the mouse device
  does not work; the mouse vector is not called and the mouse coordinates
  and button state is not updated.

F4
  Change which graphics layers are displayed. Either both layers, or only
  foreground or only background.

F5
  Redraw screen. If the right shift key is also pushed, then also sends
  some debug output to stderr.

F6 / F7
  Palette selection.

F8
  Debug menu.

F9
  Restart.

F10
  Quit.

PAUSE
  Pause/unpause VM.

PAGE-UP / PAGE-DOWN
  Scroll up/down.

Some programs use shortcut keys with control and letters. This does not
work in this program; therefore, END is an alias for the joypad A button
(the left control key also corresponds to the joypad A button, but if used
together with letter keys, will enter control characters instead).


=== Audio ===

The audio setting consists of a sequence of letters and numbers; each item
is one letter "a" to "z" followed by a number of any number of digits. (It
can optionally have - at first for negative numbers, although most options
cannot use negative numbers.)

b = Buffer size.

c = Number of output channels, which can be 1 (mono) or 2 (stereo).

e = Envelope speed. If not specified, then it is fifteenths of seconds.

m = If set to 1, then audio is initially muted. (This option is ignored if
the -n switch is used.)

n = Transpose amount.

r = Sample rate in hertz. Normally, this setting is also the sample rate
for middle C.

v = Output volume from 0 to 273. If not all of the four VM audio channels
are being used, then this number may be set higher than 273.

(Currently there is not the setting of interpolation, filter, etc.)


=== Joystick ===

The joystick parameter can be ? to list joysticks, or ? and a number to
display details about that joystick, or it can be the below specification
in order to configure joysticks.

The first part is numbers with commas in between, being the joystick ID
numbers (as shown by the ? list); up to four numbers can be specified. If
a number is omitted, then that slot is not used.

After the first part is a forward slash, and then the mapping (all
joysticks must use an identical mapping). Each item is a letter and then
a number, with no delimiters in between. The letters can be:

A B S T U D L R
  Specify which joystick button to map to the uxn joypad button;
  respectively, A, B, SELECT, START, UP, DOWN, LEFT, RIGHT. Only the first
  128 buttons can be mapped.

X Y x y
  Specify which axis to use as the X and Y axis. Uppercase letters means
  that axis is reversed; do not specify both "X" and "x", and do not
  specify both "Y" and "y".

s
  Set sensitivity, from 1 to 32767. Higher numbers mean the joystick must
  be moved more in order to register, while lower numbers means that it
  does not need to moved much in order to be registered.

H h I i
  Specify the hat number to use. Different letters correspond to different
  orientations (specify only up to one of these letters, not all of them).
  "h" is normal, "H" is reverse, "I" and "i" are sideways.


=== Nonstandard features ===

The -x switch enables the following nonstandard features, which include
some nonstandard expansion commands and nonstandard ports. They should not
be used in portable programs until they become standardized, though (you
can discuss in the mailing list of Uxn; changes may also be made in future,
possibly as a result of the discussions).

If any such features listed below become standardized in future, then their
documentation will be moved to the varvara.doc file, and the -x switch will
no longer be required in order to use them.

The list of expansion commands below uses > for output parameters (from the
emulator to the program), ? for parameters that may be input and/or output,
* for 16-bit values, and % for values of lengths other than 8-bits or
16-bits or if they are of a variable length.

03 device_id uuid% >version ?extra%
  Loads a nonstandard device, or a nonstandard command for an existing
  device or that applies globally; see below section for details. This is
  called a "UUID-based extension".

04 >pages*
  Tells number of expanded memory pages. (This is the maximum valid value
  for src_page and dst_page in expanded memory operations.) (If some of the
  pages are read-only, then this is only the number of writable pages. The
  number of writable pages might be less than the tital number of pages on
  systems with insufficient memory but that is able to emulate larger
  memory by reading from the program file instead.)

a0 offset%
  Given a 32-bit offset, seek the currently opened file to the specified
  absolute offset. (The effect of seeking (absolute or relative) when a
  file is opened in append mode is unspecified.) If the file is not already
  open, it is opened for reading and writing (the append flag is ignored);
  if writing is not allowed, then it is opened for reading only.

a1 offset%
  Given a signed 32-bit offset, seek the currently opened file to the
  specified offset relative to the current file position.

a2 offset%
  Given a signed 32-bit offset, seek the currently opened file to the
  specified offset relative to the end of the file.

a3 >offset%
  Tell the current offset of the currently opened file; the 32-bit offset
  will be stored in the expansion command buffer.

b_ ?offset%
  Same as a_ but for the second file.

Nonstandard ports of devices are:

16
  Input flags. Currently only the low bit is used (the rest must be clear).
  If the low bit is set, then EOF trigger is enabled; the vector is called
  on EOF, with the type and input both set to zero.

36*/46*/56*/66*
  Detune register. This is treated as sixteen fraction bits, and is then
  added to 1.0 and multiplied by the frequency which has been specified by
  the pitch and length ports.

a7/b7
  In addition to the usual effect (sets the append mode), writing anything
  to this port (whether or not it is the same value that was previously
  written) will close the file.


=== Extensions ===

This describes the nonstandard "03 extensions" command mentioned above.

The parts of the command are:

* Command code: Always 0x03.

* Device number: A command that does not load or override a device into a
device slot is zero, otherwise it is a nonzero multiple of sixteen. Some
extensions and some implementations may have further restrictions. If this
number is not a multiple of sixteen (but must be at least sixteen), then
the low nybble indicates how many additional consecutive devices to be
affected; e.g. #33 means to affect all four audio devices (the high nybble
is 3 for the first audio device, and the low nybble 3 means the other 3).

* UUID: Sixteen bytes, which identifies the extension.

* Version: One byte. The emulator writes a nonzero value here (the specific
value is defined by the extension) if it is supported in this mode with
this device number and other parameters, or zero if it is not implemented.
(The uxn program should put zero here by default, so that if running on an
emulator that doesn't process the 03 command at all, it will work.)

* Extra data: The number of bytes and meaning is defined by the specific
extension; this may be read-only, write-only, or some combination. If the
extension is not implemented, then the emulator MUST ignore it and MUST NOT
attempt to write anything here, and MUST NOT override any devices.

An example of how to use this:

  @load-ext1 ( -- success ) ;ext1 #02 DEO2 ;ext1/v LDA JMP2r
  @ext1 03 d0 <uuid> &v 00

This example does not use any extra data, and selects an extension for
device #d0. The <uuid> must be replaced by the appropriate sixteen-byte
UUID for the extension being selected.


=== Implemented extensions ===

This section lists the UUID-based extensions that are implemented in
this emulator (the -x switch is required, since they use nonstandard
expansion commands to activate them).

See the file extension.doc for the definition of the extensions.

* 80175132-e263-11ed-b8c9-002618745416

* 970b5a0c-2c44-11ee-ac3b-002618745416

* 9c5f1356-6bc5-11ef-a6c9-002618745416 (also requires -I and -Y)


=== Memory/device scripts ===

A command with the -m switch has the subcommands which have the format of
an optional "." to indicate executed after instead of before loading, and
then an optional letter "g" to "z" to specify the specific command (if none
is specified, then it is a memory command), and then the address in hex,
and then optionally = and the data in hex. The address is treated as a pure
number while the data is a sequence of bytes so the number of digits must
be an even number.

It can also optionally be @ and a file name, in which case the commands are
loaded from a file. The file cannot itself have @ commands, but it may have
lines starting with # as comments.

The subcommands are:

Memory (no letter)
  Write memory starting at the specified address.

Device trigger (p)
  Write and trigger devices starting at the specified address. If there are
  multiple bytes of data, then multiple consecutive ports are written to
  and are triggered.

Device set (s)
  Same as device trigger but omit the trigger; only writes are done.

Extension set (u)
  The data is the same as the 03 expansion command but without the initial
  03; it is automatically written into memory and executed as an expansion
  command. (This is a shortcut for the specific case of loading an
  extension that is not loaded by the uxn program itself, rather than
  having to use the -m and -mp switches. The address can be omitted,
  since the expansion command does not care about the address.)

Execute (x)
  Execute uxn code at the specified address, which must be nonzero, and
  cannot be in expanded memory. (The data of this command is not used.)

Screen compatibility flag (z2)
  The first byte of the data is the screen compatibility mode; see
  extension.doc for a list of the valid flags.

During the execution of any of these commands, it behaves as though the -x
switch is specified, even if it isn't specified.