Archive for category: Training

Unity3D Architectures: Entitas

Unity3D Architectures: Entitas

Unity3D is a powerful suite of tools (Project IDE, Code IDE, run-time) for game development. In Unity3D Game Architectures I present six different techniques for setting up your game. Depending on the size and maturity of your team, you are probably using some form the archtectures presented there. I recommend checking that article out first, then read below.

A newer architecture called Entitas  was presented at Unity’s Unite Conferences (2015 and 2016). I saw the most recent presentation and recently made time for a deeper dive to learn the basics.

I created a few projects. The full source is linked at the end of the article

  • Entitas Template – An ideal starting point for your next Entitas project
  • Entitas ‘Pong’ – I started with the template and created a simple, complete game

While making those projects, reading documentation, and dissecting other freely available Entitas projects, I learned a lot.

Entitas for C# / Unity3D

Entitas is a super fast Entity Component System Framework (ECS) with a version created specifically for C# and Unity3D.

As the creators explain — Entitas is open source. Internal caching and blazing fast component access makes it second to none. Several design decisions have been made to work optimal in a garbage collected environment and to go easy on the garbage collector. Entitas comes with an optional code generator which radically reduces the amount of code you have to write and lets you write code that is super fast, safe and screams its intent.

Here is an excerpt from my Entitas Pong game.

//  Create human player
Entity whitePaddleEntity                     = _pool.CreateEntity ();
whitePaddleEntity.AddPaddle            (PaddleComponent.PaddleType.White);
whitePaddleEntity.AddResource        ("Prefabs/PaddleWhite");
whitePaddleEntity.AddVelocity          (Vector3.zero);
whitePaddleEntity.WillAcceptInput   (true);

Entitas Structure

Diagram Fundamentals
  • Entities – Hold Components – E.g. PlayerEntity
  • Groups – Hold groups of Entities (as a query optimization) – E.g. BulletGroup
  • Components – Hold public variables ( Has no methods) – E.g. VelocityComponent
  • Systems – Query entity/components ( Has methods to do logic ). Most of your code is here, typically acting on one or more groups. E.g. VelocitySystem
  • Controllers – Monobehavior that bridge the ‘unity world’ with the ‘ECS world’. E.g. InputController

Example:

The InputController (Monobehavior) listens for Unity.Input on Update. When the phone’s screen is tapped, the InputController creates an InputEntity, each with an InputComponent with data regarding the tap The InputSystem (ISystem) processes once, only when new InputEntities exist, and it updates the PlayerEntity‘s VelocityComponent. The concept of Velocity is processed separately to update the game properly, etc…

Note: Entitas Components are NOT Unity Components (aka Monobehaviors). Think of an Entitas Component as serving ANY (one) of these roles;

  • Simple data storage – e.g. myComponent.score
  • Events – myEntity.WillDestroy(true) which functions something like myEntity.SendEvent (new DestroyMeEvent());
  • Visual things – e.g. myComponent.view.gameObject with some standard Unity renderers attached

Visual Debugging

entitas_systems_v1Systems

entitas_pools_v1Entities

Performance

Based on data provided by the creators we see impressive run-time performance.

Unity vs Entitas. 1000 objects with 2 components;

  • Memory: 9x (2.9 MB vs 0.32 MB)
  • CPU: 17x (105ms vs 6ms)

Entitas is MUCH faster due to its many 0ptimizations: Entitas…

  • Reuses Entities
  • Reuses Components
  • Caches Groups
  • Index Components

Compared to a typical Unity game architecture, ECS processes logic only when processing is necessary. The Entitas system architecture and query system allows me to mix ‘processing’ strategies. For example with 100 characters onscreen I can;

  • Move all characters every monobehavior.Update()
  • Move half one one frame and the rest on another frame
  • Move only those who have a changed position
  • Etc…

Evaluation

Pros

  • FAST performance
  • Data-binding is implicit (OnEnityAdded/Removed/Updated, OnComponentAdded/Removed/Replaced)
  • Querying is fast, efficient, and opens your mind to new ways to think about your game.
  • ECS embraces Single Responsibility Principle (SRP) ( link )
  • Testability*
  • Code sharing (use C# on client AND server)*

* These features are greatly enabled because the UnityEngine.* classes are separated by-design from the bulk of your Entitas game logic. Testing UnityEngine.* has historic challenges. Running UnityEngine.* on server is either undesirable or impossible depending on your technology stack.

Cons

  • Developing with Entitas is easy, but refactoring has challenges (see Growing Pains below)
  • Best to START your project with Entitas
  • Best to FULLY embrace your project with Entitas (Rather than use Entitas partially in your game)
  • Collaboration takes effort between Entitas and existing code (e.g. AssetStore code)

Neutral (Things to get used to)

  • With Entias you may have MANY more class files
  • Entitas uses code generation (its optional, but I always used it).
  • You feel like the bulk of your Entitas code is disconnected from Unity. I consider this a PRO, but it takes some time to get used to. Ex. Its standard practice to NOT store your character’s position on the gameObject.transform.
  • Everything can access everything. There is a more ‘global’ state. Ex. your enemy’s code scope can fully access your hero’s health. The creators see standard OOP-based gaming structure as ‘little boxes’ (encapsulation) that you must break with every major refactor and game feature added, so instead there is much less emphasis on these ‘little boxes’ in the Entitas paradigm.

Growing Pains

Fixing compilation errors

The (optional) Enttias code generator is based on runtime reflection. The project has to compile before you can generate. This is not an issue when you creating new components, however when it comes to changing or deleting components, your code might stop compiling. Here is a list of recipes how you can avoid bigger hassle while changing and deleting components.

Ex. I stored the position of a character as float x, y, z. Then later changed it to a custom Vector3 class implementation. In a project without code generation your IDE’s ‘Rename’ or ‘Find-Replace’ functionality makes this pretty straight-forward. However, not all of the previously generated code will respect your refactor and a bit (30-60 seconds) of manually changes will be needed. Then once the project compiles again (you can use the Entitas code generation menu option to clean up the code again. I don’t have a suggestion on how, but improving this workflow is highly desirable. For now we have some helpful workarounds.

Use this advice to speed the process when doing the following tasks;

  • Renaming component fields
  • Renaming components
  • Adding new fields to a component
  • Removing fields from a component
  • Deleting a component
  • Renaming pool names

Resources

  • Official Entitas Homepage ( link )
  • Official Entitas Examples ( link )
  • My Entitas Template ( link ) – Use this as a starting point for your next project
  • My Entitas ‘Pong’ Game ( link ) – I started with the template and created a simple game

 

Unity UI: Overview – Part 1 of 3

Category: Quick Tips, Standards & Best Practices     |     Tags: API, C#, GUI, Unity3D

I’ve been lucky to focus the past years on Unity and C#. Much of my demos, full-games, and tutorial are here RivelloMultimediaConsulting.com/unity/. If you have any comments or questions, I’d love to hear from you. Twitter.com/srivello.

Traditional Unity GUI Solutions

Unity is an amazing ecosystem for game development. For years, even big fans of the tool have been critical of the 2D/GUI/Text systems offered. Unity and the Unity community have launched various competing GUI systems (both immediate and retained) but the lack of features and lack of consistency leaves much to be desired. Luckily the amazing Asset Store (See my articles one, two, and three) of 3rd party tools and components has dutifully filled the needs of many devs.

Maintaining robust state (e.g. button) and handling adaptive layouts with Unity Legacy GUI was always very challenging. – Me

Older Options

  • Unity GUI (Immediate): This has been renamed to ‘Unity Legacy GUI’ to limit confusion with UI in Unity 4.6.x. The Legacy GUI will continue to be available and will remain as the recommended solution for Tools development (creating new windows and panels within Unity Editor). It requires developers to program the GUI in a loop that runs repeatedly.
  • NGUI (Retained): By FAR the most popular solution in recent years. There are alternatives in the asset store, but this is the most prevalent. Designed by a fantastic developer Michael Lyashenko with extensibility, flexibility, and power in mind — this project excels. It will still be popular for the future too because so many projects and teams are already at home with it. In 2013, Michael was hired by Unity to lead development on Unity UI for 4.6.x. He has since left the project, but his positive impact on the structure of the new solution is obvious.

Unity UI 4.6.x

This is the ‘New GUI’ for Unity. It was released publicly in 2014 after a long private and public beta period. I feel that Unity really wanted to get it right. And I think they have done a lot to guarantee adoption and success. Due to the complicated history of the GUI within Unity, the naming of the new system was/is debated. Perhaps some day in the future we’ll just call it ‘the’ UI of Unity and the other options will fade away. Before we’re sure of that, let’s take a look at the system. It is great.

I am pleased, and frankly shocked that Unity UI is available in the standard (free) version of Unity. – Me

Unity UI Features

  • Fast and flexible workflows: The workflow feels very at-home within Unity. Want to render text with a font? Drag a font from your OS into your project and *boom* its immediately available for run-time usage. No more need to ‘convert’ fonts to bitmap fonts. Its just as easy with images too. You can reskin any of the existing components too using your own graphics.
  • Low memory allocations and high performance: With batching, texture atlasing and the new canvas component, we’ve come up with the optimal solution to allow your UIs to execute quickly on GPUs. Draw calls are kept low and performance remains high across all supported Unity platforms and device resolutions.
  • Easy multiplatform deployment: Intelligence about the sizing (and resizing) of the app as well as layout groups (see below) helps greatly.
  • Unique animation capabilities: Use the existing (awesome) ‘Animation’ panel to animate ANY public property of your UI. Listen for UI events (e.g. button click) and react with transitions to new layouts or new scenes.
  • Intuitive Layout Tools: Laying out and resizing elements is easy with the new Unity UI. Design detailed layouts using the Rect Transform layout tools, and automate grids of UI elements with our built-in components.

Each element that can be laid out (text, image, etc…) is considered a component. The list of current components is finite, but any developer can create their own components from existing components or from scratch. We expect the list of built in components to grow — both from Unity and from the community.


UI_Main

Main UI Components (as of Unity 4.6.1)

  • UI Canvas: This is the required hierarchy root-parent to all UI elements. You can have multiple in the scene. It comes in 3 flavors; Overlay (flat HUD), Camera (tilted HUD), and World Space (speech bubble that follows your character through the scene). ( Docs, Video )
  • UI RectTransform: ( Docs, Video )
  • UI Button: ( Docs, Video )
  • UI Toggle: ( Docs )
  • UI Image: ( Docs, Video )
  • UI Text: ( Docs, Video )
  • UI Input Field: ( Docs)
  • UI Slider: ( Docs, Video )
  • UI Scroll Rect: ( Docs, Video )
  • UI Scrollbar: ( Docs, Video )

Supporting UI Components (as of Unity 4.6.1)

Common ‘How To’ Tasks

  • Designing UI for Multiple Resolutions: ( Docs)
  • Adaptive Layout: ( Docs)
  • Creating UI from C#: ( Docs)
  • More: ( Docs)

ANCHORING

flexible-anchoring

Take advantage of simple visual tools to anchor UI elements. The UI element maintains its anchored position regardless of changes to parent size or screen resolution. Want to anchor different elements relative to different positions on the canvas? No problem.

ADAPTIVE RESIZING

smooth-resizing

You can set UI elements to stretch along with the parent rectangle, or to maintain fixed margins inside it. In addition, each side of a UI element can be anchored individually, allowing you to set up sophisticated layouts without scripting.

ANIMATING UI

get-animated

Animation plays a key part in your new UI workflow for creating dynamic layouts with slick transitions. Animate any part of your UI layouts, from bouncing buttons to animated material properties for detailed motion.

What’s Next?

With each minor and major update of Unity I expect vast bug-fixes and new features with the UI system. It is very stable and ready for use already. So start experimenting! I am already working on a few upcoming posts that will explore the system in more depth. If you want to see me cover something in particular, add a comment beneath this page.

  • New Unity UI (4.6.x): Unity UI Part 2 of 3: Demo – Basic UI (Source code + Video) [Coming Soon!]
  • New Unity UI (4.6.x): Unity UI Part 3 of 3: Demo – Combining UI w/ Frameworks/Architectures for scalability (Source code + Video) [Coming Soon!]

uEP – Unity Expose Properties

Category: Full Tutorials, Quick Tips, RMC News     |     Tags: Unity3D

About RMC & Unity3D Rivello Multimedia Consulting (RMC) provides consulting services for applications and games. RMC specializes in Unity3D development (see our work here). Please contact us today with any questions, comments, and project quotes. As always, RivelloMultimediaConsulting.com/unity/ will be the central location for deep articles and tutorials, Facebook.com/RivelloMultimediaConsulting (like us!) will engage the growing RMC+Unity community, and for the latest opinions and cool links follow me at Twitter.com/srivello.

Why Use The Inspector?

For a complete introduction to Unity see my “Intro To Unity” Article. For a quick review: games in Unity are made up of multiple GameObjects that contain meshes, scripts, sounds, or other graphical elements like Lights. The Inspector displays detailed information about your currently selected GameObject, including all attached Components and their properties. Here, you modify the functionality of GameObjects in your scene. Any public field (publicly accessible variable) that is displayed in the Inspector can be directly modified while in edit mode and also while in play mode (the game is playing live). That is great.

The Inspector is a vital part of the Unity toolset with many powerful features. However, here I’ll focus on the specific programming-centric benefits of using the inspector.

Reasons

  • Gives us an (editable) view to all public fields on a game object.
  • Very powerful for experimentation, prototyping, and debugging.
  • Improves our interface to the code. E.g. instead of setting a color in code as #ff0000, you can have a GUI color picker in the inspector.

Example

public float myNumberField_float = 10f;

NOTE: Only public fields are shown in the inspector.

NOTE: Adding the attribute [HideInInspector] before a public field name will allow it to be public (for coding) but not be shown in the inspector. This is outside the scope of this article, but it is quite useful sometimes.

Why Use Properties?

As we learn in C# In Depth, for every type you write, you should consider its interface to the rest of the world (including classes within the same assembly). This is its description of what it makes available, its outward persona. Implementation shouldn’t be part of that description, any more than it absolutely has to be. (That’s why I prefer composition to inheritance, where the choice makes sense – inheritance generally exposes or limits possible implementations.)

A property communicates the idea of “I will make a value available to you, or accept a value from you.” It’s not an implementation concept, it’s an interface concept. A field, on the other hand, communicates the implementation – it says “this type represents a value in this very specific way”. There’s no encapsulation, it’s the bare storage format. This is part of the reason fields aren’t part of interfaces – they don’t belong there, as they talk about how something is achieved rather than what is achieved.

I quite agree that a lot of the time, fields could actually be used with no issues in the lifetime of the application. It’s just not clear beforehand which those times are, and it still violates the design principle of not exposing implementation.

Reasons

  • Through encapsulation you now have a publicly accessible ‘thing’ just like a field, but here you can more completely control it. For example, within the set {}  you could check the incoming ‘value’ and ensure it is between 1 and 10 before accepting the change.
  • Want to break into the debugger whenever the value changes? Just add a breakpoint in the setter.
  • Want to log all access? Just add logging to the getter.
  • Properties can be used for more advanced language features (like binding) too

Example

private float myNumberProperty_float = 10f;
public float myNumberProperty
{
	set {
		myNumberProperty_float = value;
	}
	get {
		return myNumberProperty_float;
	}	
}

Using Properties Via Inspector

By default, while Unity allows the inspector to shows with fields (variables), it does not render properties (getter/setters).

However, now you can do it all. I created the uExposeProperties (uEP) project. It is an asset store project for free. I’m hoping the community finds great uses for it. With uEP you get the best of both worlds; benefits of the inspector as well as properties.

Reasons

  • You get the benefits of the inspector
  • You get the benefits of properties
  • Your code stays very clean (only one simple attribute is added per property)

Example

NOTE: You must download the uEP package to use this functionality. It is not included in Unity.

private float myNumberProperty_float = 10f;
[ExposeProperty]
public float myNumberProperty
{
	set {
		myNumberProperty_float = value;
	}
	get {
		return myNumberProperty_float;
	}
	
}

Drawbacks

  • There is one major drawback: theoretical performance. The current implementation depends on the OnInspectorGUI() event which is far more expensive than not using it.
  • Any ideas on how to improve that?

Next Steps

  • Download the source-code (See ‘Member Resources’). Available Now.
  • Get uEP on the asset-store (Coming Soon!)

Member Resources

[private_Free member]Enjoy this members-only content!

[/private_Free member]

Unity3D Reactive Extensions 2: Syntax & Marble Diagrams

Category: Full Tutorials, Quick Tips, RMC News     |     Tags: ReactiveExtensions, Unity3D

About RMC & Unity3D Rivello Multimedia Consulting (RMC) provides consulting services for applications and games. RMC specializes in Unity3D development (see our work here). Please contact us today with any questions, comments, and project quotes. As always, RivelloMultimediaConsulting.com/unity/ will be the central location for deep articles and tutorials, Facebook.com/RivelloMultimediaConsulting (like us!) will engage the growing RMC+Unity community, and for the latest opinions and cool links follow me at Twitter.com/srivello.

Why RX?

You can read more in my first article “Unity3D Reactive Extensions 1: An Introduction“. That is recommended reading before continuing with the article below.

How to do RX?

Here is a recap. In article 1 we used an RX approach for the following (academic) exercise;

Exercise: Dispatch a double click event based on custom timing parameters.

Reactive Extensions (RX) Solution

You can see the code is easy to read and powerful. While this algorithm requires state management, we don’t have to handle it directly. The internals of RX do it for us. You can imagine with a more complex feature, the code would be dramatically more than the RX solution. Below we break-down the code and explain each step.

NOTE: The TLP Library used in this article is a work in progress. It features only limited functionality and does not conform to common RX standards in the naming, signature, and structure of major elements. These differences are why the syntax and marble diagram names below are not 100% coincidental, but the concepts are similar. The TLP team invites other developers to fork the library and contribute to it. Still it is a fantastic learning tool and quite useful as-is.

Complete Code For RX Solution

//--------------------------------------
//  Methods
//--------------------------------------
///<summary>
///	Use this for initialization
///</summary>
void Start ()
{
	// VARIABLES
	float maxTimeAllowedBetweenSingleCLicks_float = 1;
	float delayBetweenAllowingADoubleClick_float = 5;	
	int clicksRequiredForADoubleClick_int = 2;
	
	// CREATE OBSERVABLE 
	//(ORDER IS NOT IMPORTANT, BUT SUBSCRIBE MUST BE LAST)
	var mouseDoubleClickObservable = Observable

		//RUN IT EVERY FRAME (INTERNALLY THAT MEANS Update()
		.everyFrame

		//FILTER RESULTS OF THE FRAME
		//WE CARE ONLY 'DID USER CLICK MOUSE BUTTON?'
		.filter	(
			_ => 
			Input.GetMouseButtonDown (0)
		)

		//DID WE FIND X RESULTS WITHIN Y SECONDS?
		.withinTimeframe (clicksRequiredForADoubleClick_int, maxTimeAllowedBetweenSingleCLicks_float)

		//REQUIRE SOME 'COOL-DOWN-TIME' BETWEEN SUCCESSES
		.onceEvery (delayBetweenAllowingADoubleClick_float);


	//FOR EVERY EVENT THAT MEETS THOSE CRITERIA, CALL A METHOD
	var subscription = mouseDoubleClickObservable
		.subscribe (
			_ => 
			_onMouseEvent (MouseEventType.DoubleClick)

		);


	Debug.Log ("Subscription Setup : " + subscription);


}
//--------------------------------------
//  Events
//--------------------------------------
/// <summary>
/// SUCCESS: Double click
/// </summary>
private void _onMouseEvent (MouseEventType aMouseEventType)
{

		Debug.Log ("RX._onMouseDoubleClick() " + aMouseEventType);
}

 

Marble Diagrams & RX Syntax

Marble diagrams are frequently in videos and blog entries from the Rx team explaining how certain operators in Rx work. From top to bottom there are; source stream(s), operators, and then the outgoing stream. The RXJava wiki has an especially pretty set of these images.

Let’s take a closer look at the syntax we used.

  • 1. everyFrame: We observe an event stream on every frame (aka Update) in Unity…
  • 2. filter: …where the mouse button is down…
  • 3. withinTimeFrame: … X occurrences within Y seconds, which we call success…
  • 4. onceEvery: …and success can only happen every Z seconds…
  • 5. subscribe: …then call the desired method…

1. Operator: everyFrame (Similar to fromEvent)

From RXJava, we see that “the free-threaded nature of Rx is key to the performance characteristics of the event processing pipeline. However, in places where we bridge with the external world, this sometimes has negative effects due to thread-affine operations involved. The FromEvent [Pattern] bridges are one such place where we reach out to add and remove operations on events”.
 
Our specific use of everyFrame(), in pseudocode, would be like fromEvent (myMonoBehavior.Update).

2. Operator: filter

rmc_banner_filter_dropshadow_600_400_v1

You can filter an Observable, discarding any items that do not meet some test, by passing a filtering function into the filter( ) method. For example, the following code filters a list of integers, emitting only those that are even (that is, where the remainder from dividing the number by two is zero):

3. Operator: withinTimeFrame (Similar to buffer)

rmc_banner_buffer_dropshadow_600_400_v1

The buffer( ) method periodically gathers items emitted by a source Observable into bundles, and emits these bundles as its own emissions. There are a number of ways with which you can regulate how buffer( ) gathers items from the source Observable into bundles:

4. Operator: onceEvery (Similar to sample)

rmc_banner_sample_dropshadow_600_400_v1

5. Operator: subscribe

Subscribe is not an operator per se, it is something higher level in importance — When an observer subscribes to an observable sequence, the sequence begins and runs till completion. It is in the subscribe that we answer “What should ultimately happen with the outgoing event stream?”. In our example, we call a local method _onMouseEvent and we pass an appropriate MouseEventType.

NEXT STEPS

Our exploration into RX has just begun. Everyone interested is invited to download the source-code from my first article “Unity3D Reactive Extensions 1: An Introduction” and learn more. I continue to seek to find the best RX library for Unity development and have already begun to add RX into my game projects.`

Unity3D Reactive Extensions: An Introduction

Category: Full Tutorials, Quick Tips, RMC News     |     Tags: ReactiveExtensions, Unity3D

About RMC & Unity3D Rivello Multimedia Consulting (RMC) provides consulting services for applications and games. RMC specializes in Unity3D development (see our work here). Please contact us today with any questions, comments, and project quotes. As always, RivelloMultimediaConsulting.com/unity/ will be the central location for deep articles and tutorials, Facebook.com/RivelloMultimediaConsulting (like us!) will engage the growing RMC+Unity community, and for the latest opinions and cool links follow me at Twitter.com/srivello.

Why RX?

General

Obviously fantastic software can be created without RX. We work without it every day. So why consider it? Well, essentially because asynchonous programming is hard to do, brittle, and is a challenge to scale. Well as the Reactive Manifesto explains;

  1. The Need To Go Reactive – Each day applications are getting bigger, users expect more to happen in less time, and our projects are deployed to increasingly diverse set of (smaller) devices. To compete, old dogs need new tricks.
  2. Reactive Applications – They react to events; loading data, user gestures, system failures.
  3. Event-Driven – Event driven systems feature loose coupling between components and subsystems; a prerequisite for scalability and resilience.
  4. Scalable – With RX our data runs ‘as if’ it is synchronous. Even the currently synchronous stuff. So as complexity comes and delays ensue, it can flex to be asynchronous. Secondly, the decoupled nature allows for location transparency. Benefits include multi-threading (where possible).
  5. Resilient – In a reactive application, resilience is not an afterthought but part of the design from the beginning (see ‘onError’). Making failure a first class construct in the programming model provides the means to react to and manage it, which leads to applications that are highly tolerant to failure by being able to heal and repair themselves at run-time.
  6. Responsive – The philosophies and practices of RX programming seek minimal latency to the user experience.
  7. Conclusion – We expect that a rapidly increasing number of systems will follow this blueprint in the years ahead.

NOTE: While RX is designed to work with asynchronous data streams, it really doesn’t care. RX blindly accepts synchronous data within the same data flow.

Games

My first exposure to RX was regarding both UI behaviors (e.g. mouse events) and asynchronous data (e.g. loading from server). Gaming is inherently an asynchronous experience and the UI behaviors (e.g. user input) alone warrant a deep look at RX.

What is RX?

Iterables You are probably familiar with the concept of Iterables. In Unity we are used to using a List of values and looping through them and doing something synchronously. Observables In RX, it is observables that are a similar concept except the list may or may not be populated yet (i.e. it could start out empty) and may or may not be fully populated yet (i.e. ‘complete’). Still you iterate through the values, however asynchronously. Consider the following table;

Same Concept, Opposite Direction (Pull vs Push of Data)
Iterable (Pull) Observable (Push)
getDataFromLocalMemory()
.skip(10)
.take(5)
.map({ s -> return s + " changed" })
.forEach({ println "next => " + it })
getDataFromNetwork()
.skip(10)
.take(5)
.map({ s -> return s + " changed" })
.subscribe({ println "onNext => " + it })

Reactive applications use observable models, event streams and stateful clients.

Reactive extensions (RX) is the library designed for Functional Reactive Programming (FRP). It is “a library for composing asynchronous and event-based programs by using observable sequences.” What is FRP? The name comes from the language features used and the philosophy of the data exchange (See Figure 1).

Figure 1. Functional Reactive defined.

According to Haskell.org, Functional Reactive Programming (FRP) integrates time flow and compositional events into functional programming. This provides an elegant way to express computation in domains such as interactive animations, robotics, computer vision, user interfaces, and simulation. The major parts of RX;

  • Observables – Source of event stream & Subscriber – Observer of event stream.
  • Linq – Query the event stream (e.g. filter, map, zip)
  • Schedulers – Define the timing (inc. frequency) of concurrency.

As a quick primer, consider the following Observer->Subscriber event stream (See Figure 2).

Figure 2. Observer-to-Subscriber Event Stream.

Here the Observable emits an integer, it goes through an operation that adds 2 to it, and is finally received by the Subscriber (Observer). All steps are asynchronous, which means the subscriber does not actually know that the original value had been changed.

Operators

Between the Observable and the Subscriber the event stream can be operated upon. Here is a partial list of operators;

  • Transforming
    • map( ) — transform the items emitted by an Observable by applying a function to each of them
    • scan( ) — apply a function to each item emitted by an Observable, sequentially, and emit each successive value
  • Filtering
    • filter( ) — filter items emitted by an Observable
    • takeLast( ) — only emit the last n items emitted by an Observable
    • skip( ) — ignore the first n items emitted by an Observable
    • takeFirst( ) — emit only the first item emitted by an Observable, or the first item that meets some condition
  • Combining
    • startWith( ) — emit a specified sequence of items before beginning to emit the items from the Observable
    • merge( ) — combine multiple Observables into one
    • zip( ) — combine sets of items emitted by two or more Observables together via a specified function and emit items based on the results of this function

How to do RX?

Let’s consider a very typical operation; using mouse input to perform a simple operation. Compare the non-RX and RX approaches to the following (academic) exercise;

Exercise: Dispatch a double click event based on custom timing parameters.

Reactive Extensions (RX) Solution

You can see the code is easy to read and powerful. While this algorithm requires state management, we don’t have to handle it directly. The internals of RX do it for us. You can imagine with a more complex feature, the code would be dramatically more than the RX solution. You can read an in depth analysis of this code in my next article “Unity3D Reactive Extensions 2“.


//--------------------------------------
//  Methods
//--------------------------------------
///<summary>
///	Use this for initialization
///</summary>
void Start ()
{
	// VARIABLES
	float maxTimeAllowedBetweenSingleCLicks_float = 1;
	float delayBetweenAllowingADoubleClick_float = 5;
	int clicksRequiredForADoubleClick_int = 2;

	// CREATE OBSERVABLE
	//(ORDER IS NOT IMPORTANT, BUT SUBSCRIBE MUST BE LAST)
	var mouseDoubleClickObservable = Observable

		//RUN IT EVERY FRAME (INTERNALLY THAT MEANS Update()
		.everyFrame

		//FILTER RESULTS OF THE FRAME
		//WE CARE ONLY 'DID USER CLICK MOUSE BUTTON?'
		.filter	(
			_ =>
			Input.GetMouseButtonDown (0)
		)

		//DID WE FIND X RESULTS WITHIN Y SECONDS?
		.withinTimeframe (clicksRequiredForADoubleClick_int, maxTimeAllowedBetweenSingleCLicks_float)

		//REQUIRE SOME 'COOL-DOWN-TIME' BETWEEN SUCCESSES
		.onceEvery (delayBetweenAllowingADoubleClick_float);

	//FOR EVERY EVENT THAT MEETS THOSE CRITERIA, CALL A METHOD
	var subscription = mouseDoubleClickObservable
		.subscribe (
			_ =>
			_onMouseEvent (MouseEventType.DoubleClick)

		);

	Debug.Log ("Subscription Setup : " + subscription);

}
//--------------------------------------
//  Events
//--------------------------------------
/// <summary>
/// SUCCESS: Double click
/// </summary>
private void _onMouseEvent (MouseEventType aMouseEventType)
{

		Debug.Log ("RX._onMouseDoubleClick() " + aMouseEventType);
}

Traditional Solution (Non RX)

This code requires us to ‘manually’ maintain state. You can imagine with a more complex feature, the code here would be even more long-winded compared to the RX equivalent. Thankfully we can use Coroutines, otherwise there would be even more state-specific variable setup to write and maintain.

/// <summary>
/// KEEPING STATE: Timing information
/// </summary>
private int _state_clicksInLastXSeconds_int = 0;

/// <summary>
/// KEEPING STATE: Timing information
/// </summary>
private bool _wasLastEventTooRecent_boolean = false;

// PRIVATE STATIC
//--------------------------------------
//  Methods
//--------------------------------------
/// <summary>
/// Update this instance.
/// </summary>
void Update ()
{

	// VARIABLES
	int clicksRequiredForADoubleClick_int = 2;

	//
	if (Input.GetMouseButtonDown (0)) {

		if (!_wasLastEventTooRecent_boolean) {

			if (++_state_clicksInLastXSeconds_int >= clicksRequiredForADoubleClick_int) {

				//SUCCESS!
				_onMouseEvent (MouseEventType.DoubleClick);

				//STATE MANAGMENT
				_wasLastEventTooRecent_boolean = true;
				_state_clicksInLastXSeconds_int = 0;
				StartCoroutine ("DelayBetweenAllowingADoubleClick_Coroutine");
				StopCoroutine ("MaxTimeAllowedBetweenSingleCLicks_Coroutine");

			} else {

				//STATE MANAGMENT
				StartCoroutine ("MaxTimeAllowedBetweenSingleCLicks_Coroutine");
				StopCoroutine ("DelayBetweenAllowingADoubleClick_Coroutine");
			}
		}

	}

}

//--------------------------------------
//  Coroutines
//--------------------------------------
/// <summary>
/// HANDLES TIMING: Between clicks
/// </summary>
private IEnumerator MaxTimeAllowedBetweenSingleCLicks_Coroutine ()
{
	// VARIABLES
	float maxTimeAllowedBetweenSingleCLicks_float = 1;

	// TIMING
	yield return new WaitForSeconds (maxTimeAllowedBetweenSingleCLicks_float);

	// STATE MANAGMENT
	_state_clicksInLastXSeconds_int = 0;

}

/// <summary>
/// HANDLES TIMING: Between clicks
/// </summary>
private IEnumerator DelayBetweenAllowingADoubleClick_Coroutine ()
{
	// VARIABLES
	float delayBetweenAllowingADoubleClick_float = 5;

	// TIMING
	yield return new WaitForSeconds (delayBetweenAllowingADoubleClick_float);

	// STATE MANAGMENT
	_wasLastEventTooRecent_boolean = false;

}

//--------------------------------------
//  Events
//--------------------------------------
/// <summary>
/// _ons the mouse event.
/// </summary>
/// <param name="aMouseEventType">A mouse event type.</param>
private void _onMouseEvent (MouseEventType aMouseEventType)
{
	Debug.Log ("NonRX._onMouseDoubleClick() " + aMouseEventType);
}

NOTE: The Unity source-code for this article is available (See ‘Member Resources’ below).

RX & Unity

Figure 3. RX & Unity

Figure 3. RX & Unity

RX is a library that can be theoretically ported to any language. It currently exists in many languages; prominently Java and JavaScript. There are C# ports, but unfortunately not all are Unity-compatible. Unity’s (latest version 4.3.4) C# is compatible with an OLD version of Mono – Mono v2.65 (versus the latest available v3.2.7). Mono is the open source version of .NET which powers the C# language features of Unity. So, while RX libraries in C# are plentiful, there is not yet a Unity-compatible library which contains all the features we would like to see. All examples covered int his article are from the amazing people at Tiny Lab Production (TLP). Their RX library is available for free download (See ‘Member Resources’ below). The TLP team actively encourage use of and contribution to their library

RX Integration

Uses of RX

My first experimentation includes creating mostly non-RX games with few distinct RX elements (particularly mouse/key/gesture input scenarios). RX can be peppered into your project selectively. With more experience and awareness I expect the community to embrace more systemic usage of RX in Unity games. Ideas for RX In Gaming;

  • User Input (Mouse/Keyboard/Touch)
  • Constraints (keep player character onscreen)
  • Loading Assets
  • Loading From Backend Services
  • Multiplayer game state synchronization (e.g. ‘Did every player in this game room click start?’)
  • And much more… see Reactive Game Architectures

Choosing an RX Library

The RX library you choose must match your platform of choice. For me that is Unity & C#. Due to the “RX & Unity” issues above I can’t simply choose any C# library. The library chosen for this article was created by the fine developers at Tiny Lab Productions (TLP). I continue to search for a Unity-friendly library that has the scope and syntax exactly matching Netflix’s fantastic RxJava implementation.

NOTE: The TLP Library used in this article is a work in progress. It features only limited functionality and does not conform to common RX standards in the naming, signature, and structure of major elements. The TLP team invites other developers to fork the library and contribute to it. Still it is a fantastic learning tool and quite useful as-is.

Resources

While RX is new to the Unity Community, there are tons of non-Unity resources and tutorials available. Its important to note that until a robust Unity-compatible RX library is available all of the functionality may not be available. Here are some resources;

NEXT STEPS: RX Syntax & Marble Diagrams

The RX example above uses combinators to empower the event stream filtration and modification. Deeper explanation is available in my next article “Unity3D Reactive Extensions 2“.

Member Resources

[private_Free member]Enjoy this members-only content!

[/private_Free member]

Unity3D MVCS Architectures: StrangeIoC 2

Unity3D is a powerful suite of tools (Project IDE, Code IDE, run-time) for game development. In Unity3D Game Architectures I present six different techniques for setting up your game. Depending on the size and maturity of your team, you are probably doing some form of those. I recommend checking that article out first, then read below. In Unity3D MVCS Architectures: StrangeIoC (recommended reading before continuing) we dove deep into the great, free framework. I also explored an idea I had for an extension called PropertyChangeSignal. Here is more;

PropertyChangeSignal

To aid my work with StrangeIoC, I created a few classes that function together to reduce the workload. I call this the PropertyChangeSignal. Again we saw above that signals are used for many things. Speaking from a model’s perspective for every property (variable) you want to update in your model you may need SEVERAL signals. That is fine in my demo above with exactly one property, but imagine a ScoreModel with 5 variables, a TimerModel with 3, and a GameLogicModel with 25 more variables. You can quickly grow a HUGE list of signals. Now, creating a signal is super quick. It takes 30 seconds to create, and another 30 seconds to optionally bind it to a Command. Its certainly possible to grow your app in this conventional way (or some variety of this conventional way). Most people do exactly that. But I wanted a start a discussion on a different way.

Here is an example.

Let’s say we have a public message string in your data model and the whole app needs to interact with it.

A. Conventional Signals Per Property (4)

  • 1. requestMessageSignal.Dispatch() – If a mediator arrives on the scene late and wants to KNOW the current value of message.
  • 2. clearMessageSignal.Dispatch(targetValue) – If a command wants to CLEAR the current value of message.
  • 3. updateMessageSignal.Dispatch(targetValue) – If a command wants to SET current value of message.
  • 4. updatedMessageSignal.Dispatch(newValue) – After any updates happen, the model sends this out to those listening who can GET the value.

B. PropertyChangeSignals Per Property (1)

  • 1. pcSignal.Dispatch (new PropertySignalVO(PropertyChangeType.REQUEST) )
  • 1. pcSignal.Dispatch (new PropertySignalVO(PropertyChangeType.CLEAR) )
  • 1. pcSignal.Dispatch (new PropertySignalVO(PropertyChangeType.UPDATE, newValue) )
  • 1. pcSignal.Dispatch (new PropertySignalVO(PropertyChangeType.UPDATED, currentValue) )

So in B, we see far less signals used (1 vs 4), but an longer syntax for the call. Soon I’ll request your feedback based on the source-code.

Update:  Download the full source below.

Syntax Example

1. CONTEXT – SETUP BINDING

commandBinder.Bind<GameListPropertyChangeSignal>().To<GameListPropertyChangeCommmand>();

2. COMMAND – HANDLE BINDING

public override void Execute()
{
	switch (propertyChangeSignalVO.propertyChangeType) {
	case PropertyChangeType.CLEAR:
		//ASK TO CLEAR THE MODEL
		iCustomModel.doClearGameList(); 
		break;
	case PropertyChangeType.UPDATE:
		//ASK TO UPDATE A VALUE IN THE MODEL
		iCustomModel.gameList = propertyChangeSignalVO.value as List<string>;
		break;
	case PropertyChangeType.UPDATED:
		//FOR THIS PROJECT, THE VIEW LISTENS DIRECTLY TO 'UPDATED'
		//OPTIONALLY, WE COULD ALSO DO SOMETHING HERE IF NEEDED
		break;
	case PropertyChangeType.REQUEST:
		//FORCE THE MODEL TO RE-SEND 'UPDATED' (WITH NO CHANGE)
		//THIS IS VERY COMMON IN APPS (E.G. A TEMPORARY A DIALOG PROMPT)
		iCustomModel.doRefreshGameList();
		break;
	default:
		#pragma warning disable 0162
		throw new SwitchStatementException(propertyChangeSignalVO.propertyChangeType.ToString());
		break;
		#pragma warning restore 0162
	}
}

3. MODEL – DISPATCH CHANGES

private List<string> _gameList;
public List<string> gameList 
{
	get 
	{
		return _gameList;
	}
	set 
	{
		//TODO: CONSIDER ALTERNATIVE THAT CHECKS "_gameList != value" BEFORE DISPATCHING
		_gameList = value;
		gameListPropertyChangeSignal.Dispatch (new PropertyChangeSignalVO(PropertyChangeType.UPDATED, _gameList) );
	}
}

4. VIEW – HANDLE CHANGES

private void _onGameListPropertyChangeSignal (PropertyChangeSignalVO aPropertyChangeSignalVO)
{
	if (aPropertyChangeSignalVO.propertyChangeType == PropertyChangeType.UPDATED) {
		doRenderLayout(aPropertyChangeSignalVO.value as List<string>);
	}
}

Video

Vimeo responded to TubePress with an error: Not Found

Member Resources

Members can access the full source-code for this post. Membership is free.

[private_Free member]Enjoy this members-only content!

[/private_Free member]

Protected: Unity Applicant Tests: (Private Name)

Category: Source Code     |     Tags: C#, Unity3D, UnityApplicantTest

This content is password protected. To view it please enter your password below:

Protected: Unity Applicant Tests: (Private Name)

Category: Source Code     |     Tags: C#, Unity3D, UnityApplicantTest

This content is password protected. To view it please enter your password below:

Protected: Unity Applicant Tests: (Private Name)

Category: Source Code     |     Tags: C#, Unity3D, UnityApplicantTest

This content is password protected. To view it please enter your password below:

Protected: Unity Applicant Tests: (Private Name)

Category: Source Code     |     Tags: C#, Unity3D, UnityApplicantTest

This content is password protected. To view it please enter your password below: