readme.md

# SpineAnimationRig manual

This software is free-software.
このソフトウェアはフリーソフトウェアです。

Control Spine animation by timeline. This editor-application has functions such as switching animations, building tracks, and assigning values ​​from application side.
タイムラインによるSpineアニメーションのコントロールを行います。アニメーションの切り替え、トラックの構築、アプリケーションからの値の代入などの機能を持ちます。

This Editor was created for "facial control" where more animations (tracks) are composited. If you want to control a animation that needs a lot of tracks, please try it
このエディタは合成するアニメーション（トラック）が多く必要となる”表情制御”用に作られました。もし多くのトラックを必要とするアニメーションを制御したいなら、一度お試しください。

# Caution

This editor(SpineAnimationrig.exe) is provided for each version of Spine. We recommend using stable version 3.7 (SpineAnimationrig37.exe). The sample also uses 3.7.
エディタ（SpineAnimationrig.exe)はSpineのバージョンごとに用意されています。安定版3.7(SpineAnimationrig37.exe)の使用をお勧めします。サンプルも3.7が使われています。

Please refer to File-Version.
詳しくはファイルバージョンを参照ください。

# Contact , Support , Product homepage

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

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

# Contents

- Basic
  - Spine License
  - Overview
  - Features
  - Data structure
  - File version compatibility
- GUI
  - Preview area
  - Timeline area
  - Property area
  - Input value form
  - AnimationTest mode
- Type
  - Object type
    - Common object
    - Null object
    - Spine object
  - Layer type , Key property
    - PreviousKey
    - Common layer
    - animation blend layer
    - animation seek time layer
    - Transform layer
    - Event layer

# License

## Spine

Even if you do not have a Spine-License, you are allowed to use Spine in the editor.
Spineライセンスを持っていなくても、エディタ上でSpineを自由に使用することが許されています。

To edit Spine files, you need to purchase Spine-Editor and a license. This editor mainly uses pro-version features.
Spineファイルを編集する場合はSpine-Editorとライセンスを購入する必要があります。このエディタでは主にプロバージョンの機能が使用されます。

- Spine

http://esotericsoftware.com/

# Overview

SpineAnimationrig is not a video output application. It is for easy control of Spine on the application
このSpineAnimationrigは動画を出力するアプリケーションではありません。アプリケーション上でSpineの操作を簡略化するための物です。

Please refer to the "runtime readme".
詳しくはランタイムのreadmeを参照ください。

This editor does not support some features of Spine. If you get an accurate display(output image), you need to create an application using Unity etc.
このエディタはSpineの一部機能をサポートしていません。ちゃんとした出力（表示）を得たい場合は、Unityなどでアプリケーションを作る必要があります。

# Features

- 4 Directions animation blend.

Assign four animations up, down, left and right, and combine them. It is often used in facial expression.
4つのアニメーションを上下左右に割り当てて合成します。表情操作ではおなじみの機能です。

- Time-stretch(seek) animation blend.

Control playback time(time stretch). It is often used in movie-editor.
再生時間を制御してタイムストレッチを行います。動画編集ではおなじみの機能です。

- Multi track animation.

Animationrig also has a track feature. Multiple animations can be combined.
このAnimationrigファイルにもトラックがあり、複数のアニメーションを合成できます。

- Control animation-values from application. (input values)

The object has variables (input-value), It can be embedded in property values ​​on the timeline. you can design easing and timing, It is safer and easier to handle than overwriting the value directly.
オブジェクトは自由に使える変数(input-value)を持っており、この変数をタイムライン上のプロパティ値として使用することが出来ます。イージングやタイミングをデザインすることが出来、直接値を上書きするよりも安全かつ簡単に扱うことが出来ます。

- Export input values to clipbord (and file). (Preset)

Let's say you control character eyes and mouth on the application. How should you create data?
The editor has a window form for editing variables(input-value). You can output the value as text to the clipboard or file. This file is called a "preset". A class is provided at runtime to load and use this.
目や口をアプリケーションから操作するとしましょう。その場合、データはどうやって作れば良いでしょうか？
エディタでは変数編集用の専用ウインドウを持っています。またその値をテキストデータとしてクリップボード、ファイルに出力できます。このファイルはプリセットと呼ばれ、ランタイムにもプリセット用のクラスが用意されています。

# Data structure

    AAA animation
        * spine object
            + transform layer
            + spine layer
            + spine layer
        * null object
            + transform layer
    BBB animation
        * spine object
            + transform layer
            + spine layer
            + spine layer
        * null object
            + transform layer

Objects and Layers structure is shared between animations. If delete a layer, Affects all animations.
アニメーション、オブジェクト、Layer、その下にKeyのデータを持ちます。 オブジェクトとLayerの構成は、アニメーション間で共有され、常に同じ構成を取ります。 もしLayerを削除すれば、全アニメーションに反映されます。

# File version compatibility

The editor or runtime can read all old version files (backward compatible).
基本的に、エディタやランタイムは古いバージョンのファイルをすべて読み込むことができます（後方互換性）。

The version of the Animtionrig file and Spine-loader are displayed in the form caption.
Animtionrigファイルのバージョン、Spineローダーのバージョンはフォームキャプションに表示されます。

rev | Editor build revision
latest | Animationrig file version
Spine | Spine file loader version

## Spine loder version compatibility

Spine-runtime-loader has not backward compatible. Please output the file in a near version.
Spine-runtimeのローダーは後方互換性を持ちません。近いバージョンでファイル出力してください。

In principle, Editor is Used the latest runtime(loder) for each major version.
原則として、エディタは大きなバージョンごとに最新のランタイムを使用しています。

- Spine editor and runtime version management

http://esotericsoftware.com/forum/Spine-editor-and-runtime-version-management-6534

Describes how to downgrade export-file(json) versions.3.7.
出力ファイル(json)バージョンをダウングレードする手法が説明されています。

## Spine runtime 3.6

Spine-runtime needs ver 3.7 or more to use MixAdd. So the editor does not support 3.6.
MixAddを使用するには3.7以上が必要です。なので、エディタは3.6に対応しません。

But, can be run at runtime level using 3.6. Please refer to the runtime readme.
が、ランタイムレベルでは3.6を使って実行が可能です。ランタイムのreadmeを参照ください。

# Preview area

Display a preview of the current state.
現在の状態のプレビューを表示します。

## Shortcut

keys | function
--- | ---
space | play.
shift + space | play at top.
mouse right | move view position.
mouse wheel | zoom.

## Option

button | function
--- | ---
inspect | show inspect of current object 現在オブジェクトの内容を表示
stop animation | stop animation in edit mode 編集中のアニメーションを停止
fps | preview frame rate

## Edit handle

Edit-handle-mode can be used when selected Transform layer.

この機能はトランスフォームLayerを選択中の場合のみ使用出来ます。

handle | function
--- | ---
select | object select
move | edit position
scale | edit scale
rotate | edit rotate

# Timeline area

Show the animation timeline. Edit layers and keys.
選択中オブジェクトのLayer構造を表示します。

## Shortcut

keys | function
--- | ---
space | play.
shift + space | play at top.
mouse left | select key.
shift + mouse left | grid time.
mouse right | move view time position.
mouse wheel | time zoom.
ctrl + mouse left | multi select.
ctrl + a | select all keys in layer.
ctrl + i | add key.
ctrl + r | clear key.
ctrl + d | delete key.
ctrl + shift + i | add layer.
ctrl + shift + r | clear layer.
shift + ctrl + d | delete layer.

## Layer

Can be edit layers in object. Layer names are shared between animations. Execute order by up to down.
オブジェクトが持つLayerを編集出来ます。名前はアニメーション間で共有されます。実行は上から下へ順に行われます。

## Key , PreviousKey

Layer has normal-key and PreviousKey. PreviousKey Holds the previous (changed)animation values. This key is used to control transition of animation switching.
Layerには通常KeyとPreviousKeyが存在します。 PreviousKeyは変更前のアニメーションの状態を保持します。このKeyはアニメーション切り替えの遷移を制御する時に使用します。

However, there are AutoFade for animation switching control. It is a function to automatically crossfade to feel good. leave it to you.
しかし、アニメーションの切り替え制御には AutoFade があります。良い感じに自動でクロスフェードする機能です。どちらを使うかはお任せします。

## Overlap key

Allow overlapping keys on Animationrig. It is useful for jumping position. It becomes pink color.
AnimationrigではKeyの重複を許容します。これは座標をジャンプさせる場合に役立ちます。重複するとピンク色になります。

# Property area

View and edit information of objects, animations, and keys.
オブジェクト、アニメーション、Keyなどの情報を表示、編集します。

## Mouse edit , From edit

Some properties can be edited with the mouse. You can also show the input form by double click.
一部のプロパティはマウスによる編集が可能です。またダブルクリックで入力フォームを表示することが出来ます。

## Global

property |
--- | ---
Frame | Timeline framerate タイムラインのフレームレート
Memo | User memo. Please use it freely! ユーザー用メモ領域。ご自由に。

## Object

Please referrence ObjectType page.
オブジェクト項目を参照ください。

## Animation

property |
--- | ---
Name | animation name.
Preview base animation | Preview only. Setup and run base animation. プレビュー専用。下地となるアニメーションの再生。
loop ennable loop disable | Loop active.
beginframe | Loop begin frame.
endframe | Loop end frame.

## Key

Please referrence LayerType page.
Key項目を参照ください。

# AnimationTest mode

This application also supports animation track blending. You can check and preview in AnimationTest mode.
このツールにもアニメーションを重ねる機能があります。 重ねた際の動きをプレビューしたい場合はモードをAnimationTestに切り替えます。

## Shortcut

key | function
--- | ---
F6 | switch mode.
space | play.
shift + space | play at top.

## Auto fade

It is a function that can be used at runtime.
ランタイムの機能です。

It is a function to crossfade the switching of animation to a good feeling. It was born because the fade setting with PreviousKey is very difficult. It is a rough control, but a very powerful(useful) feature.
アニメーションの切り替えを良い感じにクロスフェードさせる機能です。PreviousKeyによるフェード設定が大変なため生まれました。大雑把ですが強力な機能です。

- disable

- enable

# Input value form

In this application, it can be use values ​​input from the external program(embedded application) into the timeline.
このアプリケーションでは外部（組み込みアプリケーション）から入力された数値をタイムラインで使用することが出来ます。

## How to set input-value

If you use value from external, Set a special value to Key propertys. Please select a value from the right click menu.
外部からの変数を使用する場合は、Keyのプロパティに特殊な値を設定します。 右クリックメニューから変数を選んでください。

## Preset

You can store(save) the state of values. It is saved as preset.txt in the same location as the file.
値の状態を記憶しておくことが出来ます。 この情報はファイルと同じ場所にpreset.txtで保存されます。

## Export to clipboard

Export the state of all values to clipboard. You can edit the output text format with export-menu.
値の情報をクリップボードにコピーします。 出力テキストのフォーマットはexportメニューより設定が可能です。

replace word |
--- | ---
{value0} | write value by index. インデックス番号の値を出力。
{set0.x} {set0.y} | By XY index. XYセット番号で指定。
{name.x} {name.y} | By XY name. XYセット名で指定。

- format

    eye:{ position:[{eyepos.x},{eyepos.y}] , size:[{eyesize.x},{eyesize.y}] }

- output

    eye:{ position:[0.400,0.200] , size:[0.100,0.000] }

# Object type

# Common Object

Shared property of all Objects.
全Objectタイプで使用される共通プロパティです。

property |
--- | ---
name | Object name. Allow duplicate names.
state enable state disable | Update & show object.
visible enable visible disable | Show object.
offset | Offset position.
scale | Base scale.
Group (parent object) | Inherit(link) the position, scale and etc from parent object. 親objectの位置などを継承します。
Draw Priority | Design draw priority order.

# Null Object

Null object. Not displayed by default.
空オブジェクト。デフォルト状態では表示されません。ユーザが拡張して意味を持つオブジェクトです。

You can display the temporary image.
仮画像を表示することが出来ます。

# Spine Object

This object controls the spine file.
spineをコントロールするためのオブジェクトです。

Spine file-path is recorded with relative path. Please be careful not to include personal information such as desktop pass.
spineファイルは相対パスで記録されます。パスに個人情報が入らないようにご注意ください。

### support function

function |
--- | ---
blend | yes
tintcolor | no (diffuse * modulatecolor + tintcolor)
bleed alpha | no (just a moment!)
mask | no

### property

property |
--- | ---
filename | spine exported file. Please use JSON format that is as compatible as possible spineのexportファイルを指定します。出来るだけ互換性の高い json 形式を使用しましょう。
mix duration | default mix duration time.
PreMultiplyAlpha | Change the blending method to PreMultiplyAlpha. ブレンドをPreMultiplyAlpha方式に切り替えます。

# Layer type , key property

# PreviousKey

PreviousKey is displayed in blue color。You can not edit the value or time. Only easing can be set.
PreviousKey は青色で表示されます。値や時間は編集できません。イージングのみ設定することが出来ます。

# Common layer

Shared property of all layers.
全Layerタイプで使用される共通プロパティです。

## track blend

Set the blend-weight when mixing animation. The blend calculation is below.
アニメーションを重ねた場合の値の比重を設定します。 計算は以下になります。

    track0 ... previous track
    track1 ... current track

    out = (track0.AlphaX * previous) + (track1.AlphaX * current)

- Add (default)

Default is 1.0. Add blend.
デフォルトは 1.0 で加算です。

    previous : 1.0
    current : 1.0

    out = track0.AlphaX * 1.0 + track1.AlphaX * 1.0
        = track0.AlphaX + track1.AlphaX

- replace

In the case of replace.
上書きする場合。

    previous : 0.0
    current : 1.0

    out = track0.AlphaX * 0.0 + track1.AlphaX * 1.0
        = track1.AlphaX

# Transform layer

## move , scale , rotate

Control move, scale, and rotate.

## easing

value transaction.
値の遷移を選択します。

## spline

Performs curve interpolation using the values ​​of the 4 keys.
前後4Keyの値を使って曲線補間を行います。

## rotate order

Select X,Y,Z rotation order. pass will use the previous settings when mixing animations.
回転の順序を指定します。 複数のアニメーションを重ね合わせた場合、passは前の値を引き継ぎ、使用します。

## Multi transform-layer composite

If you set multi-layers, values ​​will be composite from top to bottom.
もし複数のLayerを設置した場合、値は上から下へ合成（行列合成）されていきます。

# Animation blend layer

Composite animations with using 4(or 1) tracks on spine.
spineの4(または1)トラックを使用して、アニメーションを合成します。

## Animation name format (spine side)

Spine-animations are assigned in 4 directions (up, down, left, right) by name.
Spineアニメーションは名前規則にそって4方向（上下左右）に割り当てられます。

name format |
--- | ---
name name@up | up (+Y)
name@right | right (+X)
name@down | down (-Y)
name@left | left (-X)

If not exists animation, empty will be set.
空アニメーションにはemptyが設定されます。

## name

Set Spine-animation name.
Spineアニメーション名指定します。@以降は不要です。

name |
--- | ---
none | pass set animtion. パスします。
empty | set empty animation. emptyアニメーションを設定します。

## allow

Execution allow from animation name.
アニメーション名を比較、実行を許可、禁止します。

property |
--- | ---
allow diffrent | Only if dirrent name. 名前が異なる場合のみ
allow always | Always execute. 常に許可。

## setAnimation , addAnimation

property |
--- | ---
setAnimation | Change now! 今すぐアニメーションを変更する。
addAnimation | Change at end point. 終端でアニメーションを切り替える。

## play

property |
--- | ---
play one | One shot.
play loop | Loop.

## mix blend

Sets the animation blending method between tracks.
spineのトラック間の合成方法を設定します。

property |
--- | ---
mixReplace | Replace mode. 置き換えモード。
mixAdd | Add mode. Combine multi animations. 加算モード。複数のアニメーションを合成します。

## mix duration time

Over write the animation mix blend duration-time.
アニメーション繊維時間を上書きします。

property |
--- | ---
-1.0 | Use default mix duration. spineに設定に委ねます。
0.0 | disable mix animation. アニメーションミックスを行いません。

# Animation seek time layer

Composite time-stretched animations with using 4(or 1) tracks on spine.
再生時間をコントロール（タイムストレッチ）されたアニメーションを合成します。

When used 4 animation, Composed with alpha 1.0. The 0 frame should be in the same pose.
アニメーションを４つ使用する場合は、alpha1.0で合成されます。0フレームは同じポーズである必要があります。

## animation properties

Please refer to animations blend layer.
animations blend layerを参照ください。

## seek time

Set playback-time. if enabled loop in animation properties, Will loop-play over terminate(animation end) time.
合成値の代わりに再生時間を設定します。アニメーションに loop が設定されている場合は、終端時間以上でループするようになります。

# Event layer

Execute the event on the application side.
組み込みアプリケーションに対してイベント（コールバック）を実行します。

## ID

event name. In the case of none, it passes.
イベント名。自由な名前を設定出来ます。 noneの場合は無視されます。

## allow

Execution allow from event-ID.
IDを比較、実行を許可、禁止します。

property |
--- | ---
allow diffrent | Only if dirrent name. 名前が異なる場合のみ
allow always | Always execute. 常に許可。

## strings , floats

Send value to application side. Line return code 0x0D,0x0A is used.
アプリケーションに値を渡します。 改行はcrlf(0x0D,0x0A)を使用します。