JamChip

Pixel art and chiptune, inside Godot. One dock, three editors on a pin rail.

Tab	What it is
Pixel	A sprite editor: layers, frames, onion skin, palette, animation tags, its own undo history. Documents are .pixel.tres; exports are PNG, SpriteFrames and Aseprite.
SFX	An sfxr-style generator. Documents are .sfx.tres; exports are .wav.
Tracker	A pattern tracker over the same synth engine. Documents are .music.tres; exports are .wav.

Everything exports to formats Godot already understands, so a shipped game needs none of this at runtime. Or skip the export: PixelSprite2D and ChiptuneAudioStream hold a document and follow it as you edit.

A sprite document names ranges of its own frames, idle, run, hit, and each becomes a SpriteFrames animation of that name, so play("run") on the node works as on any AnimatedSprite2D.

Install

Copy addons/jamchip/ into your project, then enable JamChip under Project → Project Settings → Plugins.

Godot 4.7 or newer. Every suite runs on 4.7.2, and that is the oldest version this is tested against. Anything below 4.7 is unsupported: it may load and it is not something to report. Newer 4.x releases are expected to work and are not all tested.

If the project is in git, add a line to .gitattributes:

*.pixel.tres -diff -merge

A sprite’s pixels are stored as bytes inside a text .tres, so two people drawing on the same sprite conflict on lines no merge tool can read, and a diff of them is noise. This tells git to show the file as changed and stop there: pick one side, and redo the other’s strokes in the editor. Sounds, songs and palettes are plain numbers and names and merge as text does.

Shipping. Export as you would any project: with the plugin enabled, an export carries the runtime and what it opens and leaves the dock, the editors, the glyphs, the fonts and the suites behind, with nothing to set in the preset. The exclude_filter a preset would carry to skip the same files:

addons/jamchip/dock/*, addons/jamchip/host/*, addons/jamchip/tests/*, addons/jamchip/kit/fonts/*, addons/jamchip/kit/icons/*, addons/jamchip/kit/themes/*, addons/jamchip/kit/tests/*, addons/jamchip/pixel/bar/*, addons/jamchip/pixel/host/*, addons/jamchip/pixel/lane/*, addons/jamchip/pixel/panel/*, addons/jamchip/pixel/rack/*, addons/jamchip/pixel/stage/*, addons/jamchip/pixel/strip/*, addons/jamchip/pixel/tests/*, addons/jamchip/chiptune/host/*, addons/jamchip/chiptune/sfx/*, addons/jamchip/chiptune/tests/*, addons/jamchip/chiptune/tracker/*

What is inside

dock/        the dock and the three-tab panel
host/        what the plugin adds to the editor on its own behalf
pixel/       the sprite editor                    — pixel/README.md
chiptune/    the tracker and the SFX generator    — chiptune/README.md
kit/         what both of them need               — kit/README.md
tests/       the suites about the plugin as a whole; not in the zip

Click a pin to switch editors, or Ctrl+1, Ctrl+2, Ctrl+3 for Pixel, SFX or Tracker from anywhere in the editor.

Each editor opens on an untitled document: a one-pattern song in the Tracker, a Bright sound in SFX, a blank 32×32 in Pixel. Draw, type or drag straight away; the keys are in the tooltip on the Pixel canvas and the Tracker grid.

What you can put in a scene

Nothing here needs the dock open, and nothing needs the plugin enabled at run time. An export carries the runtime half of each module, runtime, model, paint, format, palettes and icons from pixel/ and runtime, model, synth, format and icons from chiptune/, and ten scripts from kit/, which is everything the game opens, and nothing else from addons/jamchip/; the Install section above has the line. An exported Linux build runs on every merge to prove it.

Nodes

Node	Extends	What it is for
PixelSprite2D	AnimatedSprite2D	The front door for artwork. Give it a PixelDocument and it draws it, animates it, and follows the document as you draw. It runs its own clock in the editor.
ChiptunePlayer	AudioStreamPlayer	The front door for sound. Give it a .sfx.tres and it plays it.
ChiptunePlayer2D	AudioStreamPlayer2D	The same, positioned in 2D.
ChiptunePlayer3D	AudioStreamPlayer3D	The same, positioned in 3D.
ChiptuneMusicPlayer	AudioStreamPlayer	The same for music. Give it a .music.tres and it loops it on the beat, or turn loop off for a one-shot.

Resources you author

Resource	File	Holds
PixelDocument	.pixel.tres	A sprite: layers, frames, per-frame timing, a palette, named frame ranges with a loop flag each.
ChiptuneSfxSpec	.sfx.tres	One sound: a waveform, an envelope, the sfxr-style parameters.
ChiptuneSong	.music.tres	A song: patterns, an arrangement, instruments, and the mix.

Two more are libraries you build up and reuse. A document keeps its own copy of what it uses, so changing a library later does not reach back.

Resource	File	Holds
PixelPalette	.palette.tres	A named set of colours. GIMP .gpl files import into this.
ChiptuneInstrumentPalette	.instruments.tres	A named set of instruments, shared by SFX and Tracker.

Resources you attach

For when a node is the wrong shape.

Resource	Extends	What it is for
PixelSpriteTexture	ImageTexture	One frame of a document, kept in step. Anywhere a Texture2D goes.
PixelSpriteFrames	SpriteFrames	Every frame of a document, one animation per tag.
ChiptuneAudioStream	AudioStreamWAV	A document rendered as a stream, for any AudioStreamPlayer.

Other Pixel* and Chiptune* classes are machinery and may change shape without warning.

Preferences and themes

Click the jar at the top of the pin rail to open the JamChip menu: Preferences…, Help, which opens this file, and About JamChip, then the last ten documents you opened or saved in this project. Pick one and its tab opens it. Preferences is a window with a section list down the left; its Theme page lists the themes: Editor, which is Godot’s own, JamChip, and one row per theme file. A choice is kept in user://jamchip/preferences.cfg, per user, and is the same in every project you open.

To make a theme of your own, press Duplicate on the row closest to what you want, give it a name, and it opens on the Edit Theme page: eight swatches, surface, surface_alt and lane, then accent, playhead, ok, warning and danger. The rest of the theme is worked out from those. Every change is saved as you make it, and the dock follows if the theme is the one in use. A swatch that drops below the contrast floor says so beside itself; the theme stays saved, and the Theme page won’t offer it until it’s fixed. Edit on a theme file’s row reopens it; the Editor and JamChip rows have no Edit.

The Saving page has one number: how many seconds between copies of unsaved work to the recovery file, thirty unless you change it, five at the least. All three tabs use it.

A theme is a file: user://jamchip/themes/<name>.cfg, one [roles] section, one key per role, colours as "#rrggbb". Show Folder on the Theme page opens that directory. The editor writes only its eight keys, so the other roles are yours to set in a text editor; a role you leave out is filled in from your surface. The roles:

surface  surface_alt  surface_raised  lane
ink  ink_dim  ink_faint  border
accent  accent_ink  playhead
ok  warning  danger
onion_previous  onion_next

A theme whose text, borders or status colours do not clear a contrast floor is listed greyed, with what fell short in its tooltip. Fix it on the Edit Theme page, or in the file and open Preferences again.

If something goes wrong

Press Ctrl+Shift+P and run JamChip: Copy Diagnostics. It puts a short block on your clipboard: plugin and engine versions, platform, what the tabs were holding, and the last failures the plugin recorded. It carries no path from outside your project and nothing you drew or wrote.

Then copy the red lines out of the Output panel too. A script error is caught by Godot before the plugin’s own code runs, so it is not in the block. If the two disagree about how bad it was, believe the red lines.

Licence

The code is MIT, copyright Glitter Snack LLC. The full text is LICENSE, in this folder beside plugin.cfg. Use it in anything, commercial included, and keep the notice. The two fonts under kit/fonts/ are under the SIL Open Font License, each with its text beside it. The JamChip name, the jar and the wordmark are trademarks and not under the MIT licence; TRADEMARK.md, beside LICENSE, says what a fork may call itself.