Skip to content

Home

Jump to bottom
Shi Johnson-Bey edited this page Jan 17, 2024 · 16 revisions

Welcome to the wiki for TDRS

TDRS (Trait-Driven Relationship System) is a Unity package for modeling dynamic character relationships for life sims, dating sims, visual novels, and adventure games. It enables game developers to track relationships between social entities (NPCs, players, factions, etc.). Designers can create and tag relationships and characters with various traits that modify how characters feel about each other. Also, they can dispatch various events that change relationships and build interpersonal histories between characters. Game designers can leverage this package to add a semblance of social intelligence for NPC decision-making and dialogue.

Warning ⚠️: The API for TDRS yet stabilized. So, The information in this wiki lags behind the latest changes. Please see the sample scene in within the repo for the most up-to-date example of TDRS in action.

System Overview

system overview diagram

TDRS manages an internal social graph data structure containing agents and directed relationships between the agent. Agents may be characters, groups, items, religions, concepts, or anything that someone might have a relationship toward. You can think of relationships as arrows that point from one node to another. Each relationship has an owner and a target. A relationship's job is to describe how the owner feels about the target and track traits that describe the nature of their relationship. Finally, Traits are tags of information that can be attached to nodes and relationships within the social graph. Their job is to provide additional information about the node/relationship and apply various effects that change its state, such as stat buffs. Traits can represent relationship statuses (dating, rivals, estranged, siblings, soulmates), faction affiliations (Jedi, Sith, Separatists), and emotional states (angry-at, sad, excited, content).

Installing TDRS

To add TDRS to your Unity project, you must download the latest version of the package from GitHub. TDRS is not available in the Unity Asset store. All releases are on the Unity-TDRS GitHub Releases page. Please follow the steps below.

  1. Find your desired release.
  2. Download the unity-tdrs_<VERSION>.tar.gz from under the Assets dropdown (<VERSION> should be the release version you intend to download).
  3. Open your project in Unity
  4. Navigate to Window > Package Manager in the top menu.
  5. Click the + icon in the top left and select Add package from tarball....
  6. Find and select the downloaded tarball
  7. You should now see Unity-TDRS appear in the Unity Package Manager window with a version number matching your downloaded version.
  8. Close the Package Manager window

Getting Started

Step 1: Add the social engine prefab to your scene

All relationships, traits, and stats are managed by a single SocialEngine script instance. This script must be present within the scene for everything to work correctly. TDRS has a SocialEngine prefab available to make things easy. You can find it in the project explorer under Packages > TDRS > Assets. This prefab comes preconfigured with the built-in effect factories and instances of the TraitLibrary and SocialEventLibrary scripts.

Step 2: Specify agent and relationship stats

You can start adding characters at this point, but things will be pretty bland. Let's add some default character and relationship stats. TDRS has an internal stat system to track various facets of characters and relationships that might affect social dynamics. For this tutorial, let's give characters a single Sociability stat and give relationships stats to track Friendship and Romance.

Steps TBD

Step 3: Add character agents

Next, let's add some character agents to the scene to see their stats and relationships. Internally, TDRS stores agents and their relationships as nodes and edges in a directed graph. In this step we create a new character. However, you could modify an existing character, assuming they are represented as an independent GameObject.

  1. Start by creating an empty GameObject in the scene hierarchy. Let's name this character "Ameera".
  2. Add a new SocialAgent component to the GameObject. This class serves as the connector between your character and the TDRS.
  3. Again, there are a bunch of fields associated with this component.
    • UID is the unique ID that we will assign this character in the TDRS
    • Traits displays runtime trait information
    • Stats displays runtime character stat information
    • Relationships displays runtime information about this character's outgoing relationships (how they feel about others).
    • Event Listeners are an experimental feature that allows users to call methods when traits are added or removed from a character.
    • Note: Only the UID and event listeners are editable. All other fields are populated at runtime and are not editable in the Inspector. We will discuss how to initialize these values
  4. Set the UID field to be ameera.
  5. Click the Play button at the top of the editor window.

Step 3: Configuring initial traits, stats, and relationships

TBD

Step 4: Create new traits

Traits are the bread and butter of TDRS (hence the name Trait-Driven Relationship System). As a game designer, you will use traits to mark characters/relationships and apply stat buffs.

Traits are defined using YAML files. Each file can contain one or more trait definitions. All definitions are loaded into the TraitLibrary by dragging their text asset in the Unity Project explorer to an empty list slot in the Trait Definitions field on a TraitLibrary component.

Below are sample trait definitions for two traits. Each trait definition starts with the trait ID followed by a colon. Then, all information pertaining to that trait is indented and provided as key-value pairs. Please refer to this YAML Cheatsheet if you need help understanding something.

You can read more about traits on the Traits Page.

awkward:
  display_name: Awkward
  description: This character struggles with social interactions and comes across as clumsy.
  effects:
    - type: StatBuff
      stat: Sociability
      amount: -3
    - type: AddSocialRule
      effects:
        - type: StatBuff
          stat: Friendship
          amount: -2
  conflicts_with:
    - charismatic

ambitious:
  display_name: Ambitious
  description: This character is driven by ambition and seeks to achieve great success.
  effects:
    - type: StatBuff
      stat: Sociability
      amount: 2
  conflicts_with:
    - lazy

Table of Contents

Clone this wiki locally