Title:  ワールド拡張の基本的な使い方
Author: 合資会社ワムソフト

●概要

「吉里吉里/KAGEX」でのワールド拡張機能を使った
スクリプティングの基本的な手順について解説します。

●前準備

吉里吉里/KAGEX のフォルダ構成を行います

 game/
  krkr.exe				吉里吉里本体
  plugin/				プラグインファイル
	extrans.dll			拡張トランジション
	krmovie.dll			ムービー用DLL
	wuvorbis.dll		OGG 再生用DLL
	csvParser.dll		CSVパーサ拡張
	layerExImage.dll	イメージ機能拡張
  data/
	system/				吉里吉里 KAGEX から配布をコピーします
	main/				システム用スクリプト。
						最初は KAGEX のサンプルをコピーして
                        作業開始すると良いでしょう。

krkr.exe を実行するとシステムが起動します。

KAGEX は起動時にまず first.ks を実行しようとします。
サンプルのシステムでは以下の順に起動するようになっています。

(1) first.ks で初期化処理
(2) first.ks の最後で title.ks を起動
(3) title.ks で「はじめから」を選ぶと start.ks 起動

任意のシナリオファイルから開始させたい場合は、デバッグメニューの
「シナリオの読み込み」をひらいて、そこにシナリオのファイル名を
入力してください。そのシナリオの冒頭から開始されます。

●シナリオファイルの基本構造

シナリオファイルは data/scenario に配置します

# 実際はどこにあっても大丈夫ですが
# フォルダわけしておいたほうがわかりやすいです

-----------------------------------------------------
; ←この記述はコメントです
; ↓この記述はラベルになります。シナリオファイル中で一意にしてください
*label|タイトル
; | から後ろは保存データのタイトルになります
; タイトルを引き継ぐ場合は *label| と空で指定すればＯＫです

; ↓シーン状態の初期化です。
[initscene]
; 作業をする上で、基本的にシナリオファイルはこの記述からはじめてください。
; 内容は macro.ks で定義されていて、基本的には
; (1) ワールド拡張の [init] を実行　キャラ状態などを全部初期化します
; (2) メッセージ窓の初期化処理
; (3) その他必要な処理
; が含まれています

【名前】会話文
 .....
 .....

[jump storage=次のシナリオファイル]
-----------------------------------------------------

●具体的な記述例

以下、具体的なシチュエーションに対する記述の例をあげていきます

凡例
　背景： 学校、廊下
　名前： あかり

◇背景を表示させたい

 (1) ファイルを準備する

　 朝、昼、夜といった時間帯別にデータを作成します。
　 ファイル名のルールは全体で統一するようにしてください。

　例
   bg01_0  学校朝
   bg01_1  学校昼
   bg01_2  学校夜

   bg02_0  廊下朝
   bg02_1  廊下昼
   bg02_2  廊下夜

　 ファイルは data/bgimage に配置します。

 (2) envinit.tjs に背景の情報を登録する

　＞詳細は world_inst.txt を参照

　・参照用の名前
　・画像ファイル（時間バリエーションつき）

  ※時間指定も同時に登録します

 (3) スクリプト中で、登録した名前を記述すれば表示される

 --------------------------------------------
 [学校 昼]  ; 時間指定つきで表示
 ....
 [教室]     ; 時間はそのままで場所だけ教室にする
 ....
 ---------------------------------------------

◇キャラクタを表示させたい

 (1) ファイルを準備する

   ファイルは  data/fgimage に配置します。

   典型的には

   akariX_AAA_BBB_CCC.png

   X  : レベル指定
   AAA: ポーズ指定
   BBB: 服装指定
   CCC: 表情指定
　　
　 といった形で要素ごとのくみあわせを展開したファイル名で構成します。
 　※要素は数値でも文字列でもかまいません。
 
   ※あらゆる組み合わせを準備する必要があるわけではありません
　　 必要なものだけでＯＫです

 (2) envinit.tjs にキャラクタの情報を登録

　　＞詳細は world_inst.txt を参照

　　形状には
　　・ポーズ
　　・服装
　　・表情
　　が要素として存在するのでその名前を登録していきます。
　　
　　考え方：
　　　ポーズ　身振り手振りの同じパターン
　　　服装　　きているもの
　　　表情　　顔の表情

　　ゲーム的に特に問題なければ「服装」を使わない、
　　あるいは「ポーズ」を使わない（固定）という形でも問題はありません。

　　サイズ的なもので
　　・レベル
　　が要素として存在します。

    この「レベル」はキャラクタの画面内での前後移動用の概念です

　　小さい＜奥、前、手前＞大きい
　　一般的には、２〜３段階作成して使います。

　　※レベルを使う場合は、あらかじめ、envinit.tjs でレベル指定も
　　　登録しておく必要があります。

　　立ち絵のデータは、背景登録で指定した「時間」に連動して
　　色補正が行われます。

 (3) スクリプト中で、登録した名前と、なんらかのポーズを記述すれば
　　 画面に表示されます

 ----------------------------------
  [あかり 制服]
 ----------------------------------

◇キャラクタの表示位置を指定したい

(1) キャラクタを登録する

(2) 表示位置用キーワードを envinit.tjs に登録

　左右位置
　　左、中、右  など

　前後位置
　　奥、前、手前  など

　表示用特殊位置
　　出, 消, 顔  など

  相対移動指定
　　左移動 右移動 など

　※キーワードは任意に設定可能。サンプルで↑の例が入ってます
 
(3) 場所の指定

 ----------------------------------
 [あかり 左]
 ----------------------------------

 キャラクタ名の指定されたタグで、場所の名前を並べればそこに表示されます

(4) 場所の移動

　既に表示されているキャラに対して場所指定すると
　現在と別の場所なら、そこに移動して表示されます。
　この時、服装やポーズはそのまま引き継がれます。

 ---------------------------------------------
  [あかり 制服 左]         ;左に出現
　【あかり】おはよう

　[あかり 右]         ;右に移動
  【あかり】今日もいい天気だね
 ---------------------------------------------

(5) 場所の移動（相対指定）

　相対的な移動も使うことができます

 ---------------------------------------------
  [あかり 左 制服] ;画面左
  [しおり 中 制服] ;画面中央
  ....

  [あかり 右移動 制服]  ; 右に移動して中央位置にくる
  [しおり 右移動 制服]  ; 右に移動して右位置にくる
 ---------------------------------------------

◇イベント絵を表示したい

(1) 画像を準備

　イベント絵用の画像を準備します。

　data/bgimage に配置します。

(2) 表示

  [ev ファイル名]

　単純にファイル名記述で表示されます

(3) 消去

 明示的に消去する場合

　[ev hide]
  
 自動消去処理

　背景表示を行うとイベント絵は自動的に消去されます

  例
  -------------------------------
  [ev ev001]
  .....
  [学校 夜]  ;  背景指定があるとイベント絵は自動的に消去される
  -------------------------------

◇コマンドの省略

 KAGEX ワールド拡張では、コマンドは２種類あります

 基本1
  [コマンド名 パラメータ=値  パラメータ=値]

 基本2
  [名前 パラメータ=値  パラメータ=値]

 ポイント１
  コマンドの種類は、単純な見た目では区別はつきません。
　基本２の形は「登録」されたものについて有効なスタイルです。
　例：キャラクタ名　などなど

 ポイント２
  登録された「値」をつかう場合は「パラメータ」の部分はほぼ省略できます

　例：
　　[あかり pos=左]        →省略→ [あかり 左]
    [あかり pose=えっへん] →省略→ [あかり えっへん]

　注意事項：「値」を登録するときに、他と重複しない名前を使うのが前提です。

　例：
　　服装に「普通」　表情に「普通」を登録してしまった場合

　[あかり dress=普通 face=普通]  ; 予想通り動く
  [あかり 普通]                  ; 表情指定のつもりで「普通」としても、
                                 ; 服装として処理されてしまう!!!
  
　重複指定したときの優先順は一応ありますが「仕様外」
　なので、つかわないでください。

◇テキストの表示とボイスの再生

※ここの解説はラインモード「page」を前提にしてあります。
　ラインモードについての詳細は kagex.txt を参照してください

基本書式
-----------------------------------------
【あかり】「おはよう」
-----------------------------------------

「【あかり】」の部分にはキャラクタの名前を指定します。


この名前指定で、以下のことが行われます

(1)メッセージ窓に名前欄がある場合は、そこに名前を表示
(2)メッセージ窓に表情欄がある場合は、そこに現在の立ち絵と連動した表情画像を表示
(3)ボイスの再生

※(2) と (3) は envinit.tjs でのキャラクタ登録時に情報を
  設定しておく必要があります

ボイス再生の例

-----------------------------------------
[あかり voice=1] ; ボイス番号1番にする

【あかり】「おはよう」   ; akari0001 が再生される

【あかり】「こんにちは」 ; akari0002 が再生される

【あかり】「さようなら」 ; akari0003 が再生される
-----------------------------------------

キャラクタの名前ごとに、自動的に番号がカウントアップして
ボイスが再生されていきますます。

名前の表記を画面上ではかえたい場合

　例：まだ名前がわからないので「？？？」と表示したい

------------------------------------------------------------
【あかり/？？？】「あさだよー」 ; 指定されたボイスがなる
------------------------------------------------------------

ボイスの指定は「あかり」に対するものになって、表示は「？？？」になります

個別でボイスを指定する場合は、１つづつボイスコマンドを指定します

-----------------------------------------
[あかり voice=1] ; ボイス番号1番にする
【あかり】「おはよう」   ; akari0001 が再生される

[あかり voice=10] ; ボイス番号10番にする
【あかり】「こんにちは」 ; akari0010 が再生される

[あかり voice=akari0004x] ; 直接ファイル名指定
【あかり】「さようなら」 ; akari0004x が再生される

【あかり】「ああああ」 ; akari0011 が再生される
-----------------------------------------

数値以外を指定（アルファベットとかがまざってる）すると、単発で
ファイル名指定できます。数値番号はそのまま次にくりこされます

※注意事項！！！
  吉里吉里は 0 ではじまる数値を 8進数とみなします。 
  "0010" と指定すると 10 ではなくて値的には 8 です

◇BGM をならす/とめる

BGM を再生することができます

 (1) 再生

 [bgm MUS001]

 ただし、「BGM」ではじまる名前なら

 [BGMXXX]

 だけでそのまま鳴ります。

 (2) 停止

 [bgm stop]

 (3) フェード処理したい場合

 フェードイン

 [bgm MUS001 time=1000] 

 フェードアウト

 [bgm stop=1000]

 (4) フェード処理を待ちたい場合

 [bgm stop=1000 wait]

◇ SE をならす/ とめる

 (1) 単発でならす

 [se SOUND001]

 ただし、ファイル名が「SE」ではじまる名前なら

 [SE00001]

 だけでそのまま鳴ります。
 以下のコマンド指定でもこの記述はそのまま有効です。

 (2) ループでならす

 [se SOUND01 loop]

 (3) 鳴っている se を止める（ループもそうでないものも）

 [se SOUND01 stop]

  基本的に直接 SE を指定する必要があります

 (4) 鳴っている se を全部止める

 [allse stop]

 (5) フェード処理したい場合

 フェードイン

 [se SOUND01 time=1000]

 フェードアウト

 [se SOUND01 stop=1000]

 (6) フェード処理を待ちたい

 [se SOUND01 stop=1000 wait]

◇高度な移動

(1) スライド移動

 移動時に time パラメータがあるとスライド移動します

 ---------------------------------------------
  [あかり 左 制服]         ;左に出現
　【あかり】おはよう

　[あかり 右 time=1000]    ;右にうねっと移動
  【あかり】今日もいい天気だね
 ---------------------------------------------

(2) 移動位置の初期化指定

 移動の指定で、「:」で区切って複数の位置を指定すると、
 移動する直前に位置を一瞬で初期化させることができます。

 --書式--
   移動先:初期位置

 ---------------------------------------------
  [あかり 左 制服]         ;左に出現
　【あかり】おはよう

　[あかり 右:中 time=1000]    ;一瞬で中に移動してから右にうねっと移動
  【あかり】今日もいい天気だね
 ---------------------------------------------

◇レイヤの属性

(1) 属性の指定

　画面に配置されているキャラクタやイベント絵には次のような属性を
　指定することができます

  rotate   回転角
　zoom     拡大率
　opacity  不透明度

  ---------------------------------------------
  [あかり 制服]
 【あかり】おはよ〜
  
  [あかり zoom=200]
 【あかり】巨大化〜
  ---------------------------------------------

  背景に対して指定する場合       [env zoom=200]
　イベント絵に対して指定する場合 [ev zoom=200]

(2) 属性のスライド移動

 これらの属性パラメータも、移動用の場所指定と同様に、time 指定を行うと
 滑らかに変化させることができます

  ---------------------------------------------
  [あかり 制服]
 【あかり】おはよ〜
  
  [あかり zoom=200 time=1000]
 【あかり】うにっと巨大化〜
  ---------------------------------------------

(2) 属性の初期化指定

 移動と同様に「:」で区切って複数の値を指定すると、
 変化の直前に値を一瞬で初期化させることができます。

 --書式--
   目標値:初期値

  ---------------------------------------------
  [あかり 制服]
 【あかり】おはよ〜
  
  [あかり zoom=200:80 time=1000]
 【あかり】うにゅと巨大化〜
  ---------------------------------------------

◇画面の切り替え

トランジションとは…

　２枚の表示内容が異なるものを、スムーズに表示きりかえすることを
　「トランジション」といいます（吉里吉里用語）

　例：クロスフェードでキャラクタの表情を切り替える
　　　水面のようなエフェクトで画面を切り替える
　などなど

　吉里吉里には、標準で、多数のトランジションライブラリが
　準備されていてそれを使うことができます。

　※参考: http://devdoc.kikyou.info/tvp/docs/kr2doc/contents/

ワールド拡張では、トランジションは、原則あらかじめ「登録」してから使います。

(1) トランジションの登録

  envinit.tjs にトランジションに名前をつけて登録しておく

　例: normal  普通のキャラきりかえ用にクロスフェード300ms 

  詳細は world_inst.txt を参照してください。

(2) トランジションの指定

 キャラクタに対して trans パラメータを指定すると、表示が変わるときに
 トランジションが実行されます。

 ---------------------------------------------------------
  ; 普通の表情で表示
  [あかり 制服 普通]
  【あかり】おはよー
  
  ; 表情を「笑」に切り替える。トランジションは normal
  [あかり 笑 trans=normal]
　【明かり】今日もいい天気だね
 ---------------------------------------------------------

　登録してあるトランジションの名前が一意に特定できる場合は、
　trans= は省略表記できます。

  [学校 trans=normal]  →省略→  [学校 normal] 

  背景やイベント絵などでも基本的に使い方は全部同じです。

 ---------------------------------------------------------
  ; イベント用のトランジションで表示
  [ev ev001 trans=event] 

  ....
  
  ; 背景を学校に切り替え
  [学校 trans=normal] 
 ---------------------------------------------------------

　※注意点：登録した名称はどの要素に対しても使えます


・複数同時のトランジション

　トランジションを指定すると、そこでいったん画面表示の完了待ち
　になるため、複数の要素 （背景とキャラクタ、キャラクタ２人、など）
　に対して同時にトランジションを実行することができません。

　例
 ---------------------------------------------------------
  [あかり 笑]
  [ひかり 笑]
  ; これだと両方瞬間なので同時に見える

  [あかり 笑 trans=normal]
  [ひかり 笑 trans=normal]
　; あかりのトランジションがおわってからひかりのトランジション
 ---------------------------------------------------------

  これを同時に行うためには、begintrans / endtrans という特殊コマンドを使います

 ---------------------------------------------------------
  [begintrans]
  [あかり 笑]
  [ひかり 笑]
  [endtrans trans=normal]
 ---------------------------------------------------------

  これで、両方の変更が同時に実行され、それ全体に対してトランジションが
　行われることになります。

　背景と同時に変更する例

 ---------------------------------------------------------
  [廊下]
  ....

  [begintrans]
  [学校]
  [あかり 制服 笑]
  [ひかり 制服 笑]
  [endtrans trans=normal]
 ---------------------------------------------------------

・デフォルトトランジション

標準状態ではトランジションは明示的に指定しないかぎり実行されません。

実際のスクリプト作業では、ほとんどの場面でトランジションを
使うことになるため、記述量が多くなってしまいます。
そこで、表示に関係したコマンドについては、そのコマンドが
実行された場合にトランジションを自動的に適用させることができます。

自動トランジションを指定可能なもの

キャラクタ
・ポーズ変更
・服装変更
・表情変更

背景
・場所の変更
・時間の変更

イベント絵
・画像の変更

これらについて、個別に指定が可能です。

 例　自動適応前
 ---------------------------------------------------------
  [ev ev001 trans=event] 
  ...

  [学校 trans=stage] 
  [あかり 制服 trans=charpose]
 ---------------------------------------------------------

 例　自動適応後

 envinit.tjs に以下を登録しておく
  eventTrans=event;
  stageTrans=stage;
  poseTrans=charpose;

　これでまったく同じ動作になる
 ---------------------------------------------------------
  [ev ev001] 
  ...

  [学校] 
  [あかり 制服]
 ---------------------------------------------------------

そのほか注意事項

 ・trans コマンドで直接指定すると、自動トランジションより優先されます
 ・trans=void で「トランジションしない」ことを明示的に指定できます

デフォルトトランジション登録の詳細 world_inst.txt を参照してください。

◇キャラクタのアクション

アクションとは…

　画面中に配置された画像を自動的に移動しつづけさせる機能を「アクション」と
　言います。
　
　例：ガクガクふるえる
　　　おじぎ動作
　などなど

　アクションは、アクション用のコマンドとパラメータの指定で実現されます。

ワールド拡張では、アクションは、原則あらかじめ「登録」してから使います。

(1) アクションの登録
  
  envinit.tjs にアクションに名前をつけて登録しておく

　例: 「おじぎ」 sinカーブで下にキャラの立ち絵がしずみこんで戻るように動く動作

(2) アクションの指定

 キャラクタに対して action パラメータを指定すると、そのタイミングで
 アクションが実行開始されます。
 
 ---------------------------------------------------------
  ; 普通の表情で表示
  [あかり 制服 普通]
  【あかり】おはよー
  
  [あかり 笑 action=おじぎ]
　【あかり】ごきげんよう
 ---------------------------------------------------------

　登録してあるアクションの名前が一意に特定できる場合は、
　action= は省略表記できます。
　
 [あかり action=おじぎ] →省略→ [あかり おじぎ] 

  背景やイベント絵などでも基本的に使い方は全部同じです。

 ---------------------------------------------------------
  ; 背景画像に対するアクション
  [env おじぎ] 
  ; イベント絵画像に対するアクション
  [ev action=おじぎ] 
 ---------------------------------------------------------

◇メッセージ窓の制御

メッセージ窓は基本的にテキスト表示があると自動的に表示されます。

(1) 手動で直接消去 / 表示する

 [msgoff]　メッセージ窓消去
 [msgon]   メッセージ窓表示

 trans= パラメータで消去/表示時のトランジションが指定できます

(2) トランジション連動制御

 envinit でのトランジション情報の登録時にパラメータ 「msgoff」を
 追加指定しておくと、そのトランジションが開始する前にメッセージ窓
 が消去されます。

「イベント絵を表示するときは常にメッセージ窓を消す」といった
 ルールをつくるときは、このパラメータ指定をしたトランジションを
 登録しておくと便利です。

 この機能は、transwait パラメータ（トランジション後少し待つ機能）
 と組み合わせて使うことが多いです。

◇選択肢と分岐

  KAG でのメッセージ窓を使ったリンクによる選択肢処理はそのまま利用可能です。

   http://devdoc.kikyou.info/tvp/docs/kag3doc/contents/Diverge.html

  KAGEX ではこれに加えて、「選択肢レイヤ」をつかった選択肢処理が利用できます。

 選択肢の登録（複数回）
  [seladd text=選択肢の内容 storage=のジャンプ先 target=ジャンプ先ラベル exp=選択時実行処理]

 選択処理の実行
  [select]

 選択処理実行後は、遷移するか、あるいは exp の処理を実行したあと、
 次の文に進みます。

◇変数

　変数処理は吉里吉里/KAG の機能をそのまま使います。

　http://devdoc.kikyou.info/tvp/docs/kag3doc/contents/Var.html

◇カットイン処理

カットイン画像を画面に表示したい場合は「レイヤ」を生成して
使うことができます。

(1) レイヤを作って表示する

 [newlay name=layer0 file=layerimage show]

 "layerimage" という画像をよみこんでレイヤを生成します。
 標準では画面の中心にセンタリングされた状態で配置されます

 レイヤにもキャラクタ同様に level の概念が有効です。
 lavel=4 にするとイベント絵より前に表示できます。

(2) レイヤを移動する

 xpos, ypos のパラメータでレイヤの表示位置を指定できます。
 レイヤ生成時に指定した名前をつかって、キャラクタと同様に
 操作することができます

 [layer0 xpos=200 ypos=200 time=1000]
 
・画面の中止が原点
・画像の中心が画像的な原点

　になっていることに注意してください。

(3) レイヤにアクションを指定する

 この指定もキャラと同様に行うことができます

 [layer0 action=おじぎ]

(4) レイヤを消去する

　単純な表示制御は show/hide で行います
 
  [layer0 hide]

 レイヤを使うシーンがおわった場合、hide にしただけだと、単純に消えただけで
 内部的なデータは残ったままになります。これを完全に廃棄する場合は
 hidelay コマンドを使います

 [hidelay name=layer0]


●ゲームをしあげるにあたっての作業

◇シーン回想への対応

 吉里吉里/KAGEX は、シーン回想用に特殊な「回想モード」が準備されています。
 このモードを使う場合は、シナリオ中に次のような記述をうめこむ必要があります。

 -----------------------------------------------------------
 ; 回想部分の冒頭にはジャンプ用にラベルをいれます
 *回想スタート|
 [if exp='kag.isRecollection']
 ; ここに回想シーンの場合の初期化処理を書く。
 ; シーン冒頭の場合は不要ですが、シーンの途中からの場合、
 ; 背景や立ち絵などを復帰する必要がある場合があります
 [endif]

 回想部分本体

 ; 回想終了指定。通常の実行時は無視されますが、
 ; 回想モードの場合はこの指定で終了します
 [endrecollection]
 -----------------------------------------------------------
 
 KAGEX 的には [recollection] を使うことで回想モードを開始できますが、
 多くの場合はシステムで開始制御する関係で kag.startRecollection() を
 直接呼ぶことになります。

●その他注意事項など

◇ファイルのかぶりについて

　別フォルダにあっても、同じファイル名、コンフリクトをおこします
　拡張子自動処理があるので、拡張子が違ってもやばい場合があるので注意。

◇登録名について

　登録名称の文字については特に縛りはありません。
　このドキュメントの例のように日本語にすると見た目はわかりやすいですが、
　記述は面倒なので英単語かローマ字での登録が作業上は速いかもしれません。
　コピぺ系のツールを使うのも良いでしょう

●マクロ機能の概要


●マクロの活用の例

サンプル：ムービーマクロ (macro.ks にサンプル登録ずみ）
------------------------------------------------
[macro name=movie]
[cancelskip]
[cancelautomode]
[eval exp='tf.moviefile = mp.file + ".mpg"']
[eval exp='tf.movieflag = "movie_" + mp.file']
[eval exp='tf.movieskip = sf[tf.movieflag]']
[eval exp='sf[tf.movieflag] = true']
[openvideo storage='&tf.moviefile']
[video visible=true left=0 top=0 width=800 height=600 mode=overlay volume='&kag.bgmvolume']
[playvideo]
[wv canskip='&tf.movieskip']
[video visible=false]
[endmacro]
------------------------------------------------

●マクロの応用

　演出の一環化（あとで全部調整できる）

　動きのパターンの登録

　移植性の担保
　
　演出さんぷる
　　
　特殊な消去。左キャラと右キャラで移動方法をかえるとかそういったもの

●各種応用

◇イベント絵の前にキャラを表示するには？

 例：画面中央に出現

☆ポイント
　キャラクタの場所・服装・表情などの状態は常に維持されます。
　原則として「差分のみ」を記述するようにします。

　→服装などは原則シーン初出の出現時のみで指定する

☆ポイント
　キャラクタの出現にも各種トランジションは利用できるが、
　シンプルに fade 指定するのが基本です

　キャラクタ一体でも事実上トランジションが実行されるため、
　案外負荷は高くなります。テンポ良い作品にしたい場合は
　表情変更では fade を使わないほうが良いと思われます。

