2D ColliderGen Documentation - Orthello

Video Tutorial

Orthello Tutorial Video

General Workflow

When using the Orthello framework, the workflow is centered around adding AlphaMeshCollider components to your game objects which will generate the MeshColliders. At these components you can tweak parameters such as the number of outline vertices, convexity of the mesh, etc.

Please take a look at the reference section below for further information on all parameters or watch the video tutorial which demonstrates the effect of the different parameters.

Steps

  1. Add 2D sprites to the scene.
    We assume that you already know how to add and set up 2D sprites.
    If you are not familiar with the Orthello framework yet,
    we recommend to check out the documentation of these great packages first.
  2. Prepare movable game objects by adding Rigidbody physics components to them.
    Without Rigidbody components, your objects will remain static.
  3. Select all objects that you wish to add a generated MeshCollider to.
  4. Choose “2D ColliderGen” – “Add AlphaMeshCollider” from the menu bar.
    Colliders will be generated automatically.
    An AlphaMeshColliderRegistry object is automatically added to the scene
    which keeps track of all AlphaMeshColliders and offers convenient access.
  5. Select objects where you are unhappy with the collider shape and tweak the “Outline Vertex Count” parameter
    of the AlphaMeshCollider component.
  6. The movable objects don’t collide with other MeshCollider objects yet -
    one of two colliding MeshColliders needs to be declared “convex” to enable
    collision testing:
    1. Select the movable objects and tick “Force Convex” at the
      AlphaMeshCollider component.
    2. Tick “Convex” at the MeshCollider component.
      Now they are ready for collisions.
  7. When using an OTSpriteBatch (Orthello Pro framework only):
    Make sure to untick “Deactivate Sprites” at the OTSpriteBatch component,
    otherwise the MeshColliders will be disabled at runtime.

You are done – enjoy physics.

Reference

Menu Entries

The 2D ColliderGen package adds a 2D ColliderGen menu to the Component menu where you will find the following menu items:

Menu Entries

Menu Entries

2D ColliderGen Menu

  • Add AlphaMeshCollider: Add an AlphaMeshCollider component to all selected game objects. Default parameter settings can be modified via the Collider Preferences window.
  • Select AlphaMeshCollider Children: Select all child game objects (recursively) that have an AlphaMeshCollider component attached.
  • Remove AlphaMeshCollider Components: Remove 2D ColliderGen components from all selected objects. This includes AlphaMeshCollider and MeshCollider components as well as AlphaMeshColliderSmoothMovesRestore components which are added to animated SmoothMoves objects.
  • SmoothMoves Specific – Add AlphaMeshCollider To BoneAnimation (SmoothMoves only): Add an AlphaMeshCollider component to all child game objects that correspond to a bone in the BoneAnimation hierarchy. This way you can quickly add colliders to an animated SmoothMoves character.
    Ignore this menu entry if you are using the Orthello framework.
  • 2D Toolkit Specific – Show ColliderGen TK2D Window (2D Toolkit only): Open the ColliderGen TK2D window which integrates 2D ColliderGen functionality with the 2D Toolkit Sprite Editor. The 2D Toolkit Sprite Editor window automatically show up when the ColliderGen TK2D window is open. In order to close the Sprite Editor window you have to close the ColliderGen TK2D window first.
    Ignore this menu entry if you are using the Orthello framework.
  • Collider Preferences: Open the collider preferences window where you can setup default collider parameter values.

AlphaMeshCollider

In order to automatically generate polygon colliders for a sprite game object, you add an AlphaMeshCollider component to it which calculates the collider based on the sprite image’s alpha channel. The colliders are created within the Unity3D editor and therefore add no additional performance cost at runtime.

The AlphaMeshCollider component provides a number of parameters such as the number of outline vertices, convexity of the mesh, etc. It also supports multi-object editing, so you can select multiple objects at once and tweak their colliders simultaneously.

There is a menu item “2D ColliderGen” – “Add AlphaMeshCollider” to add AlphaMeshCollider components to all selected objects.

AlphaMeshCollider components provide the following parameters in the inspector:

EditorAlphaMeshCollider

AlphaMeshCollider Inspector View

  • Texture Image: The texture currently used for collider calculations (Read-only). In order to use a custom image you can set the Advanced Settings – Custom Image parameter.
  • Texture Width x Height: The resolution of the texture image.
  • Editor Live Update: Update the collider immediately when changing any values. Disable live update if your computer is too slow to smoothly update the collider and hit ‘Recalculate Collider’ manually instead.
  • Alpha Opaque Threshold: Alpha threshold value in [0..1] above which a pixel is treated as opaque and thus contributes to the outline shape.
  • Outline Vertex Count: The point count of the collider shape. Note that if your sprite image has fewer corners (e.g. a box with only four corners) it will not spend unnecessary vertices.
  • Z-Thickness: Thickness of the generated collider along the z-axis. Note that this value is further scaled by the Transform component of the Gameobject using it. We recommend setting the Tansform.scale.z values to 1.0 at all sprite Gameobjects and scale them along the x and y axis only.
  • Collider Type: Used to switch the generated collider between MeshCollider and PolygonCollider2D. Switches between attached Rigidbody and Rigidbody2D Components as well while preserving rigidbody attributes as well as possible.
  • Copy OTSprite Flipping (Orthello only): Copy the ‘Flip Horizontal’ and ‘Flip Vertical’ parameters of the OTSprite component.
  • Flip Horizontal: Flip the collider horizontally. Note that this parameter is hidden if ‘Copy OTSprite Flipping’ is ticked.
  • Flip Vertical: Flip the collider vertically. Note that this parameter is hidden if ‘Copy OTSprite Flipping’ is ticked.
  • Force Convex: Creates a convex collider. Useful for objects which shall collide with other mesh colliders. If this is a requirement, tick ‘Convex’ at the MeshCollider component, too.
  • Flip Normals: Flips the normals inside-out.
  • Output Directory: The collider mesh is saved as a collada (.dae) file to this directory.
  • Group Suffix: When multiple Gameobjects share the same sprite image, the collider is created only once and loaded from disk for the other instances. In order to create two unlinked collider-versions for the same sprite image (e.g. a precise and a more approximate version) you can specify two different group suffixes here.
  • Output Filename: The name of the generated collada mesh file (Read-only).

Advanced Settings

  • Custom Image: Set a custom image to be used for collider calculations instead of the normal sprite texture.
  • Custom Rotation: Rotates the collider around its center.
  • Custom Scale: Scales the collider from its center.
  • Custom Offset: Translates the collider. An offset of 0.5 translates it by half the image size.
  • Button “Reload Collider”: Reloads the collider from disk without recalculating it. See ‘Output Directory’ and ‘Output Filename’.
  • Button “Recalculate Collider”: Recalculates the collider from scratch.

Custom Texture Region

  • Use Custom Region: If enabled, a custom region will be used for collider computations instead of the whole texture image. Can either be used to crop unwanted pixels or access regions of a custom atlas texture.
  • Position: Position of the crop-rectangle in pixels relative to the top left corner.
  • Size: Width and height of the crop-rectangle in pixels. Will automatically be clamped to the screen borders in the inspector if position + size would exceed image size.

Holes and Islands [number of enabled islands] [total number of vertices]

  • Island/Hole [n]: Whether to enable the island or hole with zero-based index n. Islands and holes are sorted by size in pixels. Note that the outermost hole (Hole with index 0) corresponds to the image borders most of the time.
  • Outline Vertex Count: The point count of the island or hole. Note that if your island or hole image has fewer corners (e.g. a box with only four corners) it will not spend unnecessary vertices.
  • Force Convex: Creates a convex collider at the island or hole. Useful for objects which shall collide with other mesh colliders. If this is a requirement, tick ‘Convex’ at the MeshCollider component, too.

AlphaMeshColliderRegistry

As soon as at least one AlphaMeshCollider has been added to the scene, an AlphaMeshColliderRegistry object is automatically added to the scene. It displays an overview of all different collider groups and provides convenient access to each of them.

The AlphaMeshColliderRegistry displays as follows in the inspector:

EditorAlphaMeshColliderRegistry

AlphaMeshColliderRegistry Inspector View

  • Collider Groups: The number of collider groups in the current scene.
  • floating_rock2_37EC32C0.dae [20 vertices] 4x
    • floating_rock2_37EC32C0.dae: Collider file name.
      Composed of: the image name, a unique-identifier, optional flipped horizontal/vertical suffixes and the collada .dae extension.
    • [20 vertices]: Number of outline vertices of the collider.
    • 4x: Number of game objects in the collider group which share the same AlphaMeshCollider.
  • Collider Mesh Path: Path of the collada mesh file.
  • Outline Vertex Count: Number of outline vertices of the collider.
  • Mesh: A link to the collider mesh as loaded from the collada file.
  • Instance <number>: A link to each object in the collider group which uses the same instance of the AlphaMeshCollider.
  • Button “Select Instances”: Hit this button to select all objects which use the AlphaMeshCollider listed above.
  • Button “Select All Instances”: Hit this button to select all objects that have an AlphaMeshCollider component attached.

Collider Preferences Window

In this window you can modify the default values of some parameters.

Collider Preferences Window

Collider Preferences Window

  • Collider Directory: Set the default output directory for generated collider mesh files (collada .dae files). Ignore this parameter if you are using 2D ColliderGen with the 2D Toolkit framework – the 2D Toolkit Sprite Editor stores the generated collider meshes differently.
  • Live Update: Update the collider immediately when changing any collider-parameters. Disable live update if your computer is too slow to update the collider smoothly and hit ‘Recalculate Collider’ manually instead.
  • Outline Vertex Count: Default point count of the collider shape. Note that if your sprite image has fewer corners (e.g. a box with only four corners) it will not spend unnecessary vertices.
  • Vertex Count Slider Max: Maximum value of the outline vertex count slider.
  • Z-Thickness: Default thickness of a collider. Ignore this parameter if you are using 2D ColliderGen with the 2D Toolkit framework – the 2D Toolkit Sprite Editor uses its own custom thickness.

Orthello Documentation

For questions about the Orthello framework, visit the official Orthello documentation page here: