RagePixel Documentation

Introduction

RagePixel is an extension for Unity. It's main purpose is to provide means for drawing and animating pixelart. The twist is, that RagePixel is not relying on the import pipeline. It brings the drawing tools inside the Editor.

RagePixel requires some setting up when you start a new project. Check out the QUICKSTART -document to get things in order.

Scene View

Scene view is where the magic happens. This is where you can draw, animate and transform RagePixel objects.

TRANSFORM

TRANSFORM-mode is the Unity default mode, where you can move, scale and rotate objects.

As an addition, there is a rectangular handle on top-right corner of the sprite. Dragging the handle lets you stretch the game object. Note: This is not resizing the underlying sprite bitmap on your spritesheet. Only stretching the current object instance.

If you want to resize the actual bitmap, you need to change to RESIZE-mode (see below).

You can reset to original sprite size by clicking the (already selected) sprite thumbnail from the inspector sheet.

PEN

PEN-mode is for drawing and modifying the actual bitmap data. There are three possible brush sizes (1 pixel, 3x3 cross and 5x5 ball).

ControlOperation
LEFT MOUSE BUTTONPaint
RIGHT MOUSE BUTTONColor picking
CTRL + ALT + ZUndo paint operation
1,2,3 or [ and ]Change brush size

Note: You can use CMD instead of CTRL on OSX

Use right-click to pick colors inside the currently selected sprite. Picking outside switches to eraser.

FLOOD FILL

FLOOD FILL works like on any other drawing application. It fills the closed pixel shapes with current paint color.

SELECT

SELECT-mode is for typical select/copy/paste/move operations. Copy selected area to clipboard and paste it to another sprite. Move selected pixels around by select+drag. You can also duplicate or clear the selected area.

Selecting is limited to underlying sprite bitmap size. When your sprite object is stretched to multiple tiling/repeating instances, you can't select over underlying bitmap edge.

SELECT-mode is disabled for GRID9-objects.

ControlOperation
LEFT MOUSE DRAGSelect an area
LEFT MOUSE DRAG (selection)Move selected pixels
CTRL + ALT + CCopy selection to clipboard
CTRL + ALT + XCut selection to clipboard
CTRL + ALT + VPaste clipboard to selected sprite
CTRL + ALT + DDuplicate selected pixels

Note: You can use CMD instead of CTRL on OSX

RESIZE

RESIZE-mode is for resizing the actual sprite bitmap on the spritesheet texture.

If your sprite has multiple animation frames, they will all be resized. If the new size is bigger, pixels will be filled with transparent. There is no undo for bitmap resize.

RESIZE-mode is disabled for GRID9-objects.

ANIMATION

ANIMATION-strip is for handling the sprite animation frames.

Add and insert frames with the NEW/DEL buttons. When a new frame is inserted, pixels from the previously selected sprite will be copied as base. You can setup multiple sub-animations in the spritesheet editor window.

Change the frame order by dragging with mouse.

ControlOperation
LEFT MOUSE DRAGReorder frames
CTRL + RIGHT ARROWSelect next frame
CTRL + LEFT ARROWSelect previous frame

Note: You can use CMD instead of CTRL on OSX

COLOR PICKER

COLOR PICKER shows the currently selected paint color. Clicking on the picker button opens up a bigger window, which let's you choose saturation/hue/lightness/alpha.

COLOR REPLACER

COLOR REPLACER is for replacing a certain color with another. Selected paint color on the left is replaced with a new color on the right. You can see the result before you apply it. You can apply the change for the selected sprite or for the entire spritesheet/atlas.

PALETTE

PALETTE is for saving preset colors. It is only a shortcut for color picking. It is not a palette in an "oldskool indexed palette" -way.

ControlOperation
LEFT MOUSE BUTTONPick color
CTRL + RIGHT MOUSE BUTTON (over sprite)Add new color
CTRL + LEFT MOUSE BUTTON (over palette)Remove color
LEFT MOUSE DRAGReorder palette colors

Note: You can use CMD instead of CTRL on OSX



Inspector View

POSITION

RagePixel coordinate system is: X->right, Y->up and Z->away. Although oldskool retro games usually refer screen coordinates as Y growing down, the reasoning is to have a coordinate system equal to how it's done in mathematics.

Unity draws objects from back to front, so Z-coordinate works as a layer value. The smaller values are in front and bigger out in the back.

Given the RagePixelCamera width/height/pixelsize, RagePixel objects always snap to actual screen pixels in editor. This way you will never have to worry about getting sprite pixels lined up.

SIZE

In the default mode, SIZE is referring to the object size, not the sprite bitmap size. You can scale a 16x16 sprite to a 100x100 and RagePixel will do the texture repeating for you.

If you wan't to reset to original sprite size, just click on the (already selected) sprite thumbnail on the inspector.

If you want to change the actual bitmap size, you need to use the RESIZE-mode from the scene view.

MODE


MODE defines how the sprite bitmap is repeated when the object is scaled. You can see from the wireframe how RagePixel is building the underlying mesh. Object on the right has a margin of 2px for every side.

MODE has two options DEFAULT and GRID9. DEFAULT is ordinary texture repeating behavior and GRID9 adds a static margin for each side.

PIVOT


Pivot defines how the sprite mesh is positioned in relation to it's position value. The three options are BOTTOM LEFT, BOTTOM and MIDDLE.

TINT COLOR


Tint color changes the vertex color that is multiplied with the sprite pixel color.

It can be used to color up the same sprite as different variations (draw the sprite in grayscale), or fade them in and out with alpha.

ANIMATION MODE

Inspector animation mode selector is used for the simple cases, where you just need one animation for the sprite. It defines the animation looping behavior. The five looping options are PLAY ONCE, PLAY REVERSE, LOOP, LOOP REVERSE and PING PONG.

Default frame delay is 200ms (5 fps). If you need multiple sub-animations or different speeds, they can be adjusted in the Spritesheet Editor Window.

PLAY ON AWAKE

This means that the animation is started automatically when the game starts or the current sprite is instantiated. It refers to the whole animation range and not the named sub-animations.

Spritesheet Editor

Spritesheet Editor is for modifying the spritesheet, setting up frame delays, defining sub-animations and importing external bitmaps. Later versions will likely bring features like merging spritesheets together.

SPRITESHEET

Upper sheet contains all the sprites in the sheet. The lower sheet contains animation frames for the currently selected sprite.

Sprite can be named for an easy scripts access.

RagePixel animation speed is determined for each frame individually. The default value is 200ms (5 fps).

NAMED ANIMATIONS

Named animations are to be used from the scripting. You can define name, start frame, end frame and looping type. If you insert frames between your sheet later on, remember to readjust the ranges accordingly. They are not automatically shifted.

IMPORT

RagePixel allows you to import external bitmaps to the sheet. Drag the texture to the texture-slot and choose the way you want it imported.

IMPORT TO SELECTED FRAME: Overrides the selected frame with the texture. If the imported texture is bigger than the target sprite, source pixels are cropped.

IMPORT AS NEW FRAME: Creates a new frame for the imported bitmap. If the imported texture is bigger than the target sprite, source pixels are cropped. Every animation frame in a single sprite are always equal sized.

IMPORT AS NEW SPRITE: Creates a whole new sprite and imports the texture. The new sprite will be sized accordingly.

NOTE: RagePixel is still in beta, importing large images might cause havoc in the whole spritesheet. Spritesheet backups are highly recommended before importing.



RagePixel API

RagePixel API is a light-weight interface for the sprite object run-time access.

The API is currently very limited. Please hit the forums to give feedback and request more features!

For code example, check out the Walking script example

MethodParametersFunctionality
SetSprite string name
int frameIndex
Choosing the current sprite from the spritesheet by name.
PlayAnimation bool forceRestart Playing the full animation. Set the loop mode from the inspector.
If forceRestart=false, the ongoing play is not restarted.
PlayNamedAnimation string name
bool forceRestart
float delayFirstFrame
Playing a named sub-animation.
If forceRestart=false, the playing of an equally named animation is not restarted.
isPlaying   Is animation playing?
StopAnimation   Stop the animation
SetSize int width
int height
Set the size of the sprite. This does not mean sprite bitmap size. It is the repeating/tiling size.
GetRect   Get the sprite boundaries (Rect).
SetHorizontalFlip bool value Is the sprite flipped horizontally?
SetVerticalFlip bool value Is the sprite flipped vertically?
SetTintColor Color color Sprite tint color