Download

Paper 2D Documentation for 4.3 Preview

Paper2D draft documentation for Unreal Engine 4.3
The goal of Paper2D is first-class support for making 2D and hybrid 2D/3D games in UE4.

The roadmap for feature development can be found here Trello and there is a forum thread for news, feedback, and support at Project: Paper2D - Engine Source & GitHub - Unreal Engine Forums.

Sprites, flipbooks, and their associated editors are an ‘early access preview’ as of the 4.3 release. While not considered fully production-ready, they are a step beyond ‘experimental’ and are being provided as a preview of things to come:

  • We will try to provide forward-compatibility for content you create.
  • The classes may change significantly in the future.
  • The code is in an early state and may not meet the desired polish / quality bar.
  • They will be promoted out of ‘Early Access’ when they are production ready.

Sprites
A sprite in Paper2D is a texture mapped planar mesh and associated material that can be rendered in the world, created entirely within the editor. In simpler terms, it’s a quick and easy way to draw 2D images in UE4.
Creating a sprite
Sprites can be created in a number of different ways:

  • By using the context menu option “Create Sprite” on a texture in the content browser, which will create a sprite that encompasses the texture.
  • From the New…Miscellaneous menu in the content browser, which will create a blank sprite.
  • By using the context menu option “Extract Sprites”, which will identify any sprites in the image that are separated by transparency and create them.
  • By importing a JSON formatted sprite sheet description, which will import associated textures and create sprites and a flipbook for the described frames.

All of the settings in a sprite can be edited using the sprite editor by double-clicking on a sprite in the content browser or by pressing Ctrl+E on a placed sprite actor in the level.

The Sprite Editor
The Paper2D Sprite Editor enables setup and editing of individual sprite assets (UPaperSprite).
Toolbar

00_SpriteToolbar.png

  • Save – Save the sprite being edited
  • Find in CB – Show the sprite being edited in the Content Browser
  • Src Tex – Toggles display of the entire texture that the sprite is referencing
  • Add Polygon – Adds an additional polygon when editing collision or render geometry
  • Snap to pixel grid – Snaps all vertices to the pixel grid when editing collision or render geometry

Mode Switching Toolbar

01_SpriteModeToolbar.png

  • View – Displays a preview of the sprite in the viewport along with general statistics.
  • Edit Source Region – Displays the full source texture and enables you to set the area within the source texture that composes the individual sprite.
  • Edit Collision – Displays and allows editing of the sprite collision shapes.
  • Edit RenderGeom – Displays and allows editing of the sprite render geometry.

Viewport
Shows the sprite being edited and enables access to interactive editing tools using standard gizmos. The viewport toolbar contains standard view options such as lit or unlit rendering mode, mesh edges, etc…

02_SpriteViewport.png

Details panel
This shows all of the editable properties of the opened sprite asset.

03_SpriteDetailsPanel.png

  • Source Texture – The source texture that contains the image to be used for the sprite.
  • Source Dimension – The size of the source region (in pixels) within the Source Texture.
  • Source UV – The offset of the source region (in pixels) within the Source Texture.
  • Default Material – This is the default material that will be used to render the sprite if a particular component doesn’t have a custom material override.
  • Pixels per unit – Adjusts the scaling factor between pixels in the texture and Unreal Units (centimeters). For example, a value of 1.28 will size a 128 pixel wide sprite to be 1 meter. This value can be adjusted per sprite, but you can also set a global default value for newly created sprites in the project settings (Paper2D plugin page). Adjusting your scale to be in a realistic range helps greatly with the stability of physics simulations, among other things.
  • Pivot Mode – Controls the way that the sprite pivot is calculated. It defaults to being computed as the center of the source region, but can be set to any of the corners or mid-points on the edges. You can also define a custom pivot point by setting the mode to Fully Custom and typing in a value for the Custom Pivot Point property.
  • Sockets – Sprites can also define sockets, which can be used as attachment points for other components or reference points to spawn effects or do queries. These can be created by adding to the “Sockets” array in the Details panel and edited in the viewport using the standard gizmos.
  • Sprite Collision Domain – Controls whether or not the sprite has collision shapes, and which domain they’ll be created in. See the ‘Editing sprite collision’ section for more details. When this is set to ‘Use 3D Physics’, Collision Thickness controls the thickness of 3D collision shapes.

Sprite list
This shows all of the sprites that share a common source texture. Double clicking on another sprite will switch the current asset being edited, which can be useful when adjusting a bunch of sprites in a row. Another approach for bulk editing is to use the ‘Property Matrix’ context menu option on several selected assets in the Content Browser.

04_SpriteList.png

Editing the source region
Each sprite is roughly defined as a rectangle from a texture, which can be edited interactively using the ‘Edit Source Region’ mode in the sprite editor, or typed in manually in the details panel (Source Dimension and Source UV, both in pixels). The actual rendered geometry can be further adjusted in the ‘Edit RenderGeom’ mode, and the collision shape can be adjusted in the ‘Edit Collision’ mode.

05_SpriteSubregion.png

Editing sprite collision
Sprites can define collision shapes just like static meshes, controlled by the ‘Sprite Collision Domain’ property. There are three different settings:

  • None: No collision geometry is generated; use this for purely decorative sprites.
  • Use 2D Physics: This is an experimental option to generate collision geometry for use with Box2D. See the notes in the experimental features section for more information on the current limitations.
  • Use 3D Physics: Collision geometry will be generated for use with PhysX. The 2D collision geometry defined in the sprite will be extruded to “Collision Thickness” units deep in the perpendicular axis to make 3D collision geometry.

06_SpriteCollision.png

The ‘Geometry Type’ setting on collision geometry is the easiest way to define collision, which has settings for loose, tight, shrink-wrapped, or fully custom geometry. Shrink-wrapped is still experimental, but the others are fully supported. The Edit Collision mode displays the collision geometry and lets you adjust it in the viewport, automatically setting the mode to fully custom.

The toolbar buttons can be used to add additional polygons or snap vertices to the pixel grid. New vertices can be added by selecting an edge and pressing the Insert key, and selected vertices can be deleted by pressing Delete.
Optimizing sprite rendering
As with collision editing, you can edit the rendering geometry using the ‘Edit RenderGeom’ mode in the sprite editor. This can be useful to optimize transparent or masked sprites, trading off some extra triangles in exchange for reduced overdraw in transparent regions of the texture. The settings and tools are exactly the same as editing custom collision geometry. Be sure to use the “Snap to Pixel Grid” tool after editing custom geometry (this will happen automatically in a future release, but is a manual process for now).

07_SpriteRenderGeom.png

Working with sprite components
Sprite components are regular primitive components, and can be posed arbitrarily in 3D, attached to other components, or have other components attached to them (including at sockets defined in the sprite asset).

Each sprite component instance can specify a custom color that will be passed down to the sprite material as a vertex color. They can also have a custom material specified that will override the default material defined in the sprite asset. You can change the current sprite asset by calling SetSprite, but note that this will only work if the Mobility property is set to Moveable (or if it is called during the construction of the actor). See the reference documentation of UPaperSpriteComponent for more details.
Creating custom sprite materials
The Paper2D plugin includes a set of basic materials that sample a texture and multiply it by the vertex color, with lit and unlit variations for opaque, masked, and translucent textures. The default material on sprites and flipbooks is unlit masked.

A custom sprite material can be created by duplicating one of the existing ones, or creating a new material in the content browser. When a sprite is rendered, the texture defined in a sprite asset will be piped into any texture parameters named ‘SpriteTexture’ in the material. The SpriteTextureSampler node in the material editor can be placed to do this automatically. Sprite instances will pass in their color as a vertex color, but it can be used for anything in the material, not just tinting.

Flipbooks (Animated sprites)
A flipbook consists of a series of key frames, each of which contains a sprite to be displayed and a duration (in frames) to display it. The property Frames Per Second controls how fast these frames will be displayed, indicating how many animation ‘beats’ will occur in a second. Key frames can currently be edited in the details panel or by using the timeline at the bottom of the editor.
Creating a flipbook
Flipbooks can be created in a couple of different ways:

  • From the New…Animation menu in the content browser, which will create a blank flipbook.
  • By importing a JSON formatted sprite sheet description, which will import associated textures and create sprites and a flipbook for the described frames.

All of the settings in a flipbook can be edited using the flipbook editor by double-clicking on a flipbook in the content browser or by pressing Ctrl+E on a placed flipbook actor in the level.
The Flipbook Editor
The Paper2D Flipbook Editor enables setup and editing of individual flipbook assets (UPaperFlipbook).
Viewport
This enables you to view the Flipbook in action so you can make sure the animation plays correctly.

09_FlipbookViewport.png

Timeline
This displays all of the frames in the flipbook animation.

10_FlipbookTimeline.png

  • You can drag the handles to modify the duration of any frame.
  • You can right click on a key frame in order to insert a new one before or after it, or to delete it.
  • The tooltip for a key frame also shows the associated sprite and duration.
  • Sprites or flipbook assets can also be drag-dropped onto the timeline in order to append them as additional key frames to the end of the timeline.

Scrub Bar
This provides playback controls and enables you to scrub thru the animation.

11_FlipbookScrubBar.png

Working with flipbook components
Flipbook components are regular primitive components, and can be posed arbitrarily in 3D, attached to other components, or have other components attached to them.

Each flipbook component instance can specify a custom color that will be passed down to the flipbook material as a vertex color. They can also have a custom material specified that will override the default material defined in the flipbook. You can change the current flipbook asset by calling SetFlipbook, but note that this will only work if the Mobility property is set to Moveable (or if it is called during the construction of the actor). You can also control play rate, play direction, looping, etc…, with various other methods on the component. See the reference documentation of UPaperFlipbookComponent for more details.

Note: Flipbooks do not currently support any form of collision. You can use a capsule or box component in conjunction with a flipbook to provide the associated collision shape.

Working with sprite sheets
Splitting up a sprite sheet in the editor
If you import a texture that contains many sprites, you can split it up into individual sprites in several different ways. The easiest way is via the context-menu option on the texture “Extract Sprites”, which will identify any sprites in the image that are separated by transparency. You can also duplicate an existing sprite from the texture and use the “Edit Source Region” mode in the sprite editor to narrow in on the specific sub-region of the texture in each sprite.
Importing a sprite sheet or flipbook from a JSON file
Paper2D includes an importer for JSON formatted sprite sheet descriptions, which can be exported from tools like Adobe Flash CS6 or Texture Packer. It will import any referenced textures and create sprite assets for each sprite. The importer also assumes that all of the sprites are frames of an animation, so it will always create a flipbook in addition to the individual sprites. You can delete the generated flipbook if it isn’t needed.

Templates
2D Side Scroller
This template shows how to create a 2D side scrolling platformer game. There are C++ and Blueprint-only variants as with most other templates.

00_SpriteToolbar.pngb5a31312834981af30799805a6010f560acc1199.png02_SpriteViewport.png03_SpriteDetailsPanel.png
04_SpriteList.pngcc13af77ff64d9c5858ae42e3ca94fe1301b2b2e.png06_SpriteCollision.png07_SpriteRenderGeom.png

09_FlipbookViewport.png10_FlipbookTimeline.pngf0d02a1fb35fbd391fc32ff8eca3c792483a7780.png

Cheers,
Michael Noland

Experimental features
Paper2D also includes some experimental features, which are totally unsupported and undocumented prototypes (here be dragons!):
[ul]
[li]Data or code compatibility is not guaranteed.
[/li][li]They may be dramatically changed or abandoned in a future build.
[/li][li]The code is in an early state and may cause editor instability or crashes.
[/li][li]They may be promoted to ‘Early Access’ or ‘Fully Supported’ or deleted entirely in the future.
[/li][/ul]

12_Experimental.png

2D Terrain Splines
2D terrain spline support is experimental and must be enabled from the Paper2D plugin settings; it is not ready for use, and is only mentioned here in case you want to experiment with it. There are no guarantees that content made with the 2D terrain component will work in a future release.

13_TerrainActor.png

Once enabled, you can place a terrain spline actor using the placement mode in the editor. The spline can be edited whenever the actor is selected (see the documentation on spline components for more information). A terrain material must be applied to the terrain component in order to define how it will be rendered (New…Data Asset in the content browser, pick Terrain Material as the type).

14_TSplineAlt.png

Terrain materials define rules for how the terrain should be textured, and each rule consists of one or more sprites that will be deformed to match the terrain spline in the region where that rule applies.

The process that generates the visuals for a terrain spline is as follows:
[ul]
[li]Break the terrain up into segments that fit a specific rule (e.g., slope is in a certain range)
[/li][li]For each segment:
[/li][LIST]
[li]Try to put a start and end cap sprite on it (if they are set in the material).
[/li][li]Fill the remaining distance of the segment with randomly picked body sprites (you can define more than one in the material).
[/li][/ul]
[li]If the spline is closed, fill the interior with the interior sprite set in the material.
[/li][/LIST]

Notes for experimental version:
[ul]
[li]Terrain splines do not currently generate collision.
[/li][li]The filled interior option will not work in cooked builds, as it currently relies on an editor-only library and is not permanently stored.
[/li][li]Tight curves can currently cause overlaps in the generated geometry.
[/li][li]Sprites being deformed to the curve are not automatically subdivided, so you may want to create some extra internal detail in the sprite editor so they more closely fit the curve (be sure to check ‘Avoid Vertex Merging’ under the render geometry section in the sprite editor).
[/li][/ul]

Tile Maps
Tile map support is experimental and must be enabled from the Paper2D plugin settings; it is not ready for use, and is only mentioned here in case you want to experiment with it. There are no guarantees that content made with the tile map component will work in a future release, and there are known crash bugs when editing tile maps.

Once enabled, you can place a tile map actor using the placement mode in the editor. A tile map consists of a set of layers which contain a regular grid of tiles. Each cell in the grid can contain a tile from a tile set or remain empty.
Tile Sets split a texture up into a regular grid of sprites, and can be created from the content browser (New…Data Asset in the content browser, pick Tile Set as the type). There is no requirement that all tiles on a layer come from the same tile set; you can mix and match, but doing so will result in more draw calls.

Sprite Atlas Groups
This feature is not ready for use yet, but in the future it will allow automatic packing of multiple smaller sprites into one or more atlas pages with controls for padding, compression settings, etc…

2D Physics
There is an initial experimental integration of Box2D 2.3.1 and various associated changes to enable 2D physics in the engine. This is a totally unsupported and undocumented prototype, exercise great caution and do not use in production. The current build only includes precompiled libraries of Box2D for Win32 and Win64, so 2D collision will not work on other platforms. Collision detection and response is automatic when the 2D domain is selected in a sprite, but queries like point traces must be separately enabled in the Physics project settings (bEnable2DPhysics option).

The integration supports collision detection and response (including Unreal collision channels/filtering), rigid body simulation, and ray casts. Non-zero extent queries, sweep tests, and overlap tests are not implemented yet. Things like CharacterMovementComponent and MoveComponent with bSweep=true rely on these sorts of queries and don’t work correctly yet.

The long term integration strategy is to make it a first class citizen, where the same techniques and knowledge used in 3D scenes will directly apply to 2D scenes; for example, there’ll only be one Overlap event, not a separate 2D and 3D one. 3D raycasts are already implemented for Box2D and you can both trace ‘in-plane’ (gameplay traces within the 2D ‘world’) or ‘perpendicular to plane’ (things like the Touch input trace to determine the object under your finger / mouse cursor), providing a proper hit result location and normal as well.

[ATTACH=CONFIG][/ATTACH]13_TerrainActor.png14_TSplineAlt.png

Cheers,
Michael Noland

[reserved for more updates]

Wow…this looks great Michael. Nice work :slight_smile:

I agree, so far I’m loving the Paper 2D toolset and I’m really looking forward to seeing it fleshed out more and more!

-Will

Those terrain splines look rad. I hope they don’t get abandoned.

And sweet, JSON data import! Rather than using UE’s clunky tools I can let other friendly tools take care of everything.

Michael Noland for President!!!

Here’s a bit more info about the JSON importing:

Cheers,
Michael Noland

Please also let us know where the built-in editing is awkward / isn’t enough so we can improve it :slight_smile:

Cheers,
Michael Noland

Just a few suggestions after briefly testing editing collision/mesh…

Moving Points:
I kept trying to click and drag a point to move them, find it very “clunky” to have to select a point then move using gizmo.
really just drop the gizmo, if you need to constrain to an axis, just use a key modifier like shift while moving.

Adding Points:
Again, very “clunky” to select an edge then press insert. (also would help if the inserted point was selected if you keep this workflow)
It would be easier to use a key modifier when you click an edge to add a point at that position on the edge.
example -
ctrl + LMB = Insert point
ctrl + RMB = Delete point

Other Suggestions:
Sync the viewports - found it annoying having to zoom and pan when switching modes.

All good points! We’re hoping to improve the sprite editing soon and make it feel a lot more like other tools in the editor, with Alt+Drag to duplicate/insert a new point, gizmos working on initial click-drag instead of having to select them first, etc…

Cheers,
Michael Noland

So, Can we use this paper2d to draw ui in future?

It’s certainly possible but probably not the right tool for that job. UMG is going to be the recommended way to do game UI from inside the editor. We’ve talked about having a draw sprite to UCanvas and a SSpriteImage Slate widget as ways to render Paper2D geometry elsewhere (the advantages there are mostly the ability to more tightly define render geometry than Slate’s brush system allows natively), but nothing is set in stone right now.

Cheers,
Michael Noland

UMG feels far away so I’ve been using Paper2D for now. There are some advantages: all the animation functions I write for fading, scaling ect can be shared between the game and ui. It also saves me from having to switch gears with Canvas and my ui and game share the same coordinate system so I don’t need to think about both. I also wrote a base class for anchoring 2d sprites to handle device differences.

That said, my only concern is this might be less performant than other methods but everything seems ok so far.

Once UMG is mature I will want to switch to it for things like text input so it would be nice if there is support for sprites so my animation functions will work and materials. Hope you can make that in for UMG sooner than later!

Thanks

I couldn’t find where the option was to use a JSON file for use with extracting sprites. If I right-click a texture and choose “Extract Sprites” it just goes ahead instantly, there’s no option to choose a JSON file. Is it an automatic thing? Like if I have the file named the same as the texture in the same directory will it just use it? Or is there another mechanism to specify the JSON file to use? Thanks.

You can either use the Import button in the content browser or drag-drop a file from explorer into it to import a sprite sheet.

Cheers,
Michael Noland

. wrong topic sorry

Wrong thread maybe?

Cheers,
Michael Noland

Everyone, report his post. He is trying to advertising on our forum. Check his other posts, he is breaking forum rules.

Will flipbook have the sprites collision ?

I cant find a solution to get current sprites collisions used in flipbook

is there a way to get the sprite that is actually played on a flipbook? or to activate flipbook sprites collisions ?