Home - imagine-uniandes/Tweenity2.0 GitHub Wiki

Tweenity Graph Editor - UI Documentation

Overview

Tweenity Graph Editor is a custom Unity Editor Window designed to manage and visualize node-based structures. The system uses a modular and extensible Model-View-Controller (MVC) architecture to promote separation of concerns and maintainability.

Architecture Pattern:

As of 2025-04-07, the Tweenity Graph Editor follows a strict and robust Model–View–Controller (MVC) architecture, designed for modularity, scalability, and maintainability in Unity's Editor environment.

This separation of concerns ensures clean code boundaries and predictable data flow throughout the system.

Model Layer (Models/)

The Model layer is responsible for representing all data structures that define the graph logic.

  • Each node in the graph is represented by a class inheriting from TweenityNodeModel.
  • Node variants such as DialogueNodeModel, StartNodeModel, ReminderNodeModel, etc., encapsulate specific properties relevant to their behavior.
  • Nodes are uniquely identified via NodeID (UUID).
  • All nodes are stored and managed via GraphModel, which:
    • Prevents multiple Start nodes from being added.
    • Provides methods to add, retrieve, and remove nodes.
  • The NodeType enum defines the classification of supported node types.
  • GraphParser handles serialization/deserialization of graph data to and from .twee format, enabling round-trip editing between the visual editor and Twine-based workflows.

Controller Layer (Controllers/)

The Controller acts as the central orchestrator of the application, maintaining the state of the graph and ensuring synchronization between UI and data.

  • GraphController:
    • Mediates all interactions initiated by UI elements (view components).
    • Manages the lifecycle of nodes: creation, deletion, editing, and transformation (e.g., changing node type).
    • Ensures business logic is enforced (e.g., only one Start node, valid connections).
    • Updates the view after changes to the model, including rerendering and refreshing.
    • Coordinates connection logic between nodes using a click-to-connect workflow (StartConnectionFrom / TryConnectTo).
    • Delegates serialization to GraphParser for export/import.
    • Responds to UI events from toolbars, right/left panels, and graph interaction.

View Layer (Views/)

The View layer is composed of Unity UI Toolkit (UIElements) visual components and GraphView-based rendering.

  • Views are logic-free and strictly presentational.
  • They display the state of the model but delegate all data manipulation to the controller.
  • Each section of the UI is modular:
    • TweenityGraphView: Central canvas for node rendering and connection drawing.
    • TweenityNode: Visual representation of a node (title, type, description, color).
    • Right Panel:
      • Each node type has a dedicated view (e.g., DialogueView, MultipleChoiceView).
      • All extend TweenityNodeView, which handles shared fields like title, description, and node type.
    • Toolbars (top and bottom): trigger controller methods for save/export/debug actions.
    • Left Panel: Currently hosts search functionality, designed for future hierarchy visualization.

Interaction Flow Summary

  1. User interacts with the UI (e.g., changes title, clicks connect, edits responses).
  2. The View notifies the Controller (e.g., GraphController.UpdateNodeTitle()).
  3. The Controller updates the Model, and then triggers any necessary view updates (e.g., rerendering the node).
  4. The Model holds the true state, while Views are synced representations.

This separation ensures that the controller is the single source of truth for application logic, while the model maintains all persistent state and the views remain highly reusable.

Project Structure

1. Models (Models/)

  • GraphModel.cs: Represents a Complete node graph containing all nodes and their connections
  • NodeType.cs: Enum of supported node types.
  • Node Models (Models/Nodes/): Data representations of each node type like StartNodeModel, DialogueNodeModel, TimeoutNodeModel, etc.
  • Responsibilities:
    • Contain and validate node data.
    • Enforce structural constraints (e.g., only one StartNode).
    • Manage custom properties per node type (Responses, Choices, etc.).
    • Support .twee import/export via GraphParser.

2. Controllers (Controllers/)

  • GraphController.cs:

    • Central manager of application state and graph logic.
    • Adds/removes/updates nodes.
    • Handles connection creation and cleanup.
    • Renders changes in GraphView.
    • Exports/imports graph using GraphParser.
    • Returns error messages for invalid operations.

  • GraphParser.cs:

    • Converts graphs to and from .twee format.
    • Used for import/export compatibility with Twine-based story structures.

3. Views (Views/)

Toolbar (TweenityToolbar.cs)
  • Save, Load, Export .twee, Zoom tools, Add Node button.
  • All actions delegate to GraphController.
Left Panel (TweenityLeftPanel.cs)
  • Search bar with real-time filtering.
  • All events routed through controller.
Graph View (TweenityGraphView.cs)
  • Visual display of graph using a commonTweenityNode.
  • Handles zoom, panning, node rendering, and edge connections.
  • Calls RenderConnections to draw visual links.
  • Each node has input/output ports.
Right Panel (TweenityRightPanel.cs)
  • Dynamically renders editable fields for selected node.
  • Each node view (StartView, DialogueView, etc.) inherits from TweenityNodeView.
  • Common editable fields: title, description, type.
  • Type-specific fields:
    • Dialogue: DialogueText, Responses
    • MultipleChoice: Question, Choices
    • Random: Paths
    • Reminder: ReminderText, ReminderTimer
    • Timeout: Condition, TimeoutDuration, dual connection buttons
  • On error, resets dropdown and shows warning via EditorUtility.DisplayDialog.
Bottom Toolbar (TweenityBottomToolbar.cs)
  • Debugging buttons:
    • Debugging: Logs full graph state.
    • Current Selection: Logs selected node(s).

Key Concepts & Interaction Flow

  • All interactions go through GraphController.
  • Views are logic-free and reflect model state only.
  • Right panel views are initialized with both the node model and controller.
  • Dynamic node type changes are supported (with validation).
  • Node connections handled via StartConnectionFrom and TryConnectTo logic.
  • Visual nodes auto-update appearance and labels using UpdateFromModel.

Visual Styling per NodeType

NodeType Background Color Text Color
Start Soft Green (#81C784) Deep Green (#1B5E20)
End Vivid Red (#EF5350) White (#FFFFFF)
Dialogue Soft Purple (#BA68C8) Light Gray (#FAFAFA)
MultipleChoice Yellow-Orange (#FFB300) Dark Brown (#422800)
Reminder Sky Blue (#64B5F6) Indigo (#0D47A1)
Timeout Light Blue (#90CAF9) Slate Blue (#1E3C50)
Random Amber Yellow (#FFD54F) Dark Brown (#422800)
NoType Dark Gray (#333333) Light Gray (#DADADA)

Last updated: 2025-04-07