Masked-compatible 2D sorting

SpriteSort2D

SpriteSort2D fixes top-down sprite sorting by sorting from a feet/base point and moving only the visual component. It does not move the actor root, collision, traces, AI location, navigation, or saved gameplay transform.

Start Setup Settings QA Checklist

spritesort2d visual depth

base point
  -> SortAxis projection
  -> DepthScale
  -> CameraDepthAxis offset
  -> VisualRoot only

Documentation

Search SpriteSort2D docs.

Search setup, origins, axes, materials, Blueprint calls, performance, and QA.

Find Instructions

Use plain terms like VisualRoot, grass, collision, masked, axis, origin, or performance.

01 Install Copy the plugin, enable Paper2D, and confirm SpriteSort2D is loaded. 02 Quick Start Add one component and use the default Auto setup first. 03 How It Works Sort by a base point, then move only the visual component. 04 Actor Setup Recommended hierarchies for players, NPCs, trees, grass, fences, and props. 05 Origin Modes Choose Auto, explicit origin, actor offset, visual bounds, or target bounds. 06 Settings Reference Understand every important component setting before shipping. 07 Blueprint Use Manual updates, enabling, disabling, changing origins, and reading debug values. 08 Materials Masked materials are the main path; translucent priority is fallback-only. 09 Performance Pick update modes and thresholds for full-game scenes. 10 Troubleshooting Fix reversed sorting, bad origins, collision movement, and large offsets. 11 QA Checklist Run release checks for gameplay safety, materials, scale, and packaging. 12 Roadmap Focused TODO list and what is intentionally not part of the MVP.

Install

Add the plugin to a project.

SpriteSort2D is a C++ Unreal Engine plugin. Test it in a clean project before using it in production.

1. Copy the folder

Place the SpriteSort2D folder in your project's Plugins folder.

2. Enable dependencies

Enable Paper2D if your project uses Paper sprites or flipbooks. The plugin declares Paper2D as a dependency.

3. Rebuild or reopen

Rebuild the project if prompted, then confirm Sprite Sort Component appears in the Blueprint component picker.

Quick Start

Use Auto first.

Do not start by hand-tuning everything. First prove the default setup works in your camera view.

1. Add the component

Add Sprite Sort Component to a PaperSprite, PaperFlipbook, character, NPC, or prop actor.

2. Leave defaults

Use OriginMode: Auto, SortingMode: Visual Depth Offset, and UpdateMode: When Moved.

3. Test crossing

Walk the player above and below a tree or wall. If order is reversed, enable bInvertSort.

When Auto is enough

Auto is usually enough for normal characters, props, rocks, signs, simple trees, and sprites with reasonable bounds.

When to add an origin

Add a Sprite Sort Origin for tall trees, grass overlays, large sprites with empty padding, or art that needs exact feet/base control.

How It Works

The actor does not move.

The plugin calculates a render-depth offset and applies it only to VisualRoot.

formula runtime

SortWorldLocation = base/origin
SortValue = Dot(SortWorldLocation, SortAxis)
DepthOffset = CameraDepthAxis * SortValue * DepthScale
VisualRoot = OriginalVisualRoot + DepthOffset

What stays fixed

Actor root transform.
Capsule, box, or custom collision.
AI and navigation location.
Gameplay traces and hitboxes.
Saved actor transform.

Actor Setup

Keep collision outside VisualRoot.

VisualRoot is the only component that should receive the visual offset.

Player or NPC

BP_Player
|-- CapsuleComponent
|-- VisualRoot
|   `-- PaperFlipbookComponent
|-- SortOriginFeet (optional)
`-- SpriteSortComponent

Tree or Prop

BP_Tree
|-- SceneRoot
|-- VisualRoot
|   `-- PaperSpriteComponent
|-- SortOriginTrunkBase (optional)
`-- SpriteSortComponent

Tall Grass

BP_TallGrass
|-- SceneRoot
|-- GroundPatchSprite
|-- VisualRoot
|   `-- GrassBladeSprite
|-- SortOriginGrassBase
`-- SpriteSortComponent

Fence or Wall

BP_Fence
|-- SceneRoot
|-- Collision
|-- VisualRoot
|   `-- FenceSprite
|-- SortOriginFenceBase (optional)
`-- SpriteSortComponent

Do

Put sprites, flipbooks, mesh visuals, and overlay art under VisualRoot.

Do not

Put collision or Sprite Sort Origin under VisualRoot. The plugin warns about this because it makes sorting harder to reason about.

Origin Modes

Choose where the base point comes from.

Most beginners should use Auto. Advanced users can force exact behavior.

Auto

Uses assigned SortOrigin, then visual bounds base, then target bounds base, then actor location plus offset.

Explicit Sort Origin

Uses the assigned Sprite Sort Origin. Best for tall trees, bosses, grass overlays, and exact artist control.

Actor Location + Offset

Uses actor location plus SortOffset. Useful when pivots are already placed at feet/base.

Visual Bounds Base

Calculates the base of visuals under VisualRoot. This is stable across repeated updates.

Target Bounds Base

Calculates the base of TargetPrimitive. Useful when fallback/target selection should define the sort base.

BoundsBaseAxis

Controls which direction is treated as sprite height. In many top-down Paper2D projects this is world Z.

Settings Reference

What each setting means.

Set project-wide defaults under Project Settings -> Plugins -> Sprite Sort 2D.

VisualRoot

The scene component that receives the visual offset. If empty, SpriteSort2D tries to auto-find it.

TargetPrimitive

The primitive used by fallback logic. It can be auto-found from Paper2D or primitive visual components.

SortAxis

The world direction used to calculate order. If sorting is backwards, try bInvertSort first.

CameraDepthAxis

The direction visuals move for depth sorting. Match this to your camera/depth setup.

DepthScale

Controls how far visuals move. If sprites visibly slide too much, lower it.

bInvertSort

Flips sort order without changing axis values. This is the fastest fix for reversed sorting.

SortingMode

Use Visual Depth Offset for normal work. Translucent Priority Fallback is only for special cases.

UpdateMode

Controls when sorting updates. Use static modes for props and movement-based modes for characters.

bDebugDraw

Draws the origin, offset line, sort value, update mode, and visual root name. Disable it for real gameplay tests.

Blueprint Use

Useful calls.

Most projects need no Blueprint calls. These are available for custom systems.

UpdateSortNow

Force an immediate update. Use with Manual update mode or after procedural setup.

SetSortingEnabled

Enable or disable sorting. Disabling restores the original visual transform.

SetVisualRoot

Assign the visual root at runtime, then the component caches its original transform.

SetSortOrigin

Assign an explicit origin component, usually at feet/base.

SetSortOffset

Adjust the actor-location fallback point without adding an origin component.

GetCurrentSortValue

Read the current projected sort value for debugging or custom UI.

Materials

Masked is the main path.

The plugin exists so top-down sorting does not require translucent materials as the default answer.

Also possible

Opaque materials can work when the visual-depth offset is appropriate for the camera and asset shape.

Fallback only

Translucent Priority Fallback exists for special cases. It is not the recommended main workflow.

Performance

Choose the cheapest update mode.

For full games, update policy matters more than micro-optimizing the formula.

On Begin Play Only

Use for trees, rocks, signs, fences, walls, and static props. No continuous updates.

When Moved

Default for players, NPCs, and moving props. Updates only after movement exceeds MovementThreshold.

Every Tick

Use for prototypes or unusual camera setups. Do not use by default for large crowds.

Manual

Use when another system knows exactly when sorting should update.

MovementThreshold

Increase this to prevent tiny movement changes from triggering updates.

WhenMovedTickInterval

Set above zero to throttle movement checks in large maps or crowds.

Troubleshooting

Common fixes.

Sorting is reversed

Enable bInvertSort. If that fixes it, keep the setting instead of changing multiple axes.

Sprite moves too far

Lower DepthScale. Try 0.005 or 0.001.

Collision feels wrong

Collision is probably under VisualRoot. Move collision outside VisualRoot.

Origin seems unstable

Make sure Sprite Sort Origin is not attached under VisualRoot.

Nothing sorts

Check VisualRoot, SortAxis, CameraDepthAxis, and whether sorting is enabled.

Player always renders in front

Confirm all sortable actors use the same axis setup and comparable sort origin/base positions.

QA Checklist

Release gates.

These checks catch most mistakes before users do.

Gameplay Safety

Actor root location does not change.
Collision component location does not change.
Gameplay traces hit collision, not visual offset.
Disabling sorting restores the original visual transform.

Sorting Scenarios

Player below tree renders in front.
Player behind tree renders behind.
Tall grass can cover the player when intended.
Moving NPCs sort against static props.

Material Coverage

Masked unlit sprite material works.
Masked lit sprite material remains compatible.
Translucent fallback is tested only as fallback.

Scale

100 static props using On Begin Play Only.
100 moving actors using When Moved.
500 mixed simple props with debug drawing disabled.

Bad Setup Warnings

Missing VisualRoot warning is clear.
Zero axis warnings are clear.
Collision under VisualRoot warning is clear.
Origin under VisualRoot warning is clear.

Packaging

UE 5.5 Editor, Development, and Shipping builds.
UE 5.6 Editor, Development, and Shipping builds.
Clean project install from packaged zip.

Roadmap

Keep the plugin focused.

SpriteSort2D should remain a sorting utility, not a full 2D framework.

Before public release

Create a demo map, screenshots or GIF, UE version verification, and a clean Blueprint-only project test.

Short term

Add automated transform preservation tests and sample masked materials.

Later

Add TileForge2D metadata integration only after TileForge2D is ready for sortable actor generation.

Not planned for MVP

No tilemap editing, no Aseprite import, no Paper2D replacement, and no forced translucent-material workflow.