Drawing Tools
Select a tool from the left panel or via keyboard shortcut. Left-click on the canvas uses the primary colour; right-click uses the secondary colour. Shape tools commit on mouse-up.
| Tool | Shortcut | Description |
|---|---|---|
| Pencil | — | Draws individual pixels with the active colour. |
| Eraser | E | Sets pixels to transparent. |
| Fill | F | Flood-fills a contiguous region of the same colour. |
| Eyedropper | I | Picks the colour under the cursor without changing the tool. |
| Line | L | Draws a straight line between two points. Click and drag. |
| Rectangle | R | Draws a hollow rectangle. Click and drag. |
| Filled Rectangle | Shift+R | Draws a solid rectangle. |
| Circle | C | Draws a hollow circle. Click and drag. |
| Filled Circle | Shift+C | Draws a solid circle. |
Colours
The overlapping swatches in the left panel show the primary (front) and secondary (back) colours. Click a swatch or the labelled picker below it to open the colour chooser.
- Left-click on the canvas paints with the primary colour.
- Right-click on the canvas paints with the secondary colour.
- Swap (X) — swaps primary and secondary.
- Hex field — type a colour directly (
#rrggbb).
Palette & Lospec
Colour Palette
The Palette panel shows your working colour set as swatches.
- Left-click a swatch → set as primary colour.
- Right-click a swatch → set as secondary colour.
- + — adds the current primary colour to the palette.
- ↺ — resets to the built-in 32-colour default palette.
Image Colours
Click ↻ next to Image Colours to extract every unique colour currently used on visible layers. The result appears as swatches — click any to set it as a colour.
Lospec Palettes
lospec.com/palette-list hosts hundreds of community-made palettes.
- Load by slug — enter the palette slug (e.g.
db16,sweetie16,na16) and click Load by slug. Press Enter to load without clicking. - Search — type a name and click Search. Click a result to load it.
Layers
Layers are stacked transparently, composited top-to-bottom. All drawing goes to the active (highlighted) layer.
| Button | Shortcut | Action |
|---|---|---|
| + | Shift+N | Add a new blank transparent layer above the active one. |
| ⧉ | Shift+D | Duplicate the active layer. |
| ⊕ | — | Merge all visible layers into a single layer. |
| 👁 | — | Toggle visibility of the layer. |
| 🔒 / 🔓 | — | Lock a layer to prevent drawing on it; unlock to allow drawing again. |
| ↑ / ↓ | ] / [ | Move the layer up or down in the stack. |
| ✕ | — | Delete the layer (disabled when only one layer remains). |
- Opacity — the slider at the bottom of the Layers section controls the active layer's transparency (0–100 %).
- Rename — double-click a layer name to edit it inline; press Enter or click away to confirm.
Reference Image
A reference image overlays the canvas to guide your drawing. It is never saved into the exported PNG or Koala file.
- Click … to load any raster image (PNG, JPG, GIF, …).
- Toggle the overlay with the 👁 button.
- Opacity — how transparent the reference overlay is (default 50 %).
- Scale — resize the reference independently of the canvas (10–400 %).
- X / Y — offset the reference horizontally and vertically as a percentage of the canvas size.
- Reset position & scale — returns position and scale to their defaults.
- Click ✕ to unload the reference entirely.
Canvas & View
Zoom
- − / + buttons in the toolbar or press − / + on the keyboard.
- Scroll wheel on the canvas zooms at the cursor position.
- Fit — fits the entire canvas into the visible area.
Grid
Toggle the pixel grid overlay with the Grid toolbar button or press G. The grid is hidden automatically at low zoom levels.
Preview Window
A floating mini-preview shows the artwork at a selectable scale (2×, 4×, 6×, 8×, or a custom value). Toggle with Preview or P. Drag the preview header to move it around the canvas area.
Status Bar
The bar at the bottom of the canvas shows: cursor position, canvas size, current zoom, colour under the cursor, active tool, and active layer name.
File Operations
| Action | Shortcut | Notes |
|---|---|---|
| New image | Ctrl+N | Opens the New Image dialog. Set width, height, background colour, or enable C64 mode. |
| Load | Ctrl+O | Load PNG, BMP, GIF, JPG, or a Koala .koa file. Loading a .koa switches to C64 mode automatically. |
| Save PNG | Ctrl+S | Exports all visible layers flattened to a single PNG file. |
| Koala | — | C64 mode only. Exports a standard Koala Painter .koa file for use in emulators or on real hardware. |
| Drag & drop | — | Drop an image file directly onto the canvas to load it. |
C64 Multicolor Bitmap Mode
What is it?
The Commodore 64's multicolor bitmap mode renders a 160×200 pixel screen where each pixel is twice as wide as it is tall (square pixels at 320×200 but each physical C64 dot covers two logical pixels). The screen is divided into 4×8 pixel tiles (40 columns × 25 rows). Every tile can display at most 3 foreground colours plus 1 shared global background colour — four colours per tile in total, all chosen from the 16 hardware colours of the C64.
PixelForge enforces these constraints in real time and can export the result in the standard Koala Painter (.koa) format, which is the most widely supported C64 bitmap format and is directly playable in emulators like VICE or C64 Forever, or on real hardware.
Enabling C64 Mode
Open New Image (Ctrl+N), tick C64 Multicolor Bitmap Mode, pick a background colour, and click Create. Alternatively, load an existing .koa file — this also switches to C64 mode. The toolbar gains a C64 BG colour selector and a Koala export button.
Colodore Colour Palette
All colours are restricted to Colodore — the 16 C64 hardware colours as defined by the Colodore reference. The 16 colours are: Black, White, Red, Cyan, Purple, Green, Blue, Yellow, Orange, Brown, Light Red, Dark Grey, Grey, Light Green, Light Blue, and Light Grey.
Throughout the app, native colour pickers are replaced by a compact 16-colour dropdown. Any colour set by other means (e.g. tracing a photo) is automatically snapped to its nearest Colodore entry.
Per-tile Colour Constraint
When you attempt to draw a colour that would add a fourth foreground colour to a 4×8 tile, the cursor changes to ✕ and the paint is blocked. The global background colour (shared across all tiles) does not count as a foreground slot. You can change the background anytime using the C64 BG picker in the toolbar; this updates the locked background layer instantly.
Active Restrictions
| Feature | Restriction in C64 Mode |
|---|---|
| Canvas size | Fixed at 160×200 px; cannot be changed |
| Colour pickers | Replaced by Colodore 16-colour dropdowns throughout |
| Hex colour input | Disabled |
| Palette panel | Locked to Colodore 16; add and reset buttons disabled |
| Lospec & Image Colours | Sections hidden (not applicable) |
| Drawing | Blocked when a tile already has 3 foreground colours |
| Layer add / delete / merge | Disabled; buttons grayed out |
| Layer lock toggle | Disabled |
| Layer opacity | Hidden (Koala format has no per-layer transparency) |
Koala Export
Click Koala in the toolbar to download a .koa file. The 10 003-byte structure is: 2-byte PRG load address + 8 000 bytes bitmap + 1 000 bytes screen RAM (tile colour pairs) + 1 000 bytes colour RAM (tile colour 3) + 1 byte global background. This is the format written by the original Koala Painter cartridge and is universally supported by C64 software.
Image Tracer
Open with the Trace button (T). The tracer converts a photograph or artwork into indexed pixel art by downscaling and applying dithering.
Loading a Source
Click Load Source… to open a JPEG or PNG image. The source appears in the left preview pane.
- Pan — drag anywhere in the preview canvas.
- Zoom — scroll wheel, or use the − / + / Fit controls.
- Crop box — the dashed rectangle defines which region of the source gets traced. Drag the box interior to reposition it; drag a corner handle to resize it. Only the area inside the box is used as input.
Destination Size
Choose a preset (16×16 up to 256×256, or 160×200 for C64) or enter a custom width × height. Selecting 160×200 automatically enables the C64 Mode group.
Dithering
Dithering distributes the error between a desired colour and the nearest available palette colour to neighbouring pixels, creating the illusion of intermediate tones. The examples below show a black-to-white gradient dithered with each method (black/white palette).
Error-diffusion methods
These scan left-to-right, top-to-bottom. Each pixel's quantization error is propagated forward to unprocessed neighbours according to a weight matrix. Results look organic and natural.
Ordered (Bayer) methods
A pre-computed threshold matrix is tiled across the image. Each pixel's channel values are nudged by the corresponding matrix entry before quantizing. Results have a regular, mechanical dot pattern — the classic retro halftone look.
Color Mode
- Full color — traces using all RGB colours; each pixel is snapped to its nearest representable value in memory. No palette restriction is applied.
- Match palette — restricts output to a specific loaded palette. The palette section appears below; load one via a Lospec slug or search, or use the current editor palette.
C64 Mode (160×200 only)
When the destination size is 160×200, a C64 Mode group appears:
- Apply C64 palette & tile constraints — after downscaling and dithering, snaps all colours to Colodore and enforces the 3-foreground-per-tile rule by replacing out-of-quota colours with the nearest allowed one. Enable this when tracing for Koala export.
- Background color — the global C64 background used during the tile constraint pass. Set this to the most common background shade for best results.
Image Enhancement
These adjustments pre-process the source before dithering. Click ↺ to reset all sliders.
| Control | Effect |
|---|---|
| Brightness | Shifts every pixel brighter (+) or darker (−). |
| Contrast | Expands (+) or compresses (−) the tonal range around 128. |
| Saturation | Uniformly boosts or reduces colour intensity. |
| Vibrance | Smart saturation — affects desaturated colours more than already-vivid ones, preserving skin tones and highlights. |
| Invert | Negates all channels (white ↔ black, etc.). |
Result Preview & Applying
The Result preview canvas at the bottom right updates automatically whenever any setting changes. Click Trace to Canvas to send the result to the main editor. In C64 mode a new C64 canvas is created automatically; in normal mode the result replaces the current active layer's content.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| E | Eraser tool |
| F | Fill / bucket tool |
| I | Eyedropper / colour picker |
| L | Line tool |
| R | Rectangle (outline) |
| Shift+R | Rectangle (filled) |
| C | Circle (outline) |
| Shift+C | Circle (filled) |
| X | Swap primary ↔ secondary colour |
| G | Toggle pixel grid |
| P | Toggle preview window |
| T | Open Image Tracer |
| + or = | Zoom in |
| − | Zoom out |
| [ | Move active layer down |
| ] | Move active layer up |
| Shift+N | Add new layer |
| Shift+D | Duplicate active layer |
| Ctrl+Z | Undo |
| Ctrl+Y / Ctrl+Shift+Z | Redo |
| Ctrl+S | Save PNG |
| Ctrl+N | New image dialog |
| Ctrl+O | Load file |
| Esc | Close Tracer / close this Documentation panel |