1.2.0-beta.1

• Add support for third-party asset container management.
  • In preparation for the introduction of IAssetSaver in NDMF 1.6.0,
    add the ability to delegate the management of the asset container to a third party.
    • No new dependencies are added.
    • By default, the behaviour of Animator As Code is the same as V1.1.0.
  • Add new optional field AacConfiguration.AssetContainerProvider to specify an asset container provider.
  • Add new interface IAacAssetContainerProvider to abstract asset container management.

The above changes have been contributed by kb10uy (KOBAYASHI Yū) (first contribution).

As specified in the changelog for the official release of Animator As Code V1, breaking changes had been planned, and will be applied starting this version:

• AacFlSettingKeyframes constructor is now private.
  • For compatibility reasons, it was public for the duration of V1.1.x, and was already marked as obsolete in V1.1.x.
• The methods AacFlBase.InternalConfiguration and AacFlBase.InternalDoCreateLayer are now private.
  • For compatibility reasons, it was public for the duration of V1.1.x, and was already marked as obsolete in V1.1.x.
  • The class AacAccessorForExtensions replaced them.

These breaking changes are meant to be the last breaking changes for the lifetime of Animator As Code V1.

1.1.0

☀️ Animator As Code V1

Animator As Code V1 has been released.

Starting from V1.1.0, all Animator As Code V1 packages are leaving Alpha/Beta.

Animator As Code V1 can now be safely used in public projects that wish to do so.

Compatibility with projects that contain Animator As Code V0

Animator As Code V1 is designed to be installed even in projects that already have Animator As Code V0.

Animator As Code V0 will not be overwritten by Animator As Code V1. Both installations will act as separate,
non-conflicting installs. Projects like FaceEmo will continue to function properly.

In fact Animator As Code V1 has already been extensively used in my own tools (Prefabulous, ComboGestureExpressions, Vixen).

There is no real need to migrate between V0 and V1, if V0 already provides all the functionality you need in your project.

If you choose to migrate, V0 and V1 are almost identical.

Features in V1 compared to V0

Sub-State Machines

• Pull major contributions from @galister which:
  • Adds support for sub-state machines, which is important because it enables the creation of states that evaluate multiple transitions within one frame,
    which is not possible to do without sub-state machines (with one exception).
    • This trait is already extensively used in ComboGestureExpressions V2 and above.
  • Share functionality of state and sub-state machines.
  • Share functionality of Int and Float parameters together.

// When using Sub-State Machines, the Sub-State Machine will evaluate all transitions until
// it resolves a destination state within one single frame.
// This means it can traverse multiple transition conditions at once, no matter how nested
// the Sub-State Machine is.
//
// This is not doable with just states, so Sub-State Machines have a functional value beyond mere organization.
var a = layer.IntParameter("IntA");
var b = layer.IntParameter("IntB");
var rootSsm = layer.NewSubStateMachine("UsingNestedSubStateMachines");
for (var i = 0; i < 16; i++)
{
    // A Sub-State Machine can have other Sub-State Machines created inside them.
    // TransitionsFromEntry creates a transition between `subSsm` and the Entry node of the Sub-State Machine it belongs in.
    // Exits creates a transition between `subSsm` and the Exit node.
    
    var subSsm = rootSsm.NewSubStateMachine($"A = {i}");
    subSsm.TransitionsFromEntry().When(a.IsEqualTo(i));
    subSsm.Exits();

    for (var j = 0; j < 16; j++)
    {
        var state = subSsm.NewState($"A = {i} and B = {j}");
        state.TransitionsFromEntry().When(b.IsEqualTo(j));
        state.Exits()
            .When(a.IsNotEqualTo(i))
            .Or()
            .When(b.IsNotEqualTo(j));
    }
}

// This creates a transition between the Sub-State Machine and itself.
// When that Sub-State Machine exits, it will re-enter itself.
rootSsm.Restarts();

Packaging, Non-VRChat projects, and non-destructive

• Make it usable in non-VRChat avatar projects.
  • VRChat-related functionality is now exposed as extension functions in a separate package.
  • Also, separate destructive functions and non-destructive functions.
  • Since this no longer requires a VRChat project, this also means it may now be usable in VRChat world projects.

// Animator As Code V1 no longer requires VRChat (compared to V0).
// VRChat-specific functions have been moved to extension methods.
// If you want to use VRChat Avatars functionality, add the `Animator As Code V1 - VRChat` package, and do the following:
//
// Add the following import:
// using AnimatorAsCode.V1.VRC;
// 
// To access VRChat parameters, use the following extension method:
var vrcAv3 = layer.Av3();
// To access VRChat assets, use the following extension method:
var vrcAssets = aac.VrcAssets();

layer.NewState("UsingVRChat")
    .WithAnimation(vrcAssets.ProxyForGesture(AacAv3.Av3Gesture.HandOpen, false))
    // VRChat State Behaviours are created through extension methods located in namespace `AnimatorAsCode.V1.VRC`
    .TrackingAnimates(AacAv3.Av3TrackingElement.RightHand)
    .Driving(driver => driver.Sets(layer.BoolParameter("A"), true))
    .TransitionsFromEntry()
    .When(vrcAv3.GestureRight.IsEqualTo(AacAv3.Av3Gesture.HandOpen));

• Make it more usable in non-destructive components.
  • It is already in use in Prefabulous and Vixen.
• Move to packages, for distribution using VCC (and now, ALCOM).

BlendTrees

• It is now possible to build Unity BlendTree assets using a fluent interface.

layer.NewState("BlendTrees").WithAnimation(aac.NewBlendTree()
    .FreeformDirectional2D(layer.FloatParameter("X"), layer.FloatParameter("Y"))
    .WithAnimation(aac.NewClip("Center"), 0, 0)
    .WithAnimation(aac.NewClip("Up"), Vector2.up)
    .WithAnimation(aac.NewClip("Right"), 1, 0)
    .WithAnimation(aac.NewClip("Down"), 0, -1)
    .WithAnimation(aac.NewClip("Left"), -1, 0)
);
var one = layer.FloatParameter("One");
layer.OverrideValue(one, 1f);
layer.NewState("Direct BlendTree").WithAnimation(aac.NewBlendTree()
    .Direct()
    .WithAnimation(aac.NewClip("DrivenByA"), layer.FloatParameter("A"))
    .WithAnimation(aac.NewClip("AlwaysOn"), one)
    .WithAnimation(aac.NewBlendTree().Simple1D(layer.FloatParameter("B"))
            // In Animator As Code, it is safe to declare points in a Simple1D blend tree in a different order (i.e. 0, 1, -1).
            // (In native blend trees, it would not have been safe to do so)
            .WithAnimation(aac.NewClip("Zero"), 0)
            .WithAnimation(aac.NewClip("Positive"), 1)
            .WithAnimation(aac.NewClip("Negative"), -1)
        , one)
);

Create Animator Controllers

• Create new Animator Controllers. This is made specifically for non-destructive workflows, where additional features are built separately,
  and then merged by a framework (i.e. Modular Avatar Merge Animator, or VRCFury Full Controller).
• Animator As Code V1 has a separate package specifically to create Modular Avatar components, see the section later on this page.

    // When creating a new controller, the ContainerMode of the configuration usually needs to be
    // set to either `Container.OnlyWhenPersistenceRequired` or `Container.Everything`.
    //
    // This is because it is not possible to add state behaviours to states unless the Animator Controller
    // is already persisted in the asset database.
    var controller = aac.NewAnimatorController();
    var fx = controller.NewLayer();

VRChat-specific features

AnimatorPlayAudio

• Animator As Code for VRChat supports for VRCAnimatorPlayAudio through the AacFlState.Audio(AudioSource or string, ...) function,
  which takes a lambda expression as a parameter.

AudioSource source = MyAudioSource(); // This can be a string instead.
AudioClip[] clips = MyAudioClips();
layer.NewState("UsingAudio")
    .Audio(source, audio =>
    {
        // Get the PlayAudio object if there's a need to edit it directly.
        VRCAnimatorPlayAudio vrcAnimatorPlayAudio = audio.PlayAudio;

        // By default, a PlayAudio created through AAC does nothing (unlike a manually created behaviour)
        // so you need to invoke anything that is relevant.
        audio
            .SelectsClip(VRC_AnimatorPlayAudio.Order.Random, clips)
            .SetsLooping()
            .RandomizesPitch(0.8f, 1.2f)
            .RandomizesVolume(0.5f, 1f)
            // "Replays" means Stop and Play.
            // "StartsPlaying" means just Play.
            // "StopsPlaying" means just Stop.
            // To do neither Stop nor Play, don't invoke anything.
            .StartsPlayingOnEnter()
            .StopsPlayingOnExit();
    });

Prettier Parameter Drivers

• As VRCAvatarParameterDriver has evolved over the years, you can now build multiple VRCAvatarParameterDriver behaviours on the same state
  through the AacFlState.Driving(...) function, which takes a lambda expression as a parameter.

layer.NewState("UsingDrivers").Driving(driver => driver
    .Copies(layer.FloatParameter("CopySource"), layer.FloatParameter("CopyDestination"))
    .Sets(layer.FloatParameter("Set"), 2.3f)
    .Increases(layer.FloatParameter("IncreaseBy2"), 2f)
    .Decreases(layer.FloatParameter("DecreaseBy3"), 3f)
    .Randomizes(layer.FloatParameter("Randomizes"), 0f, 100f)
    .Randomizes(layer.BoolParameter("RandomizesBool"), 0.25f) // 25% chance of being true.
    .Remaps(layer.FloatParameter("RemapsSource"), 0f, 2f, layer.FloatParameter("RemapsDestination"), 2f, 4f)
// This creates a second VRCAvatarParameterDriver in the same behaviour.
).Driving(driver => driver
    .Sets(layer.FloatParameter("SecondDriver"), 100f)
    .Locally() // Only this second VRCAvatarParameterDriver is local.
);

Integration with Modular Avatar (MaAc)

Using the Animator As Code V1 - Modular Avatar functions, it can create Modular Avatar components.

• Newly created Animator Controllers can be assigned into a new Modular Avatar Merge Animator.
• Synced Bool parameters (1 bit) can be created using the same Float parameters objects used in Animator As Code,
  through Modular Avatar Parameters.

var ctrl = aac.NewAnimatorController();
var fx = ctrl.NewLayer();

var toggleFloatParameter = fx....

1.1.0-beta.9

• Add AacAccessorForExtensions:
  • Add static class AacAccessorForExtensions:
    • Provides methods for use by extension functions, exposing methods departing from normal fluent interface usage.
  • Prepare to make methods marked "Not for public use" private starting from V1.2.0.
  • Due to their active use in other packages, it is not immediately private.

1.1.0-beta.8

• Fix Any state transitions will be created from SSMs:
  • Due to an implementation error, creating Any state transitions previously did not have any effect in the graph.
  • This now creates Any state from the root machine.
  • Sub-state machines "cannot" have Any state transitions created directly from them.
  • Internally, Any always comes from the root state machine, but visually in the graph, it will come from the sub-state machine.
• Make sure State and SSM names don't contain a period '.':
  • If the name of a state contains a period ".", it can cause the animator to misbehave, so sanitize it.
  • Transitions would not work properly during the runtime execution of the animator.
  • Apparently this is because sub state machines internally use the dot as a separator.
  • Sanitize the name so that menu state names such as "J. Inner" don't mess things up.
• Fix calling Or() after TransitionsFromEntry().When(...) no longer fails:
  • Calling Or() after TransitionsFromEntry().When(...) used to fail due to an unexpected internal state.
  • This was due to the implicit conversion operator, which converted a null AnimationState to a AacTransitionEndpoint containing null in it.
  • Fix this by returning null in the implicit conversion operators.

1.1.0-beta.7

• Keep AacFlSettingKeyframes public until V1.2.0:
  • Keep AacFlSettingKeyframes public until V1.2.0, where it will be made internal.
  • AacFlSettingKeyframes is still used in CGE, but CGE already accepts AAC V1.1.x.

1.1.0-beta.6

• Fix Animator Removal constructor actually needs to be public.

1.1.0-beta.5

• (BREAKING) Replace public readonly fields with properties:
  • Fix inconsistency by replacing public readonly fields with getter-only properties.
  • Add PublicAPI annotation where it was missing.
• (BREAKING) Make constructors non-public:
  • Fix inconsistency where constructors were public.

1.1.0-beta.4

(BREAKING) Rename AacFlSettingObjectReferenceKeyframes to AacFlSettingKeyframesObjectReference:

• Breaking changes:
    - Rename AacFlSettingObjectReferenceKeyframes to AacFlSettingKeyframesObjectReference.
• This makes it more in line with AacFlSettingKeyframesColor.
• AacFlSettingObjectReferenceKeyframes was introduced specifically for Vixen, and it is meant to be used as a lambda expression, so the breaking damage should be limited.

1.1.0-beta.3

• Add AacFlState.WithMotionTime to replace AacFlState.MotionTime:
  • Add AacFlState.WithMotionTime(...) to replace AacFlState.MotionTime()
  • This is more in line with the function naming convention
  • The previous naming is also preserved not to break existing uses.
• Work towards correcting inconsistencies in the API:
  • Rename *Percent to *Normalized.
  • Update inline documentation.
  • Add additional single-valued and array overloads.
  • Add AacFlSettingCurveObjectReference.WithUnit to be on-par with AacFlSettingCurve.
  • Add AacFlSettingCurveColor.WithUnit to be on-par with AacFlSettingCurve.
  • The previous naming is also preserved not to break existing uses.
• Make Component[] null-element safe and add missing multi-component:
  • Make Component[] null-element safe.
  • Add missing multi-component variations of existing APIs.
• Inline documentation pass.

1.1.0-beta.2

• Fix AacFlState.WithCycleOffset(AacFlFloatParameter floatParam) now correctly enables the parameter.
• (BREAKING) Make AacFlController.AnimatorController read-only
• Update LICENSE: Add galister for major contributions.
• Do a pass on the documentation:
  • Add and update inline documentation.
  • Mark some inconsistencies.
  • Not everything is reviewed yet.