Relay Plugin

This unofficial TaleSpire mod allows connection of sources to sinks allowing things to occur under certain conditions. If that sounds vague, it is. The reason why the description is so vague is because, in most cases, Relay Plugin is just the connection. What things will happen under what conditions depends on the sources and sinks that are configured.

Install

Use R2ModMan or similar installer to install.

Note: This plugin should only be installed on GM device. Do not install on player device.

Usage

This plugin is passive. The GM or players don't need to do anything once the plugin is configured. What actions then need to be taken to trigger a source condition to result in a sink trigger depends on the sources and sinks configured.

Configuration

There are 3 parts to Relay Plugin: Relay, Interactions and Hide.

Relay Configuration

The relay configuration is store in a file called:

org.lordashes.plugins.relay.Relay.CampaignId.BoardId.json

You can get this file name form the logs.

This means that each board has its own configuration of Relays which makes sense since Relays are typically specific to creatures or props on the board.

The format for the Relay file is:

{
  "sources": {
    "ANGEL": "org.lordashes.plugins.angel.*",
    "DOOR": "org.lordashes.plugins.relay.interaction"
  },
  "relays": [
    {
      "trigger": "DOOR",
      "condition": "{N}:{V}|^Door_Right:2$",
      "reaction": "HIDE",
      "reactionAsset": "{Jester}",
      "reactionDelay": 1.0,
      "reactionValue": "0",
      "description": "Shows/Hides Jester Based On Door state"
    },
    {
      "trigger": "DOOR",
      "condition": "{N}:{V}|^Door_Right:6$",
      "reaction": "HIDE",
      "reactionAsset": "{Jester}",
      "reactionDelay": 1.0,
      "reactionValue": "1",
      "description": "Shows/Hides Jester Based On Door state"
    }
  ],
  "sinks": {
    "HIDE": "org.lordashes.plugins.relay.hide"
  }
}

sources is set of sources indexed by a friendly name containing the corresponding Asset Data Plugin subscription. When an Asset Data Plugin message involving the subscribed key is sent, the message is processed though the relays.

sinks is a set of Asset Data Plugin keys used to trigger desired plugins when the relay conditions are met. The Relay Plugin will write to messages to these keys with the intention that this will trigger an effect in some other plugin.

relays are the connection between sources and sinks. The connections can be conditional or unconditional. When a source generates a message, any relay that has the source as its trigger property will trigger. If the relay has a condition, it will evaluate it. If the condition is empty, it is assumed the condition always passes. A condition has two parts separated by a pipe character. The first part is what is being compared and the second part is a RegEx indicating the pattern that must be matched. The first part can utilize a number of place holders which are filled in when the condition is evaluated:

{?} is replaced with the a T if the source is an asset that is owned by a PC or F otherwise. Condition only. {A} is replaced with the message action. Useless in most cases. {K} is replaced with the message key (useless in most cases unless using wild card subscribing). {N} is replaced with the name of the asset assuming the source is a creature board asset (or same as {S} if not). Usually very useful. {P} is replaced with the previous value of the state. Useless in most cases. {S} is replaced with the message source. Useful for asset identification but usually {N} is used instead. {V} is replaced with the current value of the state. Usually very useful.

The RegEx portion is just a regular RegEx except that it needs to be double escaped since it is in a JSON. If the RegEx uses groups, the group content can be used in the reactionAsset or reactionValue properties.

The reactionAsset indicates the source to be used for the sink request if the condition is passed. It can use the same place holders as the condition did but it also has one additional option:

{Name} is replaced by the CreatureId of the Creature Board Asset with the name Name. For example {Bob} would get replaced by the CreatureId of the asset named Bob. This allows using human readable names to refer to assets but still be able to trigger plugins that expect an asset's CreatureId as opposed to the name.

The reactionDelay is optional and causes the Relay to pause for the specified number of seconds before triggering the skink if the relay condition is passed. This is typically used for things like swiches or doors which have a animation time. Without a delay the sink trigger would be triggered as soon as the interaction occured. With a delay, the switch or door has time to animate before the sink is triggered.

The reactionValue property indicates what value is sent to the sink. It can be a hard coded value or it can use any of the place holders discussed earlier or it can use $1, $2, and so on which get replaced by the values of the RegEx match groups if any.

In the example above, if a message sent out on the "org.lordashes.plugins.relay.interaction" key (referred to as DOOR source) it's source name and value are compared to two possibilities: Door_Right:2 and Door_Right:6. If the message matches the first, it send a message to the "org.lordashes.plugins.relay.hide" sink to an asset called "Jester" with a value of 0. If it is the second, a similatr message is sent but with a value of 1. This causes the Jester asset to be shown or hidden based on the door state.

Interactions Configuration

Relay Pliugin provides basic core Talespire Interaction recognition but it needs to be configured ahead of time. Essentially, the configuration links location on the map with human friendly names. When a interaction occurs close enough to one of the specified points, it sends out a message on the key "org.lordashes.plugins.relay.interaction". This key can then be listed as a Relay source and thus effects can be triggered based on the interaction.

The interactions are defined in a file called:

org.lordashes.plugins.relay.Interactions.CampaignId.BoardId.json

The format for the Interactions file is:

{
  "Door_Right": {
    "x": 2.86423969,
    "y": 1.24049234,
    "z": 2.612402
  },
  "Door_Middle": {
    "x": -0.496289551,
    "y": 1.08108664,
    "z": 3.10947132
  },
  "Door_Left": {
    "x": -3.836122,
    "y": 1.059699,
    "z": 3.21177673
  },
  "Door_Bottom": {
    "x": -4.075144,
    "y": 1.27271271,
    "z": -0.215862274
  }
}

The contents for this file can be generated at Runtime.

Interact with a core Prop and then press the Back Tick key. A dialog will ask for a name. Enter a unique name for the prop you interacted with. The content with all recorded props for the session is dumped to the logs. At the end of the configuration session, you can get the contents from the logs and save it in the correct file so that it loads automatically on the corresponding board.

The friendly name is uses as the Source in the corresponding Asset Data Plugin message.

Hide Configuration

There is no configuration needed for the Hide functionality. The Hide functionality is just a sink that reveals or hides assets. It is provided though the Relay Plugin so that a Hide plugin does not need to be created. The sink key is "org.lordashes.plugins.relay.hide". The sink source expects a CreatureId (so use {Name} in the reactionAsset property if you want to refer to assets by name). A reactioValue of 0 means revealed and a value of 1 means hidden.