# How your work is organized

Projects, sprites, layers, frames and cels, and your libraries of palettes, brushes and scripts, and where each is kept.

Everything you make in pxstud.io fits into a few nested pieces. Knowing them helps with almost
everything else: what undo can take back, what a downloaded file contains, and what Sync copies
to your other devices.

## The pieces

```
Project
└── Sprite                     one image or animation (a .pxstudio file)
    ├── Layers                 stacked drawings; groups hold other layers
    ├── Frames                 the steps of the animation
    │   └── Cels               what one layer shows on one frame
    ├── Tags                   named ranges of frames
    ├── Slices                 named rectangles (hitboxes, 9-slices, export areas)
    ├── Palette                the sprite's colors
    └── Tilesets               the tiles of tilemap layers

Your library: palettes, brushes and scripts, used across all your sprites
```

**Project.** A named folder of sprites. You can have as many as you like and switch between them
in the **Project** menu. A project holds nothing but its sprites.

**Sprite.** One image or animation: its size, color mode, layers, frames and everything else
below. Each sprite opens in its own tab. Its name belongs to the project, not the drawing, so a
downloaded `.pxstudio` file takes the sprite's name as its file name.

**Layer.** Layers stack from the bottom up, and each one can be shown, hidden, locked and blended
on its own ([Layers](https://pxstud.io/docs/manual/guides/layers.md)). There are four kinds:

- **image layers**, the usual kind, holding pixels;
- **groups**, which hold other layers;
- **reference layers**, a picture to trace over, never exported;
- **tilemap layers**, painted with tiles from a tileset.

The **Background** layer is an image layer with a few rules: it's opaque, at the bottom, and can't
be moved.

**Frame.** One step of the animation, with how long it shows (in milliseconds). A still image is a
sprite with one frame.

**Cel.** The meeting point of a layer and a frame: what that layer shows on that frame. A sprite
with 3 layers and 4 frames has up to 12 cels. A cel can be **empty** (nothing drawn there yet), and
cels on one layer can be **linked** so several frames share one picture: drawing on any of them
changes all of them. Pixel art usually has empty space, so a cel only stores the part of the canvas
that's been drawn on.

**Tag.** A named, colored range of frames ("walk", "jump") with a playback direction: forward,
reverse, ping-pong or reverse ping-pong, and how many times it repeats. Exports can use one tag's
frames.

**Slice.** A named rectangle on the canvas with no pixels of its own, used to mark hitboxes, export
regions or 9-slice scaling guides. A slice can change from one frame to the next.

**Palette.** The sprite's list of colors. What it means depends on the sprite's **color mode**:

- **RGBA:** every pixel has its own color, with transparency. The palette is a set of swatches to
  pick from.
- **Grayscale:** shades of gray, with transparency.
- **Indexed:** every pixel _is_ a palette entry, so recoloring an entry recolors every pixel that
  uses it. One entry (the first, unless you change it) counts as transparent.

A palette can also change partway through an animation, from a given frame on.

**Tileset.** The tiles a tilemap layer paints with. Repainting a tile updates everywhere it's
placed, and several tilemap layers can share one tileset.

**Your library.** Palettes, brushes and scripts you make, save or fork live in your own library,
outside any sprite, so you can use them in all of them. The editor also comes with built-in
palettes and brushes. Choosing a library palette copies its colors into
the sprite; changing it later doesn't change sprites that already use it.

## The editing context

Your **foreground and background colors**, the **brush** and each **tool's options** aren't part
of any sprite. One set is shared by every tab, so switching sprites keeps your brush and colors.
They reset when you reload the page. (A [saved layout](https://pxstud.io/docs/manual/guides/workspace.md#layouts) can bring
your tool settings back.)

## What undo covers

Each sprite has **its own undo history**. Anything that changes the sprite can be undone: drawing,
layers, frames, cels, tags, slices, the palette, resizing, and the selection too.

These **can't** be undone:

- renaming a project or a sprite;
- changes to palettes, brushes and scripts in your library;
- your colors, brush and tool options;
- which layer or frame is active, and how the workspace is arranged;
- the names you give undo steps.

The history is saved with the sprite, so it's still there after you close its tab or reload the
page, and with Sync on your other devices too. The oldest steps are dropped after 1,000.

## Versions

Undo goes back step by step, and its oldest steps are dropped. To keep a state of a sprite for good,
**name it**: Sprite > Version History... > **Name this version...** keeps the sprite as it is now
on this device, until you delete the version. From the same list you can **Compare** a version with
the sprite as it is now (side by side, or with every changed pixel marked), **Restore** it (one step
you can undo) or download it as a `.pxstudio` file (without undo history: a version has none).
Naming a step in the [Undo History](https://pxstud.io/docs/manual/guides/document.md#undo-history) panel keeps a version too:
the sprite as it was at that step.

With Sync, the cloud keeps earlier versions of each sprite too: every save of the last day, then one
a day for 30 days, then one a week for a year. Name one of those (the pin button) and it's kept for
good on every device; its storage counts toward your plan until you remove the name.

## The same sprite in two tabs

A sprite can be edited in only one browser tab at a time. Open it in a second tab and it's read-only
there, with a note at the top; whatever the first tab saves shows up in it. Choose **Edit here** to
move the editing to the second tab: the first one saves and becomes read-only. When the editing tab
closes the sprite, another tab that has it open takes over.

## Where things are kept

| What | Kept |
| - | - |
| Projects and sprites | In this browser, saved as you work. With Sync, also in your account. |
| Your palettes, brushes and scripts | In this browser. With Sync, also in your account; published script versions are in the script library. |
| Built-in palettes and brushes | In the editor itself. |
| Hearted scripts | In your account, with a copy in this browser so they work offline. |
| Layouts, preferences and shortcuts | In this browser only. |
| Colors, brush and tool options | Only while the page is open. |
| Undo history | With the sprite: in this browser, with Sync in your account, and in the `.pxstudio` files you download. |
| Named versions | In this browser. Cloud versions you name are in your account. |

## Files you can download

- **A `.pxstudio` file** (File > Save As...) is one sprite: its size and color mode, palette,
  layers, frames, cels, tags, slices, tilesets, grid and reference images, and its undo history.
  It doesn't include named versions, the selection or anything outside the sprite. Open it again
  with File > Open..., and undo carries on where it was.
- **Everything at once:** on [your account page](https://app.pxstud.io/account), **This browser > Export everything (.zip)**
  downloads a zip of every project's sprites (as `.pxstudio` files, with their undo history) and your palettes (`.gpl`),
  brushes and scripts. It works offline, and signed out.