blog.Tiaan.com   Web log of Tiaan Geldenhuys

CSI is a simple C# interpreter that was originally developed by Steve Donovan and it works similar to the more recently developed C# interactive shell of Mono, named CsharpRepl. For a while I’ve been making some improvements to CSI and recently developed a plug-in/script version of it for Unity, the 3D game-development environment, which is compatible with the older version of Mono that Unity makes use of. The plugin allows one to execute C# code in an interactive console while the game is running, which can assist with debugging and be used to explore the runtime environment. The software is known to work on Unity 2.6.1 in both the Editor application and Standalone Player on Windows, but it might also work on the Mac OS. It also works on Unity 3.0.0 and 3.1.0 for PC (as of CSI version 0.8.24.3), as long as your project’s “API Compatibility Level” is set to “.NET 2.0” (not the default “.NET 2.0 Subset”).

Download and Install the Plugin

The CSI plug-in is available as a free download and released as open-source software under the MIT License. It is distributed in two formats: a ZIP file and a Unity Package, each containing the four files that need to be installed somewhere under the Assets directory-structure of your Unity project. If you prefer the packaged version, import the files into your project through the Unity Editor’s “Assets | Import Package...” menu. Alternatively, you can decompress the ZIP file’s content into an assets subdirectory, for example “Assets\Plugins\CSI” underneath you project’s root folder. After installation, you should see something in your Project window that is similar to the image shown; it represents the four files of the plug-in:

• CSharpInterpreter.cs
• CSharpInterpreter_Include.txt
• interpreter.cs
• prepro.cs

The first file, CSharpInterpreter.cs, is the primary script that implements the hosting environment for the C# Interpreter, which is a Component that can be attached to a GameObject in Unity 3D. For example, to get the interpreter GUI to show up at runtime, use the “GameObject | Create Empty” menu item in the Unity Editor, which would result in a new GameObject being shown in your project’s Hierarchy window; then drag-and-drop the CSharpInterpreter script from the Project window onto your new GameObject to attach the script to the object. You can now “Play” the scene and should see the interactive console’s user interface (discussed in more detail in the following section).

By default, the CSharpInterpreter_Include.txt file gets included during startup to configure the interpreter environment. It specifies additional namespaces and assembly references that must be included, as well as macros (such as print) that can save you some typing. You can edit this text file to tweak the interpreter environment to your liking – each line in this file is effectively processed as if it were provided manually as input to the interpreter, one step at a time.

The remaining two files, interpreter.cs and prepro.cs, contain the underlying CSI interpreter and preprocessor code that provide support for the CSI game component. You would rarely need to work with them directly.

Runtime User Interface

Once you have the CSI plug-in for Unity installed and running, its runtime user-interface will display as overlay controls shown on top of your game scene in the background – for example, see the screenshot below.

At the top is the interpreter’s output window, which is a read-only text area where additional output gets added at the bottom while the older output scrolls up. You can navigate to this area and copy some of the output text if you want.

Below the output window, on the left side, there’s a large toggle button that can be used to show or hide the rest of the GUI. You can either click on the button or use the default Alt+F2 shortcut to toggle the display state. Underneath the main toggle button you’ll find a couple of small buttons: the one on the left is a regular button that can be used to clear the output window when it gets too cluttered, the remaining buttons are all toggle buttons. Hover over the buttons with the mouse pointer to see tooltips that are shown in the bottom window to describe their purpose. The small toggle button at the top would show or hide the output window, and the one at the bottom does the same but for the tooltip bar. When running in the Editor, a third toggle button appears between these two and it controls whether the resulting objects that are returned by the interpreted C# code would be selected automatically in the Editor, for example to allow for additional editing or viewing through the Editor’s regular inspector windows.

The remaining text area is the input window where you enter the code to be interpreted. While the input window has focus, a number of keyboard keys are interpreted in special ways. For example, hitting the Enter key would send all of the input text to the C# interpreter for processing and typically result in code execution. To enter line-breaks in the input window, you can use Shift+Enter, but you can often also feed multi-line input to the interpreter in multiple steps using the Enter key by itself between steps; doing so, the prompt displayed on the large toggle-button would change from “>>>” to “...” that indicates the continuation state of the interpreter, as illustrated below.

>>>  for (int i = 1; i <= 3; i++) {
...  print(UnityEngine.Random.value); }
0.4331492 
0.1738945 
0.5771966 

Hitting the Enter key without any input text would reevaluate the previous input. You can use the up and down arrow-keys to navigate to previous input and then copy or edit it. To move the cursor between lines in a multi-line input, you need to hold down either Ctrl or Caps-Lock while pressing the arrow keys – it can take a while getting used to it, but even if you slip up and accidently navigate your history instead of the input lines, you can simply navigate the history in the opposite direction without losing earlier changes to the input text.

The input box also implements a rudimentary auto-completion or help system that gets triggered through the Alt+F1 shortcut; however, the context is typically the result of the previous step’s code (and not so much the current input text). What this means is that, to use this functionality, you’ll often end up executing an expression in incremental steps, each time navigating to the previous step’s input and appending more code to it while triggering the system. Even so, this feature can help a lot once you know how to use it. For example, as illustrated by the next session log, you can enter “DateTime.Now” (without the quotes) as input and press Enter to get the current time and make that result the current context for help; if you now press Alt+F1 you’ll get a long list of all the DateTime methods and properties available for this type of result (such as AddDays and Ticks). If you then enter “DateTime.Now.ToF” (most of which can be retrieved with the up arrow) and then press Alt+F1, the input-line would auto-complete to “DateTime.Now.ToFileTime” and show additional help: only two of the members will now show up as options (namely ToFileTimeUtc and ToFileTime), since the last portion of the input, “ToF”, is applied as a regular-expression filter to the context. The auto-completed text is the common portion of the filtered member names, and, because the auto-completed text also matches one of the member names exactly, the method prototype for ToFileTime is displayed as additional help in the output window.

>>>  DateTime.Now
(DateTime) 13/03/2010 2:28:19 PM 
-------------------------------
.ctor AddDays AddHours AddMilliseconds AddMinutes AddMonths 
AddSeconds AddTicks AddYears Add CompareTo Date DayOfWeek DayOfYear 
Day Equals GetDateTimeFormats GetHashCode GetTypeCode GetType Hour 
IsDaylightSavingTime Kind Millisecond Minute Month Second Subtract 
Ticks TimeOfDay ToBinary ToFileTimeUtc ToFileTime ToLocalTime 
ToLongDateString ToLongTimeString ToOADate ToShortDateString 
ToShortTimeString ToString ToUniversalTime Year 
-------------------------------
ToFileTimeUtc ToFileTime 
-------------------------------
Int64 ToFileTime()

Furthermore, if you wanted help on the static members of the DateTime class, type “typeof(DateTime)” as input text followed by Enter to make the type itself the current help context, then press Alt+F1 to display static member names such as IsLeapYear and UtcNow, as shown below.

>>>  typeof(DateTime)
(Type) System.DateTime 
-------------------------------
Compare DaysInMonth Equals FromBinary FromFileTimeUtc FromFileTime 
FromOADate IsLeapYear MaxValue MinValue Now op_Addition 
op_Equality op_GreaterThanOrEqual op_GreaterThan op_Inequality 
op_LessThanOrEqual op_LessThan op_Subtraction ParseExact Parse 
ReferenceEquals SpecifyKind Today TryParseExact TryParse UtcNow

Although the input text would primarily consist of C# code, the interpreter does have a preprocessor that extends the interpreter’s syntax. Refer to the original CSI documentation to get a feel for some of the possibilities using the preprocessor macros (for example, you can also display data-type metadata through a macro by typing “/M DateTime”). More importantly, the original documentation also explains how the dollar-sign session variables are implemented.

You use dollar-sign session variables to store and retrieve intermediate results in the interpreter, since the regular C# way of manipulating intermediate results as local variables does now work as you would expect. What it effectively boils down to is that, as an alternative, you have a global lookup table of variables that can be shared between consecutive interpreted steps. For example, instead of writing “int x=5” and “int y=x+3” as real C# variables, you would need to write “$x=5” and “$y=$x+3” where x and y are the names of the variables stored in the lookup table, as illustrated by the following CSI session:

>>>  $x=5
>>>  $x
(int) 5 
>>>  $y=$x+3
>>>  $y+1
(int) 9

The original CSI dollar-sign syntax has been extended for the Unity C# Interpreter plug-in. The mechanism will first try to interpret the names as those of variables you have defined, but, when retrieving variable values, it can fall back to some of the query mechanisms provided by Unity if the specified name is not a session variable. For example, if you type “$Sphere” and hit Enter, the interpreter would first look for a session variable named Sphere that may have been defined through an earlier assignment. But if that variable does not exist, the interpreter would look for a GameObject named Sphere and use that object if it exists. And if that also does not exist, it would try to find GameObject instances with the specified tag, or finally would try to interpret the specified name as that of an object type of which the instances need to be located. Therefore, writing something like “$Light” would typically give you quick access to all the light objects in your current game scene, since all those game objects would have a component of type UnityEngine.Light associated with them. To be able to include spaces or funny characters in the names, you wrap the name in curly brackets, for example, you can write “${Directional light}” and “${/Root Object/Child Object}”; also, “${Light}” and “$Light” means exactly the same thing.

Configuration Options through Inspector

When you have the GameObject with the CSI component selected in the Unity Editor, the Inspector window displays a number of configuration options (see image). Of course, these options are also available at runtime through programmatic access, although some of the values are only interpreted during the initialization phase of the interpreter. The configuration options are as follows:

• Include File – This specifies the filename, either as a relative or absolute path, of the file that will be included during initialization, such as the default CSharpInterpreter_Include.txt file. Leave it blank if no file should be included.
• Include Asset – Instead of specifying an include file though its filename, you can define a text asset in your project and drag-and-drop the asset (such as “CSharpInterpreter_Include”) from the Project window to this property to be included during initialization.
• Queued Asset – This specifies a text asset that will be executed at runtime during the next update cycle as if it were entered as input text. Once executed, the property resets again. Its initial value can be used to specify another asset that must be executed immediately after initialization, but, more importantly, it can be used while the scene is playing in the Unity Editor to execute pre-written scripts for use at runtime. Therefore, you can build yourself a library of C# scripts that you want to execute through the interpreter and drag-and-drop those scripts at runtime to this property when needed.
• Max History Size – This is the maximum number of items that will be kept in your input history for navigation.
• Max Output Size – Specifies the maximum number of characters that will be displayed in the output window.
• Show Interactive GUI, Show Output Text, Show Output As Editor Selection, Show Tooltip Text – These properties correspond with the toggle buttons on the runtime user-interface (discussed in the previous section).
• Left Margin, Top Margin, Right Margin, Bottom Margin – These represent percentages of the screen width or height that surround the runtime user-interface (when fully expanded). Values set to NaN will be calculated automatically.
• Toolbox Width – This represents the pixel width of the toolbox area to the left of the input window.
• Splitter Fraction – Specifies an approximate percentage of the user-interface height (when fully expanded) that gets split between the output window and the controls below it.
• Max Output Line Width, Max Output Line Count – With these options you can limit the maximum characters per line and the number of full lines that are written to the output window for results. (The output window will still automatically break the lines further if they are wider than the output window.)

Final Thoughts

While I’m on the topic of a project that extends the original CSI code, I would like to mention a related project by Samuel Christie called XNA Console, which sports a Python interpreter. Well, I also wrote a C# interpreter extension for the XNA Console, similar to this one for Unity and also based on CSI – it hasn’t been released publically, though, maybe someday if there is enough interest.

Also, if you look at the default CSharpInterpreter_Include.txt file, there is a line that would include the System.Linq namespace, but it is commented out. The reason for this is that the LINQ functionality that is included with the older version of Mono for Unity 2.6.1 is not fully functional (for one thing, Enumerable.Range doesn’t work quite right). But if you feel adventurous, add the namespace and see what is available; for example, doing so would make the following console interaction possible:

>>>  new int[]{7,13,19}.Select(x=>x*2).OrderByDescending(x=>x)
(Linq.OrderedSequence<int>) 
{38,26,14}

Although the code above doesn’t seem to be possible in a regular Unity C# script, it does work in the C# interpreter. However, something more complex like “$Transform.Select(t=>t.position)” still doesn’t work because the Select extension method cannot be found. Hopefully the Unity team will upgrade their Mono version to a newer one before too long. With a newer version of Mono, one could perhaps even rewrite the plug-in to use Mono’s own csharp shell, which might improve speed and stability.

Oh, and it often helps to implement a pause feature for your game and use it while working in the interpreter, unless you don’t mind falling off a cliff while navigating the input history, or a monster destroying your $Player game-object before you hit Enter, or... you get the idea. Have fun!