Get Me Started

Documentation

Table of Contents

1. What is Get Me Started?
2. Feature Set
3. Installation
4. Editor Tools
5. Basic Code Layout
6. How to load a scene
7. Creating a new scene
8. Adding scenes
9. Adding a new manager to the LibraryPrefab
10. How the HUD works
11. How to create a new Loading Screen
12. How Localization works
13. Adding new localized strings to your game
14. How saving/loading XML works
15. How the Credits work
16. Screenshots
17. Removing the XML features
18. Removing Localization
19. Removing Example Scenes
20. Shaders
21. 3rd Party Attribution
22. About the Author

1. What is Get Me Started?

Have you ever had an awesome game idea and started to work on it only to be faced with the prospect of writing the boring initalization code?  Did you quit in frustration because you just wanted to get started making the "game" part of your game?  Now you don't have to worry about that because Get Me Started does the necessary, but boring parts for you.

Get Me Started is a collection of scripts that form a basic structure to help you code any type of game while trying not to affect your code as much as possible.

2. Feature Set

• Built for Unity 5 in C#
• Run your game from any scene
• Custom loading screens with progress bars
• Asynchronous loading of scenes
• Fading logo scene on startup
• Basic main menu with settings dialog box
• Built in language localization
• Localizable Images
• Separate Music and Sound Effects tracks
• Independent Sound Effect/Music volumes
• In-Game Image quality adjustments
• Pause dialog with settings adjustments
• Basic one button dialog box
• Yes/No question dialog box with custom button text.
• Achievements dialog that slides in and out.
• Per Scene Heads Up Displays (HUD)
• Save/Load public variables to XML using XML Serialization.
• Central location for Don't Destroy scripts to manage game functionality
• Screenshot class that takes high quality screenshots.
• Scene name enum which can be updated to match the build settings with the click of a button.
• General purpose uGUI based dropdown box. (Until a Unity supported one comes out)
• Extensible credits screen
• Customizable Developer "Cheat" dialog
• Developer HUD with 4:3 safe zone markers and FPS display
• Bullet Time
• Two colour particle shader (Additive & Alpha)
• One colour plus white particle shader (Additive & Alpha)
• General purpose 10m x 10m x 12 foot tall room with one sided separated walls for prototyping
• General purpose power of two grid textures from 32x32 to 2048x2048
• A right-angle triangular prism model 1m x 1m x 1m in size
• Average height male mannequin
• Average height female mannequin
• Generic coin mesh
• Generic spike ball mesh
• Handgun mesh
• Banana mesh
• Turtle shell mesh

3. Installation

If you're starting a new project, installation is relitevely simple:

• Select  Assets -> Import Package -> Custom Package...
• Select the Get Me Started unity package file.  Everything will be placed in \Assets\GMS\ so you're safe to import all the files without messing up an existing project.
• Once imported there will be a new sub menu under Edit called GMS\

Edit -> GMS -> Setup New GMS Project

• Check the build settings to see if it worked File -> Build Settings...

The Get Me Started scenes will now populate the first few slots in the "Scenes In Build" list box.  Double check to make sure that Start is the first scene.  If the order of the scenes is a little off, incorrect scenes may load.

• Edit -> GMS -> Update Scene Enum

This makes sure that the Scene Enum matches the build settings.

• Open the Start scene and press play.

Note: You will get a Debug.Log message when you first run Get Me Started because a Library XML file has not been generated.  If you open the Developer dialog (~ key) and select Save Library XML, it will go away.  Alternatively, you can remove the XML classes from your project to get rid of it.

4. Editor Tools

• Setup New GMS Project - Located in the Edit menu under GMS this function adds the scenes in the current project to the Build Settings list and sets the project to start on the Start scene with the company logos.  If you are starting a new project, use this after you import the Get Me Started unitypackage.
• Toggle Developer Mode - Turns the Developer Mode compiler option on and off.  Turning this mode on gives you access to the Developer Dialog (The one you get by pressing the ~ key).  When you're building your final game, you will want to make sure this is off.

What this script is doing behind the scenes is adding a compiler option to Edit -> Project Settings -> Player, in the "Scripting Define Symbols" textbox called "DEVELOPER"

• Update SceneEnum - The Scene names and numbers are stored in an enum called SceneEnum and can be used to load a level.  However, they have to remain in sync with the Scenes in the BuildSettings.  You cannot access the BuildSettings information in a released game (as of April 2015).  This option adjusts the enum line in SceneEnum.cs to make things easier to keep track of.

5. Basic Code Layout

Every scene has a GameObject with a SceneManager script attached.  This class will initialize everything else.

The first task of the SceneManager is to instantiate the Library (Lib) prefab located in the resources folder.  

The Library, when spawned gets the DontDestroy script applied to it so that it's never deleted during the course of the game.  It's a regular prefab that you can access in the Resources folder and are encouraged to add any scripts your game may require.  The provided Library comes with a number of scripts already attached, such as the LocalizationManager to make sure that your game will work in multiple languages and the XMLManager which adds the ability to save data out to XML files.  Drag the prefab into the Hierarchy window and take some time to explore its scripts.

The SceneManager also works with the library to load a unique heads up display (HUD) in every scene.  If the HUD is the same between multiple scenes, it will keep the existing one.

6. How to load a scene

A static function in the Scene class called Load is provided to load a new scene.  It accepts either a SceneNames enum or an integer, which corrisponds to the Scenes number in File -> Build Settings...

Call it at any time and it will load the active loading screen (if there is one), and asynchronously load the level.

If your game needs multiple loading screens, there is Lib.Instance.LoadingScreens.SetActive(), which allows you to switch between them at any time.  Creating a new loading screen is done by copying the formatting provided by one of the existing ones with your own unique images.  They can have a spinner, a progress bar or a static image.

7. Creating a New Scene

• Select File -> New Scene
• File -> Save and name the scene.  e.g. MyNewScene
• GameObject -> Create Empty
• Name the GameObject something useful.  Giving it a name that is the same as your scene (MyNewScene) will let you know what scene is loaded by glancing at the hierarchy while the game is playing.
• Add the SceneManager script component.
• Select File -> Build Settings..., and press "Add Current" to make sure that the scene will be built with the rest of the project.
• Edit -> GMS -> Update Scene Enum   This updates the SceneNames enum to match the Build Settings scene list.  Now you can reference levels in your game by name instead of using the scene number.  e.g. RootManager.Instance.LoadLevel(SceneNames.MyNewScene);

That is all that is required, if you hit play, the root manager and Library will be available.  Any other scripts that you add will vary from game to game.  Here is a list of some scripts that are included that you may want to add:

• Heads up displays (HUD) can be added by dragging a prefab into the HUD slot on the SceneManager script.  A HUD is any GameObject with a script that inherits HUDBase.  If one is present, the SceneManager will load it when the scene is loaded.  See the "How the HUD works" section for more information.
• If you want music in your scene add the SceneMusic script and place songs in the Clips list.  One will be chosen at random when the scene loads.  For the SceneMusic to work you will also need to add an Audio Source component to the scene GameObject and set its spatial blend to 2D.  If you want more control over the music, open this script up and start modifying it, or just use it as a guide and make a new script.
• Add the SceneXML Component to save out scene data to an XML file when the level unloads and to have it load when it starts back up again.  It will save any Component attached to the game object which inherits from the MonoBehaviourXML script.  See ExampleXMLClass.cs for an example of this.
• Adding the SceneWelcomeMessage Component will use the HUD's Center Print functionality to display the level name for the first few seconds after the level is loaded.
• Add AutoLocalize and it will attach the LocalizeText script to every child Text component. It uses the text in the field as the lookup string in the Language class.

8. Adding Scenes

Adding a scene to the game isn't that hard, just a couple steps and you will be able to access it using an enum.

• Open the scene you want to add to the game.
• File->Build Settings..., Add Current
• Edit->GMS->Update Scene Enum

9. Adding a new manager to the LibraryPrefab

• Drag the \Resources\LibraryPrefab into your scene.
• Add your new Manager script to the component list in the inspector.
• Click Apply.
• Delete the prefab from the scene.
• Save the scene to write the prefab changes to disk.
• Open Lib.cs
• Find the list of public varables and add your new manager to the list.

  [...]

public DeveloperManager Developer;

public MyManager mMyManager;

• Go into the Awake() function and make sure that the component is hooked up when initalizing.

  [...]

  mDeveloper = GetComponent<DeveloperManager>();

  mMyManager = GetComponent<MyManager>();

• Save the file and any time you will be able to reference the public functions in this class by typing Lib.Instance.MyUniqueStuff.MyFunction();

If Lib.Instance.MyUniqueStuff is ever null, that means that it isn't part of the LibraryPrefab (e.g. if you removed the XMLManager, it won't be able to get the XMLManager component and be null).

10. How the HUD works

All of the HUD's in game inherit from HUDBase a basic class.  The GameObject is typically a uGUI Canvas with a HUD component added although that isn't a requirement.

The SceneManager has a slot that accepts a link to a HUD Prefab and if it is populated, when you play a scene the HUD will automatically load.

If you want any HUD text localized, remember to add the AutoLocalize script and all of the child Text fields will switch languages.

11. How to create a new Loading Screen

Creating a loading screen is fairly simple and you can make any of the standard types.  Static, with a spinning animation, or with a progress bar.

• Create a UI Canvas object.
• Set the sort order to 1000.  This puts it above all HUD's, dialog boxes, etc that are used in your game.
• If you want your image to remain a constant height, but have the edges clipped when the game is played on a 4:3 monitor (e.g. an iPad vs the 16:9 iPhones) then you will want to change how the canvas scales its contents.  There are different ways to setup the canvas, but one way of doing this is to set the "Ui Scale Mode" to "Scale with Screen Size", set a refrence resolution to something that is 16:9 resolution, for example 1136x640 or 1920x1080.  Set the "Match" sider to 1 (Height) and now all screen aspect ratios will use the height of the canvas and dynamically clip the sides depending on the monitor.
• Add a Canvas Group component.  This is adjusted by the Animator component to fade the canvas and all of its children out as one group.
• Next add an Animator component and set it to use the "Loading Screen" animations.  This handles the fade in and fade out.  You may want to duplicate this Animation Controller and create custom animations for this specific loading screen.
• To make sure the loading screen always fades in, even if the game is paused, set the animations "Update Mode" to "Unscaled Time."
• Add the Dont Destroy component script to the canvas object.  This makes sure that it sticks around while the current level unloads.
• Add the Loading Screen script component.  This script receives a callback from the RootManager when the loading of the level has completed and triggers starts the loading screen fade out animation.
• If you want a progress bar, add a UI Slider component to the canvas and set it to not interact-able.
• Drag a reference of the slider onto the Loading Screen scripts Progress Bar slot.  It will automatically recieve and update the progress information.
• Create a prefab for the new loading screen and drag the canvas into it.
• Delete the canvas from the current scene.
• Save the scene to write out the prefabs information to disk.
• Open up the LibraryPrefab and scroll down to the Loading Screen Manager.
• Increase the Prefabs array size by one and add your new loading screen prefab to the list.
• In your code, find a spot where you no longer want to start using this loading screen (This could be the main menu, or at the end of level 1, etc).  Call Lib.Instance.LoadingScreens.SetActive(index); where index is the index of the loading screen that you just added to the list.

The next time you load a level, you should now see your new loading screen.

12. How Localization works

On startup the LocalizationManager in the Library will read in all of the Language text files included in LocalizationManger's list.  It then looks in the PlayerPrefs to see what the active language is, and copies the strings into the static string fields of Language.cs.

When you change languages in the settings dialog, the Language.cs strings are overwritten with the translated ones and OnLocaleChanged() is broadcasted to every GameObject that has been loaded.  Scripts that include this function are then able to update their text fields with the proper language.  In practice, the LocalizeText and LocalizeImage components already handle this, so you don't have to do anything, unless you're extending the functionality.

If you include the AutoLocalize script on a top level GameObject, on Start() it will add the LocalizeText component to any GameObjects with a Text component attached.  It then uses the text in the text field as the lookup name in Language.cs.

If you want to exclude a specific Text component from being automatically localized, add the DontLocalize component to it.  It's an empty class that AutoLocalize looks for when it is iterating through all of the Text components.

13. Adding new localized strings to your game

• In Language.cs add a new public static string to the long list of static strings.

public static string Fantastic;

public static string MyLocalizedString;

• In "Lang English.txt" add your string

MyLocalizedString=My Localized String in English

• In your text field, set the text value to MyLocalizedString
• Add the AutoLocalize component to the parent (e.g. the Canvas) or add the LocalizeText component on the text field and fill out the paramaters in that class.

Press play and the text field should now change to the localized text.

14. How saving/loading XML works

Get Me Started is able to Save & Load public Monobehaviour variables to XML files which are stored in the Application.persistentDataPath folder.  When the XMLManager is included in the Library and the save function is called, the GameObject structure that is passed in will have it's hierarchy searched for MonobehaviourXML scripts and be saved out.

To use a MonobehaviourXML script, instead of your script inheriting from Monobehaviour, have it inherit from MonobehaviourXML.  The saving and loading happens behind the scenes, you just have to make sure that the information you want to save and load is in public variables.

To Load & Save the entire scene during Start and Destroy respectively, place the SceneXML script on the SceneManager GameObject.  If you would like to trigger it at a different time, call the Lib.Instance.XMLManager.Save(filename, gameObject) or Lib.Instance.XMLManager.Load(filename, gameObject) functions at that time.

By default the Library prefab tries to load an XML every time it starts up.  If you just installed Get Me Started you will see a Debug.Log message mentioning that the XML file is missing.  That message can be removed by opening the Developer menu (The ~ key) and selecting "Save Library XML."

In \Assets\GMS\Scripts\Examples\ there are two scripts included to show you how the XML saving works.  ExampleXMLClass is a MonobehaviourXML class that will save its contents out and it references ExampleXMLSerializedClass, a basic class with [System.Serializable] at the top.

15. How the Credits work

The Credits scene contains a Scroller which has the Credits.cs script component on it.  That script links to the Credits.txt file which it reads in on start. Any commands found on a line in the text file are used to instantiate prefabs in the list box.

The commands are always at the start of a line and between <> brackets.  The command corresponds to the name of the prefabs in the Credits script array on the Scroller.

Included prefabs that you can use are:

<lb> - A Large blank space.  Typically used as a header.

<h1> - A large header.

<h2> - A secondary header.

<cl> - A Centered Line.  It is designed to take two words (but mainly it's designed for a persons name) and put one part on the left, and the other on the right, with the space centered.

There are also two special prefabs:

[space] - is used when a blank line is found.

[lineoftext] - is used when there is text, but no command.

Once all of the prefabs have been instantiated, it will scroll up.  When the list hits the bottom, a callback notifies SceneCredits.cs and that script loads the Main Menu.

Overlayed on top of the scroller is a transparent layer called UserInput.  It's a GameObject that keeps an eye out for clicks or keyboard presses.  If the user clicks, a skip message will display for a few seconds.  If they click a second time, the credits will be skipped.  If they don't click the message will fade out and nothing will happen.

16. Screenshots

ScreenshotManager is a static class that can be called from anywhere in your game. It has two functions Take() and TakeAdvanced().  Take() will take a basic screenshot and save it to a file in the Application.persistentDataPath folder with a time stamp to make sure its unique.

TakeAdvanced() also takes a screenshot, but it briefly increases the quality of the image on the screen and optionally removes the HUD before it does so.

17. Removing the XML features

Some games don't need the included XML features.  Follow these steps and you will be able to fully remove the code from your game.

• Drag the \Resources\LibraryPrefab into the Hierarchy window.
• Remove the XMLManager from the list of components.
• Click the Apply button in the Inspector to save your changes to the prefab.
• Delete the prefab from your scene.
• Save the scene to write the prefab changes to the hard drive.
• XML Saving has now been disabled.  There may also be other classes that are there to use it, such as ExampleXMLClass or SceneXML.  You can freely remove those as well.

18. Removing Localization

If you don't want to use the included localization code, it can also be removed.

• Drag the \Resources\LibraryPrefab into the Hierarchy.
• Remove the LocalizationManager from the prefab.
• Click apply in the Inspector window.
• Delete the LibraryPrefab from the Hierarchy window.
• Save your scene.
• Localization has now been removed.  You may want to remove Language*, LanguageContainer*, AutoLocalize, DontLocalize, LocalizeText, and LocalizeImage from various places around the code as they are no longer lneeded.

If you go into the Settings dialog, the language section should automatically hide itself, but you can delete it if you don't want it there anymore.

* If you want to remove the Language.cs class, you have to make sure that anywhere that references one of its statics in the code needs to be changed to a string of some sort.  Search project wide for "Language." (Search->Find in Files in Mono Develop).  That will provide a list of everything that references the class and you can go through line by line and replace them with strings.  Skip LocalizeText.cs class if you are going to deleted it.

19. Removing Example Scenes

There are a few example scenes included with GMS.  If you want to clean things up, but keep the functionality, here is a list of scenes you can remove:

• /Assets/GMS/Scenes/Example Tutorial Scene A
• /Assets/GMS/Scenes/Example Tutorial Scene B
• /Assets/GMS/Scenes/Example Empty Scene
• /Assets/GMS/Scenes/Example Prototyping Props

Remember to go into File -> Build Settings to remove the scenes from the build process and run Edit -> GMS -> Update SceneEnum again.

20. Shaders

Get Me Started comes with a couple shaders that round out the Unity provided ones.

They work by treating two colour channels in the image as two separate black and white images.  The data in the Red channel is treated as the base colour and alpha of the particle.  And the information in the Green Channel is treated as the highlight.  The Blue and Alpha channels of the image are ignored.  The Color plus white shaders are less computationly intensive.  You will want to use those when two colours aren't absolutely required.

Red Channel - Black is transparent.  White is the Color

Green Channel - White is the Highlight Color.

Blue Channel - Ignored

Alpha Channel - Ignored

• Color plus White Additive - An additive shader that uses a colour to tint the base of the particle and uses white as the highlight.
• Color plus White Alpha - An alpha shader that uses a colour to tint the base of the particle and uses white as the highlight.
• Two Color Additive - Two colours are specified when colouring this additively blended particle.  One is the base colour and the other is the highlight colour.
• Two Color Alpha - An alpha blended particle shader that uses two colours to tint the base and the highlight.

21. 3rd Party Attribution

Tanner Helland

http://www.tannerhelland.com/music-directory/

Tim Gormly

- 8-Bit Coin http://www.freesound.org/people/timgormly/sounds/170147/

- 8-Bit Hurt http://www.freesound.org/people/timgormly/sounds/170149/

22. About the Author

Neil Marshall has been creating games for over a decade as both a Programmer and Technical Artist.  One of the more recognizable games he has worked on was the freemium Uno for iPhone & Android based phones.