CV Sprite Tool — User Manual ColecoVision Edition

Introduction

The CV Sprite Tool is a standalone, browser-based sprite editor tailored for the ColecoVision home computer. It works within the hardware constraints of the TMS9918A video processor: a 16-colour palette, 8×8 and 16×16 pixel sprites, and a two-layer colour system that mirrors how the ColecoVision renders sprites in hardware.

You can draw pixel art, create multi-frame animations, and export directly to CVBasic source code, Assembly (ASM) data blocks, or a portable JSON project file — all without leaving your browser.

Interface Overview

The tool is arranged top-to-bottom in a single scrollable page. The numbered zones below correspond to the callouts in the diagram.

Sprite Name

Type a short label into the Sprite name field (up to 32 characters, no spaces). This prefix is used for all generated labels in the output code.

The preview next to the field shows what the actual label(s) will look like — for example, entering player gives player_color1 in 1-color mode, or player_color1, player_color2 in 2-color mode.

Sprite Size Mode

Use the 8×8 and 16×16 toggle buttons on the Sprite Name bar to switch between the two TMS9918A sprite sizes.

The canvas always occupies the same screen area regardless of the active mode — only the cell size changes. This makes 8×8 cells larger and easier to paint at fine detail.

Colors & Layers

1-Color vs 2-Color Mode

Use the 1 Color / 2 Colors toggle buttons at the top of the Layers panel.

• 1-Color — A single layer with one assigned palette colour. Simple sprites.
• 2-Color — Two independent layers, each with its own colour. Richer sprites that use both hardware sprite planes.

When you switch to 2-Color mode a brief tooltip appears near the layer rows reminding you that you can click a row label or press X to toggle between layers.

Pixel Exclusivity

This is the most important rule in 2-color mode: every pixel can only belong to one layer at a time. If you paint a pixel on Layer 2 that Layer 1 already occupies, it is automatically removed from Layer 1 and given to Layer 2. Pixels do not stack.

This directly mirrors how the ColecoVision hardware works — two sprites cannot both claim the same pixel position.

Important: This applies to the Pencil, Eraser, and Flood Fill tools. There is no way to have two colours at the same pixel — that would be physically impossible on the real hardware.

Drawing Tools

Symmetry

Symmetry lets you draw on one half of the canvas and have strokes automatically appear on the other half simultaneously. Only one mode can be active at a time — clicking an active mode button turns it off.

Horizontal symmetry (above the canvas)

Vertical symmetry (left of the canvas)

Rotation, Flip & Invert

These buttons are on the right side of the canvas (the Rotation bar). They all operate on all layers simultaneously.

Color swatches (top of the Rotation bar)

Each assigned colour has a swatch row with two controls:

• Click the colour swatch — switch to that layer.
• Click the pencil icon — open a floating mini colour picker to reassign the layer's colour. Forbidden colours are greyed out.

In 2-color mode an X hint appears at the top. Press X to quickly toggle between Color 1 and Color 2 without using the mouse.

Nudge Bar

The four arrow buttons shift pixels by one cell at a time. Keyboard arrow keys also work when the Last Object checkbox is active (see below).

Wrap Mode (☑ Wrap)

Pixels that move off one edge immediately reappear on the opposite edge. This is a permanent, destructive change. Each nudge click creates one undo entry.

Clip Mode (☐ Wrap unchecked)

Pixels that move off an edge are hidden but not destroyed. The tool keeps a snapshot of the original positions. Nudging back in the opposite direction restores them exactly. The accumulated nudge is committed (made permanent) when you:

• Start drawing (mousedown on the canvas)
• Switch to a different frame

Both Colors (☑ Both Colors)

Only visible in 2-color mode. When checked, all nudge operations move both layers together. When unchecked, only the active layer is moved.

Last Object (☐ Last Object)

When checked, the nudge buttons (and keyboard arrow keys) move only the last painted stroke or shape — not the entire layer.

• Captured automatically when you finish a stroke or commit a shape.
• The checkbox auto-unchecks 5 seconds after the last arrow-key move.
• Pixel exclusivity is maintained — moving an object onto another layer's pixels clears those pixels from the other layer.

Animation Frames

The Animation / Frames panel sits below the nudge bar and is expanded by default. Click the chevron (›) at the left of the panel header to collapse or expand it.

Managing frames

• + Add — Add a blank frame. Maximum 10 frames.
• ← → buttons above each thumbnail — Reorder frames.
• ⧉ Clone button on a thumbnail — Duplicate that frame.
• ✕ Delete button — Remove a frame. Only visible when more than one frame exists.

The currently active frame has a highlighted border. Click any thumbnail to switch to it.

Animation Playback

The animation preview canvas (80×80 px) and playback controls are on the right side of the Animation panel.

Playback controls

Speed

Use the − and + buttons beside the speed display to step through available frame rates: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60 fps. The default is 4 fps (WAIT 15). The display shows the fps value and its equivalent CVBasic WAIT value.

Background colour

The row of small swatches below the playback buttons sets the temporary preview background colour. This is cosmetic only — it does not affect the sprite data. Transparent (index 0) shows a checkerboard. This setting also controls the tint of the Trace layer when in colour mode.

Bkgd / Trace Layer

The bottom row in the Layers panel is the Trace (reference image) layer. It is for tracing reference artwork — it does not contribute to exported sprite data.

Modes

• Color mode — Displays a flat-colour tint over the canvas. Click the colour swatch to choose a tint. Useful as a temporary background colour while drawing.
• Image mode — Shows a loaded PNG image. Use the ⇄ toggle button (visible when an image is loaded and the layer is visible) to switch between colour and image mode.

Importing a reference image

1. Click ⬆ Import PNG and select a PNG file.
2. The image is loaded at its original size and scaled to the canvas area.
3. If the image is not 16×16 pixels, a warning alerts you that it will be scaled.
4. Use the Opacity slider to make it transparent enough to draw over.
5. The 👁 visibility button toggles the layer on/off.

Output Panel

The Output Panel at the bottom of the page shows a live preview of the exported code, updated instantly as you draw. Select a format using the tab buttons, then click 📋 Copy to copy to the clipboard (the button briefly shows "Copied!").

The active output format is also reflected in the Output Mode tabs at the very top of the page, and determines the format used by the Save button and the per-layer Import/Export buttons in the Layers panel.

sprite_color1:
    BITMAP "XXXXXXXXXXXXXXXX"
    BITMAP "X..............X"
    BITMAP "X..............X"
    BITMAP "XXXXXXXXXXXXXXXX"
    '  ... 12 more rows ...

DEFINE SPRITE 0,1,sprite_color1
SPRITE 0,100,100,0*4,1

' animFPSIndex: 3  (4 fps, WAIT 15)
' animMode: loop

' ═══ Frame 1 ═══
sprite_f1_color1:
    BITMAP "..."
    '  ...

' ═══ Frame 2 ═══
sprite_f2_color1:
    BITMAP "..."

; sprite_f1_color1  — Color 1: [1] Black
sprite_f1_color1:
   db 255,129,129,129,129,129,129,255
   db 255,129,129,129,129,129,129,255
   db 255,129,129,129,129,129,129,255
   db 255,129,129,129,129,129,129,255

{
  "spriteName": "player",
  "numLayers": 2,
  "layerColors": [1, 8],
  "layerColorNames": ["Black", "Medium Red"],
  "animFPSIndex": 3,
  "animMode": "loop",
  "frames": [
    {
      "frameIndex": 0,
      "layer1": [[0,0,...], ...],
      "layer2": [[0,0,...], ...]
    }
  ]
}

Save & Load

Save (💾 Save button)

Downloads a file in the currently active output format:

Load (📂 Load button)

Opens a file picker. Accepted file types:

• .json — Restores the full project.
• .bas — Imports CVBasic source. Reads BITMAP blocks, frame labels, and SPRITE colour statements.
• .asm — Imports assembly data. Reads db decimal rows and frame label naming. Accepts both decimal and legacy hex-pair formats.

New (⊞ New button)

Clears all frames and resets the project to a single blank frame. A confirmation dialog prevents accidental data loss.

Per-layer Import / Export

Each layer row has its own ⬆ Import and ⬇ Export buttons that work in the active output format. Use these to exchange data for a single layer/frame rather than the full project.

Keyboard Shortcuts