Standalone Tools & Unity Script

Introduction

On a few occasions now, I've been working on a Unity project and wanted to make a stand-alone tool that used some of the project's C# script files.

After a certain amount of trial and error, I've settled on an approach which works well for me, so I thought I'd share it here.

Prerequisites

  • Windows.
  • Visual Studio.  (I used version 2012)
You might be able to do something similar with MonoDevelop, but I prefer using Visual Studio.

Method

1. Create Tools Directory

Create a directory called "Tools" in your project's root folder.

{Project}
  |
  +- Assets
  |
  +- Tools

The C# files you want to share will be somewhere inside the Assets directory.  You shouldn't create a Visual Studio project in this directory too, because all its junk and intermediate files would become assets in your Unity project, which is not a good idea.

2. Create Visual Studio Project

Using Visual Studio, create a new C# command line application inside your "Tools" directory.

3. Link the Source Code

In the Visual Studio project, choose "Add Existing Item" (Shift+Alt+A), browse to the class you want to include, then click "Add As Link".


 This allows the project to refer to source code outside its own directory.

4. Conditional Compilation Directives

In the Visual Studio project, add directives which will only exist when the code is compiled using your tool.

> Solution Explorer
  > Project
    > Properties
      > Build
        > Conditional compilation symbols:


This allows you to wrap tool-specific code in:
   #if TOOLS
   ...
   #endif

and game-specific code in:
   #if !TOOLS
   ...
   #endif

Because you don't want to ship your game with the tools related code compiled in to it, since that would be wasteful.  As for the game-code, some of that might drag in classes you don't want to have to worry about in your tools.

5. UnityEngine

Your script code will invariably contain the line "using UnityEngine", and possibly refer to several Unity classes.

One approach would be to wrap those in conditional defines so they get excluded from the tool, but that would quickly get out of hand.

A better approach is to provide stubs for the tool code, for basic classes such as Vector3 etc.  This allows the game code to remain the same, and allows the tool code to function identically.

I have a small set of stubs at the moment, and if there's any interest then I might clean them up and share on github.

6. You're Done!

You can now compile and run both your game and your tool(s), sharing the same set of C# code!

Previous attempts

cut & paste

Just copy the script files into the project and butcher them until they compile.
  • Not a good idea for so many (hopefully obvious) reasons.
  • Arguably okay for throw-away tool that you literally just want to run once.

SVN extern

Use version control to isolate the code you want to share, then use Subversion's "extern" feature to refer to it from both the project and the tool.
  • Intrusive, in terms of your project's layout.
  • Fiddly to get working with Unity's version control systems.

Symbolic links

Use symbolic links to make the Unity project's source code appear inside the stand-alone tool.
  • Doesn't work well with version control software.

No comments:

Post a Comment