Introduction

Spine can import the content of an Adobe Photoshop PSD file saved through Adobe Photoshop or any other graphics software capable of exporting in this format. The layers of the PSD file will be imported as attachments within a new or existing Spine project. Additionally, it is possible to automate the creation of skins, placeholders, slots, and more using a layer tagging system.

The aim of this feature is to enable the use of similar functionalities as in Photoshop to Spine, without the necessity of owning Adobe Photoshop.

Below is a non-exhaustive list of software that generates PSD files:

• Affinity
• Clip Studio Paint
• GIMP
• Krita
• Paint Tool SAI
• Photopea
• Procreate

Usage

To open the PSD import dialog, choose Import PSD from the main menu.

The Import PSD dialog that opens has three sections: Input PSD File, Output PNG File, and Import Data.

Import PSD File

This section allows you to select the path of the PSD file and set the options to use during the import process. The available options are:

• PSD File: The path to the PSD file you want to import.
• Scale: Scales the layers before writing the image files. This is useful when using high-resolution images in the PSD compared to those you want to use in Spine.
• Padding: The number of transparent pixels to add around each image. This can avoid aliasing artifacts for opaque pixels along the image border.
• Trim whitespace: When checked, whitespace around the edges of each layer is removed. When unchecked, all images are the size of the PSD file canvas.
• Ignore hidden layers: Hidden groups and layers are not output.

Output PNG Files

This section allows you to define the folder where the images extracted from the file will be saved. The available options are:

• Folder: The folder where the extracted images will be saved.
• Overwrite confirmation: If the checkbox is selected, a confirmation dialog will be shown to the user in case saving the images would result in overwriting others. The confirmation dialog will list all images that will be overwritten if the user chooses to proceed.
• Images path: The dropdown menu allows you to select:
  • a skeleton from those present in the current project; clicking it sets the Folder with the value of the selected skeleton's Image Folder.
  • PSD Path; clicking it sets the Folder with the value of folder that contains the PSD file + /images.

Import PSD file

This section works like the last part of the Import Data dialog. Please refer to the documentation of that section to understand its behavior.

PSD Setup

Spine is capable of producing different outputs based on the content of the PSD file.

Origin

Spine uses the position of guides to determine the 0,0 origin within the editor. The first horizontal guide determines the y, while the first vertical guide determines the x. In the absence of horizontal and/or vertical guides, respectively, half of the width and half of the height will be used. Subsequent guides after the first for each dimension will be ignored by Spine, so the user can use them without affecting the import process. You can control the origin also by using the [origin] tag on a layer as explained in the section below.

Be aware that the origin of the editor might be in the center or aligned to pixels. That depends on the guides' position (guides can also be placed off-pixels), or on canvas width/height (odd sizes imply the editor origin is in the center of a pixel). Be sure to place the origin in the right place to avoid blurriness artifacts. You should take extra care for the setup pose and other static poses.

Tags

By customizing layer names using tags, it is possible to automate the creation of skins, placeholders, slots, and more within Spine, as well as control the execution of certain functionalities like layer merging, resizing, and more.

Tags are text elements contained within square brackets added to the layer name and are composed as follows: [tag:value]. The tag is mandatory, while the :value depends on the tag and may be mandatory, optional, or not used. If the :value is omitted, the name of the layer or group will be used as the value. Tags can be inserted at any point in the layer name, for example: head [slot] or [slot] head. There are tags that can only be used on layers, others only on groups, but most can be used on both.

Group and layer tags

• [bone] or [bone:name] Layers, slots, and other bones are placed under a new bone. The new bone is created at the center of the first visible layer. Groups with the bone tag can be nested.
• [slot] or [slot:name] Layers are placed in a slot.
• [skin] or [skin:name] Layers are placed in a skin. Images of a layer with the skin tag are placed in a subfolder on disk with the name of the skin.
• [scale:number] Layers are scaled. Their attachments are scaled inversely so that they appear the same size in Spine.
• [pad:number] A padding of number is added to the layer or the children of the group. Useful to add a different padding from the one set through the Padding option.
• [folder] or [folder:name] Layers are placed in a subfolder on disk. Groups with the folder tag can be nested.
• [overlay] The layer is used as if it was a clipping mask for all underlying layers.
• [trim] or [trim:true] or [trim:ws] or [trim:false] or [trim:canvas] or [trim:mask] If the value is:
  • not set, true, or ws: forces the layer to have whitespace removed
  • false or canvas: forces the layer to have the canvas size
  • mask: forces the layer to be cut based on the size of the layer mask. This allows control over the size of an image even when using the Remove whitespace option. A layer mask can be useful when a mesh needs empty space around the edges to insert vertices in Spine.
• [ignore] The layer, groups, and child groups will be ignored, therefore not produced in the output.
• [!bones] Prevents the effect of the [bones] tag on this layer or group.
• [!slots] Prevents the effect of the [slots] tag on this layer or group.
• [!name] Prevents the effect of the [name:pattern] tag on this layer, or group and its children.
• [!path] Prevents the effect of the [path:pattern] tag on this layer, or group and its children.
• [!bone] Prevents the effect of the [bone:pattern] tag on this layer, or group and its children.
• [!slot] Prevents the effect of the [slot:pattern] tag on this layer, or group and its children.

Layer tags or groups with a [merge] tag

• [mesh] or [mesh:name] The layer is a mesh or, when name is specified, a linked mesh. The name must match the name of an existing mesh. When [mesh:name] is used, the linked mesh uses the size of the source mesh.
• [path:name] Specifies the name of the image file on disk for the layer, if it needs to be different from the attachment name.
• [origin] The center of the layer is used to determine the Spine editor origin. The layer is not output.

Group tags

• [merge] Layers in this group will be merged into a single layer, and a single image will be produced as output.
• [bones] Adds a [bone] tag to all immediate children.
• [slots] Adds a [slot] tag to all immediate children.

A pattern is a string that contains an asterisk (*). The following tags have a different behavior if the value is a pattern:

• [name:pattern] Adds a prefix or suffix to the layer names in the group. The name conversion happens before the other pattern tags described below are applied.
• [path:pattern] Adds a prefix or suffix to the layer paths in the group. The layer path pattern is applied even if the layer has no [path] tag.
• [bone:pattern] Adds a prefix or suffix to the layer bones in the group.
• [slot:pattern] Adds a prefix or suffix to the layer slots in the group.

For each of these, The pattern must contain an asterisk (*).

How attachment properties are determined

The order, tag values, and layer names determine how Spine creates slots, attachments, placeholders, skins, and image paths. When the file contains many groups and layers and many tags are used, it is helpful to understand how Spine interprets them to create the listed elements in order to achieve the desired result.

The hierarchy of a layer is obtained by traversing from its outermost ancestor group to the layer itself. If a layer or group contains both the [skin] tag and the [folder] tag, precedence will be given to the [skin] tag.

Spine assigns the following properties to the layer in this way:

• Slot: the value of the closest [slot] tag up the hierarchy, if present. Otherwise, it is the name of the layer.

• Skin: values of the [skin] tags from the hierarchy are selected. The closest [skin] tag up the hierarchy determines the name of the skin, and the remaining [skin] tags determine the skin folders where this skin will be placed.

• Placeholder: values of the [folder] tags from the hierarchy + the layer name.

• Attachment: values of the [folder] and [skin] elements from the hierarchy + the layer name.

• Attachment image path: if the [path] tag is present on the layer, it corresponds to the value of the attachment, but replacing the layer name with the [path] tag value. Otherwise, it is simply the attachment name.

Slash in Layer Names and in Slot, Skin, Folder, Path Tags

Adding a slash / in a layer name or in the value of a slot, skin, folder, or path tag will change its behavior. When a slash is found:

• inside a name, it allows to define subfolders.
• at the beginning of a name, it resets the hierarchy.

To create folders for slots, it is necessary to use a / inside the name, as the slot assigned to the layer is the last one in the hierarchy.

Blending Modes

Spine will recognize the following blending modes applied to a folder or layer. The slot in Spine will have the corresponding blending mode.

• Normal corresponds to the Normal blending mode in Spine.
• Multiply corresponds to the Multiply blending mode in Spine.
• Screen corresponds to the Screen blending mode in Spine.
• Linear Dodge corresponds to the Additive blending mode in Spine.

Draw order

When importing a PSD file, Spine will try to make the draw order reflect the layer order in the PSD. However, that is not always possible. For example, in a situation like this:

• A [slot:slot-folder-1/A]
• B [slot:slot-folder-2/B]
• C [slot:slot-folder-1/C]

slot-folder-1 cannot be both before and after the slot-folder-2. In this case, the folder position is determined by the last slot found in the folder. There might be other similar cases in which the layer order in the PSD cannot be mapped exactly to the draw order in Spine.

Limitations

Spine can only import pixel data for each layer. This means that if a layer does not contain pixels, such as adjustment layers, it will be ignored. Furthermore, if layer styles are applied, they will also be ignored as layer styles are not saved within the image pixels. If layer effects are used, it is recommended to rasterize all layers before importing the file into Spine.

Known Photoshop features currently not supported by the import PSD feature include:

• Adjustment and fill layers (when not saved as pixel data)
• Layer styles
• Gradient for layer masks
• Percentage fill of a layer

If you really need the features listed above, you can do one of the following:

• Transform the unsupported layers into smart objects. Photoshop will save a rasterized version of the resulting layer into the PSD file, and Spine will be able to import it without any additional effort.
• Use the old Photoshop to Spine script or other scripts available in the spine-script repository.
• Generate a Spine-compatible PSD using the Spine compatible psd script.

Next: Command line interface Previous: Import