Asset Naviagtion & General Execution Library (ANGEL) Plugin

This is an unoffical Talespire plugin which allows use of Asset Bundle custom content assets in Talespire. Typically these assets are obtained via R2ModMan from Thunderstore but can be obtained by other means as long as the containing folder follows the R2ModMan deployment process.

This plugin replaces Custom Asset Library Plugin (CALP) and eventually will integrate the functionality of Custom Asset Library Plugin Integrated Extension (CALPIE) but CALPIE functionality has not been integrated yet.

Supported Features:

- Basic Static Asset Bundle Assets - Spawns with own base
- Aura/Effects - Spawns attached to selected mini
- Filters - Spawns attached to the camera
- Audio - Allowing playin asset audios
- Animate - Allowing playing asset rigged animations
- Blendshape - Allowing playing blendshape sequences
- Morph - Allows swapping between Angel assets
- Variants - Allows swapping between Angel assets
- Size - Allows info.txt file to dictate the default base size
- Analyze - Diagnostic tool for analyzing assets

Change Log:

2.3.1: Fix bug with flying mode offset
2.3.0: Added delay option to sequencer
2.3.0: Bug Fix for looping sequences
2.2.0: Added Blendshapes' Sequencer
2.2.0: Changed assets file to a simple list to make it easier to tweak
2.2.0: Added missing Angel.Portrait.png
2.1.1: Corrected audio and animate target on player devices
2.1.0: Audio and animations are requested on all player's devices
2.0.0: Added support for external plugin content handlers allowing other plugins to handle additonal file formats
1.9.9: Fixed issue with reloading ANGEL assets whose size has been changed though GM Tools
1.9.7: Restored ANGEL creature icons
1.9.6: Enforce animation order
1.9.6: Relocate the cache folder
1.9.5: Fixed bug with removal of weather effects on player devices
1.9.4: Migrated Link change detection from SetLink to DataChanged
1.9.4: Improved logging
1.9.4: Refectored some code
1.9.2: "Hid" required base, when flying, in the flying base.
1.9.1: Bug fix for flying (temporary).
1.9.0: Modified how filters are spawned and removed to fix filter persistence.
1.8.0: Bug fix for players not being able to see ANGEL content.
1.7.1: Note: This version breaks Fly Mode. This is being worked on.
1.7.1: Bug fix for Line Of Sight issue. This uses a new base for ANGEL assets.
1.7.0: Changed Angel content attachment point to allow compatibility with fly mode.
1.7.0: Optimized Show/Hide code for greater performance.
1.6.3: Added warning about perforance when running debug or trace diagnostics.
1.6.2: Moved visibility logging from debug to trace (improving performance when running debug).
1.6.1: Sorted menu groups.
1.6.0: Fixed stealth mode. 
1.5.5: Added Variants.
1.5.5: Added Size.
1.5.5: Added Aura Modifiers.
1.5.1: Morph bug fix and re-assignment of default binding keys.
1.5.0: Basic morph functionality added.
1.4.0: Added rigged animation functionality.
1.3.0: Fix bug with filters coming back.
1.3.0: Added custom sound.
1.3.0: Added custom mini analysis function.
1.2.1: Repack with missing filter icon. No plugin change.
1.2.0: Added Filters
1.1.0: Added Aura/Effects
1.0.0: Initial Release

Installation:

1. Install using R2ModMan or simlar means
2. The first time you select a Asset Bundle custom content mini, the Mod.Io windows will ask if you want to download a base (unless your Talespre is set up to automatically accept all downloads). Confirm the download. This should only happen once and download the base that is used with the asset bundle custom content.

NOTE: If you have assets installed that were registered from CALP, you will need to unregister them or uninstall and re-install them before ANGEL plugin will be able to see and register them.

Usage:

The plugin provides a Thunderstore asset library similatr to the core library but showing only asset bundle based assets. The library is navigated in a similar manner to the core library.

Left Hand Icons: These indicate the category (kind) of assets such as Creature, Aura, Effect, Prop, Slab. Mid Buttons: These are groups within the category used to organize the assets. If there are more groups than can be dispalyed the arrows to the right of the groups can be used to cycle though the groups. Right Hand Icons: Assets that can be added to the board. Displayed in two rows. Arrows can be used to cyclce though a row at a time when more assets, than the screen can show, are available within the selected group. Bottom Screen: This areas show information about the asset that was last under the mouse pointer.

1. Open the Asset Bundle library. Default: F10.
2. Select the catgeory using the left icons.
3. Select the group using the group buttons.
4. Select the asset from the asset list.
5. Place the based down on the board. Note: At this point the placement process is only via a base. No asset is expected at this point.
6. Mini will appear once placed.

Animate

LCTRL+1 through LCLTL+8 = Play the indicated animation in the asset's animation list. LCTRL+9 = Prompt for a animation name (or partial name) and play the first animation, in the asset's animation list, that matches. LCTRL+0 = Stop all animations.

Note: Animations are not persistent. If an animation is playing at the end of the session, it will not resume in the next board/session.

Audio

LALT+1 through LALT+8 = Play the indicated audio in the asset's audio list. LALT+9 = Prompt for a audio name (or partial name) and play the first audio, in the asset's audio list, that matches. LALT+0 = Stop all audio.

Note: Asset audios are not persistent. If an audio clip is playing at the end of the session, it will not resume in the next board/session.

Morphs

Adding Morphs

When a mini is spawmed, morphs can be added to it which then allows the user to cycle through the various morphs. The current functionality provides only basic morph functionality with no UI for the morph functionality. It does not use the core TS morph menu.

1. Spawn a Asset Bundle creature using the Angel menu. (This functionality does not work on normal assets)
2. Ensure the spawned asset is selected.
3. Spawn a another Asset Bundle creature from the Angel menu but this time holding RSHIFT+RCTRL while clicking the menu selection.
4. Message about adding a morph will appear.

Note: A double modifier (RSHIFT+RCTRL) was chosen to minimze the chance of accidentally holding the keys while selecting.

Removing Morphs

Use the same process, selecting an asset from the Angel menu that is already in the morph list, to remove the asset from the morph list.

Using Morphs

Cycle between the different morphs using the Cycle Morphs key. Default: F11.

Forced Auras/Effects

To spawn a creature asset as an aura, while an Angel asset is selected, hold down LSHIFT+LCTRL while selecting the asset (to be turned into an aura) from the library.

Note: This is not necessary for actual aura assets. This is only necessary when the asset is a creature but the user want to use it like and aura.

Analyze

F1 = Dump custom mini analysis to the log. Includes CBA data, animations, audio, and heirarchy analysis.

Diagnostics

When Angel is running in Debug or Trace diagnostics, it can significantly affect the performance. This occurs because these levels generate a lot of good disgnostic level for troubleshooting problems but due to the numerous log write, it slows down the plugin significantly (especially Trace). To avoid this performance hit, use a diagnostic level of None, Error, Warning, or Info when using Talespire. Switch to Debug or Trace only when getting logs for troubleshooting.

There are two places where you may need to set the diagnostic level. The angel plugin has its own diagnostic level which can be set using R2ModMan Config Editor. However, the Logging Plugin, which ANGEL uses for logging, has a option to override plugin diagnostic levels and use the one specified in the Logging Plugin instead. Ensure that the "Allow Plugins Logging Level" is set to true in the Logging Plugin configuration or set the desired logging level on the Logging Plugin itself.

Persistence

The Angel Plugin avoids using Asset Data Plugin (ADP) for storing content because ADP has one large flaw - it needs other players connected when making changes (such as turning on Light plugin or using Angel plugin). This was someone address by adding the Redistribute feature added to Asset Data Plugin but this is not ideal since it requires manual action by the DM.

Instead Angel uses a tactic similar to Stat Messaging where it stores the information on a Talespire property that Talespire replicates as part of the core functionality. In this case, Angel uses the Link as opposed to the Name property.

As a result of this, filters (such a weather effects) are implemented using a mini, just like normal minis, except the base defaults to hidden and the content appears in front of the camera and not at the base location. To remove a filter, delete the corresponding base.

Limitations:

1. When being placed, mini are not displayed. Only the base is placed. This limitation may be overcome in a future version.
2. Initial startup is very slow to register assets. However, the registered assets are cached so succesive starts are much faster.
3. Successive starts detect new assets but do not currently detect deleted assets. This limitation may be overcome in a future version. Work around: Use the provided batch file, in the .Cache sub-folder, to remove the assets file and the angel.portraits.* files.
4. The Link of creatures are used to hold the asset bundle data. If using the Link feature, the plugin content needs to be appended to the end of the link or the asset will revert to just a base on next load. Most link will not have a problem with the addition becuase it is added as a query parameter.
5. No mass Aura remove yet.

Thunderstore Asset Pack

Thunderstore packs support a number of different types such as Creature, Aura, Effect, Filter, etc. Since these functions where performed by CALPIE and currently the ANGEL Plugin only supports CALP functionality, all assets will be treated as Creature type regardless of their kind. They will still be placed under the appropriate category icon but auras and effects will not snap to selected minis and filters will not snap to the camera. Instead they will all be spawned with a base like a Creature mini. This will change once CALPIE functionality is integrated into the ANGEL Plugin but not at the moment.

Info.txt

The info.txt file is used to communicate to ANGEL information such as what type of asset the asset is, what group is should show in, and other features. Below is a sample file:

{
  "kind": "Creature",
  "category": "Creature",
  "groupName": "Mystical",
  "description": "Cluck-A-Bull",
  "name": "cluckabull",
  "tags": "mystical,creature",
  "author": "Meshy",
  "version": "1.0",
  "comments": "Animated by Lord Ashes",
  "prefab": "lacluckabull01",
  "animationOrder": [ "Static", "Idle", "Peck", "Claw", "Cluck", "Flap" ],
  "variants": [ "lacluckabull01_Sit", "lacluckabull01_Lie" ],
  "blendshapes": 
  [
    {
      "name": "Flap",
      "elements":
	  [
        {
          "audio": null,
          "animation": null,
          "style": 130,
          "blendShapeIndex": 1,
          "start": 0.0,
          "end": 100.0,
          "step": 5.0
        }
      ]
    },
    {
      "name": "Peck",
      "elements": 
	  [
        {
          "audio": 1,
          "animation": null,
		  "delay": 0,
          "style": 258,
          "blendShapeIndex": 2,
          "start": 0.0,
          "end": 100.0,
          "step": 15.0
        },
        {
          "audio": 1,
          "animation": null,
		  "delay": 2,
          "style": 258,
          "blendShapeIndex": 3,
          "start": 0.0,
          "end": 100.0,
          "step": 15.0
        },
        {
          "audio": 1,
          "animation": null,
		  "delay": 4,
          "style": 258,
          "blendShapeIndex": 4,
          "start": 0.0,
          "end": 100.0,
          "step": 15.0
        }
      ]
    }
  ]
}

kind = Indictes how the asset is treated by the plugin. Options: Creature, Aura, Effect, Filter. category = Indicates under which main icon the asset is found. Defaults to Kind (above). groupName = Indicates the group in which the asset is found. description = Description of asset. Currently not used. name = Indicates the name which the asset will have when spawned. tags = Tags by which to search. No yet used but will be used in the future. author = Indicates the author show on mouse over. version = Indicates the version shown on mouse over. comments = Comments regarding the asset. Currently not used. prefab = Name of the prefab to be instances in the asset bundle. Defaults to name. animationOrder = List of animation names used to force the order in which animations map to the trigger keys. variants = Additional prefabs inside the same asset bundle typically variations on the same asset. blendshapes = Defenition of blendshape sequences with optional audio and animation triggers.

Tweaks (Cache Location)

When ANGEL registers assets it adds information about the asset into a cache file as well as its portrait. Thus allows the plugin to start faster on successive sessions because it does not need to repeat the complete registration step. This cached assets file is a JSON file which essentially contains the info.txt content for each asset as well as a few extra pieces of data. This file is what ANGEL uses to generate the ANGEL menu. This means this file can be used to make some tweaks registered assets without having to rebuild the asset. The most common use of this is to Change the group that the asset appears in.

By default the cache folder is a sub-folder of the ANGEL plugin install folder. This means when ANGEL plugin is removed, there are no extra files that need to be removed. However, this also means that when the ANGEL plugin is updated, the cached files disappear because R2ModMan removes the folder and re-creates it when it installs the newer version. This is usually not a problem since ANGEL will re-regster the assets at the beginning of the next session but it can be a problem if you have applied a bunch of asset tweaks.

To avoid this issue the ANGEL plugin can be configured to place the cache folder outside the ANGEL plugin install folder. By default that is where it will be configured but by changing the configuration to something like [LocalContent], the cache will exist outside the ANGEL plugin folder and thus ANGEL plugin updates will not remove the tweaks.

Dark Angel (Disclaimer)

If this plugin is used in a manner which is identified as a way that the plugin should not be used in, including but not limited to the plugin being used if marked dead/broken/obsolete and the plugin detects this, it may heckle the users or play harmless pranks on the user. If the user follows the basic usage of this plugin including checking for obsoleteness aftter updates, they won't be heckled or pranked.