Best Practices for Importing Unity Assets

2018-10-03,

Importing Assets into Unity Projects: 9 Best Practices

Importing a new Asset into Unity can be a bit of a hassle at times, but if you follow these 9 best-practices, you'll be saving yourself a LOT of headaches! 

At least 20-30% of the support requests we get from new users of our tools could be solved by following these simple importing best-practices.

So let's dive in.

1. Verify that your project is error-free

Before you start, make sure there are no compiler errors or runtime errors in your project. If you don't, this makes it harder to make sure that the asset is not causing any errors, and to distinguish errors caused by the asset from the ones in your project.

2. Make a backup!

If you use version control, commit your changes before importing any new asset. Otherwise, copy the complete project to another location.

3. Import into a clean project first

This allows you to check that the package works correctly with your version of Unity and that there are no errors. Although the Asset store team does not allow publication of assets that don't compile without errors, and they have a system to ensure version compatibility, some errors can still slip through the cracks, especially if it is caused by changes in minor versions of Unity.

If you get any errors, you need to investigate those first before you continue. Do not import a package that has errors into your main project!

Once the asset is in the clean project, you can also examine the folder structure. Make sure it is compatible with the project structure in your project. If there are overlapping folders, you may want to consider changing your main project's structure so that the asset will be easy to remove if necessary, and to avoid the possibility of conflicts.

A well-designed asset will clearly separate core functionality from demos, but make sure when you remove demo-material, you don't get any errors. You can add the demos again after the test.

It is also a good opportunity to run the demos of the asset and see if they run as expected. If they do, and you have problems later when importing the asset into your main project, it is a good clue that there is a compatibility problem. If they don't, you know it is a problem with the asset. Investigate why they don't work before importing into your project.

This project also serves as a place where you can look at demos, do tutorials and experiments, and access included documentation. This avoids cluttering up your main project, and reduce the risk of introducing errors in your main project while learning how to use the asset.

If you are a programmer, also check whether the classes are in a separate namespace. If they are not, it could be one cause of errors later on.

4. Import into your main project

After you imported the asset, look at the console and make sure there are not any errors. If there are, you should investigate those first. If there are no errors, run the demos and see if they work as expected. If they don't, you need to investigate that first.

5. What to do about errors in Step 3

In this case, the errors cannot be due to something you are doing or because of other assets in your project, and contacting the asset's support with the errors is your best option.

6. What to do about errors in Step 4

In this case, you know the asset works in a clean project, and something in your project prevents it from working properly.

A Step 4 error often indicates a conflict. The problem with conflicts is it is not clear where the responsibility lies until all the work has been done to determine what the issue is. Furthermore, there are cases where a problem with asset A causes an error in asset B.

To hone in on where the conflict lies, you will need to import assets one by one.

First, import the new asset into a clean project; then import the remainder of the assets one by one until you see errors. The first asset that gives errors will be the one that conflicts with the new asset. (You can now contact both asset developers, or try to drill down into the issue deeper.)

Once you determined what the cause of the conflict is, you can contact the relevant tool developer to ask for a fix or work-around.

7. Reporting errors and bugs to an Asset developer

In many cases, a developer cannot help you resolve an issue without enough information. There are a few things you can do to help get the issue resolved as quickly as possible.

  1. Provide the version of Unity, the version of the asset, and your build platform.
  2. If it is a Step 3 error, mention that you are getting the error in a clean project.
  3. If it is a Step 4 error, mention that it works in a clean project, but not when imported into your main project. Mention any other steps you have taken to isolate the issue and the results, and what other assets you are using.
  4. List the exact error(s). If you get more than a handful, list the first few. Often a screenshot of the console is sufficient. The developer may ask you for more information (such as a stack trace), but providing the exact errors already narrows down the possible issues.
  5. If you don't have any errors, but something is not working, the more detail you provide the better. A good model for reporting bugs is this: When I did X, I expected Y to happen, but instead Z happened. A common class of bugs is where nothing happens (which is often reported as "The asset does not work".) In this case, the format above is very helpful to the developer to nail down what may be going on. For example: When I clicked on an item, I expected the Item dialog to pop up, but instead, the dialog does not popup. With this report, the developer can now ask you a series of questions that can expose the issue.

8. Maintain a list of assets in your project

Although the folder structure of assets can help you keep track of which assets you have, it is sometimes difficult, especially when you are using more than one asset from the same developer or an asset uses a name that is not easy to recognize.

In reasonably sized projects it is a good idea to maintain a list of assets and their versions (a simple text file will do).

You may also want to consider exporting a package from step 3 that you can keep as backup. (The asset store does not allow you to download specific versions of assets, so if you need to use an older version it can be hard to find.)

9. Upgrading Assets

It is a good idea to follow the same steps (1 to 4) above when upgrading an asset. In this case, you face another source of problems, in addition to the ones you can get the first time you install an asset: errors and bugs caused by breaking changes in the asset. Most assets do not describe their changes well enough for you to know upfront, so the only way to know is to test it. If you follow the steps above, you will be able to isolate breaking changes from other issues; and be able to use the extra information to ask developers for help in case you need to.

It is also not always a good idea to keep all your assets up to date all the time, especially on complicated projects. I usually follow this upgrade strategy:

  1. Platform assets (such as Facebook SDK, Google Services etc.) typically have updates that reflect API or policy changes, so these need to be updated fairly frequently.
  2. I update Unity for a project every few months, as well as assets that provide core functionality to the project.
  3. Assets that have isolated functionality hardly have to be updated at all. I just keep on using them as long as they work.

 

Join the Devdog Community!

If you're interested in any of our tools or want to hang out with the rest of the community, head over to our Devdog Discord channel. Can't wait to see you there! 

Rucksack - Multiplayer Inventory System

Rucksack is the most flexible and extensible inventory solution with UNet support that enables you to easily setup player inventories, NPC inventories, banks, premium shops and much more!

Odin - Inspector and Serializer

Odin puts your Unity workflow on steroids, making it easy to build powerful user-friendly editors for you and your entire team. 

With an effortless integration that deploys perfectly into pre-existing workflows, Odin allows you to serialize anything and enjoy Unity with 80+ new inspector attributes, no boilerplate code and so much more! 

You May also Like

10:30
7 Things Every Game Developer Needs on Their Website

Prior to Devdog, I ran an online games industry news media for and about Nordic game developers for nearly two years.

During that time, I often reached out to new game developers directly, apart from interviewing the ones who sent a press release directly to me.

10:30
5 Ways to Identify if a Unity Asset is Worth Buying

A few weeks ago, we bought a Unity Asset that really let us down.

In developing our own assets, we spend a lot of time on the Asset Store, researching the market and getting inspired.

10:30
Taking Inventory Pro Item Collections To The Extreme

Item Collections in Inventory Pro are powerful collections that can contain items, stack, unstack, merge items and much, much more.

As we'll soon see, however, these features aren't only useful when creating a traditional RPG inventory system, but can be used in many aspects of your game. 

About us

We're a developer and publisher of best-in-class tools and asset for the Unity game engine. We develop and sell but also publish products like Odin for talented developers and artists around the world.

Subscribe