5.X Integrating Rumor

This is the guide for integrating Rumor into a Unity3D project. If you are a writer, see the Beginner's Guide instead.

Installing Rumor

There are a few different ways to install the Rumor plugin into Unity. This guide covers two options.

Unity Package

You can install Rumor by downloading the latest .unitypackage release from the releases page. This is a good choice if you either don't know how or want to avoid using git submodules.

You can then import the package as you would with any other Unity package by going to Assets > Import Package > Custom Package..., and then selecting the package you downloaded.

Submodules

You can install Rumor by adding the repository as a submodule in your git project. Using submodules is a good choice if you want bleeding edge updates.

Setting up Rumor using submodules will not be covered in this guide, but Pro Git has an excellent guide if you are interested in learning more.

Compilation

To compile a new Rumor, you need a string which contains the contents of the script you wish to execute. For example:

/// <summary>
/// This is an example of how a Rumor may be initialized using a script.
/// </summary>
public class Example : MonoBehaviour
{
    private Rumor rumor;

    void Awake()
    {
        var str = ": Hello World!";
        var nodes = new RumorCompiler().Compile(str);
        rumor = new Rumor(nodes);
    }
}

There are many ways to retrieve the script to compile. In this example, the script is embedded directly in the source code, but it can also be loaded from disk, downloaded from a server, or retrieved from a custom class which procedurally generates new scripts.

Execution

On creation, Rumor automatically executes up until

You will also need to update Rumor manually in the Update method. For example:

void Update()
{
    rumor.Update(Time.deltaTime);
}

Integrating Rumor

Input

Rumor needs to be notified when the user wants to continue the dialog after they have finished reading and also needs to be notified of which choice the user has selected if a choice is available. This can be done by calling the Advance() and Choose(string) methods, respectively. For example:

if (Input.anyKeyDown)
{
    rumor.Advance();
}

rumor.OnWaitForChoose += (Dictionary<string, string> choices) => {
    foreach (var choice in choices)
    {
        // Spawn a buttom from the pool
        var button = choicePool.Spawn<Button>();
        button.onClick.RemoveAllListeners();
        button.onClick.AddListener(() =>
            {
                rumor.Choose(choice.Key);
            }
	);

        var text = button.GetComponentInChildren<Text>();
        text.text = choice.Value;

        button.transform.SetAsLastSibling();
    }
}

Fetching

Rumor does not provide any visual capabilities and leaves the implementation of it up to you. You can poll for what should be displayed by calling various methods on RumorState, which represents The Stage.

The state can be accessed through the variable State. rumor.State.Dialog is a dictionary of characters and their respective lines and rumor.State.Choices is a dictionary of choice ids and choice display text.

Instead of polling the state, you can also subscribe to events on the state to be notified when dialog or choices have been added. You can see the RumorState source code for a listing of events you can subscribe to. Some examples of events include:

• OnAppendDialog
• OnSetDialog
• OnClear

Bindings

You may want to add the ability to play sounds or trigger a number of different methods or effects in Unity. You can do so by using any of the Bind methods on the Rumor. The bound methods can then be called from an expression statement in a Rumor script. More information on bindings can be found in the expressions reference.

Saving

Serialization in Rumor doesn't save just the marker of where you are. Instead, when you serialize Rumor, all of the compiled object code (the object representation of the script) along with the position of your iterator and what variables are in your scope are saved. If this is too much space or undesirable, you can also serialize just the scope.

You can use .NET serialization for Rumor, but you can't use Unity serialization because this library has been developed to be compatible with .NET applications.

To serialize:

private static MemoryStream Serialize<T>(T o)
{
	MemoryStream stream = new MemoryStream();
	IFormatter formatter = new BinaryFormatter();
	formatter.Serialize(stream, o);
	return stream;
}

To deserialize:

private static T Deserialize<T>(MemoryStream stream)
{
	IFormatter formatter = new BinaryFormatter();
	stream.Seek(0, SeekOrigin.Begin);
	object rumor = formatter.Deserialize(stream);
	return (T)rumor;
}

This is not the only way to serialize the data, but it is one of the many .NET serialization examples that can be given.