Skip to content

3.X Integrating Rumor

Jump to bottom
Ava Pek edited this page Feb 27, 2021 · 1 revision

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.

Rumor Setup

A complete example can be found in the Examples folder if you prefer to learn by example rather than by a guide.

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 intialized using a script.
/// </summary>
public class Example : MonoBehaviour
{
	private Rumor rumor;

	void Awake()
	{
			var str = "say \"Hello World!\"";
			rumor = new Rumor(str);
	}
}

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 that procedurally generates new scripts.

If you wish to have more control over the compilation of the script, you can also create your own compiler, or configure the RumorCompiler. For example, if you wish to use two spaces to indicate an indentation instead of four:

var obj = new RumorCompiler(2).Compile(str);
rumor = new Rumor(obj)

Configuration

After creating the Rumor, you can continue to configure default values. For example, it can be useful to configure the name of the default speaker:

rumor.Scope.DefaultSpeaker = "Narrator";

Execution

Finally, you can start execution of the Rumor script by calling Run() and passing the resulting IEnumerator to a StartCoroutine() call. For example:

StartCoroutine(rumor.Run());

You will also need to update the 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(int) methods, respectively. For example:

if (Input.GetMouseButtonDown(0) || Input.GetKeyDown(KeyCode.Space)) {
	rumor.Advance();
}
if (Input.GetKeyDown(KeyCode.Alpha1)) {
	rumor.Choose(0);
}
if (Input.GetKeyDown(KeyCode.Alpha2)) {
	rumor.Choose(1);
}

You can route input to Rumor any way you desire; it may be better to use a UI element to display choices and have that provide the index number of the choice to the Choose method instead of hard coding it to a key.

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 list of choices.

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:

  • OnSetDialog
  • OnAddDialog
  • 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.

Clone this wiki locally