MANUAL FOR TRACKER2D

Press the help button again at any time to close this window. Complain to the dev until he creates a proper navigable table of contents for this manual!

The most basic tutorial follows:

  1. Select an instrument from the instrument menu.
  2. The QWERTY row on a standard (English-language) keyboard represents a Western chromatic scale; press any key there to select a note; plus and minus allow you to adjust your octave.
  3. When the "PEN" tool is selected (which it is when you first load up the application), clicking on a square will put instructions on the tile based on the parameters on the left.
  4. Once you have some instructions painted on the screen, press the play button in the lower left to get the bugs moving. Whenever they move over a grey tile, they'll play sounds based on the instructions in the tile.
The rest of this manual is intended to provide a highly detailed look into how Tracker2D functions. It may not always be up to date, and furthermore requires significant expansion and revision. It also may benefit from more elaborate visual styling, but I don't think that's quite as important beyond a very basic level.

UI FUNCTIONS

We need text here!


The Field

This is literally where the music happens. The way the UI is currently set up, you can see a 30*23 'slice' of the entire field (although this may change if we implement a zoom feature).

Depending on your current field setup, you may see up to 8 bugs and a variety of colorful tiles with various icons on them. What follows are some examples of tiles and how their parameters affect their appearance.

An image depicting several Tracker2D tiles.
A few rules of thumb:

Someday, I intend to implement alternate coloration and graphics schemes that the user can switch between at will.


The Left Bar

This uses HTML5-based controls. From top to bottom, the following functions are available:
Minimap: This shows a small view of the entire field. Clicking anywhere on it will move your view to a different part of the field. When you're using the Select or Paste tools, it also shows an overlay representing which tiles are currently in the selection buffer.
Pitch Indicator: This indicates your current pitch (we use mathematics to convert it into an actual pitch in hertz). When you press number keys and/or +/-, it changes. You'll also hear your instrument play.
Instrument Menu: This allows you to select which instrument is applied to the tile you're painting. It slides out when you roll over it so you can see the full names of the instruments.
Audio FX Button: This opens the new Audio Effects window, which allows you to set audio effects to apply to tiles. It is in desperate need of documentation.
Flow Control Menu: Use the "Change" button to select a flow control effect to apply to your current tile.
Volume Slider: Click and drag this slider to set the volume attribute for a tile.
Bug Storage: This shows the status of Tracker2D's 8 bugs (analogous to audio channels). By hovering over one of the boxes, you can see on the minimap the location of the corresponding bug. The other major functionality of this (click a box to toggle whether a bug is on the field or in storage) is mentioned in the UI.
Tick Counter: This shows how many units of time/tempo have passed since the last reset. It is updated by both manual resets and the reset tile.
Facebook: This takes you to Tracker2D's Facebook page, which opens in a new window. Pretty basic.


The Bottom Bar

This uses jQuery controls and HTML5 Canvas for icons. There are two rows, but tools with similar effects are placed together. Some tools have a selection indicator (a blue overlay).

First, the field painting bloc:
Play buttonPause buttonPlay/Pause Button: Changes state when clicked. Clicking it when it shows the play icon will the bugs to move. Clicking it when it shows the pause icon will cause the bugs to stop moving. Please note that attempting to use many other tools will pause playback.
PenPen: Click on a tile in the field, and it will put the musical instructions you've selected in the left bar onto that tile. This tool supports click and drag.
AudioFX PenAudio Effects Pen: This tool is essentially identical to the regular pen, except that it only adds or modifies the audio effects that are being applied to a tile. It does not affect tiles without notes in them. Like the normal pen, this tool supports click and drag.
EraserEraser: The eraser removes musical instructions from tiles that you click on. This tool supports click and drag.
SelectSelect: This tool allows you to select a rectangle of tiles on the field. It requires two clicks, but the rectangle can be as large as the field, or as small as a single tile. When this tool is selected, it draws a translucent grey overlay over the tiles you have used it to select. Furthermore, your selection is remembered until you draw a new one or perform file I/O (which uses the same 'buffer' functionality as this tool. If you replace the contents of your selection box by, for example, drawing inside it, this will not change the contents of the select buffer.
PasteMix PastePaste:This tool pastes the current contents of the select buffer where you click (which specifically determines the upper left corner of where pasting begins). In the UI Properties window, you can switch between the dfeault overwrite paste mode and one that doesn't overwrite tiles that currently have instructions in them.
QueryQuery: When you hover over a tile in the field with this selected, a window will pop up that displays detailed information about the contents of not only the tile, but any bugs that are in the tile.
Move Bug ToolMove Bug: This tool allows you to move a bug to a different tile. First, select the bug, then select the tile you want to move it to.
Turn Bug ToolTurn Bug: This tool rotates a bug in place. Currently, it only turns bugs clockwise. You can tell which direction a bug is heading in by looking at the direction their "nose" points.
EyedropperEyedropper: When you click a tile with this tool activated, your current options in the left bar will change to those in the tile you've clicked.
Pointer AdjusterPointer Adjuster: This tool makes the first tile you click with it point to the second tile you click with it.
Arrow PenArrow Pen: This is an alternate painting method to the normal pen that uses the keyboard. You can reposition the 'cursor' of the arrow pen (a yellow translucent overlay) by clicking on the map. Then, you can move it one tile at a time by pressing arrow keys on the numpad (2/4/6/8). Press "5" to change whether it paints tiles with your current properties or not when you move it around.
ExtrapolatorExtrapolator: This tool requires you to select two tiles on the field. If the tiles contain data in them, it draws a line between them; the data in the line's tiles is 'extrapolated' into a gradual transition between the values in the tiles you clicked. You can change which tile property is used in the UI properties menu.
Fill SelectionFill Selection: Once you've selected a rectangle using the select tool, you can use the fill button to replace all the tiles in the selection with your current tile. This is more useful from an art perspective than it is for music.
Horizontal FlipperVertical FlipperSelection Flippers: These tools flip your current selection horizontally or vertically. You don't need to have the selection tool active to use these. Please note that using them sets your paste mode back to overwrite mode.

The menu bloc:
HelpHelp: This pulls up the manual you're reading (or alternatively dismisses it if's already open). You presumably figured that out when you clicked on it in the first place. However, if you've been following the code repository, there's always the chance you first opened up this manual separately instead of looking at the iframe it's intended to spawn in.
Bug PropertiesBug Properties: This is very underdeveloped. Currently, it allows you to adjust the volume multiplier for individual bugs, which is multiplied by tile volume. In the future, it may contain more properties that allow you to adjust the specifics of a bug's playback.
Edit TileEdit Tile Properties: Click a tile on the field when this is selected to open a menu allowing you to manually adjust many of its parameters. This is currently the only way to set a tile's "flow control value" (which is currently only used for the counter).
Song PropertiesSong Properties: This menu allows you to adjust global properties for a song, including attribution data. It's currently also the location of the one UI option, at least until a new UI menu is created.
UI PropertiesUI Properties: This menu allows you to alter some aspects of how you interact with Tracker2D and edit files. These settings are saved between sessions, but not URLs - so if you change UI settings on the Github Pages version, for instance, they won't change on Kongregate.

The file I/O bloc:
Store Bug Positions: When you click this button, the current locations of your bugs are stored. This includes the storage unit on the left side of the screen, and it pauses any playback that might be occuring.
Restore Bug Positions: This moves your bugs back to wherever they were when you last clicked the "Store Bug Positions" button or loaded a new file, depending on which is more recent. Bugs will be moved into or out of the storage unit. Like the bug storing function, it also pauses playback.
Revert: As the program explains when you click this button, Revert attempts to change the tiles on the field to what they were when you last saved or loaded a file. This doesn't affect the positions of your bugs.
Save File: This pulls up your browser's download dialog, allowing you to save a Tracker2D file to your computer. Currently the files are stored as plain text, which means you can technically edit them manually if you understand the format well enough, although it's not recommended in most cases. Note that the file saving routine calls the same "store bugs" routine as the "Store Bug Positions" button.
Load File: This pulls up a dialog allowing you to load a text file from your computer that hopefully matches the Tracker2D format. I should probably change the extension on these things at some point. The loader then interprets the file as a Tracker2D field; in the process, it calls the "Restore Bug Positions" algorithm and uses a value stored in the file to choose which version of the loading algorithm to use.


The Dialog Windows

As of this writing, there are five of these that have any thing interesting within them.

Bug Properties

Currently, the only purpose of this window is that it lets you adjust the volume multiplier on a bug, which is multiplied by the volume data of a tile to get the total playback volume of a sample. Use this sparingly; at its absolute lowest it can combine with tile volume to reduce a sample's volume to an essentially inaudible 0.01%.

UI Properties

As previously mentioned, the settings here alter how you interact with Tracker2D, and are saved between sessions in your local storage. A list of options available through here follows.

Tile Properties

Click this button, and then click a tile on the field, and you will open up a more detailed editing window that allows you to edit a single tile in ways that are otherwise inaccessible; read on for more information about those.

Song Properties

Important field information is stored here; these values are stored at the end of a savefile, along with an internal version number (which is not user-updatable and is used to improve backwards compatibility).

  • Tempo:
  • Represents how fast the song is in beats per minute; this defaults to 120. Tempos can range anywhere from 1 to 999 BPM, although I personally don't recommend pushing your tempos to values that are too extreme.
  • Playfield Size:
  • Use this to adjust your filesize in increments of 64 tiles, up to a maximum of 512*512 tiles. Due to the current state of implementation, I recommend only enlarging your files when you're certain you will need more space. Each expansion gives you more room than the last, but also makes the program more resource intensive.
  • Song Metadata:
  • These fields allow you to declare the author and title of a track, as well as write a description. The default values are rather derogatory.

    Audio FX Properties

    This menu is activated by pressing the "Show UI" button on the menu bar. It allows you to alter what filters are applied when you paint a tile; you can have up to 8 of them at any given time. For more details on each effect does, see the effect reference section of this manual.



    Effect Reference

    Tracker2D gives you a couple ways to adjust the sound and playback order of tiles.


    Audio Effects

    Due to the major audio rework of late September, you can now apply up to 8 audio effects to every tile.

    The Audio FX Properties window generates relevant input fields for each filter. A description of each follows:


    Flow Control Effects

    These effects do not change the sound of a tile, but they change how bugs interact with the field. Many of them rely on a tile's "pointer" value, which indicates another tile on the map that they point to. On the field, a flow control is indicated with an overlay.



    Tips and Tricks


    How Tracker2D Works

    Here, I'm hoping to provide a basic idea of how the code that supports this program functions.

    This program relies very heavily on the HTML5 Canvas and Web Audio APIs in order to simplify various tasks important to its functioning. With graphics and audio being fairly abstracted, much of the code I write pertains to things like user input, file operations, and the occasional bit of number crunching.

    Tracker2D preloads its entire soundbank before allowing the user to operate it. This can take some time depending primarily on the speed of the user's internet connection, but generally should not be too long on modern connections, as the 4 megabytes of samples actually represents the majority of the program's size. Other parts of the program are not prebuffered due to this lopsided sound to code, text, and images ratio. In the future, the sound bank may be extended further (so far, a sound effects bank and a synthesizer sound bank are planned), which would skew the ratio even more.

    Understanding the main loop is a good place to get started on your journey to really grokking Tracker2D. It essentially functions as the core of a game engine, and there are two especially important points I need to immediately bring up:

    1. The main loop is designed to run as often as possible, but also to keep everything synchronized, hence the use of a delta timer.
    2. Tracker2D's computation functions are ideally separated from its conveyance (rendering) functions, so that if the program visibly slows down or "lags" (appears especially choppy due to its framerate lowering), things like sound playback and field state updates should be at least somewhat resistant to performance problems.
    To be fair, Tracker2D does not have particularly demanding graphics, so your performance should theoretically be primarily a function of how good your CPU is (and possibly your sound card and graphics card, depending on what tasks the CPU can offload onto them). I have had little opportunity to analyze the performance of Tracker2D, so you can add benchmarking to the list of development tasks I would be greatly thankful for you assisting me with.

    These sections are very incomplete (or perhaps not even written yet), even compared to some of the others.

    The Rendering Loop

    Like most programs with any sort of graphics, Tracker2D performs a great deal of graphics functions at any given time. While the actual graphical elements are again very simple (and essentially placeholders barring the creation of more detailed artwork), the graphics rendering loop isn't. This section only refers to graphics tasks handled with HTML5 Canvas - there are several important ones that are handled using standard HTML DOM elements.

    1. After blanking the canvas at the beginning of the loop, Tracker2D first draws a simple background.
    2. Tracker2D then draws the tiles, starting with a grid to distinguish them and indicate the overall size of field elements. After this, it computes the viewable area of your current file and paints tiles in said area. Once the colors are painted, the program continues by drawing any relevant overlays. This includes not only indicators of tile data type, like flow control, but overlays that extend beyond a single tile, like that of the selection buffer.
    3. We then call the bug drawing routine, which unlike the rest of the graphics code is a method of the Bug object. Bugs have a small arrow overlay (that you could interpret as a nose with the current graphics) that's added after the bug itself is painted on the screen.
    4. The final step of each instance of the rendering loop is to draw Canvas based UI elements. The most obvious examples of these are the bottom toolbar and the minimap.

    Tiles

    (Intentional) Bug Behavior

    The Tracker2D Field File Format

    Tracker2D stores its files as multidimensional arrays of plaintext. A compression feature is planned for the long run, but in the mean time, plaintext is helpful for debugging.

    The first value in a save file is the file's "size" - its length and width in tiles, which can be squared to get the total amount of tiles. The bulk of a file is composed of strings representing the tile data in order of column (move down before going right) [FINISH THIS]


    More text and better formatting coming eventually.