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 - C++ - Epic Developer Community 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
- 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
- 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…
Details panel
This shows all of the editable properties of the opened sprite asset.
- 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.
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.
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.
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).
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.
Timeline
This displays all of the frames in the flipbook animation.
- 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.
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.
Cheers,
