BitsySharp - Bitsy for C#/Unity3d
Author: Dylan Engelman 2018 https://github.com/lordofduct
Original Author: Adam LeDoux https://github.com/le-doux/bitsy
A port of the engine portion of Bitsy to C#. It allows the parsing of Bitsy ‘Game Data’ which is generated by the ‘Bitsy Game Maker’. Once parsed and ran it will draw its results to a ‘Bitsy.IRenderSurface’ so that you can have it render to any C# compatible graphics interface you’d like.
This package comes with a Unity compatibility layer included. This includes and implementation of ‘Bitsy.IRenderSurface’ for the Unity Texture2D. You can then attach the resulting Texture2D to any material in your Unity game that accepts a Texture2D.
It also contains several extensions to help customize your Bitsy experience. An IBitsyScriptExtension for adding your own custom functions to the BitsyScript, several event/delegate hooks for reacting to events in Bitsy, and a way for loading custom Fonts from an image/texture (in Unity, though easily migrated).
Use In Unity3d
Head on over to releases and download the latest ‘UnityPackage’ to import into your project.
Once imported into your project you should find a folder named ‘Bitsy’ containing several code files and an ‘Examples’ folder. Check out the ExampleScene in there for a more hands on example of how this is set up.
General Steps: Create a Renderer surface on which Bitsy shall be rendered. I usually go with the ‘Quad’ (GameObject->3D Object->Quad), but any Renderer whose material accepts a ‘Texture2D’ as its ‘mainTexture’ (see: https://docs.unity3d.com/ScriptReference/Material-mainTexture.html). We need somewhere to render our Texture2D.
Add the ‘BitsyComponent’ component to this surface. It is not necessary to be on the same object as the Renderer, though this is helpful. If you decide to put the component elsewhere, just make sure to drag a reference to the Renderer onto the ‘Renderer’ property for ‘BitsyComponent’ in the inspector.
Save your Bitsy ‘Game Data’ in a text file anywhere in your project’s Assets folder (creating a TextAsset). Drag a reference to that ‘Game Data’ onto the ‘GameData’ property of the ‘BitsyComponent’ in the inspector.
Configure any other aspects of the ‘BitsyComponent’ you see fit (see inspector tooltips).
And you’re off to the races!
You can enable/disable the BitsyComponent to start and stop the game.
Call ‘RestartGame’ to reload the game and apply any changes to the configuration.
Creating Bitsy Extension Functions
Bitsy Extensions are implemented as the interface ‘IBitsyScriptExtension’ and attached to the BitsyGame.ScriptInterpreter.ScriptExtension field.
CAUTION - This should be attached before the game begins because Bitsy needs to be aware of any extensions when it starts to interprets dialog/scripts. This is because despite Bitsy interpreting scripts lazily, it does compile them and store them for reuse. If the extensions changes after that the already compiled scripts may not work.
For your convenience the IBitsyScriptExtension interface is already implemented for you as the ‘BitsyScriptExtensionTable’. This is a hash table you can add functions keyed on the functions name (as the name would be called in BitsyScript).
Functions should take the shape of the EvalFunctionCallback delegate: public delegate void EvalFunctionCallback(Environment env, object args, System.Action
Where: ‘env’ is the environment the script is operating on. ‘args’ is the array of args parsed by the ScriptInterpreter, you must validate these args yourself ‘onReturn’ is the callback handle to signal that your function has completed. This MUST be called otherwise Bitsy will hang.
Note some predefined extension functions have been defined in the ‘BitsyExtensionFunctions’ static class. And if you call ‘BitsyExtensionFunctions.CreateTable()’ you’ll receive a premade ‘BitsyScriptExtensionTable’ with all the extension functions added. You can just attach this as your extension for your game, as well as add to this table any extra functions you may want to add.
Creating Custom Fonts (in Unity3d)
You can create your own custom font by creating a 128x128 texture divided into 256 8x8 tiles (that is 16 tiles wide by 16 tiles high making 256 tiles). The tiles are number 0->255 starting in the top left, going left to right, top to bottom. Each tile’s index matches the char code of that index.
Check ‘Bitsy/Unity/DefaultFont.tga’ as an example of the default Bitsy font for a visual representation.
The texture can be of any format that unity supports. Though I suggest a lossless bitmapped format like bmp or tga (targa) to maintain pixel perfect fidelity of the font.