Jelly Sprites

Thank you for your purchase! Jelly Sprites is a easy to use soft body physics system for both Unity and 2D Toolkit sprites. Jelly Sprites use a set of rigid bodies linked by spring joints to influence the mesh of the sprite, thereby deforming and stretching the sprite as as the bodies react to forces in the world.

Support

If you have any problems, queries of feature requests regarding Jelly Sprites, please do feel free to contact me - I will always take the time to reply to every question, and try to help you in whatever way I can. Email is generally the fastest way to contact me.

Email: hughlowry@hotmail.com
Twitter: https://twitter.com/mr_square 
Unity Forums: PM mrsquare

Unity Asset Store reviews would be much appreciated if you feel that the package (and post-purchase support) has been of a suitable quality.

Creating a Jelly Sprite

In Unity, simply click Gameobject->Create Other->Jelly Sprite. You can now simply drag a valid sprite into the Jelly Sprite’s ‘Sprite’ field in the inspector, and it should become visible in the scene view.

2D Toolkit Support

2D Toolkit support is disabled by default so as to not cause compile errors for users that do not own 2D Toolkit. To enable it, simply extract the 2DToolkitJellySprites.unityPackage file (located in the '2D Toolkit' folder) into your project. Once done, an option to create a ‘2D Toolkit Jelly Sprite’ should appear in the Unity GameObject dropdown menu.

Detecting Collisions

Each Jelly Sprite is made up of multiple rigid bodies - when these rigid bodies collide with other bodies/triggers, they will pass messages up to the parent Jelly Sprite using the following functions:

	void OnJellyCollisionEnter(JellySprite.JellyCollision collision)
	void OnJellyCollisionExit(JellySprite.JellyCollision collision)
	void OnJellyCollisionStay(JellySprite.JellyCollision collision)

	void OnJellyCollisionEnter2D(JellySprite.JellyCollision2D collision)
	void OnJellyCollisionExit2D(JellySprite.JellyCollision2D collision)
	void OnJellyCollisionStay2D(JellySprite.JellyCollision2D collision)

	void OnJellyTriggerEnter(JellySprite.JellyCollider trigger)
	void OnJellyTriggerExit(JellySprite.JellyCollider trigger)
	void OnJellyTriggerStay(JellySprite.JellyCollider trigger)

	void OnJellyTriggerEnter2D(JellySprite.JellyCollider2D trigger)
	void OnJellyTriggerExit2D(JellySprite.JellyCollider2D trigger)
	void OnJellyTriggerStay2D(JellySprite.JellyCollider2D trigger)

These work almost identically to the standard Unity collision functions - simply implement one or more of them in any script attached to the Jelly Sprite GameObject, and they will get called whenever one of the child rigid bodies receives a collision/trigger message. The JellyCollision/JellyCollider objects that are passed as arguments contain both the original collision data, plus details on exactly which child rigid body reported the collision.

Jelly Sprite Inspector Settings

Sprite
The sprite to render

Use 2D Physics
Controls whether the sprite will use the Unity 2D or 3D physics system.

Attach Neighbors
By default, each Jelly Sprite rigid body is connected to the central rigid body only. Choosing the 'Attach Neighbors' option will also connect each body to its nearest neighbor, resulting in a stiffer, more stable Jelly Sprite.

Body Configuration
Changing the body configuration controls the physical layout of the Jelly Sprite rigid bodies and colliders. Some shapes may be more appropriate to certain sprites – for instance, you would generally want to use the circle configuration for a circular sprite in order for it to behave in a natural looking way. It is worth experimenting with the different options to see what works best – some shapes may also be more stable than others depending on your chosen gravity and spring stiffness values. The layout of the individual bodies will be shown in the scene view as green circles.

For each body type, you also have the option of converting to 'Free' mode, which allows you to manually tweak the positions of each body. The suggested workflow is to generate the basic configuration using one of the predefined shapes, then click the 'Copy Configuration To Free Mode' button, which will enable custom editing. Once in Free mode, you can alter body positions and radii in the scene view by clicking and dragging the individual bodies, and alter these values in the Jelly Sprite inspector window. The inspector also allows you to add and delete points.

It is worth nothing that when in free mode, all Jelly Sprite rigid bodies are connected to a central body – this is also true for the triangle, circle and rectangle configurations, and therefore 'Free' version of these shapes should behave identically to their fixed counterparts. The 'Grid' layout, however, uses a lattice style spring structure, which is not preserved when switching to Free mode, so the resulting Jelly Sprite'sbehaviour may be altered somewhat.

Collider Radius
This value controsl how large the rigid body colliders are, measured as a fraction of the overall sprite size. Shrinking the colliders can make shapes less stable and may also allow other rigid body object to pass through the Jelly Sprite. This may or may not be desirable depending on your project.

Collider Scale
This value can be used to stretch or shrink the overall shape of the soft body. Use this to tailor the shape to suit your sprite – eg. an elliptical sprite can be better modelled by simply squashing a circular configuration.

Lock Rotation
Chooses whether or not the Jelly Sprite should be allowed to rotate around the z-axis.

Kinematic Central Body
Allows the user to set the central point as kinematic, which will prevent it from moving and therefore can be used to prevent the Jelly Sprite from moving, or to suspend it in mid-air.

Sprite Scale
How large the actual rendered sprite is. In order to maintain stability of the soft body, you should scale the sprite using this value rather than using the usual transform scale values.

Control Point Influence
This slider controls how strongly each mesh vertex is influenced by the displacement of the physical bodies. Increasing the value will make the mesh deformation more accurately represent the soft body shape, but may also cause visual artefacts.

Physics Material
The physics material applied to each soft body collider. Use this to control friction or bounciness.

Drag/Angular Drag (3D physics mode only)
Controls the drag values of the colliders. Use this to make objects fall slower when in 3D mode

Gravity Scale (2D physics mode only)
Controls the gravity scale of the colliders. Use this to make objects fall faster or slower when in 3D mode

Spring Stiffness
Controls the stiffness of the spring joints that connect the individual bodies. If you find your sprite is collapsing under its own weight, try increasing the spring stiffness.

Spring Damping
The degree to which spring oscillation is suppressed.

Mass/Mass Type
Sets the mass of the soft body – this can be defined either on a global scale (so the mass of the entire sprite is equal to the mass value) or on a per body scale (so each component body will have this mass, meaning that the total mass will be equal to (Mass x Number of Bodies)

Mesh Vertex Density
Determines how many vertices will make up the visible mesh. Higher values may provide more smoothly deformed sprites, but with an increased performance cost.

Attach Points
Attach points allow you to attach child GameObjects to Jelly Sprites. The position of the child objects will deform correctly as though they were a point on the visible mesh. You can also attach Jelly Sprites to other Jelly Sprites - doing so sets the central rigid body of the child sprite to be Kinematic, so that the child sprite will track the position of the main sprite while still independently reacting to physical forces. You can also add Attach Points at runtime using the AddAttachPoint() function.

Scaling a Jelly Sprite

At runtime, you can use the Jelly Sprite’s Scale() function to dynamically scale the Jelly Sprite. 

Known Issues & Workarounds

Currently there is no way for scripts to manually prevent 2D colliders from interacting with each other (although this can be done with 3D colliders). Jelly Sprites rely on the individual  bodies in each sprite not being able to hit one another - for this reason, when running in 2D mode, each Jelly sprite must be placed in a layer that cannot collide with itself. This limitation has been raised with the Unity development team, and will hopefully be fixed by them in a future update.

Legal

All sprites and artwork included in the package are the property of Stuart Wood and may not be used in other projects without his prior consent.