Table of Contents

1. About The Project
   • Tecnologies
2. Getting Started
   • Prerequisites
   • Installation
3. Features
4. Usage
5. VR projects builded with Tweenity
6. Contributing
7. License
8. Contact
9. Acknowledgments

About The Project

The Tweenity plugin streamlines the connection between Twine and Unity3D tools by reading and interpreting Twine graphs in Unity. Specifically, this plugin was designed to support a methodology aimed at enabling the rapid prototyping of simulators in Virtual Reality.

To facilitate creation, this plugin allows the loading of a simulation using Twine graphs, where each node can have special behavior or functionality depending on the Node Type (selecting options from dialogues with different consequences, reproducing random events in the simulation, defining specific consequences based on user interactions, defining simulator responses when the user does not execute an expected action, or reminding them of the expected action in the simulation).

Additionally, Tweenity allows for some extra features in sample scenes, such as the execution of sample graphs, sample dialogues, simulator reactions (e.g., animations), movement of Mixamo characters along predefined paths, and the playback of audio instructions with a human guide (also from Mixamo).

(back to top)

Technologies

• (Unity version 2021.1.13f)
• (Twine version 2)
• (version 2021)

(back to top)

Getting Started

You can use this plugin by importing it into your Unity project or by cloning this code repository.

Prerequisites

Make sure you have Unity (and/or Unity Hub) installed, and you can open the project using Unity version 2021.1.13f1 or any higher version.

Installation

Using unity package

1. Download Tweenity plugin as unity package
2. Open your Unity project
3. Go to Assets > Import package > Custom package

6. Open the package previously downloaded.

Cloning repository

1. Open your terminal or command prompt.

2. Navigate to the directory where you want to clone the repository.

   cd path/to/your/directory

3. Run the following command in your terminal to clone the repository:

   git clone https://github.com/VivianGomez/Tweenity.git

4. Open the project in Unity Editor or Unity Hub (Open > Add project from disk)

5. Select the folder called Tweenity

(back to top)

Features

Node types

To enhance the utilization of the graph in the creation of VR simulators, a series of node types have been defined, derived from the requirements identified in real multidisciplinary projects. Each node type offers specific functionality for the simulation, and it is possible to combine up to two node types in a single step.

• START Node: This type of node allows modeling the initial step of the simulation. Therefore, there should only be one per graph.

• END Node: This type of node allows modeling the final step of the simulation. Multiple END nodes can exist because several endings could be modeled in a simulation.

• RANDOM Node: It allows modeling the scenario in which we want to randomly select the next path. This makes simulations more dynamic, and the story is not the same all the time. Thus, after the player performs the current node action, the next path will be randomly selected.

• MultipleChoice Node: Allows modeling the scenario in which the user can take one of several actions, but each one has a different consequence.

• REMINDER Node: With this type of node, a reminder (blue arrow) will be placed above the specified interactive object in the current step.

• TIMEOUT Node: Allows modeling the case in which there is a time limit to perform a step. If the user’s action has not been performed after a certain amount of time, it automatically advances to another step of the simulation (specified in the body of this node).

• DIALOGUE Node: It models the scenario in which creators wish to include a dialogue allowing the player to choose from several response options, each with different consequences.

• Typeless Node: The Tweenity plugin also includes the possibility of having a node without a type in case a step doesn’t fit into the previous types.

Additional features

a. Dialogue boxes associated with graph reading and response options available at each node.

b. A Human guide, combining Mixamo rigging and Oculus LipSync, to facilitate audio instructions in the simulation.
c. The movement of NPCs with Mixamo skeletons along predefined paths.
d. The possibility of use a blue arrow to remind the user which object to interact with during training.

(back to top)

Usage

To understand how to use Tweenity, the plugin provides a couple of example scenes—one for PC and one for VR. These scenes are located in Assets > Scenes > Tweenity

The VR example scene loads a sample graph and allows to visualize all the different types of nodes, user event waiting, visual debugger, and simulator response actions.

Visualize sample graph on Twine

First, you need to import the Entwee format, which is the syntax used and interpreted within Unity by the Tweenity plugin. To do this, follow the steps:

1. Go to Twine editor and select the opction Twine > Story Formats

2. Then, press the 'Add' button to import the Entwee format.

3.That option will open a small input field where you need to paste the following link https://mcdemarco.net/tools/entwee/format.js, and then click the 'Add' button.

4. This action will add the Entwee format and yo will see it as your "Proofing format"

To visualize the example graph in the Twine editor:

1. (recommended) Download and use Twine locally as a desktop application. Note: This option keeps the files locally, ensuring information privacy.

2. Download the sample graph.

3. Open the Twine application.

4. Go to the Library > Import option.
   

5. Select the downloaded file and make sure to check the box with the graph's name. Then, Click on Import Selected Files.

6. This wiil open the complete graph

Note: Twine may encounter issues with imports. If you receive any error messages in step 6, simply restart the application.

Create your own graph on Twine

When building your own simulations or games, you will need to create your own graphs. Follow these steps to do so:

1. Open Twimne editor, and click on "New" option (this create a new graph)

2. That will open a small input field, write there the name of your graph, then click on "Create"

3. Then this will open the graph editor

4. There you can create your story/simulation script using format described on paper of Tweenity and ProcoColVR methodology or using same format of sample graph

Export Twine graph and import into Unity

Once you've finished your graph, you can export it for use in Unity. Follow these steps to do so:

1. First, ensure that you import the Entwee format as a Proofing format (as described in (as is described on Step 4 of this section) Note: If this format is not tagged as 'Use for proofing,' you can mark it by clicking on Entwee and selecting 'Use to Proof Stories.'

2. Then, go to ypur graph and select Build > Proof

3. This action will download the text file. Then, go to Unity and navigate to the folder Assets/Resources/Tweenity/TwineTXTs, and create a new empty .txt file with the name of your story or simulation graph.

4. Then, copy the text from the downloaded file in Step 3 into the new .txt file.

Note: This step is very important because the proofing format can manage different character encodings that may not be understood by the Tweenity plugin

(back to top)

VR projects builded with Tweenity

Tweenity originated as a result of developing two virtual reality training simulators. These simulators aimed to replicate a procedure involving a series of steps with varying sequences, hence the proposal to use graphs for defining simulations. Below, we showcase the projects created with Tweenity.

Videos Showcase

P - Birth simulator A simulator to provide a training environment for physicians in which they can make decisions about the first minute of a baby’s life after delivery. In this project, we had a team composed of two physicians, two developers, and one designer. (Video)

Some begginers projects builded in a Jam called JamVR:

Here are the three standout projects from our JamVR event. These simulators were built within a one-month timeframe, with the collaboration of multidisciplinary teams that included designers, developers, and experts in the specific domain of each simulator. All samples can be reviewed on the Padlet of Created Simulators (including videos, descriptions ans source code): Padlet Link

1. A human rights simulator prototype in a war context for personnel in the Colombian Navy. (Video, Final submission, Graph)
2. A risk simulator prototype for workers in the cement sector. (Video, Final Submission, Graph)
3. A simulator prototype for diagnosing heart failure in a virtual patient. (Video, Final Submission)

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the GPLv3 License. See LICENSE for more information.

(back to top)

Contact

• Vivian Gómez - vn.gomez@uniandes.edu.co
• Pablo Figueroa - pfiguero@uniandes.edu.co

(back to top)