16

Work in progress!

Development repository: https://github.com/lowagner/bitbox-16

This is the wiki page for the 16-color palette, 16x16 pixel tile/sprite game and music editor.

Development can be read up on at the Pyra forums, and some older stuff here.

User Manual

Hit select to change the mode, and other buttons are mostly well documented.

Instrument Editor

An instrument is made up of 16 or fewer instrument commands, which specify which sounds to play and when. It takes some getting used to, but the commands are very powerful. You can specify up to 16 instruments, but there are only 4 "players". Each player can play any instrument, so they are a versatile quartet.

When editing an instrument, and it doesn't make any sound, make sure to add a note. The melodic waveforms (sine wave, triangle, saw, or square wave) require a note to sound. (Also ensure a nonzero volume, but each time a note is hit the instrument volume is set to some default.) For the noise waveforms (white noise, red noise, violet noise), a note is not required; the noise will begin when the noise waveform is encountered in the instrument command list.

Also make sure to add some wait commands (e.g. W4) when changing waveforms or volumes or anything really. The instrument commands are all parsed simultaneously unless there is a wait.

Instrument Commands

name	values	description
break	04-64	ends the instrument commands early if the track position is less than the parameter. 64 quits always, since max track length is 64.
side	sh, L_, _R, LR	puts audio output into left/right channels (or none, shh), or various values in between
waveform	∿, ∧∨, //, ..., #-, ...	sine, triangle, saw, square, and various noise waveforms
volume	VX, with X=0-f	sets instrument volume
note	C, C#, ..., Bb, B, C, ... Eb	plays a note, second partial octave is shaded funny
wait	WX, with X=1-g	pauses command evaluation for X frames (still plays notes if applicable)
fade in	<X, with X=0-f	sets change-in-volume-over-time to +X units
fade out	>X, with X=1-g	sets change-in-volume-over-time to -X units
vibrato	~X, with X=0-f	smaller two bits of X (0,1,2,3) correspond to vibrato amplitude, second two bits (0,4,8,c) correspond to vibrato rate
bend	╯X, with X=0-7, or ╮X with X=1-8	frequency bends up ╯ or down ╮, faster with increasing X.
note inertia	iX, with X=0-f	the bigger X is, the more the instrument will slide between notes
bitcrush	◣X, with X=0-f	crunches the sound a bit. only values X<=7 make sense.
duty	ΓX, with X=0-f	sets the point at which pulse wave transitions from min to max (X=8 is a square wave)
duty delta	ΔX, with X=0-f	sets the change-in-duty-over-time to X units
randomize	RX	randomizes the next command's argument based on X; possible values are filled in on X, with 0-3 on the bottom row (left-to-right), 4-7 on the next row up, then 8-11, then 12-15 on the top row
jump	JX, with X=0-f	jump to instrument command X. make sure there's a wait (e.g. W4) between X and the jump point (if X is earlier)

Example Instruments

The first instrument sounds eerie and ghostly:

position	command	description
0:	C	play a C note
1:	∿	sine waves are the eeriest
2:	if	set a high inertia, so notes will slide around
3:	Wf	wait 15 frames
4:	~c	start a vibrato
5:	Wf	wait 15 frames
6:	Wf	wait 15 frames
7:	>1	fade out slowly

The next instrument uses random wavefunctions to sound edgy and percussive:

position	command	description
0:	C	play a C note
1:	R_	randomize next command, keep it melodic
2:	∿	some arbitrary waveform
3:	W7	wait for some amount of time
4:	J0	jump back to command 0

Homework: change the above instrument to make the "computer-blinky-noisey" sounds from early movies/shows with computers in the scene. (Though you may also want to decrease the wait to make it sound like it's processing faster.)

The randomize command is an excellent command, and it can be applied to every other command (besides break). It can even be applied to itself, or to another randomize command.

Our final example instrument uses arpeggios to sound fancy (lifted from LFT's chiptracker):

position	command	description
0:	#_	start with white noise
1:	W3	wait 3 frames
2:	_Π	switch to square wave
3:	Δ6	change the wave's duty
4:	>1	fade out slowly
5:	C	hit high C
6:	W3	wait 3 frames
7:	G	hit G
8:	W3	wait 3 frames
9:	Eb	hit E flat
a:	W3	wait 3 frames
b:	C	hit C
c:	W3	wait 3 frames
d:	J7	jump back to command 7

It fades out over time, which is a nice effect. Try adding some randomizer commands to see what you can come up with!

Track Editor

The track editor is much like the instrument editor; you use commands to play notes, adjust the volume, etc. It's a little like a MIDI specification, since you need to put notes in relative to each other (with waits).

There are three main differences between the instrument and the track editor:

1. The smallest unit of time on a track is called a "tick". You can't specify one note and then another in any shorter time than one tick (W1 in between each note). The actual duration of a tick depends on the song speed (if you want to sync things up with your instrument command waits). The track length, like a measure length, is measured in how many of these ticks, from 4 to 64 (in steps of 4).

2. IMPORTANT! When attempting to play notes, you need a nonzero track volume at the beginning of your track, for all tracks. You may also want to set the octave using the commands below, and the instrument. On the instrument editor, a default volume can be assumed, but on the track editor, it must be specified.*

3. There is room for 32 track commands as opposed to 16 instrument commands. This means you can play up to 31 track notes (using the volume V command, then 31 N commands, see below). If you need more, put fancy arpeggios/grooves in your instrument commands, and then use fewer track notes.

name	values	description
break	00-60	waits until the track position given, or quits track commands if that time is now or passed
octave	OX, with X=0-6, ==, +X or -X, /X or \X with X=1-2	absolute octave OX, reset to instrument value ==, or relative changes (+X or -X with ceiling, /X or \X for wrap around)
instrument	IX, with X=0-15	switch to instrument X
volume	VX, with X=0-f	sets track volume
note	C, C#, ..., Bb, B, C, ... Eb	plays a note, second partial octave is shaded funny
wait	WX, with X=1-g	pauses command evaluation for X ticks (still sounds last note if applicable)
note and wait	NX, with X=0-f	hits a note relative to last previous note (0, 4, 8, c) -> (0, +1, +2, -1) semitones and then waits (0,1,2,3) -> (1, 2, 3, 4) ticks; e.g. 5 means play a note up from previous, and then wait 2 ticks.
fade in	<X, with X=0-f	sets change-in-volume-over-time to +X units (1 unit of volume per tick)
fade out	>X, with X=1-g	sets change-in-volume-over-time to -X units
vibrato	~X, with X=0-f	the amplitude is set by the least significant two bits (0-3), and the rate is set by the most significant two bits (0, 4, 8, c).
inertia	iX, with X=0-f	note slides
transpose	TX, with X=0-f	GLOBAL transpose song. T0 resets to no transpose, anything else adds to song_transpose mod 12.
speed	SX, with X=0-f	set song speed (song_speed = 16-X), larger X is a faster song (smaller tick size)
length	LX, with X=1-g	set track length to 4*X ticks
randomize	RX	randomizes the parameter of the next command based on X; possible values are filled in on X, with 0-3 on the bottom row (left-to-right), 4-7 on the next row up, then 8-11, then 12-15 on the top row
jump	JX, with X=0-u	jump to track command X (steps by 2). make sure there's a wait (e.g. W4) between X and the jump point (if X is earlier)

*Technical consideration for point 2: you don't need to put in a volume for any track beyond track 0, but you'll have to play from the beginning of the song to hear the track. So it's useful to put a volume there for testing the track, but you can remove it later if you wish, since when playing the song the track volumes persist from one track to the next.