wobbledoll - Asset Documentation

Quick Start

Installation

    .1Import the package into Unity. It will appear in Assets/wobblewares/Nesting Doll
    .2Drag the Nesting Doll from the Assets/wobblewares/Nesting Doll/Core/Prefabs folder into the scene. Feel free to add more than one doll and change their size and materials.
    .3In the inspector for the first doll's NestingDollBottom, drag the second doll's bottom into the Current Nest field to automatically make one doll nest inside the other.
    .4You can now use the provided methods on the NestingDollTop and NestingDollBottom components (i.e Attach, Detach, Nest and LeaveNest) to control the Nesting Dolls behaviour.

For Universal Render Pipeline (URP) support, you must unpack the .unitypackage files located inside Assets/wobblewares/Nesting Doll/ and Asssets/wobblewares/Kit/ (for samples)

Samples

The included samples can be used as reference for how to use specific functionality of the Nesting Dolls. The samples are located in Assets/wobblewares/Nesting Doll/Samples. Note that the samples utilise wobblekit (a free lightweight vfx package) which can be deleted if the samples are not required.

Switch to Linear colour space for best visual results in the sample scenes!




Compatibility

Unity Version & Platforms

Tested in Unity 2022.3.37f1 LTS on Mac but is simple enough to work on most recent Unity versions on all platforms.

Render Pipeline Compatibility

The asset is provided with basic materials, prefabs and sample scenes for both the Built-in pipeline and the URP. Don't forget to unpack the URP.unitypackage located inside Assets/wobblewares/Nesting Doll/Core for URP support. 

Basic wobbly toon materials and VFX have also been provided for both pipelines through the included wobblekit package and are utilised in the provided sample scenes.

No Dependencies

No external dependencies are necessary. The asset can be imported into a vanilla Unity project with no problems.


Configuration

The core of the asset is the prefab located in Assets/wobblewares/Nesting Doll/Core/Prefabs/. This prefabs consists of an empty GameObject with two children (Top and Bottom). Each child has a Rigidbody, Mesh Collider and Audio Source component attached..

A lower-poly convex MeshCollider is included for collisions. This can be replaced with your own collider (eg. a BoxCollider approximating the doll shape) if desired.


NestingDoll/Top

The NestingDollTop component can be used to specify which bottoms can be attached with and the audio clips played during attach and detach events.

Attached Bottom - Assign a NestingDollBottom in the inspector to automatically attach them at runtime.
Restriction - Controls which Bottoms this Top can be attached to. The available options are:
  • AllowAny - This top can be attached to ANY bottom with no restrictions.
  • BasedOnSize - This top can be attached to bottoms with a similar size, configured using Maximum Size Difference.
  • Manual - This top can only be attached to bottoms which have a Compatibility Id that exists in the Compatible Bottoms list.
Maximum Size Difference - The maximum difference between this Top and a target Bottom before attachment is restricted. This is only used when Restriction is set to BasedOnSize.
Compatible Bottoms - The list of ids representing the Bottoms that can be attached. This is only used when Restriction is set to Manual.
Audio - Configure AudioSource and AudioClips used to play audio when the Top is attached and detached.



NestingDoll/Bottom

The NestingDollBottom component can be used to specify which bottoms can be nested within one another and the audio clips played during Nest and LeaveNest events.

Current Nest - Assign a NestingDollBottom in the inspector to automatically nest them at runtime.
Shrink When Nested - Should this bottom shrink to match its nest.
Allow Nesting While Incomplete - Can this bottom be nested even when it has no attached top.
Restriction - Controls which bottoms this top can be attached to.
  • AllowAny - This bottom can be nested with any other bottoms
  • BasedOnSize - This bottom can be nested inside bottoms with a similar size, configured using Required Space In Units
  • Manual - This bottom can only be nested inside bottoms which have a Compatibility Id that exists in the Compatible Nests list.
Compatibility Id - The id of this Bottom used when defining Compatible Nests and Compatible Bottoms.
Compatible Nests - The list of ids representing the Bottoms this bottom can be nested inside. This is only used when Restriction is set to Manual.
Required Space In Units - The required size of any target bottom before nesting is allowed. This is only used when Restriction is set to BasedOnSize.
Audio - Configure audio source and clips used to play audio when the bottom is nested and removed from nests.



Functionality

The following functionality is supported:

  • Attach a top to a bottom
  • Detach a top from a bottom
  • Nest a bottom inside another bottom
  • Remove a bottom from a nest
  • Check if a Top can be attached to a specific Bottom
  • Check if a Bottom can be nested inside another Bottom
  • Listen to events OnNest, OnLeaveNest, OnTopAttached and OnTopDetached

Physics Movement & Collisions

The asset uses a Rigidbody for all physics based interactions. When the Top and Bottom are detached, they both have their own active Rigidbody. However, when a top is attached to a bottom OR a bottom is nested inside another bottom, the individual rigidbodies on each part are removed and all physics is controlled by the outermost bottom.

Rigidbodies are currently removed and re-added at runtime when attaching or nesting. This means that you are currently unable to configure rigidbodies in the inspector as their properties will be reset when attaching or nesting.


Events

All events can be subscribed to via the NestingDollBottom component. Note that the NestingDollTop component does not invoke any of its own events as all interactions require a Bottom.
Listen to the OnNest and OnLeaveNest actions to be notified when a bottom is inserted or removed from a specific bottom.
Listen to OnTopAttached and OnTopDetached to be notifed when a top is attached/removed from a bottom.


VFX

The Nesting Doll prefab uses a Standard Unity material with basic UV unwrapping and has a single diffuse texture. A UV layout texture is also provided with the package to use as reference to create your own designs.



SFX

Custom sound effects have been provided for attachment and nesting of the dolls. Swap them out with your own sound effects in the NestingDollTop and NestingDollBottom inspectors.


FAQ

How do I attach/detach tops and bottoms?

If you would like the top to automatically start attached to the bottom at runtime, assign the desired bottom into the Attached Bottom field on the NestingDollTop inspector. 
Otherwise, at runtime use the methods Attach and Detach on the NestingDollTop component.

How do I nest dolls inside eachother?

If you would like dolls to begin nested inside eachother, use the Current Nest field on the NestingDollBottom inspector. This field will automatically nest the configured doll inside the Bottom specified in the field. You can chain multiple dolls by nesting their respective bottoms in the order you desire. See sample scenes for an example of the most common configuration.

You can also nest dolls inside one another using the Nest and LeaveNest methods on the NestingDollBottom inspector.

How can I configure which dolls can attach / nest with eachother?

By default, Nesting Dolls are able to nest inside any other doll. You can configure this behaviour on both the NestingDollTop and NestingDollBottom inspectors by setting the compatibility Restriction type. Setting the type to Based On Size will provide expected behaviour where tops can attach to bottoms of a similar size and smaller dolls can nest inside larger ones.

If you need to manually control compatibility, use the the restriction type of Manual and specify compatiblity ids. For example, to allow the red Nesting Doll to nest inside the blue nesting doll, set the Compatibility Id field on the blue doll's NestingDollBottom to a unique identifier (eg."blue") and add "blue" to the Compatible Nests list on the red doll's NestingDollBottom.


Licensing

  • You can use this asset in personal or commercial projects
  • You can edit the assets freely, but cannot repackage, resell or redistribute them in any way.
  • No credit required, but you can provide a link to  https://wobblewares.com  if you want!

Contact  ian@wobblewares.com  if you need more information.