runtime.md

# SpineAnimationRig - Runtime

- License
- Files
- How to implement
- How to implement in Unity
- Run unity sample
- How to set values from application
- How to use preset file
- Serialize / Deserialize (state save/load)
- Event callback
- UserMemo
- How to use runtime 3.6

# Contact , Support , Product homepage

Please access the following
以下よりアクセスしてください。

- https://ko-ta2142.github.io/SpineAnimationrigPage/
- https://sameasm.net/spineanimationrig/

# License

The runtime does not use spine-runtime alone.
ランタイムは抽象化されているため、単体ではspine-runtimeを使用しません。

If you use Spine-runtime, the Spine license also applies.
Spine-runtimeを使用する場合は、Spineのライセンスも適用されます。

## Aimationrig runtime

Under the MIT License.

This runtime(files) is licensed under the Expat License, sometimes known as the MIT License: Copyright Ko-Ta Takeuchi.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.

## Spine runtime

- Spine License - runtime

http://esotericsoftware.com/spine-runtimes-license

Some Spine-animations may not play(draw) correctly. If the animation display is disturbed, Please use the attached patch files.
Spineアニメーションによっては正しく再生されない可能性があります。もし表示が壊れる場合は、付属のパッチファイルを使用ください。

    spine_runtime_patch/3.7/
    spine_runtime_patch/3.8/

# Files

common |
--- | ---
CommonMS | Basic binary operation class.
Animrig.Misc | Types and Multi platform binary-rw functions.
Animrig.Animationrig | Read animationrig format file. Build data structure.
Animrig.AnimationrigState | Do the animation!
Animrig.StateInput | Send value to the animation from application.
Animrig.StateRenderer | Control the renderer virtual class.
Animrig.SpineRenderer | Spine control class.
Animrig.Preset | Load and execute from *.animrig.preset.txt file.

unity |
--- | ---
Animrig.Unity.AnimationrigIUnityStateRenderer | StateRenderer interface.
Animrig.Unity.AnimationrigStateComponent | AnimationrigState component.
Animrig.Unity.AnimationrigSpineRendererComponent | StateRenderer-Spine component.

spine mix-add patch |
--- | ---
3.7 | Spine 3.7 latest runtime patch.
3.8 | Spine 3.8 latest runtime patch.

# How to implement

## Need a drawing environment(workspace) for spine

This runtime only has function to control spine. You need to setup an environment(workspace) to load and draw the spine.
このランタイムはspineを制御するだけの機能しか有していません。spineを読み込んで表示させる環境をご用意ください。

## Load and create

First, Read the file. And create AnimationrigState from Animationrig data class.
まずファイルを読み込みます。読み込んだ Animationrig データから実行用の AnimationrigState を生成します。

        // setup data
        var anim = new Animrig.Animationrig();
        // load
        {
            MemoryStream ms = CommonMS.LoadFromFile("data/sample.animrig");
            anim.LoadFromBinary(ms);
        }
        // setup state
        var state = new Animrig.AnimationrigState(anim);
        state.OnEvent = EvenetCallback; // event callback

## Update

Execute by calling AnimationrigState.Update().
AnimationrigState.Update() を呼ぶことで実行します。

        // deltatime : 1sec = 1.0
        state.Update(0.1);

Not enough to control spine. You need to define a class for control.
これだけではspineを制御するには不十分です。コントロール用のクラスを定義する必要があります。

## Define renderer control class

Define AnimationrigStateRenderer class for control. The finished thing is AnimationrigSpine.cs file.
コントロール用 AnimationrigStateRenderer クラスを定義します。出来上がったものが AnimationrigSpine.cs ファイルになります。

    // property
        public class SpineRenderer : StateRenderer
        {
            public static readonly int SaveVersion = 1;
            public Spine.AnimationState state = null;   // Spine
            public Spine.Skeleton skeleton = null;      // Spine

            public SpineRenderer();
            // common
            public override void Update(double deltatime);
            // spine control
            public override void SetAnimation(int trackindex, int usetrack, string basename, bool loop, bool addanim, MixBlend trackmix, float duration, bool seekmode);
            public override void SetTrackBlendAlpha(int trackindex, int usetrack, float alpha1, float alpha2, float alpha3, float alpha4, bool exists);
            public override void SetTrackSeekTime(int trackindex, int usetrack, float time1, float time2, float time3, float time4, bool exists);
            public override void SetMixDuration(float duration);
        }

These methods are called back in AnimationrigState.Update(). Relay the instruction to Spine.AnimationState & Skeleton.
これらメソッドは AnimationrigState.Update() 関数内でコールバックされます。設定された Spine.AnimationState & Skeleton へ命令を中継します。

Please see RendererObject for details.
詳しくは RendererObject をご覧ください。

## Set renderer objects

AnimationrigState provides StateInput to control with the application. Set that class to the Renderer property.
AnimationrigState にはアプリケーションとやり取りするための StateInput が用意されています。Renderer プロパティにセットしてください。

        // create state renderer
        var spinerenderer = new Animrig.StateSpineRenderer();
        spinerenderer.state = spineobject01.AnimationState;
        spinerenderer.skeleton = spineobject01.Skeleton;
        // in sample.animrig file
        // [0] : spine object
        // [1] : null object
        state.InputObjects[0].Renderer := spinerenderer;

If you set a different object-type in the animation file objects, throw the exception error.
もしアニメーション中のオブジェクトと異なるタイプ(object-type)を指定した場合、例外が投げられます。

# How to set values from application

Manipulating values ​​from the application is very easy Access InputObjects to set the value. It has a simple easing function.
アプリケーションからアニメーションへ値を送るのはとても簡単。 InputObjects にアクセスして値を設定します。 標準でイージング機能を持っています。

        // inputvalue[0] = 0.5
        state.InputObject[0].SetValue(0 , 0.5f);
        // use easing
        // duration : 1.0
        // ease : InOutQuad
        state.InputObject[0].SetValue(0 , 0.5f , 1.0f , Animrig.Easing.InOutQuad);

# How to use preset file

Adjust the value on the editor, You may want to use it on your application. It's very easy to do with the Preset class.
エディタで値を調整し、それをアプリケーションで使いたいと考えることもあるでしょう。 Preset クラスを使えば簡単に実現できます。

        // load preset
        preset = new Animrig.Preset();
        {
            MemoryStream ms = CommonMS.LoadFromFile("data/sample.animrig.preset.txt");
            preset.LoadFromStream(ms);
        }

## SetPreset

Set the contents of the preset to a value. It has a simple easing function.
指定した名前のプリセットを InputObject に反映します。 標準で簡単なイージング機能を持っています。

        preset.SetPreset(
            state.InputObjects[0],
            "happy",       // preset name
            1.0,           // duration
            Animrig.Easing.InOutQuad   // ease
        );

## SetDefault

Set values to default on editor.
もしエディタでデフォルト値を設定していれば、その値を設定します。初期状態では0.0になります。

## SetClear

Set values to 0.0f.
値を 0.0 で設定します。

# Serialize / Deserialize (state save/load)

AnimationrigState has the state serialize function.
AnimationrigStateには状態の保存機能を持っています。

    // save
    var ms = new MemoryStream();
    state.SaveToBinary(ms);

    // load
    ms.position = 0;
    state.LoadFromBinary(ms); // return bool

Only AnimationrigState is restored. Objects(such as spine) are not restored. If you need a full state restore, you need to define the object SaveLoad function.
復元されるのはAnimationrigStateだけです。 spineなどは復元されません。もし完全な状態復元が必要なら、オブジェクトのSaveLoadをあなたが用意する必要があります。

If the animation data(Animgrig file) has changed, Save data compatibility is lost. but, It will try to restore as much as possible. If fewer changes , may be possible to restore.
もし、アニメーションデータ(Animgrig file)に変更が入った場合、基本的には互換性は失われます。しかし、出来るだけ頑張って復元しようと試みます。 少ない変更であれば、復元できる可能性があります。

# Event callback

Set the function to AnimationrigState.OnEvent to receive the event of the event-object on the application side.
アプリケーション側でイベントオブジェクトのイベントを受け取るにはAnimationrigState.OnEventに関数を設定してください。

    public void OnAnimationrigEvent(Animrig.AnimationrigState state, ref Animrig.StateEventData data)
    {
        // If you want to know the event source object, use InputObject.UserObject property.
        // anim.State.Inputs[0].UserObject = YoureGameObject;           // set
        // var YoureGameObject = data.Input.UserObject as GameObject;   // get
        if (data.Strings0 != "") Debug.Log(data.Strings0);
        if (data.Strings1 != "") Debug.Log(data.Strings1);
    }

    // event
    anim.State.OnEvent = OnAnimationrigEvent;

# UserMemo

User-Memo is free areas from editor. If you want to keep special settings ​​in the file, please use it.
エディタのユーザメモは自由に使うことが出来ます。もし特殊な値をファイルに保持させたい場合は、この領域を使うと良いでしょう。

    if (anim.UserMemo.Length > 0){
        var settingdata = anim.UserMemo[0];
    }

# How to implement in Unity

Components are provided for use with Unity. You can easily setup spine. At first I think that it is good to test with Unity.
Unityで使う場合は、コンポーネントが用意されています。 spineの準備も楽ちんなので、まずはUnityで触って感触を掴むと良いと思います。

## Setup spine

Please see the official page or etc.
ここでは説明しません。オフィシャルページなどをご覧ください。

http://esotericsoftware.com/spine-unity

## Include Animationrig asset

Include the following files (copy to asset folder).
以下のファイルを組み込んで（assetフォルダにコピーして）ください。

    runtime/csharp/lib/*.cs
    runtime/csharp/lib_unity/*.cs

Animationrig appears on component menus.
component メニューに Animationrig が追加されます。

## Setup AnimationrigState Component

First, setup AnimationrigState object. Create an empty GameObject and attach the AnimationrigState component.
まず AnimationrigState を準備します。 空のGameObjectを作り、AnimationrigState コンポーネントを追加してください。

- Animrig TextAsset

Set Animationrig binary file. To use binary files in Unity, you need to change the file-extension to .bytes.
Animationrigバイナリファイルを指定します。Unityでバイナリファイルを扱うには .bytes に拡張子を変更する必要があります。

- Preset TextAsset

Set the Preset text file. This file is used in text format .txt.
Presetテキストファイルを指定します。これはテキスト形式 .txt で取り扱います。

- AutoUpdate (def : true)

Automatically update time using Unity's Update(). If you want to control manually, please disable.
Unityの Update() を使用して自動で時間更新を行います。手動でコントロールする場合は無効にしてください。

- UpdateOnce (def : true)

Call object update only once.
一回のUpdateでオブジェクトのUpdateを一回だけ呼び出します。60フレームで動作するなら問題ありません。

- Renderer Objects

Set the GameObject to link with the animation. It will be explained in the next section.
リンクさせるGameObjectを指定します。次のセクションで説明します。

## Setup SpineRenderer Component

Attach Animationrig-SpineRenderer component to the spine game object.
spineのゲームオブジェクトに Animationrig - SpineRenderer コンポーネントを追加します。

SpineRenderer relays the operation of AnimationrigState.
SpineRenderer は AnimationrigState の操作を中継する役割を持ちます。 このコンポーネントを追加しないかぎり影響を受けません。

- Override Update (def : false)

In Unity, spine components update time. If AnimationrigState does it, please enable.
Unityではspineのコンポーネントが時間更新を行います。AnimationrigStateに委ねる場合は有効にしてください。

- Override Enable

Synchronize with GameObject.selfActive.
GameObject.selfActiveと連動させます。

- Override Transform

Synchronize with GameObject.Transform. Set the Local coordinates. Create a RootTransformObject like the image.
GameObject.Transformと連動させます。ローカル座標が設定されるので、画像の RootTransformObject のようにルートを設けてください。

- Override Color

Synchronize with the Spine.Skeleton-color.
Spine.Skeletonの色と連動させます。

- Override Default Mix

Overwrite spine-DefaultMix. If you want to set it manually, please disable it.
SpineのDefaultMixの値を上書きします。手動で設定する場合は無効にしてください。

- Pixel per Unit (def : 100)

Set the spine(GameObject) scale. There is a factor of 100 between editor and unity.
spine(GameObject)の倍率を指定します。エディタとunityでは100倍の差があります。

- Transform Scale (def : 1.0)

Set the overall scale.
全体の倍率を設定します。大きさ、位置全てに影響を与えます。

## Attach Spine GameObject

Back to the AnimationrigState component. Set RendererObjects to GameObject.
AnimationrigState コンポーネントに戻ります。 RendererObjectsにアニメーションと対応するGameObjectを設定していきます。

If the RendererObjects name is none, please update it with the reload button.
もしRendererObjectsの名前などがnoneの場合は、reloadボタンで更新してください。

# Run unity sample program

The sample program demonstrates the following features:
サンプルプログラムは以下の機能のデモンストレーションになっています。

- Switch animation to a good feeling (fade)
  良い感じにアニメーションを切り替える機能（フェード）
- Composite animation to a good feeling (track)
  良い感じにアニメーションを合成する機能（トラック）
- Manage and set values ​​collectively to a good feeling (preset)
  良い感じに値を管理、設定する機能（プリセット）
- Ccontrol values ​​from an application to a good feeling (direct input)
  良い感じにアプリケーションから値を操作する機能（ダイレクトインプット）

## Animation fade

Interpolate switching of animation to a good feeling.
アニメーションを切り替える際の繋ぎを良い感じに補間します。

        if (name == "empty")
        {
            // 1 sec fade , clear animation
            anim.State.ClearTrackFade(2, 1.0f);
        }
        else
        {
            // 1sec fade , next animation
            anim.State.EntryTrackFade(2, name, 1.0f, Animrig.Easing.InOutQuad);
        }

You can also check the fade feature on the editor.
エディタ上でも動作確認することが出来ます。

## Animation tracks

Animationrig also has a track function. It is possible to combine multiple animations. The sample can overlap breathing motion and various movements.
Animationrigでもトラックの概念があります。複数のアニメーションを合成することが可能です。サンプルでは呼吸モーション（breath body noise)に様々な動きを重ねることが出来ます。

        anim.State.EntryTrack(0, "setup");
        anim.State.EntryTrack(1, "lol");
        anim.State.EntryTrack(2, "testmotion");

## Preset

Even if you control the animation from the application side, you may use values ​​designed on the editor. You can register a preset in the editor and use it.
アニメーションをアプリケーション側からコントロールする場合であっても、エディタ上でデザインされた値を使用するケースは少なくありません。 エディタでプリセットに登録し、それを用いることが出来ます。

        if (name == "default")
        {
            // 1 sec fade , set default
            anim.Preset.SetDefault(anim.State.Inputs[0], 1.0f);
        }
        else
        {
            // 1 sec fade , set preset
            anim.Preset.SetPreset(anim.State.Inputs[0], name, 1.0f);
        }

## Direct input

If you want to control the eyes from camera image processing and the mouth from microphone voice input, change the value directly.
もしカメラの画像処理やマイク音声入力から、口や目をコントロールしたいなら直接値を変更しましょう。

        anim.State.Inputs[0].SetValue(0, a1, 0.0f);
        anim.State.Inputs[0].SetValue(1, a2, 0.0f);

# How to use runtime 3.6

The editor does not support 3.6, but you can run 3.6 Spine by changing the program a little.
エディタは3.6に対応していませんが、プログラムをちょっと変更することで、3.6のSpineを実行することが出来ます。

However, You can not be used MixAdd function.
ただし、MixAddの機能は使用できません。

## Editor side

The editor uses output in the format 3.7 or higher. These are for editor only , and not use it for programs.
エディタは3.7以上の形式で出力した物を使用します。これらはエディタ専用で、プログラムでは使用しません。

## Program side

Animationrig-runtime uses Animrig.SpineRenderer to control Spine. This class derived from the abstract class Animationrig.StateRenderer , and It is possible to control other objects by deriving an abstract class.
Animationrig-runtimeがSpineを操作するには Animrig.SpineRenderer を使用します。これは抽象クラス Animationrig.StateRenderer を派生したクラスで、抽象クラスを派生させれば他のオブジェクトを扱うことも可能です。

This time Animrig.SpineRenderer corresponds to 3.6.
今回はこの Animrig.SpineRenderer を3.6に対応させます。

This work is easy. Change Spine-runtime version to 3.6 and compile. Then you will get errors.
作業は簡単です。まずSpine-runtimeを3.6に変更し、コンパイルします。すると数カ所でエラーが出ます。

        // mix blend
        /* comment out
        if ((track.MixBlend == Spine.MixBlend.Replace)||(track.MixBlend == Spine.MixBlend.Add))     // safe code
        {
            switch (trackmix)
            {
                case MixBlend.Add:
                    track.MixBlend = Spine.MixBlend.Add;
                    break;
                case MixBlend.Replace:
                    track.MixBlend = Spine.MixBlend.Replace;
                    break;
            }
        }
        */

Please comment out all of MixBlend code.
MixBlendの箇所をすべてコメントアウトしてください。

# Classes

# Animationrig

## Create

## LoadFromBinary

## Update

## Animations[] AnimationCount

## UserMemo

# AnimationrigState

## Create

## Update

## EntryTrack EntryTrackFade

## ClearTrack ClearTracks ClearTracFade

## Tracks TrackCount

## InputObjects[] ObjectCount

## EventCallback

# StateInput

## SetValue GetValue ValueCount

## ObjectType

## Renderer

# ValuePreset

## Create

## LoadFromStream

## SetPreset SetDefault SetClear

# StateRenderer

## Enable Visible

## ObjectType

## SetTransform

## SetColor

## Update

## SetAnimation

## SetTrackBlendAlpha

## SetTrackSeekTime

## SetMixDuration