Database

Working with TDRS's Database

TDRS uses a logical database called RePraxis to store information that should be available to preconditions and other queries. RePraxis allows us to write declarative queries to express various relationship patterns.

Information related agents' and relationships' traits and statuses are automatically updated in the database. Users are encouraged to store additional information in the database that they find useful.

Users can access the database via the DB property on the SocialEngine instance. Remember, to only access it after the social engine has been initialized.

SocialEngine.Instance.State.DB // <-- Get the DB instance from the singleton.

The examples below query using the CSharp interface. If you want to translate these to social events, use the content within the Where(...) method calls.

How to query agents?

Say we want to see if there is an agent with the ID "jon". We can simple do the following.

var db = SocialEngine.Instance.State.DB;

QueryResult result = new DBQuery()
    .Where( "jon" )
    .run(db)

How to query relationships?

Now, say we want to check if "jon" has a relationship with "daenerys". We would change our query to the following:

var db = SocialEngine.Instance.State.DB;

QueryResult result = new DBQuery()
    .Where( "jon.relationships.daenerys" )
    .run(db)

All relationships are stored with the pattern:

<ownerUID>.relationships.<targetUID>

If we wanted to get all the agents that jon has a relationship to, we could replace the target UID with a variable that will bind to any of jon's relationship targets in the database. We name the variable ?target, but you could name it whatever you like.

var db = SocialEngine.Instance.State.DB;

QueryResult result = new DBQuery()
    .Where( "jon.relationships.?target" )
    .run(db)

How to query traits?

Traits are stored similarly for agents and relationships (see patterns below). Only the trait ID is stored.

// How agent traits are stored
<agentID>.traits.<traitID>

// How relationship traits are stored
<agentID>.relationships.<targetID>.traits.<traitID>

So you could use the following query to check if jon has the targaryen trait and if jon and daenerys are lovers.

var db = SocialEngine.Instance.State.DB;

QueryResult result = new DBQuery()
    .Where( "jon.traits.targaryen" )
    .Where( "jon.relationships.daenerys.traits.lover" )
    .Where( "daenerys.relationships.jon.traits.lover" )
    .run(db)

How to query stats?

Stats, like traits, are stored similarly for agents and relationships (see below). Please note the ! before the stat value. This is a special "exclusion" operator in RePraxis to indicate that the path preceding the ! only has one value. In this case, the value is the current value of the stat.

// How agent traits are stored
<agentID>.stats.<stat name>!<value>

// How relationship traits are stored
<agentID>.relationships.<targetID>.stats.<stat name>!<value>

Let's update our query to include a check to see if the romance from jon to daenerys is above a given threshold. Notice, we first store the romance stat in the ?rom variable, then use the gte (greater-than or equal to) operator to see if ?rom is above 40.

var db = SocialEngine.Instance.State.DB;

QueryResult result = new DBQuery()
    .Where( "jon.traits.targaryen" )
    .Where( "jon.relationships.daenerys.traits.lover" )
    .Where( "daenerys.relationships.jon.traits.lover" )
    .Where( "jon.relationships.daenerys.stats.Romance!?rom" )
    .Where( "gte ?rom 40" )
    .run(db)

How to store project-specific data?

Users are allowed to add whatever custom information they want to the database. You can use the Insert(...) and Delete(...) methods on the database instance to add and remove data. This is particularly helpful if you want to make additional information available to your social event preconditions.

For example, you could add information about each character's location and add a precondition to a loud-argument event that says that only characters at the same location as the two characters involved can respond to the event.

// somewhere in your custom code
db.Insert("agentUID.location!LocationID")

# event YAML file
- name: "LoudArgument"
  roles:
    - "?initiator"
    - "?other"
  responses:
    - effects:
      - "DecreaseRelationshipStat ?initiator ?other Friendship 15"
      - "DecreaseRelationshipStat ?other ?initiator Friendship 15"
  - preconditions:
      - "?initiator.location!?locID"
      - "?bystander.location!?locID"
      - "neq ?initiator ?bystander"
      - "neq ?other ?bystander"
    effects:
      - "DecreaseRelationshipStat ?bystander ?initiator Friendship 10"