Devices are external systems to the Uxn code such as the screen, the mouse, the keyboard, etc. There is a maximum of 16 devices, each device have 8 bytes to read from, and 8 bytes to write to.

Devices

An emulator implementation can choose which device to implement or to leave out, these are the suggested addresses and ports of this specific emulator.

devicei/oNotes
0x000x08
00systemvector*red*The system device's vector is automatically set by the emulator and is the first vector that is triggered in a program.
green*
blue*
10consolevector*charThe console's vector is currently unused.
byte
short*
string*
20screenvector*x*The screen device's vector is triggered 60 times per second, it is typically used to update pixels on the screen.
width*y*
height*addr*
color
30
40
50
60
audiovector*adsr*The audio devices' vectors are currently unused.
position*length*
outputaddr*
volume
pitch
70midivector*The midi device's vector is triggered when a midi note is received.
channel
note
velocity
80controllervector*nilThe controller device's vector is triggered each time a key is pressed or released.
button
key
90mousevector*nilThe mouse device's vector is triggered each time the mouse moved, or a button was pressed or released.
x*
y*
state
chord
a0filevector*name*The file's vector is currently unused. The reading/writing of a file will set the success short to the length of that data.
success*length*
offset*addr(r)*
addr(w)*
b0datetimeyearh*refreshThe datetime's vector is currently unused.
yearl*
dayh*
dayl*

Screen Device(PPU)

Buffersbackground64kb
foreground64kb

The screen device is made of two screen buffers, that are combined to form the pixels on the screen. The sprite device can be written to with a x*, y* and color.

The color byte defines the layer to draw on, the type of data to draw, and the colors to use. To paint a pixel on the first layer, use the #01, to paint a pixel on the second layer, use the #11.

* * M L            D C B A            
| | | +---- Layer  | | | +---- Blend   
| | +------ Mode   | | +------ Blend   
| +-------- Flipx  | +-------- Blend  
+---------- Flipy  +---------- Blend  

The device can also draw multiple bytes at once by writing the address* to a series of bytes in the screen's sprite address, to paint a 1-bit 8x8 sprite(8 bytes) on the first layer, use the #21, to paint a 1-bit 8x8 sprite on the second layer, use the #31. The blending mode 1, is demonstrated in the table below. To learn more about the sprite format, see .chr format.

high nibblelow nibble
0bgpixel00802
1fg110912
2bg1-bit220a2
3fg330b32
4bg2-bit401c03
5fg51d13
6bgnil621e23
7fg731f3

Audio Device(APU)

When pitch is written to any of the audio devices, it starts playing an audio sample from Uxn's memory, pointed to by addr* and length*. It loops the sample (unless told not to) until it reaches the end of the ADSR envelope defined by adsr*.

Several fields contain more than one component:

adsr*pitchvolume
output
SubfieldAttackDecaySustainReleaseNo LoopNote NumberLeftRight
Size (bits)44441744

Each of the ADSR components is measured in 16ths of a second, so writing #4444 to adsr* will play a note that lasts for exactly one second. If adsr* is #0000 then no envelope will be applied: this is most useful for longer samples that are set to play once by setting the most significant bit of pitch to 1.

The two volume components set how loudly the next sample will play. #ff sets maximum volume for both speakers.

When pitch is written, any sample that is currently playing will be replaced with the sample defined by all the values set in the device. While the sample is playing, the output byte can be read to find the loudness of the envelope at that moment.

Audio Sample Format

All samples used by the audio devices are mono and signed 8-bit, so the space taken up by samples is minimized. The sample rate of the samples depends on length*:

length*Sample typeSample rate
> 256Middle-C pitched sample44,100 Hz
2–256Single wavelengthVariable

Long samples are assumed to be already pitched to Middle C and will loop (unless No Loop is 1) until the end of the envelope. To play the sample at the same rate as it was recorded, write the Middle C MIDI note number, #3c, to pitch. To play at double or half speed, for example, write an octave higher or lower to pitch.

The minimum sample size that can be pitched at 44.1 kHz to Middle C with reasonable accuracy is 337 bytes long, which represents two cycles of the 261 Hz wave. The single wavelength mode in Uxn allows much smaller samples to be used, even down to only two bytes for a square wave. In this mode the length of the entire sample is taken to be one cycle of the Middle C note, so the pitch is not heard to vary even if length* were to change between sample plays.

Controller Device

This button byte works similarly to a NES controller, where there the state of each one of the 8 buttons is stored as a bit in a single byte. The keys byte contains the ascii character that is currently pressed.

0x01Ctrl0x10Up
0x02Alt0x20Down
0x04Shift0x40Left
0x08Escape0x80Right