clutter manual

A palette animation editor for indexed images. Open clutter. The numbered labels in each screenshot match the numbered notes under it.

An animation here is a list of complete palettes played over one fixed image. The pixels never change; each frame swaps the palette. On a PlayStation that means uploading a new CLUT per frame and nothing else.

1. Importing an image

Everything runs in the page; nothing is uploaded anywhere.

the format dialog shown on import
  1. Open… takes a PNG, or a .clutter.json project saved earlier. Dropping either on the canvas does the same.
  2. Before the image loads you choose the colour format: RGBA8888, RGB565, or RGB5551 for the PlayStation. The screenshots in this manual use RGB5551.
  3. An indexed PNG keeps its own palette and indices. A truecolour PNG is quantized, and this dialog then also asks how many colours (2 to 256).
  4. Import loads it as an animation of one frame.

2. The window

clutter with an image loaded
  1. The image, drawn with the palette of the current frame. The mouse wheel zooms.
  2. The palette of the current frame, one square per entry.
  3. The generators, which create frames, and the edits that work across frames.
  4. The timeline: one cell per frame, each a complete palette.
  5. Frame editing and loop settings.
  6. Play and its speed.
  7. Zoom: Fit fills the canvas, 1:1 shows one screen pixel per image pixel.
  8. Status: frame count, current frame, loop setting, and the result of the last action.
  9. The link to this manual.

3. Selecting and editing entries

palette entry 17 selected in the editor
  1. Click an entry to select it and open it in the editor. Shift+click selects every entry between it and the last one clicked; Ctrl or Cmd+click adds or removes one. Most tools work on the selection.
  2. The entry's channels, in the units the format stores: 0-31 for RGB5551, so what you set is exactly what the hardware gets.
  3. The PlayStation semi-transparency bit. It only matters when the primitive is drawn semi-transparent; otherwise the colour draws solid.
  4. The packed value as stored. You can type a value here.
  5. Set for all writes the selected entries' colours into every frame, or into every frame of a selected span. Use it for a colour that should not animate.
  6. Copy from… gives the selected entries the colour of another entry, frame by frame, so if that entry animates the copies animate with it.

RGB5551 cannot hold an opaque black: 0x0000 is always transparent. The editor shows a warning under the value when an entry is set to it.

4. Colour cycle

Rotates the colours of the selected entries one step per frame, the Deluxe Paint way. Here entries 1-16 are the bands of the waterfall, so cycling them makes it flow.

the colour cycle dialog
  1. The entries being cycled. They are cycled in index order; a selection with gaps is cycled as if it had none.
  2. How far the colours move each frame. 1 is one entry per frame, 0.5 is one every two frames, a negative value runs backwards.
  3. wrap: a colour pushed off one end comes back at the other. Off, it drops out and the emptied entries repeat their neighbour.
  4. How many frames to add. The default is one full turn of the selection.
  5. How many of those frames the format can tell apart. If two would come out identical, it says so here before you generate.
  6. Generate adds the frames after the current one.

5. Frames and playback

the timeline after a colour cycle
  1. The timeline. Drag to scrub. Shift+drag selects a span of frames, or moves the loop marker if you start on it; Esc clears the span. The wheel zooms the timeline and the middle button pans it.
  2. Insert, delete, duplicate, and move the current frame left or right.
  3. hold: how many playback ticks the current frame stays on screen.
  4. Loop mode: none, forward, backward, or ping-pong.
  5. Set loop here: after the first pass, playback loops from this frame to the end.
  6. Play, or Space, at this many ticks per second. The arrow keys step one frame, Home and End jump to the ends.
  7. Frame count, current frame and loop setting.

6. HSB ramp

Generates frames that shift the selected entries' hue, saturation and brightness. If a span of frames is selected, the ramp is applied across that span instead, and the step count comes from the span.

the HSB ramp dialog
  1. Hue offset in degrees, from the first value to the second over the run. Equal values hold it still.
  2. Saturation multiplier, from - to.
  3. Brightness multiplier, from - to.
  4. The easing curve the ramp follows.
  5. How many frames to generate.
  6. closed: the last step comes back round to the start, so the ramp loops without a jump.
  7. RGB5551 only: the colour used when a result comes out as 0x0000, which would draw as transparent.
  8. How many of the frames the format can tell apart. In this example only 11 of 12 differ at 5 bits per channel.

7. Interpolate

Adds frames between the existing ones, blending each pair. Only the selected entries are blended; the others are copied from the frame on the left.

the interpolate dialog
  1. What will be blended: how many gaps, and how many entries change.
  2. New frames per gap, 1 to 64.
  3. The easing curve.
  4. RGB5551 only: the replacement for a result of 0x0000.
  5. How many frames will be inserted, how many differ, and the new length.

8. Phase shift

Delays the animation of the selected entries by some number of frames, so entries that animate identically can be set out of step.

the phase shift dialog
  1. How many frames to delay the first selected entry by. Negative shifts the other way.
  2. Extra delay added for each further selected entry, rounded down: a row of lights that chase each other.
  3. wrap: colours shifted past the last frame come back at the first. Off, they drop out and the vacated frames repeat their neighbour.
  4. What the shift will do.

9. Colour format

the format dialog for a loaded image
  1. Format… changes the format at any time. Colours are kept at full 8-bit precision and only shown through the format, so switching to RGB5551 and back loses nothing.
  2. What the change will do.

10. Export

the export dialog set to a multi-palette TIM
  1. What to write: the raw image data, the sequence of palettes, a .tim holding the image and every palette, the palettes alone as a .clt, or a text file from a template.
  2. For the PlayStation formats: how many palettes sit side by side in the CLUT before the next row starts. 1 stacks them.
  3. Exactly what will be written: depth, CLUT size and layout.
  4. Export saves the file.
the export dialog set to a text template
  1. The template. {{#frames}}...{{/frames}} repeats once per frame, {{#loop}}...{{/loop}} and {{^loop}}...{{/loop}} depend on whether the animation loops, and :hex or :hex4 formats a number in hexadecimal.
  2. An unknown placeholder is left as written, so a typo shows up in the output.

Placeholders: name nameId nameUpper width height pixelCount paletteSize frameCount totalTicks fps loopStart (-1 when not looping) loopMode colorFormat colorFormatId, and inside {{#frames}}: index hold offset isLoopStart.

Save writes the project as .clutter.json, which Open… reads back.