ECS for Unity: design notes + next prototype

Recently I’ve been thinking a lot about how a high-quality ECS would appear / present itself within Unity, how it would interact with standard Unity3d game-code at the API level, how it would appear in the Unity Editor, etc. This evening, I had a go at making some of that within Unity itself.

NB: a few weeks ago I made a small Editor Plugin that used Reflection to upgrade and fix some of the core Unity Editor code/GUI. That was practice for what I’m doing here. It’ll hopefully appear on the Asset Store at some point (pending review right now!) – it has the full source unobfuscated, so you can see for yourself both what and how I got it to do its clever bits.

Continue reading “ECS for Unity: design notes + next prototype”

Intelligent “new (thing)” control for #unity3d

In Unity, hundreds of times a day you do “new (folder)” or “new (C# script)” etc. But Unity makes this ridiculously hard: you have to hunt and peck a tiny button and then hunt-peck a tiny item in a huge dropdown that is very easy to miss.

And you can’t do any of this from the keyboard. Even though you’re fully in keyboard mode and about to write the name of the New Thing (required!) and if it’s a script: type in the source code.

Screw that.

UPDATE: Now available in Asset Store – get the source

For a mere $2, I will Intelligent New you long time:

Source is included. If you want to see how I did it, knock yourselves out…

My context-sensitive New for Unity

So, what I’ve made today:

intelligent-new-demo-1
intelligent-new-demo-1

  • Select any folder or object in the Project window
  • Hit “shift-N” (because Unity sucks and steals Ctrl-N and refuses to let you choose a better one. Stupid stupid stupid.)
  • A popup appears pre-filled with a sensible new file name OR folder name
    1. If you were on a folder, it prepares to auto-create a new folder
    2. If you were on a script file, it prepares to auto-create a new script
    3. The name is pre-selected and editable, exactly as with Unity built-in
  • Sometimes that intelligent guess above will be wrong, so … hit Tab, and it switches type, while keeping the text selected and editable

Net result: super-fast workflow for creating new scripts and organizing your project.

(This required an ungodly amount of hacking and trial and error to work around bugs, bad documentation, and obvious missing core features from Unity APIs. But it works, and seems to be pretty seamless now)

Implementation Notes

A subset of the things I discovered / re-discovered on the journey to this one small fix / improvement:

  1. AssetDatabase.CreateAsset is basically broken: can’t create C# scripts at all. Don’t try.
  2. ScriptableWizard is unusable in Unity less than 5.0, because they made a core method private / non-overridable. Don’t bother.
  3. You can find the Project window and others by doing a reflection on the Assembly to find the magic C# Type of known Unity private classes (that SHOULD BE public!) and comparing at runtime. Hoops? Jumping through? Because an API has something private that should have always been public? Welcome to Unity customization! :)
  4. You can find the exact position of the selected row by adding yourself as a callback on Unity’s own row-by-row rendering of their built-in windows, and saving the data every frame. Sounds scary; works great (one of the few bits here that is a perfect hack with no downsides)
  5. Popups need you to create a new class, and that class MUST BE in file of its own or you will break Unity (internal bugs in Unity window management that trigger when you reload/restart Unity)
  6. …if you trigger that bug (or in any way end up with floating, non-closeable windows), go to the Layout menu and re-select the layout you’re already using. It will kill any unexpected windows. Phew!
  7. Unity still hasn’t made the Indent width (in pixels) public. The documentation insults you by saying that when you hardcode the number 20 this will break your code in future. YES, WE KNOW. SO MAKE THE DAMN NUMBER PUBLIC, YOU BASTARDS.
  8. There is a 2 pixel top and bottom padding needed to surround textfields in 1-line popups. I hardcoded this, it may have a number somewhere in the API. Good frickin’ luck trying to find it. Given the taunt about indents above, I very much doubt it is public.
  9. If you have a button or non-editable textfield with a changeable title, or anything that can be changed by a keypress during rendering, it is critical that in OnGUI you read Event.current.type and switch() on it. As far as I can tell, this has never been documented except in forum threads and blog posts by Unity staff. Once you know about it, you can sort of guess it from reading the undocumented bits of the API, but it’s damn hard to find references to it online. (I found it years ago by trial and error and blind luck). Until you do this you get race conditions when changing GUI based on keypresses. Ugh.

    Compatibility

    Critically, this (should) work no matter how much I customized Unity elsewhere. It’s peeking into the actual window and render areas to decide what to popup and where on screen.

    The only conflict I expect is one that – thanks to some brainfart design at Unity corp – we can’t workaround: I had to hardcode “shift N” as the keyboard shortcut :(.

    Want it yourself?

    I thought it would take me about 10-20 minutes to do. HAHAHAHAHAHAAHAH! If I’d done this as a client project, I worked out it cost almost $1500 in billable hours. Ugh.

    I’m going to use this in production for a while. If it continues not to break or corrupt anything, I’ll put it on the Asset Store.

    Next up…

    …I’m going to do some context-sensitive New for the Hierarchy window, I think. Now that I have these hacks working, that’ll be quite a lot easier.

#Unity3d’s missing core: No runtime objects

Here’s a game:

  • Player
    • Inventory
      • Gun 1
        • AmmoHolder
      • Gun 2
        • AmmoHolder

Some of those are 3D visual objects: Player, Gun 1, Gun 2.

Some of those are abstract concepts, or data: Inventory, AmmoHolder.

(in a Diablo clone, the Inventory might be a visual object, but only when you bring up the popup-window to display it. By contrast, in a simple FPS, your inventory may not be displayed at all – no need for it!)

Unity cannot handle this situation.

What you need

Classes:

  • PlayerClass
  • InventoryClass
  • GunClass
  • AmmoHolderClass

In Unity, you have to make “everything” extend MonoBehaviour. That’s fine for PlayerClass and GunClass: you make a dummy GameObject for each, place it into the scene, and attach the class as a Component.

But that’s impossible for InventoryClass and AmmoHolderClass: if you make them into MonoBehaviours, Unity prevents you from using them as standard classes any more:

  1. Cannot instantiate them
  2. Cannot use Garbage Collection

…because they have no GameObject to be attached to – they don’t exist! They are abstractions only.

This is core to programming: we use abstractions all the time. Without them, coding would be horrendously inefficient both for the programmer and (to a lesser extent) for the computer.

What Unity offers

You have three alternatives here:

  1. Create fake GameObjects anyway. Put them “somewhere”. Work really hard to make sure they never accidentally appear in front of the camera (!), or interact with the scene due to physics (!), etc
  2. Use plain C# classes. This is an extremely bad idea: Unity has never supported C# classes for anything; Unity has a custom memory-management solution (called, slightly confusingly, “Serialization”) which is incompatible with plain C#. It requires every object to extend Unity.Object. You can workaround this; it requires major work and is very hard to get right.
  3. Use ScriptableObject, which appears to have been invented for this. According to many Unity developers: “this is what ScriptableObject is for”. However, that’s wrong. Very wrong.

ScriptableObject to the rescue?

So … ScriptableObject is something that extends UnityObject (fixing the problem of “plain C# classes aren’t compatible with Unity”), and you can use in a Scene, and can be referenced by MonoBehaviours, and just work, right?

Wrong.

ScriptableObject is all those things, except: it doesn’t exist in the Scene. It’s an Asset.

This is where Unity docs really screw the pooch. We know for a fact that an SO is an Asset; when we try to use it like a MonoBehaviour, several things break and stop working.

…but it also “kind of” works in-Scene. The docs have no explanation for this. What are the limits? Well, basically: no-one knows, except through trial and error. This is so core to your code that it sometimes instead means:

trial and oh-crap-that-didn’t-work-time-to-rewrite-every-damn-class

Why is Asset-hood so bad?

You already have all that – it’s called the Class – and to have an Asset too simply creates problems:

  • An Asset is a special thing in Unity. It interacts with Unity’s core systems in very different ways to a C# object. Building, runtime Loading, editing in the Editor – all are “different”.
  • You can’t create them in the Editor. (you can write your own hack/script to fix this. It’s only 10 lines of code. But … yeah. It’s a hint that this isn’t what Assets are intended for)

But .. what’s ScriptableObject for?

Unity’s official docs are rather … incoherent … on the subject. My guess is that they were written by someone who didn’t really understand ScriptableObject, and was looking at the source code thinking:

WTF is this? Um. Err. Well … it kind-of seems to sort-of do … this? Maybe?

…and worked it out from observation.

What the docs are TRYING to say is:

(gross over-simplification here to make things easy to understand): Unity’s memory-management COPIES every instance many times, and doesn’t support pointers/references.

This is a HUGE problem in game-development.

ScriptableObject is a workaround that uses diskspace to make templates out of objects, and then simulates pointers by using one shared-file on disk to hold the data for thousands of in-game objects.

This works very well, because the way we built Unity’s core architecture (3D Meshes, Textures etc) already supports that workflow: File-on-disk generates optimized in-memory-object, which is shared/batched wherever possible.

Going off on a tangent, it waffles about “ShopStore” and “Multiple Scenes” and stuff that the author clearly didn’t really understand. The obvious way of implementing what’s described in the docs is many times simpler, and works much better – you would never do it using ScriptableObject.

What the docs perhaps should have instead said was:

You can also abuse this system to make hardcoded fake in-scene objects that don’t have to be attached to a GameObject.

This will fail if you have any Procedural Content – but Unity was specifically designed never to be used in games that have procedural generation, and no-one should be doing procedural work in Unity, so that’s fine.

Wait … what? What do you mean “we all do procedural generation”? Wh … why? Why would you do such a thing? do you have any idea how slow that will be in Unity? Most of our code assumes everything is done at compile time! We can’t handle dynamic code!!!

(NB: Unity used to be really, really bad at procedural work. Way too slow. There’s really no reason not to be doing tonnes of procedural code in Unity games today – except that Unity itself still has a load of political blocks on it. It doesn’t support procedural properly in places where it could)

ScriptableObject is great, but most game-development works with procedural content. I’m not talking about complex cool stuff like Sir, you are being hunted. I’m talking about stuff like:

The set of objects in your inventory changes from moment to moment while you play the game. Because otherwise it would be a pretty boring game

When you try to use ScriptableOject here, you are abusing it. It’s not intended for that, it doesn’t work correctly with that, and it’ll make your life hard. IT’s not ScriptableObject’s fault; it’s your fault.

What does Unity need?

At a conceptual level, Unity has:

  • “Physical Runtime objects”: things that have 3D physical presence in the editro (not Physics as in “Physics Engine”, but rather: everything has a Transform)
  • “Runtime OOP Objects, dependent upon GameObject”: generated from OOP Classes (but MUST be attached to a Physical Runtime object)
  • “Compile time OOP Objects”: these are Unity Assets, and can be used for some performance and coding tricks. They are they poorly-documented ScriptableObject, and should probably have been named ScriptableAsset in the first place since they are absolutely not Objects!

What’s missing?

  • “Runtime OOP Objects, independent of GameObject: the classic “Object” from OOP.

I think … not sure, this seems obvious, but if so: why is not already the case? … I think: Unity should be saying “make your classes extend ‘Unity.Object’, and then use them. All will be fine. We’ve made it work under-the-hood; trust us, guys, it’s cool. Everything’s cool.”.

My guess is that’s some internal bug with Unity Serialization that makes this untractable. Maybe something like:

GUESS: Unity Seriailization is internally hardcoded with a fixed number of recognized classes, somewhere, that can only be added to by hardcoding new ones. Because we don’t have access to Unity’s source code, we cannot re-generate those, and the Unity Editor (for same reason) can’t do it for us.

So: our legitimate C# classes can never be fully treated as a Unity Class.

Instead, Unity has to support a fixed number of hardcoded classes (O hai! ScriptableObject, MonoBehaviour), and those have to use reflection tricks at runtime to provide (limited) support for the infinitely many user-authored clases from C#.

OK, so this is slightly more than a “guess”. They have form here: When trying to figure out some obscure Unity Serialization bugs, I found some places where Unity would load extra, hidden, information for particular Unity classes. There was nothing in memory on this, suggesting that they had hardcoded a lookup for their set of “known” Unity classes, and were getting the data that way.

…but that’s the kind of thing that’s going to be a genuine mind-f*ck to try and unravel. This makes me inclined towards it: even with the money and resource Unity has, it would be non-trivial to fix. And I’m pretty sure no-one likes the status quo.

Conclusions

We’ll just keep writing source code like it’s 1999:

  • Use C# as if it’s C
  • F*ck Garbage Collection (we can’t have it :( Sob.)
  • Manually memory-manage the scene and objects; make everything a GameObject, and manually Destroy() everything each time you replace it or it goes out of scope
  • As a bonus: the Unity Editor has much better support for Developing and Debugging games which use GameObjects than it does for any alternatives (C# Classes; ScriptableObjects)

I’m crossing my fingers that Unity version 6 will dump Serialization, and this problem will go away. Like magic, Unity will fully support C# (Dictionary’s! Objects! Garbage Collection! YAY!)

…of course, by then, I might have finally switched to Unreal. Because frankly I’ve got better things to do with my life than work in low-level programming languages!

Some thoughts on loading Scenes in #unity3d

How do you program a “level”?

This is not usually a problem in a game engine, but Unity requires you to isolate each “level” as a Scene. And Unity’s Scenes have some strange design choices (bugs?) – IMHO they were designed for toy projects, not for production games.

Here’s a stream-of-consciousness on what works, what doesn’t, and how I can workaround / do it better within Unity… it’s not carefully researched, mostly it’s from memory / off the top of my head. So … it might not all be true :).

When I switch to Unreal4, I’ll be using posts like this as a baseline to compare where Unity failed, and how badly – or vice versa.

UPDATE: added some more approaches and ideas/commentary

Continue reading “Some thoughts on loading Scenes in #unity3d”

Fix #Unity3d’s broken OnMouseDown

This one has annoyed me for years: Unity’s OnMouseDown has never really worked. (NB: it works perfectly if you make a scene with a single cube; but that is not a game. It breaks completely as soon as you add multiple objects, colliders, etc to a scene)

The main reason to use a 3rd party engine is to avoid re-inventing the wheel; it’s tragic that Unity can’t even do mouse-input out of the box. Let’s fix it!

Continue reading “Fix #Unity3d’s broken OnMouseDown”

Unity3D: display a variable instantly on screen

You need this ALL THE TIME when developing, and Unity lacks it as a core feature:

  1. Create a Text label on your GUI
  2. Drag/drop a variable onto the label, and it will automatically display the value

Completely impossible, due to short-sighted design decisions in the Unity Editor from 10 years ago that never got changed. So, let’s fix it. It’s hugely annoying not being able to do this!

Continue reading “Unity3D: display a variable instantly on screen”

#Unity3D plugin review: Advanced Inspector

The author of Advanced Inspector gave me a free copy over Christmas. I’d considered it many times, and always ended up choosing not to buy, and write my own fixes/workarounds instead. So I was keen to try this out on a hobby project and see how well it works in practice.

What is it?

A replacement for Unity’s built-in Inspector. This (optionally) changes the editing interface for every single Component in your Unity projects.

Why do we need it?

When you run Unity, you get the standard multi-pane IDE that is the Unity Editor. Whether you’re a programmer, a designer, or an artist, this is your main portal into Unity, and the starting point for all your work.

Anything you select in the 3D/2D scene causes an Inspector panel to appear, with all the editable data about that thing. Unity’s built-in Inspector is very basic; by modern standards of GUI/UX, it sucks. Fixing GUI is very expensive, so instead … Unity has gradually been making the Inspectors more and more customisable.

Traditionally this was very hard to do; in the last 12 months it has become much easier, and Unity has unlocked more features. To date, I’ve not been sure if the 3rd party plugins are fully using the new features.
Continue reading “#Unity3D plugin review: Advanced Inspector”

Unity’s failure as an Entity System, example 1: Selecting things

Entity Systems in Unity… some examples of the problems

This is a new series of blog posts, where I’m going to document specific ways + concrete examples in which Unity fails (sometimes spectacularly) as an “ECS” game engine.

I like Unity; but the core architecture (which is very old) is a half-assed ECS, and if we’re to upgrade it into a really good, modern, architecture … we first need to understand exactly where it’s failing, and why.

So, let’s start with Selecting Things…

Background

Game

A 2-player card game where each player normally draws a card each turn, and then plays one or more cards. Sometimes (e.g. when discarding because “too many cards in hand”) they have to select more than one card at once.

Initial version of game will be 1-player versus computer. Very soon: want to upgrade to OPTIONAL 2-players on-screen, with one using the mouse, other using gamepad. Ultimately, want to also add over-the-internet multiplayer (which ends up interfacing with the codebase in a very similar way to the original 1-player-vs-computer, so we can ignore for now).

Code Situation

Player taps card. Now … we must inform many other scripts and independent systems, so they can choose to eg.

  • ignore (if invalid for current state of game)
  • react (e.g. zoom to display the card more clearly)
  • “select” internally (side-effects include: deselect other things)
  • advance the game (if it was waiting-for-input)
  • ..etc

Problem

What/where do you send the “player clicked on a card; can some piece(s) of code PLEASE deal with this??!!?” ?

Addendum

In Unity, only the low-level “card” object can sensibly detect it has been clicked on.

Both Unity’s Physics (old) and EventSystem (new) effectively force this via their core design. Both require you to attach scripts to the physical objects that will be clicked.

In practice, this is bad for OOP (and bad for ECS too). When there’s e.g. 100 cards all of which must be separately clickable, your code is really in the wrong place. You don’t want cards (which sometimes are in a deck, sometimes on the table, sometimes “virtual” (perhaps in a virtual, unopened booster pack etc)) … to be containing all the GAME logic required to know what to do when they’re touched!

Classic Entity System / ECS solution

  1. Create a SelectedByPlayer component
  2. Add it to the card
  3. Sit back, and relax. Code that cares about input will scan “get me all SelectedByPlayer components” on each frame, and react accordingly

Everything works automatically; any System/Processor that’s “waiting for a selection”, or “making render changes when selections add/remove”, etc … will pick up what it needs, with no work.

You can add new input-handling routines simply by adding them. That’s all. No other changes needed.

Attempting to solve this in Unity

UNITY 4.6/5.0

Maybe … NB: I’ve only just started using the new GUI/EventSystem in Unity 4.6+ .. create a custom Input event, and a custom InputModule that can understand that, and then put all the code for ALL affected systems/processors into one monolithic ugly, hard-to-maintain script from Hell.

I suspect that this code will be quite maintainable w.r.t. adding new Input hardware in future – e.g. allowing mouse vs gamepad. But it’s going to suck at the rest, all the business-logic and handling. Which is going to be > 95% of the maintenance cost.

You get one small benefit: you can separate-out different inputs (click versus drag). Sadly, in reality: 95% of game actions will be simple clicks. This is one of those “the code architecture sounded great in academic situation, but reality is so unbalanced, it works out less well in practice” situations.

This is a classic OOP solution, and has the downsides. The only significant benefit I can think of is that it’s a “known” Hell: if you’ve done a lot of OOP game coding, you’ll be familiar with the pain you’re going to run into.

UNITY CLASSIC

Make a new class “CardClickManager” whose sole purpose is to reference all the possible bits of OOP code that “might” need to react, and which has to be updated by hand EVERY TIME you modify, add, or remove some input-handling code ANYWHERE else in the codebase.

Pretty much the same as above, except it:

  • … is even more simplistic (no event-dispatch systems)
  • … making it even harder to maintain + debug
  • … is slightly more proprietary

Conclusions / Improving Unity

So far, I cannot think of any sane, maintainable solution here other than “suck it down and use OOP, and suffer forever”, or “throw away Unity GameObject/Component, and implement a proper ECS”.

That’s fine, though. That’s the point of these posts – to hilight situations where there’s no good middle-ground, where we must create the data-centric, cleanly-separated architecture of a modern ECS.

Counter-ideas very welcome! Comment away, guys…

Towards a Unity3D ECS: what GUI? What features?

This year, one of my goals was to build a sane, powerful, viable Entity System / Entity-Component System within Unity3D. Something I could build current and future games on, and save a lot of dev-time (both in ease-of-use and in easily adding missing features that I wish Unity had).

So, progress?
Continue reading “Towards a Unity3D ECS: what GUI? What features?”

Debugging A* Pathfinding in Unity

I needed fast, efficient, … but powerful, adaptable … pathfinding for my hobby project. My minions have to fly, walk, crawl, teleport, tunnel their way across a procedural landscape. Getting to that point has been tricky, but the journey’s been interesting.

We want something that intelligently routes creatures around obstacles, and picks “shallow” routes instead of scaling cliffs (or vice versa for Giant Spiders etc). Something like this:

Screen Shot 2014-08-10 at 20.09.36

Continue reading “Debugging A* Pathfinding in Unity”

World-exploration game, done differently

Inspired by Markus / @notch, and how he got MineCraft going in the early days, I’m live-prototyping a game idea I’ve been thinking about for ages. It’s about exploring a landscape … where cities affect dungeons, and dungeons affect cities.

(this is stress-relief for me, an “evenings and weekends” project. By day, I’m helping Schools teach children to program, but that’s HARD (no investors, lots of costs – at the moment, I get paid nothing))

Play in web browser here (very early prototype!)

Screen Shot 2014-07-25 at 12.31.23

July 2014

Current build focusses on the “City building” interface. Initially, you won’t be building cities, you’ll be building small camps / trading forts, etc. So this lets me play with the interface, the scale, the rendering, etc. Make sure it’s fun.

Create something – but take screenshots! Because there’s no “save” yet. Super-early prototype.

Long term gameplay

  1. Explore a huge landscape in FPS
  2. Any location, “create a camp”, and it switches to the isometric view you see in current demo. Build yourself a home/fort/etc.
  3. Fast-travel between locations, but this triggers “random encounter” events … or run between locations manually.
  4. Turn-based / DungeonMaster style dungeons are randomly generated near to each camp. Explore the dungeons for resources and to level-up.

Unlike e.g. Skyrim … when you find an interesting location, you can’t fast-travel to it. You have to build a camp next to it, and fast-travel to that. But your camp can be overrun/destroyed/stolen while you’re away.

So … you’ll be building (and maintaining) a lot of bases around the world. I want to be sure that base-building is easy and fun, even after you’ve done it lots of times already, before progressing with the rest!

(I’m trying to make it “repeatably fun” by having the landscape HUGELY affect your base design)

How to tidy your Unity code by putting it in a DLL

The importance of Re-use

Here’s a story that may sound familiar:

You downloaded Unity, watched some tutorials on YouTube, and had a physics “game” running the same day. Excited, you started writing the game you’ve always wanted to make. Possibly – bitten before when trying this with GameMaker etc – you thought to organize your source code: folders, subfolders, logically-named scripts, etc.

Fast-forward a few months, and you have 50 scripts in 40 sub-folders, some of it re-usable, some of it hardcoded for your game. Hoooo-Kayyyy… Well, it’s not too bad. And then a new opportunity comes along – a paid contract, a game-jam, a collaboration with a friend – and you want to re-use some code from your main project. You look at the folder structure, you look at how intertwined it’s all become … and you weep.

Without re-use, what seemed like an “easy” project becomes just a little too much work, and you never finish it. Back to square one :(.

Code re-use in Unity

There are five major aspects to code re-use when making Unity apps. Most of these are shared with general programming, but these are the ones I’ve found *especially* important when doing Unity development.

Good names

The best way to get good at naming things in a program is to focus on “what makes a bad name”, and “Don’t do that”. e.g.

  • If you have to open a Script to remember what it does … it has the wrong name.
  • If you keep typo’ing the script when referencing it in other scripts … it’s the wrong name
  • If your script is more than a thousand lines long … it’s the wrong name AND you’ve put too much junk in there; split it!
  • If you can’t find a script, because you can’t remember which folder it’s in … the folder name is wrong, AND the script name is wrong (should have been a name that forced you to put it in the right place first time!)
  • …etc

Renaming scripts in Unity is a minor pain: you rename it, then you have to close the file in MonoDevelop, re-open it, and (assuming it was a C# class) rename the class in source-code too. (I keep hoping latest Unity will do this automatically, but I’m a version behind at the moment).

We need Sub-folders. Lots of Sub-Folders

… you can never have too many. Give them good names, though!

De-couple your code

Ah, now it gets tricky. The art of decoupling takes much practice to master.

Decoupling is why C# (and Java) has the “interface” keyword. The concept is much easier to understand after you cocked it up, written code you can’t re-use, because everything’s too inter-dependent.

“I can’t just copy/paste that script to my new project, because it references 3 other scripts. Each of which … references another 12. ARGH!”

Unity itself doesn’t use Interfaces (though it really ought to!) – and you have to use a little ingenuity to use them yourself (Google it, it’s only a few small caveats). But C#-interfaces simply give you a compiler-compatible way of decoupling: you have to design your classes as decoupled to start with. Again, google this and ask around – it’s too big a topic for me to do justice to here!

Package your code, so you can re-use it

Libraries. This is why The God Of Programming invented Libraries. So, how do you do a Library in Unity?

Libraries in Unity: the easy DLL

There are two kinds of DLL’s:

  1. Real DLL’s, as used by Real Men, who write all their code in C++
  2. Fake DLL’s, as used by the rest of us, who just want an easy life so we can focus on making our game

A DLL is a great way of packaging code – it’s a very widely-used standard. So, Unity uses DLL’s for this (good move) – but if you google “Unity make DLL” you’ll get distracted by the huge complexity and depth of C++/Unity integration, and you don’t need any of it. Instead, you’ll be doing “DLL light”, which is easy.

But, as with most Unity features, it’s almost entirely undocumented. And, out of the box, it will fail. For bonus points, Unity will give you completely the wrong error message when it goes wrong. Yay!

Step 1: write a Unity script in Unity

Do something simple. I wrote a class that makes random numbers, following XKCD’s advice:

using UnityEngine;

/** In Unity 3, you cannot have namespaces. So comment out this next line. Unity 4 is fine */
namespace MyTestDLL
{
	public class DLLClass
	{
		public static int GetRandom()
		{
			return 4;
		}
	}
/** In Unity 3, you cannot have namespaces. So comment out this next line. Unity 4 is fine */
}

Make a second script that uses that first one, e.g.

using UnityEngine;

public class TestScript : MonoBehaviour
{
	void Start()
	{
		print( DLLClass.GetRandom() );
	}
}

…attach it to a GameObject, check it works.

Step 2: follow Unity’s docs on creating and using a DLL

You’d think this would be enough, but it isn’t. However, the docs are simple, direct, and I found them easy to follow.

So http://docs.unity3d.com/Documentation/Manual/UsingDLL.html = read this and do what it says

NB: they write a slightly more complex script to use than mine, with but whatever. The idea is the same.

Step 3: Use the namespace, Luke. And Interfaces. And …

Now that your DLL is compiling/building in MonoDevelop … you are no longer stuck with Unity’s arbitrary rules and restrictions! The world is yours!

(so, even in Unity 3, you can now use the namespace. Which makes it MUCH easier to keep your code well-organized ;))

Step 4: What about the [square brackets]?

These Just Work ™ exactly as they did in Unity scripts. e.g.

using UnityEngine;

namespace MyTestDLL
{

/** Hey! Look! Unity editor-features ... coded outside of Unity */
[ExecuteInEditMode]
[System.Serializable]
	public class DLLClass
	{
...

Step 5: Editor extensions, editor scripts, editor GUIs, etc

This is where it breaks. If you had any Editor scripts (which, in Unity, MUST be stored in the “Editor” root folder, or one of its subfolders), you can include them in your DLL – but they won’t work.

Worse, when you trigger them (e.g. by selecting a GameObject that did custom editor rendering), you’ll get:

Error: multi-object editing not supported !

…at least, you do in Unity 3.x. Fixed in 4.x, I suspect? But I haven’t gone back to try it since I fixed the bug :).

There is some mumbo-jumbo on the internet (and Unity forums) about complicated workarounds, notably courtesy of AngryAnt (with a Jan 2014 post here, with some extra info worth reading but NOT required!). But these are long-since outdated and unnecessary. The fix is very simple: we must create TWO DLL’s!

  1. DLL #1: the one we already had
  2. DLL #2: will contain ONLY the editor-scripts, and we’ll drag/drop it into Unity’s “Editor” folder.

This is extremely logical, simple, and easy to remember. And it works beautifully! But .. how?

Step 5a: Upgrade MonoDevelop project to output not one, but two, DLL’s

First, right-click on the top-most item in MonoDevelop’s “Solution” panel, and select “Add New Project…”:

Screen Shot 2014-05-24 at 20.54.53

As you did earlier, choose “Library (C#)”. I recommend naming this “SomethingSomethingEditorScripts” (where “SomethingSomething” is your library name, which you used for the first DLL).

Second, you need to edit the References (as you did with first DLL), and this time repeat the steps and add ALL of:

  • UnityEngine.dll
  • UnityEditor.dll
  • AND: instead of the “.Net Assembly” tab, use the “Projects” tab and select your main DLL/library. It should be the only option

That gives you something like this:

Screen Shot 2014-05-24 at 20.58.22

…see how I have two “projects” in MonoDevelop, one which just uses normal Unity stuff, the other which additionally uses Unity Editor stuff? And the second one “references” the first, so it can see/use/create the classes and methods from the first one.

Step 5b: Put the DLL’s in different places

Build, and find the output files. The first project/DLL will still only be making one DLL, but the folder for the SECOND project/DLL will conveniently build BOTH projects and contain BOTH DLL’s.

Make sure you put one DLL “anywhere except Editor” and the other one “in Editor, or a subfolder of Editor”.

Finally, create some GameObject’s, open up the DLL’s in Unity’s Project view (expand the triangle) and drag/drop the Scripts onto your objects as desired. Click on them in the Scene view, and all your OnGUI, OnGizmos etc methods should run exactly as normal.

Step 6: Rejoice!

Now you can share your code with other Unity projects simply by drag/dropping the 2 x DLL’s into a new Unity project. BOOM!

Beautiful! Easy, simple, impossible-to-screw-up ;). That’s how I like my code re-use…

JumpTest v0.2 (different jumping algorithms in Unity)

New version up on the webplayer link:

Screen Shot 2013-08-14 at 18.46.23
http://t-machine.org/web/WebPlayer-jumptest/WebPlayer.html

Test jumps

Proving quite fun just playing around with it and testing different jumps:

Screen Shot 2013-08-14 at 18.56.00

Screen Shot 2013-08-14 at 18.54.41

User-aimed jumping

Two jumps in a row using the same algorithm, but it aims your jump based on where you’re looking when you hit the spacebar. In this case, second jump I flicked the mouse up at last moment before jumping, giving a higher/longer arc:

Screen Shot 2013-08-14 at 18.53.35

Mirrors in Unity Free version – almost works

UPDATE: see end of post for another idea…

One of the ways they make you buy Unity Pro is gimping the non-Pro version by taking away Stencil Buffer and Render-to-Texture (needed for … many (most?) of the truly interesting effect you can think of). Except … it’s only needed by old-school OpenGL programmers, because everything RtT does can be mimicked in Shaders. Stencils … maybe also?

Anyway, I’m working on a hobby project and don’t need or want the Pro version for now (I’d like to support Unity, but these days the jump in price is way too expensive, at $X000 (they price-gouge you if you’re purchasing from within EU) for a simple hobby project). If/when we’re using it at work, and I have lots of cash, sure – but for now: can’t find that much money.

For the most part, I’m happy to go without RtT for now – generally speaking, hobby projects don’t “need” those kind of effects (and if they do: maybe it’s not a hobby any more?). There’s just one exception: reflections.
Continue reading “Mirrors in Unity Free version – almost works”