User Guide
Pixi is still early on, and I am inexperienced in delivering a project, to be quite honest. When Pixi reaches a point where I feel it is stable and has all expected baseline features of a typical editor, I plan on investigating and learning the best way to package and handle updates for users.
Pixi uses mach-core and currently mach-sysgpu. Both of these are also in active development, and at the moment Pixi is not in a very stable state. One of the more recent developments was transitioning away from zgui to a generated set of Dear ImGui bindings, as well as a sysgpu backend. Switching to sysgpu as the backend is desirable for a number of reasons:
-
sysgpuis likely to be the continuously supported backend formach-coreas development continues. -
sysgpuresolves a long-standing bug on macOS that reduced stability, and could crash the system. -
sysgpuis owned by hexops and seems to have a tighter scope, not to mention API improvements over time.
However, due to a few developments not aligning, I've recently merged the change to the new bindings which allows building using -Duse_sysgpu=true, but this is currently broken on Windows. If not on macOS, its suggested to build Pixi using Dawn zig build run, and on macOS use sysgpu zig build run -Duse_sysgpu=true.
Requirements: git and zig (Install zig using zigup and get the latest mach-nominated version here)
Then clone pixi and checkout the sysgpu branch:
git clone https://github.com/foxnne/pixi.git
cd pixi
Then you are able to build and run using the following:
Dawn
zig build run
sysgpu
zig build run -Duse_sysgpu=true
If all is successful you should be presented this:
On the far left, the column of icons is the sidebar. Each option on the sidebar corresponds to a different explorer pane. The first icon corresponds to the file explorer pane. The other panes will be discussed further in the guide.
In the center of the editor is the artboard, which contains a menu bar, file tab bar, and canvas. When no file or folder is open, a Open Folder button rests beneath the pixi logo. You can also access the Open Folder... dialog from the File menu.
Users of VSCode should find many similarities between the interface layout and that of VSCode.
Upon choosing a root folder for a project, which can be any folder, the file explorer pane will display the tree of files starting at the root.
If you wish to follow along with this guide, click Open Folder and navigate to the directory you cloned Pixi and to the following folder: .../pixi/assets/src. Pixi uses its own workflow for its cursor and editor artwork, so its a decent example of how a Pixi project works.
To create a new file or folder, right-click the base folder and choose New File.... A dialog will open asking the user to specify the dimensions of the new file, which consists of specifying each tile's width and height in pixels, and then the number of tiles wide (rows) and tall (columns).
It is worth noting that the workflow of Pixi is designed to prioritize minimizing the amount of steps and programs it requires to produce, package and get artwork efficiently into a game engine or framework. The packing process will be covered a bit more in depth later, but for now, choose tile sizes that are plenty large for your artwork. Leave ample room around a character, for instance, to allow room for jumping, swinging weapons, etc. This extra blank space will be automatically trimmed when the project is packed.
Upon creating a new file, you should now see the artboard change to display the canvas with a grid corresponding to the tile widths and heights with a tab showing the file's name. You will also see a new pane open at the bottom.
This new pane is the flipbook, which shows a sequential view of the tiles of the file individually. You can scroll right or left to view individual sprites on their own, or select a sprite in the canvas to have the flipbook automatically scroll to it. In the future when you create a new animation, you can preview and adjust the animation framerate here.
Tip: The explorer pane and the flipbook both have grips to change the size of each.
If you are following along and have the pixi/assets/src folder open, select the cursors.pixi file in the explorer pane.
Pixi has 2 control schemes. One is for mouse/keyboard, which uses scroll with no modifier key to zoom and middle-mouse button to pan. The other is for trackpads, which uses 2-finger scrolling for panning and (cmd on macOS, super on Linux, and ctrl on Windows) + scrolling to zoom.
The bottom icon on the sidebar opens the settings pane. In the Input tab of the settings pane you can easily switch between mouse and trackpad.
With your preferred input method selected, zoom into the top left corner of the cursors.zig file's canvas.
Now that we have a simple file open and ready, we can open the tools pane, which is the second icon from the top on the sidebar.
In this pane, we have various tools at the top, the primary and secondary colors/pickers, and then palettes. Hover over the tools or colors for more information as to what they are and how to activate the color picker (right click).
Select the pencil tool and hover over the canvas. You will see a "preview" pixel display at the tip of the cursor. Drawing should be straightforward.
Tip: Right click activates the dropper, which will sample the top-most layer (and subsequent layers if transparent) and set the primary color to the sampled color. Sampling a layer will automatically switch to that layer. Sampling transparency will automatically switch to the eraser, and sampling color will automatically switch back to the previously used tool.
Note that once a change is made, the file is marked dirty until it is saved, typical to other drawing programs. (cmd/super/ctrl) + z will undo the last change, and (cmd/super/ctrl) + shift + z will redo the previous undo. Currently there is no limit to the number of undos a file can have. You can save a file with the hotkey (cmd/super/ctrl) + s.
Tip: The hotkeys for the current tools can be seen by hovering over the tool.
Once you've gotten comfortable with using the zoom/pan and tools to draw, select the dropdown under the Palette heading in the tools explorer pane, and select resurrect-64.hex. This is a palette .hex file downloaded from lospec.com, which Pixi can display and use. Once the palette is loaded, simply click a palette button to set the primary color. You can download and install any number of lospec palette .hex files for use across projects.
Navigate to the third icon from the top of the sidebar to reveal the layers explorer pane. This pane simply lets you create, select, rename, duplicate, delete, or reorder layers within the file, as well as set their individual visibility. This should be familiar to anyone that uses a program that makes use of layers. The layers are stacked from top to bottom, so the bottom-most layer is the layer visible on top in the canvas. Simply click and drag to reorder layers.
Now navigate to the sprites explorer pane. This is the fourth icon on the sidebar from the top.
Pixi uses the concept of the origin to maintain a singular point of reference between multiple sprites, even when packed tightly in an eventual final atlas.
Press escape to select the pointer tool, and then select any tile in the canvas.
In this pane, you can select multiple tiles. Shift + click to select all tiles between the current selection and the new selection. (cmd/super/ctrl) + click to select or deselect individual tiles. With an active selection, you can drag the X and Y sliders to set the origin of a tile.
If you are still within the cursors.zig file, selecting any of the existing cursor tiles should display what the origin corresponds to, which is the "tip" of the cursor. This means the images can be drawn anywhere within the tile and still display at the correct position later within an engine/framework. Check the origin of both the pencil tool cursor and the bucket tool cursor to see how each has its own origin. Editing of the origin can be done using the sliders in the explorer panel.
Tip: A great use case for this is a top down game, (my own is Aftersun, if you'd like to see a larger project using Pixi) where character origins are important for y-sorting. By being able to easily set all the origins of the artwork while drawing, there is less headache making sure all sprites are drawn from the same position later.
Navigate to the animations explorer pane. This is the fifth icon in the sidebar from the top.
Here you can manage creating, renaming, or deleting animations. In Pixi, an animation is simply a start index and length of the animation, which outlines the sprites in the animation with begin and end markers. Currently, a sprite can only be part of a single animation.
Tip: If you need to copy a tile from one place to another, there are two options:
- You can select a sprite with left click using the arrow tool, and then press
(cmd/super/ctrl) + c. Then select another tile and press either(cmd/super/ctrl) + vto paste to the current layer, or(cmd/super/ctrl) + shift + vto paste all available layers. - You can select a sprite then press
(cmd/super/ctrl) + (left arrow/right arrow/up arrow/down arrow)to copy a sprite over to the next tile.
Try drawing some simple animation frames and then select the animation tool in the explorer pane or press a. If you hover over the animation tool, it gives some help text of how to use it. Simply press (cmd/super/ctrl) while over your start tile, and drag to the end tile. You should see markers show up to enclose your animation frames and will be met with a popup to name your animation.
With your new animation created and selected, now press space or the play button on the far left of the menu bar above the flip book to play the animation. You also have a slider to adjust the frames per second of the animation.
To edit the animation frames of an animation, select the animation first and then click + drag without (cmd/super/ctrl) pressed.
Note: Creating an animation names the sprites sequentially with the animation name as the prefix. This is handy also for single sprites, as the cursors are. Notice how all the cursors have single frame animations just to handle naming them for easy use later.
Now feel free to close the cursor.pixi file without saving, unless you have changes to the cursors you wish to apply to Pixi.
Next we will walkthrough the sprite packer.
Navigate to the packing pane in the explorer, this is the final option in the sidebar we haven't covered, just above the settings icon.
As long as you have a project folder open, you will have the option to pack the project. When you pack a project, pixi will search through your file tree and find/load all .pixi files and pack them together in your final atlas. You can find the options for packing in the explorer, with a combo box to select what files will be packed. The options are either 'Full Project', Current Open File (if you have a file open, and All Open Files.
Tip: If you ever need to manage several separate atlases, just simply split your project folder into two trees and open one subfolder at a time, so you can simply pack all project files together.
Press Pack.
You should now see the following, which will be all of pixi's artwork packed tightly together in an atlas. In the explorer pane now you should be able to see a few details of the final atlas, such as the texture size, and number of sprites and animations.
If you select the export button, you will be presented with save dialog. When exporting the atlas, pixi will actually create two individual files:
- The final packed texture
- A
.atlasfile which contains JSON output describing the origins, positions, and animations of the final sprites
When choosing a name for the output, leave off the extension as the extensions for the two files will be handled automatically.
You just went through all of the steps for creating new files, artwork, animations and the final packing and exporting of the atlas!
