APimage Plugin リファレンス

概要:
	APimage Pluginは、アニメーションする Partial Image(=部分画像)を
	提供するプラグインである。Macro_CharLayers.ks と組み合わせて目パチ
	口パクを表現するために作成された。

	通常、吉里吉里/KAGで目パチ口パクを実現しようとすると、セル
	アニメーションを使用する。しかし、セルアニメーションはあくまで
	ベース画像に対する画像貼り付けであり、[pimage]タグで表情を
	変更しているような実装には向かない。表情を追加するたびに
	セル画像およびアニメーション記述ファイル(.asd)全体の追記変更が
	必要になり、煩雑となるため。
	この問題を解決するため、本プラグインでは、[pimage]とほぼ
	互換で、アニメーションが実行可能なタグ [ap_image]タグを提供する。
	これにより、部分画像単体でアニメーションが可能になり、
	セル画像・アニメーション記述ファイルを(追記ではなく)「追加」する
	だけで、表情が追加できるようになった。

**********************************************************************
使用方法：
	1. APimage.tjs と Macro_APimage.ks(1.70以上) を用意
	2. override.tjs(なければdata/senario/以下あたりに作成)に
	　 以下の行を追加。これで AnimationLayer クラスが拡張される
	　　　　KAGLoadScript("APimage.tjs");
	3. first.ks の先頭で以下の一行でプラグイン読み込み
	　　　　[call storage="Macro_APimage.ks"]
	これで後述するアニメーションpimageが使用できるようになる。

**********************************************************************
使用例：
	最も簡単な使用例として、一秒ごとに画面上のキャラクタの目を「開く」
	「閉じる」という動作をする apimage を考えてみる
	「開く」と「閉じる」の二つの画像(100x50dot)を横に連結した画像
	「ぱちぱち.png」(200x50dot)を用意し、一秒おきにぱちぱちさせる.asd
	ファイル「ぱちぱち.asd」を作成する。
		ぱちぱち.asd:
		===== ここから ======
		*loop
		@copy
		@wait time=1000
		@copy six=1
		@wait time=1000
		@jump target=*loop
		===== ここまで ======
	その後、これらを適当なレイヤの適当な位置に[ap_image]で貼り付ける。
		[ap_image layer=1 storage=ぱちぱち dx=200 dy=150 width=100]
	これで、layer1/foreにて、目をぱちぱちするアニメーションが実行される。

**********************************************************************
アニメーション定義ファイル(.asd):
	アニメーション定義ファイル.asdはセルアニメーションのものとほぼ
	同一のものを使用する。ただし、以下の相違点・拡張がある。
	　1. ベース画像は用意しない(KAGのap_imageタグ中でstorage=で指定する)
	　2. そのため、.asd中に@loadcellタグを書く必要はない(無視される)
	  3. @pos x= y= タグが追加になった。.asdファイル中で親レイヤとの
	     相対位置を変更できる。def:x=0,y=0
	  4. @size w= y= タグが追加になった。
	　5. @copy タグの dx/dy/sx/syは指定しないと0と判定されるようになった
	　6. @copy タグに sixとsiyが追加された
	　7. @loop/@noloop タグが無視されるようになった。
	詳細は末尾の「タグリファレンス for アニメーション定義ファイル(.asd)」
	を参照のこと。

**********************************************************************
タグリファレンス for KAG:
	 これはKAGスクリプト中で使用できるタグのリファレンスである。
	 パラメータを指定しなかった場合、(def)またはdefaultと書いてある
	 ものがデフォルト値として採用される。

[ap_image name= layer= page= storage= dx= dy= width= height= target=]
説明:
	アニメーションpimageを作成する。
	全てのパラメータは、layer=で示す親レイヤに設定するのではなく、
	作成される子レイヤに設定されることに注意(例：visible/opacity/index)。

引数:
	name=		ap_imageの名前。後にセグメントを指定する場合に使用
			される。省略可、省略するとstorageと同じ
	layer=		親レイヤーの番号。kag.fore.layers[##] の ## の部分。
			省略すると 0 とみなされる。baseやmessageは指定できない
	storage=	アニメーションパターンの画像ファイル名＆情報ファイル
			(拡張子除く)。省略不可。透明部分を含んでいてもよい。
			実際には storage.png と storage.asd を参照する
	page=		foreまたはbackを指定。省略するとfore。
	dx/dy=		画像の貼り付け先座標。parentレイヤに対する相対位置で
			指定する。省略すると 両方0(.asdファイル中で指定してもよい)。
	width=		一アニメーションパターンの表示横サイズ。省略すると
			読み込んだセル画像の横幅(パターン数を考慮しない)。
			パターン数が１より大きい場合は要指定
			※.asdファイル中で[size]タグで指定してもよい
	height=		表示縦サイズ。
	target=		.asdファイル中のアニメーションの開始ラベル。
			省略すると.asdの最初から。
	visible=	そのアニメーションpimageを表示するかどうか(def=true)
	opacity=	透明度。省略すると255。
	index=		表示優先順位。省略すると親と同じ。
	wait=		このアニメーションを待つかどうか。def=false(待たない)
;未実装	mode=		

使用例:
	; 立ち絵画像 「あかね」をlayer=1に表示し、漫符「＃」をap_imageで追加、
	; トランジションしながら表示する。
	[backlay]
	[image page=back layer=1 storage=あかね top=0 left=300]
	[ap_image layer=1 page=back storage="＃" dx=160 dy=20 width=100 height=50]
	[trans method=crossfade time=1000]


[ap_delimage name= layer= page=]
説明:
	apimageを削除する。nameを指定しなかった場合は同ページの全てのapimageが
	削除される。
引数:
	name=		削除するapimageの名前。無指定なら「全て」を意味する
	layer=		親レイヤーの番号。kag.fore.layers[##] の ## の部分。
			省略すると「全て」とみなされる。
	page=		foreまたはbackを指定。省略すると両方となる

[ap_animstart name= layer= page= storage=(.asdファイル) target= waitprev= wait=]
説明:
	アニメーションを開始する。KAGデフォルトのセグメントアニメーションと
	同様、[ap_image]実行時には target= で指定したアニメーションが自動的に
	開始されるが、その後に、.asdファイル中の他のアニメーションシナリオに
	ジャンプする必要がある時に指定する。
引数:
	name=		アニメーションさせるap_imageの名前。省略すると全ての
			ap_imageを対象とする
	layer=		親レイヤーの番号。kag.fore.layers[##] の ## の部分。
			省略すると「全て」とみなされる。
	page=		foreまたはbackを指定。省略すると両方。
	# storage=	.asdファイルを指定。省略すると[ap_image]で指定した
	#		storage=の拡張子を.asdに変更したものを使用
	target=		実行を開始する.asdファイル内のラベル名。省略すると先頭
	waitprev=	前のアニメーションを待つかどうか。def=false(待たない)
	wait=		このアニメーションを待つかどうか。def=false(待たない)
	canskip=	waitprev/wait 時にskip可能かどうか。def=true


[ap_animstop name= layer= page=]
説明:
	アニメーションを停止する。
引数:
	name=		アニメーションを停止させるap_imageの名前。省略すると
			全てのap_imageを対象とする
	layer=		親レイヤーの番号。kag.fore.layers[##] の ## の部分。
			省略すると「全て」とみなされる。			
	page=		foreまたはbackを指定。省略すると両方。
	immediate=	すぐ停止するかどうか(def=true)
			すぐ停止すると、アニメーションは最終画像にならない。
			immediate=falseだと、[s]または[home]までアニメー
			ションが進んでから停止する
			ただし、ap_animstop はアニメーションの停止を待たない
			ため、待つ必要がある場合はこの後 ap_wa を実行する
			必要があることに注意。


[ap_wa name= layer= page= canskip=]
説明:
	アニメーションの終了([s]または[ap_animstop]後の[home]タグ)を待つ。
	内部的には "apimage:名前" というトリガを待つだけ。
	ループしているアニメーションを待つと、いつまでも待ち続けるので
	注意。
引数:
	name=		アニメーションを待つap_imageの名前。省略すると
			全てのap_imageを対象とする
	layer=		親レイヤーの番号。kag.fore.layers[##] の ## の部分。
			省略すると「全て」とみなされる。
	page=		foreまたはbackを指定。省略すると両方。
	canskip=	true(def)|false。クリックでスキップ可能かどうか。
			ただし、スキップしてもアニメーションは続く(最終
			画像にはならない)ことに注意。

**********************************************************************
[piamge]との相違点
	・当然、アニメーションできる。
	・[pimage]に指定できる画像パラメータ(色合い、ggammaなど)は、全て
	　ベース画像に従い、個別には指定できない。
	・ロード時にアニメーションを再開する位置がデフォルトの.asdと
	　異なる。詳細は下部「セーブとロード」項参照。


**********************************************************************
Macro_CharLayersと併用する場合の追加マクロ


[char_ap_image name= apname= page= storage= dx= dy= width= height= target=]
説明:
	[char_ap_image]を呼ぶラッパ。キャラクタ名が指定できる。
	ただし、これはキャラクタの pimage として追加するのではなく、
	単純にそのレイヤにap_imageを追加するだけである。従って、
	該当キャラクタを trans_char すると消えてしまう。ワンショット向け。
	ループするものや、trans_char で消えては困るものは、[disp_char] の
	storage=で指定すること。
引数:
	name=		対象キャラクタ名。省略すると全てのキャラクタを対象と
			する
	apname=		アニメーションさせるap_imageの名前。省略すると storage
			と同じ。
	page=		foreまたはbackを指定。省略すると両方。
	storage=	アニメーションパターンの画像ファイル名。省略不可。
			アニメーション情報ファイルは.asd 
			まず name_storage.asd を探し、無ければ storage.asd を
			対象とする。
	dx/dy=		画像の貼り付け先座標。親レイヤに対する相対位置で
			指定する。省略すると両方0だが、.asd ファイル中で
			指定してあればそれを優先する
	width=		一アニメーションパターンの表示横サイズ。省略すると
			読み込んだセル画像の横幅(パターン数を考慮しない)。
			パターン数が１より大きい場合は要指定
			※.asdファイル中で[size]タグで指定してもよい
	height=		widthと同じ、表示縦サイズ。
	target=		アニメーションの開始ラベル。省略すると.asdの最初から。
	visible=	そのアニメーションpimageを表示するかどうか(def=true)
	opacity=	透明度。省略すると255となる。
	index=		表示優先順位。省略すると親と同じ。
	wait=		このアニメーションを待つかどうか。def=false(待たない)
;未実装	mode=		


[char_ap_delimage name= page= apname=]
説明:
	[ap_delimage]を呼ぶラッパ。キャラクタ名が指定できる。
引数:
	name=		対象キャラクタ名。省略すると全てのキャラクタを対象と
			する
	apname=		対象アニメーションイメージの名前。省略すると全ての
			アニメーションイメージを対象とする。
			まず name_apname.asd を探し、無ければ apname.asd を
			対象とする。
	page=		foreまたはbackを指定。省略すると両方となる


[char_ap_animstart name= apname= page= target= waitprev= wait=]
説明:
	[ap_animstat]を呼ぶラッパ。キャラクタ名が指定できる。
引数:
	name=		対象キャラクタ名。省略すると全てのキャラクタを対象と
			する
	apname=		対象アニメーションイメージの名前。省略すると全ての
			アニメーションイメージを対象とする。
			まず name_apname.asd を探し、無ければ apname.asd を
			対象とする。
	page=		foreまたはbackを指定。省略すると両方
	target=		実行を開始する.asdファイル内のラベル名。省略不可。
	waitprev=	前のアニメーションを待つかどうか。def=false(待たない)
	wait=		このアニメーションを待つかどうか。def=false(待たない)

[char_ap_animstart_ary name= page= apstart= waitprev= wait=]
説明:
	[ap_animstat]を呼ぶラッパ。キャラクタ名が指定できる。
引数:
	name=		対象キャラクタ名。省略すると全てのキャラクタを対象と
			する
	page=		foreまたはbackを指定。省略すると両方
	apstart=	実行アニメーション名とラベルのセットを、"apname*ラベル"
			の形で空白で区切って指定(def=なし)。
			例：apstart="！*start Σ*oneshot"
			↑'！'アニメーションを*startから開始、"Σ"アニメー
			ションを*oneshotから開始。
	waitprev=	前のアニメーションを待つかどうか。def=false(待たない)
	wait=		このアニメーションを待つかどうか。def=false(待たない)

[char_ap_animstop name= apname= page=]
説明:
	[ap_animstop]を呼ぶラッパ。キャラクタ名が指定できる。
引数:
	name=		対象キャラクタ名。省略すると全てのキャラクタを対象と
			する
	apname=		対象アニメーションイメージの名前。省略すると全ての
			アニメーションイメージを対象とする。
			まず name_apname.asd を探し、無ければ apname.asd を
			対象とする。
	page=		foreまたはbackを指定。省略すると両方
	immediate=	すぐ停止するかどうか(def=true)
			ただし、char_ap_animstop はアニメーションの停止を
			待たないため、待つ必要がある場合はこの後 char_ap_wa
			を実行する必要があることに注意。


[char_ap_wa name= apname= page= canskip=]
説明:
	[ap_wa]を呼ぶラッパ。キャラクタ名が指定できる。
引数:
	name=		対象キャラクタ名。省略すると全てのキャラクタを対象と
			する
	apname=		対象アニメーションイメージの名前。省略すると全ての
			アニメーションイメージを対象とする。
			まず name_apname.asd を探し、無ければ apname.asd を
			対象とする。
	page=		foreまたはbackを指定。省略すると両方
	canskip=	true(def)|false。クリックでスキップ可能かどうか。
			ただし、スキップしてもアニメーションは続く(最終
			画像にはならない)ことに注意。

**********************************************************************
タグリファレンス for アニメーション定義ファイル(.asd)
数値を指定できる箇所では、必ずTJS式が指定できる。&は不要。

@pos x= y= ix= iy= opa= iopa=
説明:	部分画像の親画像からの相対位置を指定する。初期状態では
	[ap_image dx= dy=] で指定された位置になっている。
	指定を省略すると位置は変更されない。
引数:	x/y=	部分画像の、ベース画像中の相対位置を設定する。
	ix/iy=	部分画像の、現在の位置からの相対移動幅を設定する。汗漫符の
		ように、部分画像が動く場合に使用する。
	opa=	透明度(0-255)を指定。指定しない場合は何もしない。
		初期値は255。
	iopa=	相対透明度を指定。指定しない場合は何もしない。

@size w= h=
説明:	部分画像の表示域の縦横幅を指定する。初期状態では セル画像の縦横幅、
	または[ap_image width= height=]で指定された値になっている。
	アニメーション画像を読むだけでは実際の表示域の大きさは分からないため、
	パターン数が１より多い場合は要指定。
引数:	w/h=	部分画像の表示域の縦横幅。

@copy dx= dy= sx= sy= sw= sh= six= siy= affine=
説明:	部分画像を表示域にコピーする。コピー元座標とコピー先座標を指定する。
引数:	dx/dy=	コピー先の表示域座標を指定する。省略すると 0。
	sx/sy=	コピー元画像のコピー元左上座標を指定する。省略すると 0。
	sw/sh=	コピー元画像のコピー縦横サイズを指定する。省略すると表示域
		サイズと同じ。
	six/siy=コピー元画像の、表示域座標で格子化したインデックス位置を
		指定する。six=1は、sx=1*width に等しい。
	affine=	Layer.affineCopy()を使用する９パラメータを、"," 区切りで
		affine,A,B,C,D,E,F,type,clearの順で指定。パラメータの詳細は
		http://devdoc.kikyou.info/tvp/docs/kr2doc/contents/f_Layer_affineCopy.html
		を参照。
		指定しなかった場合はデフォルト値となる。デフォルト値は
		"true,1,0,0,1,0,0,stNearest,false"となっている。
		affineを指定すると、dx/dyは無視される(affineに含まれるため)。

@loop/@noloop
説明:	互換性のために残すが、何もしない
引数:	なし

@clear
説明:	表示領域をクリアする。
引数:	なし

@loadcell
説明:	何もしない。.asd との互換性のために残してある。
引数:	なし。あってもよいが無視する。

@trigger name=トリガ名
説明:	KAGに対してトリガを引く。トリガはkag.conductorに対して引かれ、
	kag.mainConductorでないことに注意。
引数:	name=トリガ名

@home
説明:	[ap_image_stop * immediate=false]で停止した時に、実際に停止する
	ループ中の場所。他はオリジナル.asdと同じ。

他のパラメータは全てオリジナルの.asdと同じ。


@home、@sで停止する場合、オリジナルの.asd と違い、「直前の@copyが
そのアニメーションレイヤ全体を書き換えるものだった」ようにすれば、
栞ロード時にアニメーションレイヤを(その最終画像で)復旧可能。
※オリジナルは「元画像と同じでなければいけない」という制限があったが
　APimageにはこの制限はない
これは、APimage内で「最後に実行した@copy」を覚えていて、
ロード時にこの@copyを必ず実行するため。従って、複数の@copyで
一枚の画像を作った場合は復旧できないことに注意。

**********************************************************************
.asdファイルの例)
	@pos  x=10 y=50	← なければ [ap_image dx= dy=]で指定されたものになる
	@size w=64 h=64	← なければ [ap_image width= height=]で指定された(略)

	*loop
	@copy six=0	← セル画像の(0*w,0*h)-(wxh) を 0,0 にコピーする
	@wait time=200
	@copy six=1	← セル画像の(1*w,0*h)-(wxh) を 0,0 にコピーする
	@wait time=200
	@copy siy=1	← セル画像の(0*w,1*h)-(wxh) を 0,0 にコピーする
	@wait time=200
	@copy six=1 siy=1 ← セル画像の(1*w,1*h)-(wxh) を 0,0 にコピーする
	@wait time=200
	@jump target=*loop ループする


**********************************************************************
セーブとロード：
	・.asdファイルの動作中にセーブされた場合、ロードすると、.asd
	　ファイル中の「セーブ時直前に通過したラベル」から再開される。
	　[s]または[home]で停止していた場合は、停止したまま、[s]または
	　[home]直前に実行された[copy]を再実行する。
	　そのため、セーブ・ロードに関して、以下の条件がある。
	　　1. ラベル直後の[copy]タグ(複数でもよい)で、当該APimage
	　　　 レイヤ全体が更新されること
	　　2. [s]または[home]の直前の[copy]タグ(一つだけ)で、
	　　　 当該APimageレイヤ全体が更新されること
	　そうでなければ、再開時画面が崩れたようになる。

	・グローバル変数 sf.ap_image_restart_as_default を 1 に定義
	　すると、セーブロード時の動作が、↑ではなく、KAGデフォルトの
	　.asdファイルのように[ap_image]または[ap_animstart]で指定
	　したラベルから再開されるようになる。互換性のために残した。
	　KAGなら、以下をfirst.ksの先頭あたりに書けばよい。
	　[eval exp="sf.ap_image_restart_as_default = 1"]

	・.asdファイルで定義したマクロなどはセーブデータに含まれるため、
	　マクロは.asdファイル先頭で定義すればよい。逆に、パッチで
	　.asdファイル中のマクロなどを変更しても、セーブされてしまって
	　いるのでロード(またはセーブデータ削除)しないと反映されない



**********************************************************************
制限：
	・レイヤの上下・左右反転には対応していない。

**********************************************************************
実装：
	アニメーションするPartialImage(AnimPimageLayer)を定義し、これを内包
	するようAnimationLayerクラスを拡張。AnimPimageLayer は一枚の
	AnimationLayerに対して複数定義でき、目パチ、口パクなどを別々に登録
	可能。
	アニメーションレイヤは、kag.{fore|back}.layers[##]の
	子レイヤとして定義される。表示優先順位は親レイヤの相対。子レイヤである
	ため、@moveタグで親レイヤを動作させると、自動的にそれに追従する。