.. image:: logo.png :width: 506px :height: 140px Shapes2D for Unity ****************** Thanks for using Shapes2D, a Unity asset for easily creating art assets in the Unity editor. You can use Shapes2D for creating PNG sprites, prototyping, game jams, UI, effects and more! Shapes2D is available in `the Unity asset store `_. Getting Help ************ Check out `the forums `_ or email oliver@sub-c.org. Follow me `on Twitter `_ for occasional progress updates. Features ******** - Extremely easy to use - Shapes can act as sprites or Unity GUI objects - Convert to Sprite button can turn shapes into a .PNG with one click - Multiple layered shapes can be collapsed into a single .PNG - Works with Unity GUI masking Shapes can optionally be used procedurally at runtime (see `Performance`_), meaning: - Shapes can be scaled up without becoming pixellated - Shapes can be modified/animated at runtime using the `Scripting API`_ Base shape types are: - **Circles/Ellipses** (with settings for donuts, arcs, pies and wedges) - **Paths** (made of quadratic Bézier curves, up to 32 segments, optionally fill closed areas) - **Polygons** (convex or concave, up to 64 vertices) - **Rectangles** (and rounded rectangles) - **Triangles** Customizations include: - Outlines - Blur - Gradient fills - Texture fills - Pattern fills (grids, stripes & checkerboard) Usage ***** After importing Shapes2D, go to ``GameObject->Shapes2D`` and choose one of the template Shapes. Once your Shape is created, you can tweak its various options from the Shape component in the Inspector. In the Shape component, sizes are typically specified in world units and outlines will keep the same thickness no matter how they are scaled. Unity GUI ========= To use Shapes2D with canvas game objects, just add a Shape component to them. In Unity, canvases may be scaled quite a lot to fit your screen, depending on your settings. That means the scale of units may be very different than when dealing with sprites (canvases do use world units, which is why they appear so huge in the editor, but they are scaled down by Unity at runtime to overlay your screen). So, you may have to scale values (like outline size) up quite a lot to get the same effect in a UI component as with a sprite. Anti-Aliasing ============= If you set blur to 0, Shapes2D will add resolution-independent anti-aliasing to Shapes so that they will look smooth regardless of scaling - essentially it is just modifying the blur value on the fly as you scale in and out. If you set blur to some value greater than 0, then blur is specified in world units and will stay fixed. Sorting ======= Shapes can act like sprites or UI components, and will obey the same sorting rules. For sprite-based Shapes, use the attached SpriteRenderer component to specify the sorting layer and order. For UI components, the parent canvas has sorting options and the children will render in the order they appear in the hierarchy. Convert to Sprite ================= To convert a Shape component to a sprite, press the "Convert to Sprite" button in the Shape component in the inspector. A PNG asset will be created in a folder called ``/Assets/Resources/Shapes2D Sprites``, and the object will be converted into a SpriteRenderer or Image, depending on the object. Any active child Shapes will also be combined into the PNG, allowing you to create complex layered Shapes. To revert the sprite conversion, either use Unity's Undo function or just re-enable the Shape component and any child Shapes. Sizing ------ Shapes2D defaults to 100 pixels per world unit to determine the size of the generated PNG, so if your Shape is 1x2 world units, a 100x200 pixel PNG will be created. However, for UI Shapes where the parent canvas is not in world mode, Shapes2D assumes the size in world units is already specified in pixels and just uses that value divided by the canvas's scaleFactor. You can change the pixels per world unit setting by going to ``/Shapes2D/Preferences`` in your Project pane (assuming you kept the default import location). Scaling UI ---------- For rectangular UI components, after converting to a sprite you may want to convert the resulting PNG into a 9-Slice so your component can scale without having its borders stretched. To do that, just select the PNG asset in the Project window and use Unity's Sprite Editor to bring in the borders a little (the green bars in the Sprite Editor). Hit Apply, and then change the Shape's Image component to have an Image Type of "Sliced". Now Unity will be able to tile the parts of the image outside the borders instead of stretching them. Performance *********** If you convert your Shapes to sprites, then Shapes2D has no impact on the performance of your game. However, before converting to sprite, Shapes are rendered on the fly using shaders, which is why they look so smooth when scaled up and can be changed at runtime via scripting. For simple Shapes like rectangles that isn't such a big deal, but for complex shape types like polygons and paths it can be really expensive. Lots of math has to be done for each pixel, so the size of the Shape on the screen matters. To make things worse, Shapes do not batch and require one Material per Shape. Changing any Shape properties via scripting causes properties to be re-sent to the GPU which is also a performance hit. Mobile in particular does not have very good performance, depending on what you're doing. Nevertheless, using the included Stress Test demo I am able to get 1000+ non-complex Shapes on-screen at once at 60fps on my MacBook Pro. Dynamically modifying Shape properties at runtime is slower, and I get about 500+ Shapes running at 60fps. On mobile, performance is much worse and I recommend testing on all target platforms before attempting to use Shapes2D procedurally. You should be able to get away with small numbers of non-complex shapes. If performance becomes an issue, a good workflow is to rapidly create Shapes when prototyping and then either "Convert to Sprite" or replace them with artist-created assets later. You should test on each of your supported platforms and decide if you can afford to use a procedural Shape or if you should replace prototype Shapes with sprites (or perhaps an animated mesh, for certain types of effects). Path Performance ================ Paths (even line paths) are the most expensive Shape type for performance, and I recommend always converting them to sprites unless you are very sure your target platform can handle it. The more segments you use, the more expensive rendering will be. If you do need dynamic procedural curves or paths at runtime, you might want to look into a vector solution which would convert your paths into a much more performance-friendly mesh. There are other assets on the Unity Asset Store for that! On mobile, performance for paths is very bad - convert them to sprites first! Polygon Optimization ==================== Polygon Shapes have an additional "optimized" rendering mode which can be selected via a checkbox in the Unity Component Inspector. Optimized polygons: - Are about as fast as the other Shape types, even on mobile - Are slow if you want to update their vertices dynamically via code (and slow to Instantiate) - Will render fine for most polygons but will show rendering artifacts if vertices are too close to each other, if vertices are too close to polygon edges, or if polygon edges intersect each other Non-optimized polygons: - Are slow in general, and slower the more vertices you have - Are very slow on mobile - Can have their vertices updated quickly - Should always render correctly If you intend to Convert to Sprite anyway, go ahead and leave your polygons non-optimized so you don't have to worry about rendering issues. Supported Platforms ******************* Shapes2D has been tested on OSX, Windows, iOS, Android and WebGL. For polygons and paths with high numbers of vertices, Shapes2D shaders may not compile for the ``Direct3D9 Graphics API``, meaning you should not target that platform if you intend to use complex shapes procedurally (converting to sprite is fine because the shaders aren't required at runtime). If you notice any problems with Shapes not appearing or appearing wrong, please `let me know `_! Scripting API ************* To modify Shapes from code, you can do things like this: :: Shapes2D.Shape shape = GetComponent(); shape.settings.outlineSize += Time.deltaTime; shape.settings.outlineColor = new Color(1, 1, 1, 1); etc... If you want to modify a Shape's attributes from your ``Start()`` method, you may need to add a call to ``shape.ComputeAndApply()`` to prevent a flicker of the Shape's initial attributes on the first frame. See below for customizable settings. API Documentation ================= Enums_ `The Shape Component`_ `UserProps (customizable settings)`_ Enums ----- .. doxygenenum:: Shapes2D::ShapeType .. doxygenenum:: Shapes2D::FillType .. doxygenenum:: Shapes2D::GradientType .. doxygenenum:: Shapes2D::GradientAxis .. doxygenenum:: Shapes2D::PolygonPreset The Shape Component ------------------- .. doxygenclass:: Shapes2D::Shape :members: settings, ComputeAndApply UserProps (customizable settings) --------------------------------- .. doxygenclass:: Shapes2D::Shape::UserProps :members: blur, correctScaling, endAngle, fillType, fillColor, fillColor2, fillOffset, fillRotation, fillScale, fillTexture, gradientAxis, gradientStart, gradientType, gridSize, innerCutout, invertArc, lineSize, outlineColor, outlineSize, polygonPreset, roundness, roundnessPerCorner, roundnessBottomLeft, roundnessBottomRight, roundnessTopLeft, roundnessTopRight, shapeType, startAngle, triangleOffset, usePolygonMap, polyVertices, pathThickness, pathSegments, fillPathLoops