Charset Editor Guide

The Charset Editor draws the character set a Commodore 64-family program uses for text and, with the Tile Workshop, for character-mode graphics. It edits all 256 glyphs of character memory, each 8 × 8 pixels, and exports either an editable project or a crustyBASIC include your program can install.

This guide covers the editor on its own. For building a level out of those glyphs, see Help → Tile Workshop Guide.

Before you begin

1. Open a C64, C128, or Plus/4 project.
2. Choose Tools → Charset Editor, or double-click a charset asset in the Explorer.
3. Create a new charset with New Charset, or open an existing .64c binary or .c64charset.json project.
4. Save regularly. In the desktop app, Save charset writes into the current project; in the browser preview it downloads a copy instead.

Charsets live in the project's charsets/ folder and are listed in the manifest's assets.charsets array. The editor is a C64-family tool: the palette it writes names VIC-II colour registers, so the same asset is expected on a C128 or Plus/4 as on a C64. There is no charset editor for NES (its characters are CHR patterns inside the NES Tile Workshop), for Apple II, or for the other targets, and the Tools menu disables the entry when the target does not match.

Standard and multicolour

Choose the mode before you draw, because the two are different shapes and converting between them loses information:

	Standard	Multicolour
Shape	8 × 8 pixels	4 × 8 fat pixels
Colours	Two: glyph colour and background	Four: background, colour 1, colour 2, and the cell colour
Brush values	Lit or clear	Background, colour 1, colour 2, cell colour
Palette editor	Not needed — the two colours come from the screen registers	Screen palette, saved with the project

Switching mode converts all 256 glyphs at once, and there is no undo. Standard to multicolour keeps only whether each pixel pair was lit; multicolour to standard loses which of colours 1, 2, or 3 a cell used. Decide first, then draw.

The editor at a glance

• Glyphs — the 256 glyphs as hex-labelled buttons. Click one to edit it. Copy glyph duplicates the current glyph over another index, which is the quickest way to build a family of similar shapes.
• Centre grid — the glyph you are drawing, with a status line and a count of how many cells are lit. In multicolour that count is out of 32, not 64.
• Colour — the value the brush paints with. The four multicolour slots are labelled with the register each one drives.
• Screen palette (multicolour only) — maps the four slots to any of the 16 C64 colours. It is stored in the project, and the C64 Tile Workshop previews maps with it, so the tools and the game cannot drift apart.
• Tools — Draw, Erase, Fill, Clear glyph, and Invert glyph. Fill spreads the colour under the pointer across that connected region, so in multicolour it fills one colour rather than only the empty cells. Invert is two-state: lit cells become the background and unlit cells take the current colour.
• Preview — a fixed 1× view of the finished glyph.
• Byte data — the glyph's eight output bytes. Type decimal, $hex, or 0x values separated by commas or spaces and leave the field to apply them. Copy glyph bytes puts the same text on the clipboard for use in source.
• Export — the include name and the glyph range to write.

Step by step

1. Set the mode. Standard for text and simple tiles, multicolour for chunky colour art.
2. Set the colours. In multicolour, pick the four screen colours first. Watch the warning that appears when the cell colour is below 8: colour RAM only shows a cell colour from 8 upwards, and below that the cell renders as two-colour hi-res no matter what you drew.
3. Draw the glyph. Choose a brush value, then click or drag on the grid. Fill spreads the current colour across the region under the pointer.
4. Work across the set. Use the glyph list to move around, and Copy glyph to duplicate a shape before editing the copy.
5. Check the bytes. The byte data field is the exact eight bytes the machine will read; it is the fastest way to confirm a glyph matches a reference listing.
6. Save. The project is written as .c64charset.json in charsets/.
7. Export the include. Give it a name and a glyph range, then Export charset include.

Choosing the export range

The defaults are glyphs 64 to 127, and that default exists for a reason: a charset include overwrites what it installs, and exporting all 256 glyphs would replace the letters and digits the ROM font still supplies. Exporting only the range you actually redrew keeps the ROM font for everything else, which is usually both smaller and safer.

The generated include starts with the asset marker, then one CONST C64_CHARSET_<NAME>_GLYPH_<n>(7) AS U8 line per glyph in range, then C64_CHARSET_<NAME>_INSTALL_CHARSET, which:

1. calls CHARSET_COPY_DEFAULT to start from the machine's own font, and
2. stamps each exported glyph over it with CHARSET_DEFINE.

A multicolour charset also gets _COLOR_BACKGROUND, _COLOR_1, _COLOR_2, and _COLOR_CELL constants plus palette and colour-RAM routines, because those colours have to be written to the VIC-II as well. A standard charset emits no palette block — its two colours come from the screen registers your program already sets.

Include the generated .cbi from your game source and call the install routine during setup.

Import

What	How it is handled
.64c binary dump	The two-byte load address is read and shown, then eight bytes per glyph are decoded. A shorter set is padded to 256 glyphs with blanks.
.c64charset.json, .c64charset, .charset.json, .charset	An editable project; it must contain exactly 256 glyphs.

A binary is converted into an editable project rather than being edited in place, and the load address is not kept in the project. Importing from the Explorer or by dropping a file always decodes a binary as standard, while the editor's own Open charset decodes it in the mode you are currently in — so if you are importing a multicolour dump, set the mode first.

The parser reports three specific problems rather than failing silently: a file with no room for even one glyph, data that is not a whole number of eight-byte records, and more than 256 glyphs. A project that does not match the expected shape is reported as an invalid charset project.

There is no image import here. Glyphs are drawn, converted from a .64c, or generated as data.

Across the platforms

Target	Charset Editor
c64, c128, plus4	Available. All three use the same C64-addressed output.
vic20, mega65	Not offered, even though both are Commodore machines with their own character memory.
nes	Not offered. NES characters are 2bpp CHR patterns, edited in the NES Tile Workshop.
apple2 and the rest	Not offered.

Opening an existing charset asset from the Explorer works regardless of the current target, because the saved asset records its own platform. The asset itself stays C64-family data.

Practical advice

• Decide on standard or multicolour before drawing anything, and keep a copy of the project before switching mode "just to look".
• Keep the letters and digits you are not redrawing out of the export range, and let the ROM font do that work.
• Reuse shapes with Copy glyph rather than redrawing; a charset is easier to keep consistent when similar glyphs share an origin.
• In multicolour, plan around four fat pixels per row. Detail finer than two pixels cannot survive, so design accordingly rather than fighting it.
• Keep the screen palette inside the charset project and let the tile map preview use it, so the art, the map, and the game all agree.
• Painting follows the pointer and does not filter mouse buttons, so a right-click also paints. Use Draw and Erase rather than clicking idly over the grid.
• There is no undo. Save before a mode switch, an invert, or a large fill.

Troubleshooting

A standard glyph is drawn in dark grey, not the amber swatch

Standard-mode glyph values are shown through the project's palette, and a neutral default maps the lit colour to a dark grey. The brush swatch beside the tool list is a fixed amber for legibility. Switch to Multicolour, choose a brighter colour 1, and switch back if you want a different standard-mode appearance; the palette is kept across the mode change.

My cell colour is ignored

Check the warning under the Screen palette. A cell colour below 8 is stored by colour RAM but the VIC-II only shows it from 8 upwards; below that the cell is drawn as two-colour hi-res. Pick a colour from 8 to 15.

The export refuses to overwrite my file

That is the generated-include check. Crusty Studio only replaces a .cbi that carries the @crusty-asset marker line with a matching kind; anything else is treated as hand-written source and left alone. Export to a different name, or remove the file yourself. The refusal is reported in Output, not in the editor.

The import produced the wrong colours

A .64c decoded in the wrong mode is the usual cause. The editor's Open dialog decodes in the mode you are currently in; importing from the Explorer or by dropping always decodes as standard. Set the mode first, then import.

"Invalid C64 charset project file"

The project must contain exactly 256 glyphs, each 8 rows of 8 (standard) or 4 (multicolour) values in range. A hand-edited file with fewer glyphs will not load.

Next step

Draw a replacement for the glyphs your game actually uses — a cursor, a border, a HUD icon, or a set of tiles for the Tile Workshop — export only that range, include the result from main.cbs, and call the install routine at start-up.