_images/logo_large.png

v2.0.0


Unity Crash Course

RetroBlit offers a code-only development approach that is very unlike normal Unity development, however a very basic knowledge of Unity is still required to setup a RetroBlit project. This guide will help you get going in minutes!

If you’ve ever done anything in Unity before you will likely not need this guide at all.

Get Unity!

Download and install Unity from the Unity website. The minimum required version for RetroBlit is 2017.1.1, which is the version we’ll be using for the rest of this tutorial.

Unity is free of charge (as in beer, no credit cards, no royalities) so long as your annual income from your Unity projects (or related fundraising) is under a certain amount, a large amount at that. See the Unity website for up to date details.

When installing Unity you will be presented with a list of platforms you want to support, as well as other optional tools. You can change your installation at any time so don’t worry about making the wrong choice here. If you’re developing on a Windows machine I highly recommend you select Microsoft Visual Studio Community (free) as your C# code editor. You can use any editor you like, but with Visual Studio you will get create code completion and Debugging facilities, other Desktop platforms have similar solutions.

_images/unity_install.png

Create a RetroBlit Project

While setting up your first project you will require internet connectivity. Afterwards you only require internet connectivity if you want to update Unity and/or RetroBlit.

Launch Unity from your Desktop. The first time you launch Unity you will be asked to login with your account. If you do not have a Unity account yet you can create one now, or use a sign-in partner like Google or Facebook.

_images/unity_login.png

Once logged in you will see a list of tutorials or project templates. We’re not interested in any of these as they do not relate to how development is done for RetroBlit. Simply click New on top to start a new project.

_images/unity_wizard.png

Now select a 2D project, turn off Analytics (you can turn them on later if you want, but they’re out of scope of this guide), enter your project name and path, then click Create Project. Give Unity a few moments to create your new project.

_images/unity_newproject.png

The next screen will be your main Unity IDE screen. It may look overwhelming at first sight, but don’t worry, for RetroBlit we only need to learn a tiny subset of this IDE.

_images/unity_mainscreen.png

First lets add RetroBlit to this project. Click on Window->Asset Store to open up the Asset Store.

_images/unity_openstore.png

Now search for “RetroBlit”.

_images/unity_assetstore_search.png

RetroBlit should appear on the top of the search results, you may have to scroll down a bit past the search refining options to see it.

_images/unity_assetstore_searchresult.png

Click on RetroBlit Retro Game Framework and you should arrive on the asset page. Scroll down a bit and you will see either an Import button if you already own RetroBlit, and Update button if a new version of RetroBlit is available, or an Add to Cart button if you have not purchased RetroBlit yet. Once ready click the Import button to proceed.

_images/unity_assetstore_import1.png

A dialog should show up now warning you that RetroBlit is a Complete Project and will overwrite your existing project settings, we very much want this, click Import.

_images/unity_assetstore_import2.png

Finally Unity will show you what files it’s about to import, leave them all selected and click Import.

_images/unity_import_final.png

Great, you now have yourself a RetroBlit project! You can now close the Asset Store window by right clicking the Asset Store tab on top. From now on you will not require internet connectivity to develop your game.

A Unity project stores all its files in an Assets folder which you can see in the lower left corner of the IDE window. Unity projects are typically split into multiple Scenes, but for RetroBlit we only need one scene per project. To get started expand your Assets folder, and click on the Scenes folder. RetroBlit comes with a bunch of examples including a barebones Scene called MyGame, double click MyGame now.

_images/unity_selectscene.png

Now click the Play button on top of the screen and… that’s it! Your barebones RetroBlit game is running! If you don’t see the game make sure the Game tab is selected on the row just below the Play button.

_images/unity_play.png

From this point on you will mostly use the Unity IDE to click the Play button on and off, and view runtime logs!

Writing Code

To start writing code you can use Unity IDE to open the project in Visual Studio by clicking Assets -> Open C# Project, this option will also create the Visual Studio project if one doesn’t exist yet. You can also just double click a source file under the Assets folder (bottom left of the Unity IDE). Finally you can just directly open a source file from your project folder with any editor you like.

_images/unity_opencode.png

In this guide we’re using Visual Studio. Using the Visual Studio Solution Explorer expand the Assets/RetroBlit/Scripts/MyGame folder, and open the MyGame.cs file. The entire demo you saw earlier is contained in this file, have a look. For an explaintion of what is happening here please see The Game Loop.

_images/unity_code.png

Of course a project of any complexity would require more source files, you can add source files anywhere inside the Assets folder, so go ahead and organize your code how you like it.

Compiling Code

Compiling code is trivial! You don’t actually have to do anything, when you next click on the Unity IDE window it will scan your project for changed files and compile changed or new source files for you! If there is a compilation error it will be shown on the bottom of the Unity IDE window. Clicking the error will show the console, which may contain more details and other errors.

_images/unity_compile_error.png

The console is important because it will also show you warnings and logs. You can log to the console yourself:

UnityEngine.Debug.Log("Hi there!");
_images/unity_logging.png

It gets even better! Double-clicking any log line or compilation error will take you directly to that line of code in your code editor, granted that your code editor supports this level of integration.

Adding Resources

Adding resources is also very trivial. Simply put your images, sounds, music, and even tmx tilemaps into any folder in your project that descends from a folder named Resources. The Resources folder must itself be somewhere under the Assets folder.

MyGame example has its sprite sheet located at Assets/RetroBlit/Resources/Demos/MyGame/MySprites.png.

As with source file compilation any resource changes are automatically picked up by Unity next time the Unity IDE window is in focus. It’s worth noting that in a typical Unity application the user will want to edit specific resource import settings, but RetroBlit takes care of all of that for you, so you do not have to do anything else!

Debugging

Unity supports live debugging, which works great with Visual Studio, and some other editors. Simply set your breakpoints in your code editor, and attach to the Unity process. You may also attach to the Unity process before you press the Play button, which is great for setting breakpoints in your initialization code.

For Visual Studio specifically you may have to install Visual Studio Tools for Unity to debug Unity, but if you’ve installed Visual Studio via the Unity installer than you probably already have this plugin installed.

Deploying Your Game

This is where Unity really shines. Deploying your project to a wide variety of platforms is very simple! First go to File -> Build Settings.

_images/unity_build1.png

Select your target platform. If you don’t see your platform here you may have not installed support for it, just re-run the installer and select the platform from there.

Ensure your game scene is shown and selected in the Scenes in Build list. If it is not then you can simply click Add Open Scenes to add it.

Now you can just click Build and build your game with default settings, or you can customize the build by clicking Player Settings…

_images/unity_build2.png

From the Player Settings you can configure a myriad of options, such as game title, icons, splash screens, supported resolutions, portrait/landscape orientation (mobile), developer information, and more. For a final product you will likely want to fiddle with these settings, but meanwhile the default settings will do just fine!

_images/unity_build3.png

Demo Cleanup

RetroBlit comes with a number of examples and optional material that you may want to remove to reduce the size of your project. You may delete any of these folders:

RetroBlit/Docs

RetroBlit/Resources

RetroBlit/Scenes

RetroBlit/Scripts/Demos

RetroBlit/Scripts/MyGame

Of course if you continue building on top of the MyGame example then make sure you move its files to somewhere else before you delete RetroBlit/Scripts/MyGame, RetroBlit/Scenes, and RetroBlit/Resources/MyGame!

Other Tips

Because RetroBlit doesn’t use most of Unity IDE you may want to select the option Maximize On Play so that your game window fills more of your screen. Also notice that there is a Scale slider that can resize the game window. If this slider is not at 1x then what you’re seeing will be scaled up/down and may look distorted.

_images/unity_max.png

You may want to test your game on different resolutions to see how it would look. You can select an existing resolution from the drop down, or enter your own custom resolution.

_images/unity_res.png

You can enable a Stats overlay that will show you some performance metrics for your game, including frames per second.

_images/unity_stats.png

From Window -> Profiler you can open the Profiler which can give you quite a bit of insight into where your game may have performance issues. I suggest reading more on the Profiler online to learn how to best get useful information out of it.

_images/unity_profiler.png

Getting More Help

Unity has another great advantage, it is extremely popular! If you run into any issues with it just search online and you’re bound to find an answer quickly!