FREE US SHIPPING ON ORDERS $175+

translation missing: en.general.currency.dropdown_label

0 Cart
Added to Cart
    You have items in your cart
    You have 1 item in your cart
      Total

      Game Development — game development

      Unity - Undefined Script Order of Execution Bugs

      Unity - Undefined Script Order of Execution Bugs

      When a bug consistently reproduces for one person but never does for another, or it appears in a build but not in editor or vice-versa, it may be from an undefined script order of execution bug. These bugs occur regularly if using Unity normally, and the cause is subtle. The inconsistency also makes them a pain to track down and fix. These are easily the worst type of bug out there due to their inconsistent nature. This document will explain how these bugs happen, demonstrate the reasons for inconsistency in whether they occur or not, methods for fixing them, and ways of designing your code so there’s no room for these bugs to manifest in the first place. To start, here's a simplified example of a script execution order bug, shown below:


      class CharacterUI : MonoBehaviour

      {
      public UiImage activeSkill; //set in inspector

      public Skills characterSkills; //set in inspector

      void Start()
      {
      activeSkill.sprite = characterSkills.skillsKnown.primarySkill.sprite;
      }

      }

      class Skills : MonoBehaviour

      {
      SkillData skillsKnown; //initialized from Resources.Load

      void Start()
      {
      skillsKnown = Resources.Load<SkillData>();
      }
      }

       

      For someone testing the game, they may always, consistently, get a null reference exception in Start() of CharacterUI, resulting in a broken-looking UI. For the developer and several other testers, the bug may absolutely never happen. The bug may also never happen for anyone in-editor, but does happen for some people in builds.


      Why does this happen?

      First, let’s establish that the CharacterUI’s Start() depends on Skills running Start() before it. Otherwise, when it would access the data within characterSkills.skillsKnown, skillsKnown would be null. With that in mind, for the above case, what actually defines the order the two Start() methods run? The order of execution for Start() between these two classes is completely undefined. Because it’s undefined, if these two objects are created at the same time at scene startup, Unity determines this order arbitrarily, and it varies between in-editor sessions and builds, and per machine! For some people the bug may always happen in editor and never in build, and others it may always in the build and never in editor, and for others it may never happen at all. This all depends on whether, for a given machine and build/editor session, Unity happens to decide if Skills runs before CharacterUI, or CharacterUI runs before Skills. While we work through the example, consider that for an actual codebase in a game, the classes involved in such a bug will be more numerous and complex.


      Solutions

      There's a few solutions available for our contrived example. One solution would be changing Skills to initialize on Awake(), which will always run before anything else’s Start(). But what if for your case’s current logic, both need to use Awake() or both must use Start() due to other dependencies from other classes? If both use Awake, you'd run into the same issue, as the order between the two Awake calls are undefined. If both must use Start, it’s the same as the example undefined order problem.


      The general solution requires explicitly defining the script's priority/order. There's a way to do this in the project's script settings, but it's a pain to manage it there (and gets out of hand as you get into hundreds of classes), so you can instead use an attribute on the class, which looks something like [DefaultExecutionOrder(150)]. Below I show the attribute applied to the classes to fix the bug.


      [DefaultExecutionOrder(10)]
      class CharacterUI : MonoBehaviour {
      public UiImage activeSkill; //set in inspector

      public Skills characterSkills; //set in inspector

      void Start()
      {
      activeSkill.sprite = characterSkills.skillsKnown.primarySkill.sprite;
      }

      }

      [DefaultExecutionOrder(-5)]
      class Skills : MonoBehaviour {
      SkillData skillsKnown; //initialized from Resources.Load

      void Start()
      {
      skillsKnown = Resources.Load<SkillData>();
      }
      }


      The lower the order value, the earlier its mono methods like Start() are executed relative to other monobehaviours. Now, the execution order for the Start() calls has been defined, so Skills Start() will always run before CharacterUI's Start(). Note, this execution order affects Start, Awake, Update (and all other types of update like FixedUpdate, LateUpdate), as well as OnEnable, OnDisable. For example, the Skills’ class OnEnable() would run before CharacterUI’s OnEnable().


      Note: if just one class had its order defined, such as CharacterUI’s, the bug could still occur as Skills’ order relative to it is still undefined.


      Preferred Solution - Avoiding this Problem By Design

      The above solution of using the DefaultExecutionOrder attribute is fine if the damage is already done and the code can’t be refactored. However, the ideal solution is to design your code in a way where this issue doesn’t have room to occur in the first place.


      Solutions for this problem at a design level involves avoiding using Start() or Awake() for anything which depends on another game object's state. Instead, you should have some dedicated code in another class responsible for initializing your objects and using them together, rather than having your individual objects cross-referencing each other. As a red flag, if you require your Start() or Awake() methods to run in very particular orders between separate objects of classes in order for them to function properly, they should be redesigned so they are initialized explicitly by hand in another class. The thought process behind this is that if their initialization order is so important for them to function at all, this order deserves to be explicitly defined by hand, line-by-line, in one location, and not spread out throughout the codebase by using the DefaultExecutionOrder attribute. Let’s look into an example.


      For a contrived example, imagine you have classes A, B, C, D, and E which all depend on each other in different ways in their Start() and Awake() methods. If you need to understand the order which they initialize and you’re using the DefaultExecutionOrder attribute, you’d need to go between each class and make note of their order number, then organize those order numbers lowest to highest, then separately consider how for this order their Awake()s run first, followed by their Start()s, and some classes may be missing one and have the other. There is a much clearer way - just introducing one simple class, which takes references to each involved class and explicitly initializes them in a manually defined order, passing their dependencies as arguments.


      e.Initialize();
      d.Initialize(e);
      c.Initialize(d, e);
      b.Initialize(e, c, d)
      a.Initialize(b, c);


      Now, the order of initialization to a developer is extremely clear by just looking at it, the dependencies between classes are also extremely clear, and very importantly, there’s also no room for undefined execution order bugs because you have explicitly defined the initialization order by hand.


      Note that when defining initialization orders by hand, you may encounter things called cyclic dependencies. For example, if system A requires B to be initialized, and B requires C to be initialized, and C requires A to be initialized, there’s no possible valid order to initialize them in. Resolving cyclic dependencies can be complicated and requires some sort of refactoring, so it’s outside of the scope of this document. Resolving cyclic dependencies is the expression you’d want to use when researching solutions.

      Coffee Crisis Chroma Integration: A Behind-the-Scenes Look

      Coffee Crisis Chroma Integration: A Behind-the-Scenes Look

      Table of Contents

      1. Introduction 3
      2. Overview of Chroma Integration in Coffee Crisis 4
      3. Installing Razer Synapse for development 11
      4. Installing UnityChroma(Native) SDKs 12
      5. Creating animations 13
      6. Testing on real/emulated hardware 18
      7. Behind the scenes look 19

      1. Introduction

      We, Mega Cat Studios, have recently wrapped up development on Coffee Crisis, a multiplatform 2D Beat'em Up game for Sega Genesis, PC, and Xbox One! One of the features exclusive to the PC port that we implemented into Coffee Crisis was Chroma support. Chroma is a unique, proprietary, next-generation technology that Razer implements into its product line of high-end gaming equipment, which allows dynamic lighting on its equipment. Products created by Razer which implement their top-of-the-line Chroma technology include their keyboards, mice, mousepads, computer cases, and much more. Using the Chroma SDK, developers can integrate Chroma support into their games and applications, and configure the lighting on Razer's Chroma-enabled products. Such examples of Chroma integration include making the products light up as a VU meter in multimedia applications, encoding gameplay information on products, and even attempting to show images on the device by approximately color mapping colors in images to certain buttons/keys on the device.

      Coffee Crisis is a neo-rogue brawler that puts you in the shoes of the only baristas on Earth with enough heavy metal in their veins to fend off an alien assault. Play solo or join up with a friend to fight across eight unique locations ranging from your Coffee House HQ to the far reaches of outer space. Go up against an army of wild alien enemies, and the humans they have brainwashed with a variety of weapons, special moves, suplexes, and coffee!

      The Smurglian race has come to Earth and they're not leaving until they steal our three most prized commodities: heavy metal, free WiFi, and our coffee. Crunch through fistfuls of alien meat as you stop their invasion, and enjoy random modifiers to the enemies and action on each playthrough. It's a unique cup of beat 'em up action every time you play!

       

      1. Overview of Chroma Integration in Coffee Crisis

      As part of our feature set of Coffee Crisis, we implemented Chroma integration into our game. The game was created for PC/Xbox One using Unity3D, a closed-source but critically acclaimed video game engine created by Unity Technologies, applauded and used by Indie and professional game developers worldwide. To add Chroma integration into Coffee Crisis, we used the official Chroma and Chroma Native Unity3D SDKs. For our game, we utilized Chroma for showing colorific animations on the Blackwidow Chroma Keyboard in cutscenes and menus, and on encoding gameplay information. Specifically, we implemented the following:

      • Menus
        • Main Menu
          • Animating keyboard to depict the background animation

        • Credits
          • Displaying a static color image of the final cutscene's background

      • Cutscenes
        • Story cutscenes
          • Applying a 5-color, brown palette cycle of concentric squares on the keyboard

       

          • Death metal/mod mode intro cutscene
          • Displaying a static color image of cutscene's background

      • Game
        • Encoding various game information on the keyboard
        • Encoding a health bar on the top row FN keys
          • Keys
            • Keys F1-F12
            • Printscreen
            • Scroll Lock
            • Pause
          • Bar increases/decreases as health changes
          • Bar color tweens
            • From green (max health)
            • To red (low health)
        • Encoding the hit combo counter on the row of numeric keys
          • Number keys 0-9
          • Bar increases as hit combo increases
          • The bar becomes full and fully green after 20 hit combos
          • Bar color tweens
            • From red (low hit combo)
            • To green (high hit combo)
        • Encoding the hit combo cooldown timer on the first alphabetic row
          • Keys QWERTYUIOP
          • Bar decreases from full as cooldown timer decreases
          • Bar color tweens
            • From red (low amount of time left)
            • To green (high amount of time left)
        • Encoding the amount of time left on the invincibility and damage multiplier powerups
          • Feature only viewable on full-sized keyboards, not half-sized (Blade keyboards on Razer laptops)
          • The feature can be disabled by
            • Selecting the keyboard type in the options menu
              • Full-sized keyboards
              • Blade keyboard
            • This saves CPU cycles
          • Keys 0-9 on Numpad
          • Keys 1-9 color tween
            • From green (high amount of time left)
            • To red (low amount of time left)
          • Key 0 stays a particular color based on powerup type
            • Yellow for invincibility
            • Red for a Damage multiplier

        • Encoding modifier information
          • Features only available in mod modes (various options set in Options Menu)
            • Modifiers toggle set on
            • Twitch integration enabled
            • Mixer integration enabled
          • Keys M1-M5
          • During voting in a Finish Them Zone
            • Keys M1-M4
              • Encodes the number of votes for the mod category
              • Color tweens
                • From green (low amount of votes)
                • To red (high amount of votes)
                • Zero votes display black

            • Key M5
              • Encodes the total amount of votes during the vote session
              • Color tweens
                • From green (low amount of votes)
                • To red (high amount of votes)
                • Zero votes display black

          • After voting in a Finish Them Zone
            • Keys M1-M4
              • Encodes the number of modifiers in play for the mod category
              • Color tweens
                • From green (low amount of mods)
                • To red (high amount of mods)
                • Zero mods display black
              • Modifier amount ranges
                • Twitch/Mixer
                  • 0-2 mods
                • Not Twitch/Mixer, but modifiers on
                  • 0-5 mods
            • Key M5
              • Encodes the total amount of mods in play during the Finish Them Zone
              • Color tweens
                • From green (low amount of mods)
                • To red (high amount of time left)
                • Zero votes display black
        • Encoding pain/powerup pickup
          • Every time the player
            • Is hit
              • All other keys unused by other bullet points flash red
            • Picks up a powerup
              • All other keys unused by other bullet points flash yellow

      This guide will show aspiring Indie video game developers how to set up and use the Unity3D Chroma plugins for game development, as well as show an exclusive behind-the-scenes look on how we implemented the Chroma functionality in Coffee Crisis!

       

      1. Installing Razer Synapse for development

      Before you can even use a Blackwidow Chroma keyboard for development, you must plug it into your computer for the first time. It goes without saying, but Chroma development will only work for Chroma-enabled Blackwidow keyboards. Certain Blackwidow keyboards do not include Chroma support; please check your user's manual.

      Plugging in your Chroma Blackwidow keyboard

      Plug in your Chroma Blackwidow keyboard into your computer. Some Blackwidow keyboards have 2 USB cords; one as a piggyback cable, another for the keyboard. Make sure at a minimum to connect the USB cable labeled "Razer" and not "Port". After plugging in your Chroma Blackwidow keyboard, the keyboard's drivers should install from online, and it should light up. In order to control the lighting and handle it in code, you will next need to install Razer Synapse software.

      Installing Razer Synapse for development

      Razer Synapse is a piece of software created from Razer which will allow you to configure the Chroma lighting on your Chroma-enabled devices, as well as interface with the lighting with code (after we implement code and the Unity Chroma plugins).

      To begin, download and install Razer Synapse. At the time of this writing, the latest version is Razer Synapse 3 Beta, while the previous is Razer Synapse 2. Download and install either version (for this guide, we'll use Razer Synapse 3 Beta). After launching the installer, select which features you want to be installed, and where to install it. At a minimum, you will want to install Razer Synapse software and Chroma.

      1. Installing UnityChroma SDK

      Now that we have both Razer Synapse installed and the drivers installed with the Razer Chroma Keyboard (via plugging it in), it is time to set up our Unity project to interface with Chroma!

      In order for a Unity project to interface with Chroma devices, you will need to install the Unity3D Native and non-native plugins for Chroma SDK. You can find the native plugins here, and the non-native here. The former plugins are required for usage in compiled games (they interface with the hardware), while the latter plugins are used in the Editor only for creating Chroma animations. The latter ones should be removed for compiled builds, to reduce filesize bloat in the compiled builds. Please read the instructions from each download page on how to use the plugins and install them.

      1. Creating animations

      With the keyboard's drivers installed, Razer Synapse installed, and the Unity3D Razer plugins installed into your project, you should be good to go for developing with Chroma! Below are a few conceptual notes on how Chroma works in Unity. Full-details on how to use Chroma with Unity can be found in the tutorials on the pages where you downloaded the Unity3D Chroma plugins.

      Chroma color with the Unity3D plugins works in either one of 2 ways: via Chroma animations, or by manually updating the colors of keys on-the-fly. The former method will be discussed in this section, while the latter in the next section. Chroma animations should not be confused with Unity's animations. The latter is used for changing properties of a GameObject's components overtime via keyframes (especially sprites and image graphics), while the former is used for changing the colors of Chroma-enabled devices over time.

      Chroma animations are simply .chroma filetypes, stored in the StreamingAssets folder within the Assets folder in the root folder of the project. Unfortunately, Chroma devices are only supported on Windows machines, so when compiling the game for other platforms (Mac and Linux), you should remove the ChromaSDK plugins, UnityNativeChromaSDK plugins, and the StreamingAssets folder with the Chroma animations, since they will bloat up the build's filesize and are unused for those platforms.

      To create Chroma animation, go to GameObject>ChromaSDK>Create 1D/2D Animation. For Keyboard animations, we will want to use 2D Animations. The Chroma animations should be placed in your StreamingAssets folder.

      In order to edit Chroma animations, right-click the animation, and click ChromaSDK>Edit Chroma Animation. This will bring up a custom Chroma Editor in the Inspector.

      In the custom editor, you can select the device type ("Keyboard" for this tutorial), select key types from the keyboard, and assign colors to each key in each frame in the animation. You can also import an image to assign colors to each key (however, this feature seems to crash often). When modifying colors, the Chroma devices attached to the computer will update to display your color configuration.

      Alternatively, to individually assigning colors to each key, you can use the Chroma capture tools to map an image onto the various keys. To use these tools, Goto Windows>ChromaSDK>Open Chroma Particle Window. To learn how to use these capture windows, check out the tutorials here.

      Animation playback

      Now that we have our animations defined for the game, we will need to add code to playback our animation. Any Unity3D script that utilizes the native Chroma plugins will need this namespace added to the top of the script:

      #if UNITY_STANDALONE_WIN

      using ChromaSDK;

      #endif

       

      Furthermore, Chroma support is only supported in the Windows platform, so make sure to add #if UNITY_STANDALONE_WIN code blocks around Chroma code. Below is a quote from the API documentation here for the most important API functions for playback:

      1. Testing on real/emulated hardware

      Now that we have animations defined and code for playing the animations, you will want to test them on hardware. You can either test it as such on real hardware (by playing the game with the Chroma device connected) or with the Chroma Emulator. The Chroma emulator will simulate Chroma lighting for a variety of devices. At a bare minimum, you will need one real Chroma device setup first before it can be used. Usage should be straightforward.

      1. Behind the scenes look on Coffee Chroma Integration

      A limitation of the Unity Chroma setup is that animations are static; it doesn't really allow for combing several animations to encode data. When designing the in-game Chroma animation, we wanted to encode most of the game's information on the keyboard. Luckily, we were able to exploit a few things in the Unity Chroma set up as a workaround and allow dynamic key lighting. Coffee Crisis' in-game Chroma animation is simply a dummy Keyboard animation with no keys lit.

      We heavily utilize the SetKeysColorAllFramesName API function in order to manually update the keys in an Update() thread; however, there is a catch to this method. In order to edit an animation during runtime, you must do the following:

      • Close it first with CloseAnimationName
      • Manually change your keys' colors with SetKeysColorAllFramesName
      • Play dynamic animation back with PlayAnimationName

      This sequence of code events was what allowed us to pull off dynamic animations in-game. A problem with using an update() thread to update dynamic Chroma animation in such a fashion is that it may lag other people's machines. Different models of Chroma keyboards have higher fresh rates, and running such an update thread at full speed will severely lag other people's machines. As a workaround to this issue, we added a cooldown timer, to update dynamic Chroma animations every 250ms. Please see our truncated, relevant code attached, for a sample of how we set up dynamic Chroma animations to work.

      Mega Cat Developer Juice Guide v1.0 (08/23/17)

      Mega Cat Developer Juice Guide v1.0 (08/23/17)

      One of the most important elements of implementing a feature or mechanic is ensuring it looks and feels good for a player to interact with. In this way, as a developer, programming a game to work and meet the functional requirements laid out for you is only part of your responsibility. Improving the look and feel of a game through added programming efforts represents the idea of "juice" to a developer. Developers can " juice" things up by exaggerating, emphasizing, or otherwise drawing extra attention to certain events in the game through various means such as:

      • Spawning added graphical elements
      • Modifying existing graphical elements
      • Implementing Camera/screen effects
      • Adding/modifying sound effects

      Impactfulness / Feel

      Developers often want a certain element in the gameplay element to feel more "impactful". This refers to adding "weight" and "feel" behind something taking place, such as an enemy or player receiving damage, the player character landing after a long fall, or a missile exploding. To juice something up to feel more impactful, exaggeration and emphasis are your tools to get the job done. For example, when an enemy receives damage, you could do the following to make it feel more impactful to the player:

      • Apply a shake or jitter to the enemy sprite’s position for a brief moment
      • Make the enemy's sprite frame flicker on and off every few frames
      • Knockback to the enemy, even if only slightly
      • Particles spawning at the hit location (e.g. blood for a human, nuts & bolts for a robot, etc.)

      Simply playing a damage animation for the damaged enemy or player alone is not enough to emphasize the damage.

      Where should we focus on impactfulness?

      Generally, the activities that the player performs the most should be made to feel the most impactful. For example, in a side-scroller beat-em' -up, the player’s primary focus is on hitting enemies. Therefore, hitting enemies should be the top priority on the list of game elements to juice up, and to make impactful. Here are some general rules for things that a developer should focus on juicing up to feel more impactful:

      • Enemy receiving damage
        • Enemy knockback
        • Enemy position jitter/shake
        • Make the enemy's sprite frame flicker on and off every few frames
        • Particle spawn at hit location
        • Screen shake that is stronger than if the player attacked but missed

      Example of enemy position knockback, blood/impact particles at hit location, enemy sprite frame flickering

      • Player receiving damage

        • Knockback
          • Be careful, can negatively affect balance or feel depending on the context
        • Make the player's sprite frame flicker on and off every few frames
        • Particle spawn
        • Camera shake


      Example of player knockback, sprite frame flicker, blood particle spawn

      • Enemy attacking
        • Shockwave on impact
        • Quick Sprite shake on impact
        • Dust cloud poof on impact
        • Screen shake if the attack hits the grounds/walls
      • Player attacking

        • Shockwave on impact
        • Quick Sprite shake on impact
        • Dust cloud poof on impact
        • Screen shake
      • Enemy defeat (especially bosses)

        • Explosions if appropriate
          • Make sure to include smoke if so
        • Extra particle spawning similar to receiving e damage
        • Screen shake
          • If it’s a big enemy falling over/exploding

      Example of extra particles on Overlord hit, screen shake and chromatic aberration on hit/defeat, and tractor beam movement on enemy death

      Obtain a powerup or item

      Examples of juices upon powerup pickup

      • Obtaining a reward

      • Gaining score

      • Moving a menu selector / confirming menu selection

        • Play sound effect
        • Apply transform/scale/shader animation to selected menu element
        • Change highlighted item's sprite to an alternative one

      • Changing to a new menu screen

        • Have old menu elements fade out or /move off of the screen
        • Have new menu elements fade in or transition in from the off-screen

      Example of menu fadeout and elements moving

      • Beginning/exiting a level/stage

        • Transition fade in/out
        • Sound effect
        • Particle effect local to the camera
        • Player character animation

      Example of transitions, player animation effects

      Shoot em' up/Run n' gunner juices:

      • Explosion

        • Screen shake

          • Base the amount based on explosion size

        • Smoke clouds which linger and slowly dissipate after the explosion

        • An extremely satisfying explosion sound effect

        • Spawn/despawn light source to imitate a flash of light light

          • Quickly doing this creates a flash of light

          • Good for short-lived explosions

      • Projectile/Bullet impact

        • Particles on impact

          • Sparks

          • Broken projectile

          • Etc.

        • Sound effect based upon the surface hit, examples

          • Different sounds for hitting stone

          • Different sounds for hitting the dirt

          • Etc.

      • Gunfire

        • Muzzle flash

        • Lightsource spawn for a brief moment on each shot to simulate muzzle flash emitting light

        • Smoke particles drifting up from muzzle during firing

        • Bullet casings or shells falling from the gun on shooting or reloading, appropriately

        • Character knockback while shooting

          • Should be subtle if present at all

          • Could be significant for very slow and powerful weapons