Cybernetic powers for your cyber avatar.
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-16 19:26:47 +01:00
Lib backdated avisor 0.1.0 commit 2026-09-07 22:36:00 +01:00
Main backdated avisor 0.1.0 commit 2026-09-07 22:36:00 +01:00
.gitignore backdated avisor 0.1.0 commit 2026-09-07 22:36:00 +01:00
protograph.toml backdated avisor 0.1.0 commit 2026-09-07 22:36:00 +01:00
README.md update formatting 2026-10-16 19:26:47 +01:00

avatarVISOR

Rationale

In Resonite, it is common for users to install various systems onto their avatar. Everything from simple boopers, to full information & control systems. The issue becomes that, these systems are installed & tied to a specific avatar. If you want to have multiple avatar models (say you have a Winterpaw, a Renou, a Sap Avali, and an Expie), you have to manually install all these systems on every avatar.

While previous work in this area, primarily Colin's Avatar Standard does help with this by making avatar systems easier to port across multiple avatars, it still requires users to update every one of their avatars with every update to each system, usually by pulling out each avatar, dragging systems over with an inspector, and resaving a new version of the avatar.

avatarVISOR intends to further modularise avatars so that the avatar model itself can easily be swapped out, while keeping all the same systems, and provide tooling to make the user experience just as easy as Resonite's native avatar equipping.

High-level overview

avatarVISOR separates your avatar into the following two pieces

  • Host/supervisor objects: wrap packages, providing useful functionality, and act to scope DynamicVariableSpaces to ensure unintended behaviour if variables in packages were allowed to link freely with whatever they are parented under.
    • Avatar Supervisor: This is the actual 'avatar' object as far as Resonite is concerned. Generally, you will save the supervisor with in a fully complete state, with all your systems, assets & renderers on it so that you don't have to manually equip those whenever you open a new session. The supervisor also manages the lifecycle of equipping & de-quipping various packages.
    • Installer hosts: contain de-quipped packages and additional logic to enable the easy installation UX.
  • Packages: are anything that contain a set of systems, assets, or renderers. There are three main categories:
    • Core: Everything you want to keep available at all times, your common systems, assets & logic. Will also contain things like your name badge, context menu, and the systems parent slot, and computes the final value for things like, multiple systems trying to drive the same blendshape.
      While still technically referred to as a 'package', the core package is more likely to be built into a specific person's supervisor, instead of being regularly swapped out.
    • Presentation: What, up until this point I have been referring to as an 'avatar model', and contains your avatar's body, armature, VRIK configuration, assets, systems, etc. Basically everything that's unique to one specific 'look' of your avatar. Generally, you you would have one presentation for each of the avatar bases you like to use.
    • Expansion: Provides a way to easily (un)install multiple systems, assets, etc at once. For example, you might have an expansion package for an outfit you don't want to have loaded at all times.

Packages, while designed to be modular and easily swappable, they're still fully expected to be specific to one person's avatar, as for example, one person's avatar might have common materials in the core package, so it is fully expected that someone else loading your presentation for example would, at best, look incorrect.

Limitations

  • As mentioned, packages are not likely going to Just Work when swapped between entirely distinct ecosystems. This is to be expected though, as standardising literally everything you could do with an avatar would be impossible, and you would already need to edit the presentation anyway as you would probably want to, for example, retexture the model, and use of avatarVISOR would likely make that process easier than without it. But key specific issues that make this hard are:
    • Different avatar models will differ in the specifics of blendshapes, bones, position of body parts relative to bones, etc
    • The case of multiple systems trying to affect the same thing, for example, blendshapes, there has to be explicit handling to calculate the final value, and systems that use an 'overlay' material have to be explicitly expected in each mesh renderer, as you cant arbitrarily modify lists in ProtoFlux
  • While, you can install everything common to each presentation into your core, and everything specific to each presentation within that presentation, you might have some things that are common, but only amongst half your presentations so you either have to copy that into each presentation and manually keep each up to date with any changes, create expansion packages for everything common and remember to manually equip each expansion package as needed, or store it in your core where it will be loaded unnecessarily. This is also problematic for each expansion package which needs to have specific assets for each presentation.
    • A workaround to this could be to use a trick to selectively enable hierarchies and BooleanValueDrive the URI field of assets - only loading assets when required but this can be quite tedious.
    • Ideally, we'd have a proper package management & dependency system, (aka. Molecule) within Resonite that allows these dependency trees to exist and have things automatically spawn out when needed. In fact, Molecule would eradicate a lot of the reason for avatarVISOR to exist as you could just reuse your core package on all your avatars.

Technical Specifics

Host/supervisors:

Avatar supervisors must:

  • Have the tag avisor_supervisor
  • Have a dynamic variable space avisor , with the following variables:
    • avisor/Root (Slot, required): Reference to the avatar root.
    • avisor/SupervisorSystem (Slot, required): Reference to the avatarVISOR systems slot (ie. for dynamic impulse scoping)
    • avisor/PresentationHolder (Slot, required): Reference to a slot that the presentation will be held within.
  • Have a dynamic variable space Avatar , which SHOULD have the following variables:
    • Avatar/Root (Slot): Reference to the supervisor avatar root
    • Avatar/Name (string): Dynamic field of the name of the supervisor root
  • Respond to the following Dynamic Impulses:
    • avisor.RequestPresentationSwitch (async, with the installation package host as a Slot argument): Perform the presentation switch procedure

Installer hosts must:

  • Be tagged with avisor_installer
  • Have the avisor dynamic variable space.
    • avisor/Root (Slot, required): Reference to the installer root
    • For packages containing a presentation package:avisor/PresentationHolder (Slot, required): Reference to a slot that the presentation is held within.
  • Present some kind of UI that allows user with compatible avatar supervisors to push a button (i.e. via context menu), which triggers an async dynamic impulse a slot argument (that is the root of the installation package) directed at the slot referenced by SupervisorSystem with the tag avisor.RequestPresentationSwitch
  • To determine if the user is using a compatible supervised avatar:
    • Find a child of the local user slot with the tag avisor_supervisor
    • Read the Dynamic Slot variable avisor/SupervisorSystem

Packages

Packages must:

  • Not have either the Avatar or avisor dynamic variable spaces,
    • May read from the avisor dynamic variable space, but MUST NOT contain any components such as DynamicValueVariable in this space.
  • Not have any references outside the package hierarchy, or any references from outside in.
  • Handle being moved between different hosts (i.e. between different supervisors & installation packages) gracefully.

Proceedures

Presentation switch

I do not trust Resonite to reasonably handle switching the VRIK and everything while a user is in an avatar (and also things like the reference assigners), and I am also concerned about dynamic variables accidentally having their values overwritten, I am being cautious by delaying on every move, but whether this is actually required I am not sure. All moves of slots should be done without PreserveGlobalTransform (ie, just set the parent)

  1. De-quip the user's avatar (ie. equip a basic avatar)
  2. Create a temporary slot outside of any host that has the DynamicVariableSpaces: avisor & Avatar
  3. Move the contents of the avatar's PresentationHolder slot to the temporary slot.
  4. Delay for 5 updates
  5. Move the contents of the installer's PresentationHolder into the avatar's PresentationHolder
  6. Delay for 5 updates
  7. Move the contents from the temporary slot into the installer's PresentationHolder
  8. Re-equip the user's original avatar.
  9. Delete any temporary slots & avatars.