User Guide

Interface settings

Open Settings to choose the panel language and hide tools you do not use. Hiding a tab only simplifies navigation; it does not delete presets or project data.

New users start in English. The selected language is stored locally and persists when ArtFlow is updated. Reinstalling should not be used as the normal way to change language.

Gemini keys

Gemini is required only for AI Name and optional AI-assisted operations.

1. Create a key in a Google project you control.
2. Paste it into the Gemini key field.
3. Save the key.
4. Use the connection status or a small AI batch to confirm access.

ArtFlow can store multiple user keys and switch when a request limit is reached. A successful save confirms that the key was captured; actual model access can still fail because of project billing, regional access, model availability, or quota.

Never include API keys in screenshots, support logs, PSD layer names, or exported audit files.

TinyPNG keys

TinyPNG is optional. Local PNG optimization works without a network key. Add a TinyPNG key only when you deliberately select the TinyPNG method.

ArtFlow sends the exported PNG to TinyPNG for optimization. If privacy or offline operation matters more than file size, keep the local method.

Naming configuration

The Unity naming section controls the convention used by PSD to Unity and its validators. A project-specific convention should be explicit and versioned. Changing it halfway through a production can make old memory and new names disagree.

Use the naming contract exported with the project when artists and developers need to review the same prefix, suffix, anchor, and 9-slice rules.

Local storage and reset behavior

Settings, prompts, presets, local AI learning records, and saved keys live in UXP plugin storage on the current machine. They are not a shared team database.

Before clearing plugin data:

• Export any AI memory or audit data you need.
• Record project-specific naming configuration.
• Confirm required API keys can be recreated.
• Save important presets outside the plugin when the workflow supports export.

Corrupt or unavailable local storage should not prevent the basic AI Name screen from loading; ArtFlow falls back to safe defaults and prunes recoverable memory data.

Security boundaries

Use personal or project-controlled keys, restrict them in the provider dashboard where possible, and rotate a key if it appears in a recording or public support attachment. ArtFlow cannot protect a key that has already been copied outside its local storage.

When Manual Name is the better tool

Use Manual Name when the desired change can be described as a rule. It is faster and more predictable than AI for cleaning imported files, applying a known prefix, replacing a project term, or making a numbered series.

Manual actions use the active layer scope and filters. Keep Preview enabled until the result list matches the intended Photoshop selection.

Set a fixed name

Enter a name and run Set Name. When several layers are selected, enable numbering to create a unique sequence such as:

ic_reward_01
ic_reward_02
ic_reward_03

With one selected layer, ArtFlow does not append a number solely because numbering is enabled.

Clean existing names

Use the cleanup actions for narrowly defined corrections:

Action	Use it for	Example
Remove text	Delete a known fragment	icon_temp_coin -> icon_coin
Trim start/end	Remove a fixed number of characters	old_btn_play -> btn_play
Remove Copy	Remove Photoshop copy suffixes	btn_play copy 2 -> btn_play
Remove trailing numbers	Clear an obsolete sequence	icon_star_17 -> icon_star
Find / Replace	Change a project term consistently	store_coin -> shop_coin

Run one logical cleanup at a time. A smaller preview is easier to verify and undo than a chain of unrelated transformations.

Add structure

Prefix, suffix, sequence, and case controls turn readable names into production names.

Close Button -> btn_close
Reward Icon -> ic_reward
Settings Panel -> fra_settings

For Unity UI, use the naming profile rather than inventing abbreviations. The prefix communicates role to the importer; the remaining stem communicates purpose to the team.

Use filters deliberately

Advanced filters limit which selected layers participate. They can include or exclude pixel layers, Smart Objects, text, groups, and hidden content.

Before applying a batch:

1. Confirm the Photoshop selection.
2. Confirm the enabled layer types.
3. Decide whether hidden layers belong in the operation.
4. Run the action and inspect the preview count.

If the count is surprising, clear the preview and correct the scope before applying.

Detect duplicates and invalid names

Check duplicates reports collisions without changing the PSD. Fix duplicates appends a unique number where required.

The validator checks the current profile. Fix All can convert names to snake_case, remove invalid characters, and keep the result unique. Automatic cleanup cannot infer a missing semantic role, so review generic names such as layer_01 or a frame named with ic_.

Preview, apply, and undo

The safe sequence is:

1. Run one manual action.
2. Review old and proposed names.
3. Correct the scope or settings if needed.
4. Choose Apply.
5. Use Undo immediately if the committed result is wrong.

Changing an option invalidates an older preview. Run the action again so the visible proposal always corresponds to the current controls.

Important: Undo is a recent-action safety tool, not a replacement for normal PSD versioning. Save important documents before large production batches.

The naming model

ArtFlow names UI elements in this order:

role_purpose_state

Names are lowercase snake_case. The prefix is always first because it describes how the element should be interpreted. Use btn_close, not close_button.

Built-in prefixes

Prefix	Intended role
btn_	Clickable button or control
ic_	Non-clickable icon or visual indicator
fra_	Frame, panel, card, or container sprite
text_	Text or label
bg_	Large background
pop_	Popup or modal root
bar_	Progress or fill bar
badge_	Badge or counter
tab_	Tab root
scroll_	ScrollRect root
tgl_	Toggle root
sld_	Slider root
inp_	Input field root

Choose the role represented by the layer, not merely its shape. An icon inside a button is still ic_; the parent interactive group is btn_.

Component states

State suffixes describe visual alternatives:

_normal
_highlighted
_hover
_pressed
_selected
_active
_disabled
_on
_off
_locked

Use a state only when the PSD contains that actual visual state. Do not add _pressed because a developer might need it later.

Component examples

Button

btn_play
  fra_play_bg_s9_40
  ic_play
  text_play

Toggle

tgl_music
  fra_music_bg
  ic_music_on
  ic_music_off

Slider

sld_volume
  fra_volume_bg
  bar_volume_fill
  ic_volume_handle

Input

inp_player_name
  fra_player_name_bg
  text_player_name
  text_player_name_placeholder

Scroll view

scroll_shop
  fra_shop_viewport
  content_shop

9-slice suffixes

Add _s9 to a frame sprite that should use Unity sliced image mode:

fra_panel_s9
fra_panel_s9_24
fra_panel_s9_24_32

A single number applies one PSD-pixel border value. Two numbers represent horizontal and vertical border values. Use a value that preserves corners and decorative edges.

Optional layout metadata

ArtFlow normally infers anchors from PSD geometry. Add metadata only when the inferred result cannot express the intended responsive behavior.

btn_settings@anchor=top-left
fra_coin_counter@anchor=top-right
bg_main@stretch=full
fra_bottom_nav_bg@stretch=h-bottom

Do not put both @anchor=... and @stretch=... on one layer. Metadata is removed from the Unity GameObject and sprite filename; it exists only to guide layout reconstruction.

What weak names do

Weak names no longer have to block every layout export. ArtFlow can create export-only fallback names such as img_auto_001, grp_auto_001, or text_auto_001 without renaming the PSD.

Fallback names preserve layout, but they do not describe behavior. A passive auto-named object will not become a button, toggle, slider, tab, scroll view, fill bar, or sliced image. Name behavior-critical elements before handoff.

Team profiles

The built-in contract is the default profile. A studio convention may replace its tokens while preserving the same roles. Keep one active profile per project, record its version, and do not mix conventions inside one export set.

Before importing

A Unity handoff contains exported sprite files and a layout JSON file. Keep the exported structure together until the import is complete.

Use a supported Unity project with uGUI available. Back up or commit the project before testing a new importer version on production assets.

Install the importer

Copy:

PipelineProImporter.cs

to:

Assets/Editor/

Unity compiles editor scripts automatically. Resolve compilation errors before opening the ArtFlow import command.

Import the layout

1. In Unity, open Tools > ArtFlow > Import Layout.
2. Select the exported layout JSON.
3. Choose the destination requested by the importer.
4. Wait for asset import and hierarchy creation to finish.
5. Inspect the created Canvas or layout root.

Do not move or rename sprite files during the import. References are resolved from the exported data and asset paths.

What the importer can reconstruct

Depending on the exported names and data, the importer can prepare:

• RectTransform hierarchy and relative placement
• Image and Text-oriented objects
• anchors and stretch behavior
• sliced Image setup from _s9...
• Button state graphics
• Toggle child roles
• Slider fill and handle relationships
• ScrollRect viewport and content structure
• input field background, text, and placeholder
• bar fill behavior
• safe-area aware structure where exported

The importer reduces repetitive assembly. It does not know game logic, navigation destinations, localization keys, data binding, or animation intent unless your Unity project adds those systems.

Verify the result

Check the hierarchy in this order:

1. Canvas reference resolution and root scale.
2. Large background and panel alignment.
3. anchors at several Game view aspect ratios.
4. sprite import mode and alpha.
5. 9-slice borders and Image type.
6. button, toggle, slider, input, and scroll references.
7. text content, font mapping, alignment, and size.
8. active, hidden, locked, and disabled states.

Test at least one tall mobile aspect and one wider aspect. A layout that matches only the source PSD size has not yet proven its anchors.

Text and fonts

Photoshop and Unity do not share an identical text engine. ArtFlow carries text and font context forward, but the Unity project must contain the intended font asset.

When using TextMeshPro, provide a valid Assets/... .asset path in the font mapping. Duplicate PSD font mappings or invalid TMP paths should be resolved before relying on automated text setup.

Expect to review line wrapping, kerning, fallback glyphs, and vertical alignment. These are engine-level differences, not necessarily export failures.

Reimporting safely

Treat the generated hierarchy as pipeline output until it has been accepted. If developers add game logic directly to generated objects, define a team rule for reimport so a later handoff does not overwrite or duplicate their work.

A practical model is:

• ArtFlow owns imported visual hierarchy and sprite updates.
• Project scripts own gameplay behavior and data.
• Prefab wrappers or integration scripts connect the two.

When import looks wrong

Return to the Photoshop review report first. Confirm that the affected object had valid bounds, a useful role prefix, and non-conflicting layout metadata. If the JSON is valid but Unity behavior is wrong, record the Unity version, importer version, object name, and relevant JSON node before changing the source PSD.

Two optimization paths

ArtFlow can optimize PNG output locally or through TinyPNG.

Mode	Processing	Best for
Local	On the computer with pngquant	Private work, offline use, predictable batch processing
TinyPNG	Cloud API with a configured key	Strong general compression with low setup effort

Optimization runs after export. ArtFlow compares available candidates and keeps a usable result rather than blindly replacing a file with a larger or failed candidate.

Local optimization

Local mode reduces the image to a palette with a configurable maximum color count. Lower values can reduce file size, but gradients, soft shadows, glow, and subtle transparency may show banding.

Start with a generous color limit for polished UI. Test representative files before applying an aggressive setting to the entire asset set.

Good candidates:

• flat icons
• hard-edged badges
• limited-color pixel art
• UI elements with simple shading

Review carefully:

• gradients
• translucent smoke or effects
• soft shadows
• skin tones or painted illustration
• already optimized PNGs

TinyPNG

Add your key in Settings > TinyPNG API Key, save it, and select TinyPNG in the export optimization controls.

TinyPNG requests use an external service and its quota. A valid key can still be rate-limited or exhausted. ArtFlow can rotate among saved keys where configured and can fall back to local optimization when the active workflow allows it.

Fallback and failure

If TinyPNG is unavailable, the export summary identifies whether a file:

• used TinyPNG,
• used local fallback,
• kept the original,
• or failed optimization.

The original exported asset should remain the safety baseline when an optimization candidate is invalid. A compression error must not be interpreted as a successful smaller file.

Verify quality

For a new project or preset:

1. Export a small representative set.
2. Compare dimensions and transparency.
3. Inspect gradients and edges at 100% and against the intended background.
4. Compare file sizes.
5. Open the assets in the target runtime.
6. Save the settings as an export preset only after acceptance.

Do not publish an exact percentage-saving claim based on one file. Compression depends heavily on the source image.

Privacy

Local mode does not need a network request. TinyPNG sends the exported image to TinyPNG for processing. Choose the mode that matches the project’s data policy.

Choose Pack or Split

Pack arranges selected Photoshop layers into cells on the current canvas. Split reads one or more pixel or Smart Object layers as an atlas and exports individual PNG cells.

Set the row and column count before choosing either operation.

Pack selected layers

1. Select the layers in the intended order.
2. Set rows and columns.
3. Enable Fit to cell only when resizing is acceptable.
4. Enable Guides if the PSD should retain visible grid boundaries.
5. Choose Pack.

ArtFlow places as many selected layers as the grid contains. Extra layers are ignored and reported. If the canvas is too small for a valid cell size, the operation stops.

Fit-to-cell changes scale to fit the available area. Inspect small text, pixel art, and sharp UI edges after scaling.

Split an atlas

1. Select one or more pixel or Smart Object layers.
2. Set the exact source rows and columns.
3. Enter an output prefix.
4. Choose whether transparent edges should be trimmed.
5. Select the required output folder.
6. Confirm the displayed cell count.
7. Choose Split.

The cell preview follows:

rows x columns = exported PNG count

ArtFlow merges the selected visual source temporarily for export. The source PSD structure remains unchanged.

Naming output

With prefix cell, output follows a sequence such as:

cell_0.png
cell_1.png
cell_2.png

Choose a semantic prefix before export if the target pipeline relies on filenames.

Transparency and trimming

Trim removes empty transparent boundaries around each cell. Fully transparent cells cannot derive visible bounds, so ArtFlow reports them and may preserve the full cell dimensions.

Disable trimming when every frame must keep identical dimensions or a fixed pivot relationship.

Transaction safety

Grid Split treats a batch as one output operation. If the operation fails, partial output is cleaned where possible so an incomplete folder is not mistaken for a finished atlas.

Still verify:

• expected file count
• consistent dimensions when trim is off
• alpha edges
• sequence order
• output folder

Open the completed output folder from the log or completion action and inspect the first, middle, and last tile.

Effect clipboard

Select a source layer and choose Copy FX. The panel records the copied effect state. Select destination layers and choose Paste FX.

Paste is additive and aims to preserve effects already present on the target. Test on one representative layer before applying to a large mixed selection.

Remove unused effects

Remove Unused FX removes disabled effects from selected layers. It is intended for cleaning copied or legacy effect stacks without deleting enabled visual effects.

After cleanup, compare a few layers at the same zoom and blending context. Disabled effects should not change the current appearance, but the PSD history and future edit options will change.

Convert to Smart Object

The conversion tools can convert selected layers, or supported top-level layers, into individual Smart Objects.

Use individual conversion when each item must remain independently editable or exportable. Confirm selection and hierarchy first; conversion changes the Photoshop layer type and may affect later automation that filters by pixel, text, or Smart Object.

Overlay Shot

Overlay Shot duplicates the selected overlay into the group below and clips copies to child layers. It is useful for applying a shared lighting, color, or texture treatment across several visual parts.

Verify:

• the intended source overlay is selected,
• the destination group is directly below,
• child order is correct,
• clipping produces the intended appearance,
• no unsupported child should receive a copy.

Split text

Text splitting converts a supported horizontal text layer into separate output layers while preserving positions, including auto-wrapped lines where supported.

The naming pattern can use:

{layer}
{index}
{text}
{line}

Set a maximum output count before running the operation. Keeping the original hidden provides an immediate reference and safer recovery.

Review line wrapping and special characters. Photoshop typography can include ligatures, combining marks, and layout behavior that should not be assumed to split like plain characters.

Split pixel content

Pixel Split separates alpha-connected regions from a pixel or Smart Object layer. Glyph mode is suited to character-like parts; Object mode is suited to distinct visual islands. Optional AI grouping can improve ambiguous grouping but introduces an external request.

Advanced controls include alpha threshold, minimum pixel count, maximum output layers, naming pattern, and whether to hide the source.

Begin with a small representative layer. A low alpha threshold may connect faint shadows; a high threshold may break soft artwork into fragments. Minimum pixel count filters noise but can also remove intentionally tiny marks.

Recovery

Use the provided undo path immediately after a bad split where supported. Keeping source layers hidden instead of deleting them is the safer default. For high-value files, save the PSD before any operation that creates many layers.

What a preset stores

ArtFlow has several preset types because each solves a different repeated decision:

Preset	Stores	Does not do automatically
Rename button	Label and naming pattern	Select layers or bypass preview
Export preset	Current export configuration	Start an export
AI prompt preset	Saved naming prompt	Spend a request until Run AI is chosen
API key preset	A Gemini or TinyPNG key	Guarantee service quota
Convention preset	A naming convention link/profile	Change a project unless selected

Keep preset names specific enough to distinguish projects or output targets.

Rename pattern tokens

Custom rename buttons can combine literal text with:

{name}    current layer name
{i}       sequence index
{parent}  direct parent group
{group}   group path
{type}    pixel, smart, text, or group

Example:

ui_{parent}_{name}_{i}

Test the pattern on a small selection with Preview enabled. Parent and group values inherit source PSD naming quality, so validate the result if legacy names contain spaces or temporary labels.

Export presets

Configure Export first, then save the current configuration. Applying an export preset updates settings only; it does not write files.

Use:

• Set to load a preset,
• Update to replace it with current settings,
• Rename to clarify ownership or target,
• Delete to remove an obsolete configuration.

Include format, scale, padding, filtering, folder behavior, and optimization expectations in the preset label when confusion is likely.

Prompt presets

Store prompts by naming mode. A UI naming prompt and a general asset-description prompt are not interchangeable.

Review a saved prompt after the naming profile changes. A prompt cannot override the validator, but stale instructions can produce weaker suggestions and waste quota.

Key presets

Saved keys allow switching or service fallback behavior. Treat keys as secrets:

• do not put them in screenshots,
• do not include them in support logs,
• do not commit exported settings,
• revoke a key that may have been exposed.

Maintenance

Review presets when a project convention, destination folder, Unity version, or external service changes. Delete or rename ambiguous presets instead of accumulating several entries called “Default.”

Reset Settings removes saved configuration broadly. Use targeted preset controls for routine cleanup.