The most basic tutorial follows:
We need text here!
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.
A few rules of thumb:
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.
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/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.
Pen: 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.
Audio 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.
Eraser: The eraser removes musical instructions from tiles that you click on. This tool supports click and drag.
Select: 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.
Paste: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.
Query: 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: 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: 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.
Eyedropper: 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 Adjuster: This tool makes the first tile you click with it point to the second tile you click with it.
Arrow 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.
Extrapolator: 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 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.
Selection 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:
Help: 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 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 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 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 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.
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%.
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.
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.
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).
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.
Tracker2D gives you a couple ways to adjust the sound and playback order of tiles.
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:
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.
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:
These sections are very incomplete (or perhaps not even written yet), even compared to some of the others.
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.
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.