■CSScriptプラグイン


●CSScriptについて

PMXエディタのプラグイン機能を、内部スクリプトとして直接実行することのできるプラグインです。
内部ではプラグインDLLを生成しているので、通常のプラグインと同等の機能を実行することが可能です。

尚、本プラグインにはスクリプト編集用に簡易エディタを搭載しておりますが、
これは最低限の編集機能しか有しておりません。

インテリセンス機能などVisualStudio等のような扱いやすい編集サポート機能はありませんので、
プラグイン／スクリプト作成については編集内容に対して適宜環境を選択してください。

※.NET Framework4.0必須



●とりあえずサンプル

メニュー[表示] - [サンプルスクリプト]　（またはF1キー

サンプルスクリプトが一覧表示されます(選択すると内容が右側に表示されます)
編集メニュー(または右クリックメニュー)から、選択中のサンプルスクリプトを開くことが可能なので、
実際に実行して(パラメータ値を変更するなどして)、試してみてください。

※サンプル窓 [編集]-[旧仕様の表示] から PMD向けのレガシーサンプルが表示されるようになります。






§ 機能説明


●画面構成

中央：スクリプトコード編集画面
右下：スクリプト実行ボタン
左下：ビルド結果出力

となっております。

コード編集については「一般形式」と「簡易形式」を選択することが可能(上部タブ)で、それぞれ別管理となっています。

コード作成後、右下部の実行ボタン(またはメニュー[ビルド]-[実行]／F5)より、スクリプトを実行することが可能です。
ビルド失敗時は出力結果にエラー行が表示されますので、それを頼りにコード内容を修正してください。


■一般形式
一般的なプラグイン作成形式。
C#における通常のソースファイルとして編集可能です。複数ファイルのインポートはできません(アセンブリとして追加参照することは可能)

■簡易形式
一般形式においての Run() 関数内の処理にのみ特化して記述が可能です。クラスやメンバ関数などを定義することはできません。
かわりに専用のヘッダ／フッタコードが用意されており、局所的な編集に特化したスクリプトを簡易に記述することが可能です。




●参照設定

アセンブリ参照を設定します。.NETフレームワークの機能や自作のアセンブリ機能を使用するため、
ビルド参照に追加する必要があります。

[ビルド] - [アセンブリ参照追加] からシステムに登録されているアセンブリ一覧が表示されます。

※初回起動時は読み込みのためかなり時間がかかります。また一部のアセンブリは表示されない場合があります。

下部の参照アセンブリリストが登録済みのアセンブリ。上部リストから任意に選択し追加することが可能です。
外部アセンブリについては[ファイル]メニューから直接DLL(またはexeファイル)を指定してください。

例外的に PEPlugin.dll(プラグインDLL) とSlimDX.DLLについては自動的に追加されております
(アセンブリリストにはありませんが、個別追加の必要はありません)



●using設定

一般形式／簡易形式にて共用で使用する using項目を別枠で編集します。
[編集] - [using項目編集] から編集画面が表示されます。

※一般形式ではコード内に直接using項目を記述することも可能です。
※両形式に対しての共通ヘッダコードとして使うことも一応可能(非推奨)



●ヘッダ／フッタコード

簡易形式のコードに自動的に追加されるコード内容です。
標準設定で、ヘッダにはPMXの取得／各接続変数の定義、フッタにはPMX／Form／Viewの更新 が記述されております。

内容の編集は、[編集] - [ヘッダ(フッタ)コード編集] から行うことが可能です。
有効／無効設定は、[ビルド] - [簡易形式:ヘッダ(フッタ)コード追加] においてチェック指定をする必要があります。

※標準状態でフッタコードは無効。サンプルの内容によっては標準で有効なスクリプトもあります。

コメント表記で "//+H" や "//+F" と記述することでメニュー側の設定に関わらずヘッダ及びフッタを有効化することが可能です。

Cプラグイン用のヘッダ／フッタはそれぞれ別のコードとなっています。
"//+CP" でヘッダ／フッタと同様に強制的に Cプラグイン用として動作させることができます(新規作成から選択推奨)



●コードの全体像

■一般形式

[アセンブリ参照]

using項目
＋
一般形式に記述されたコード


■簡易形式

[アセンブリ参照]

using項目
＋
(プラグイン用のクラス定義開始)
＋
ヘッダコード(有効時)
＋
簡易形式に記述されたコード
＋
フッタコード(有効時)
＋
(プラグイン用のクラス定義終了)


となります。エラー時の表示行数はこれらの総コード状態での行位置となりますのでご注意ください
(ステータス表示(スクリプトエディタ左下)での行位置は調整済)



●簡易形式の一般化

[編集] - [簡易形式を一般形式へ変換] より簡易形式に記述したコードを一般化することが可能です。

※その際一般形式に記述されていた内容は破棄されますのでご注意ください。

簡易形式に記述した内容でプラグイン化(後述)する場合などに活用してください。




●スクリプトの保存／読み込み

作成したスクリプトは専用のデータファイル(*.cx 中身はxml)に保存することが可能です。
読み込みはファイルメニューから、またはD&Dで行うことも可能です。



●プラグインDLLの生成

現在のスクリプトを標準のプラグインDLLとして外部生成します。

[ファイル] - [プラグインDLL生成]

を選択後、生成DLL名を指定することでプラグインDLLが生成されます。
生成されたプラグインはPMXエディタ再起動後に有効になります(プラグインフォルダ以下に配置／起動時に一括読み込みのため)

注意点として、簡易形式で作成したプラグインDLLは登録メニュー名が全て同じ標準名("CSScript生成プラグイン")になります。

その場合、一旦一般形式へ変換し、対象の登録メニュー名を変更することで個別対応が可能となります。
尚、簡易形式でプラグインを生成しようとした場合、警告メッセージが表示されます。









§ コード編集ヒント


スクリプトコードはC#で記述する必要があります。内部動作は通常の.NET仕様ですので、他の.NET環境との連携も問題ないと思われます。

PEPlugin 内の各データは、プラグインデータ一覧([表示]-[プラグインデータ一覧])で表示されるサブウィンドウから、
コード側へ簡易にペースト追加することが可能です。

左側が型名、選択後表示される右側が型内のメンバ(プロパティや関数他)になります。

それぞれ右クリックメニューから、スクリプト側へ追加することができます(ダブルクリックでも可能)

メンバは、特定変数(argsやpmx)からの短絡系として追加することも可能となっていますが、
一般形式では事前に定義する必要があります("args"は定義済)。簡易形式では問題ありません(標準ヘッダにて全て定義済)


プラグインデータは説明部に表示される型名を辿ることで各メンバ情報を参照してください。
※登録単語による自動補完機能が内蔵されていますが、対象の全件検索のため取り扱いは難しいです(登録単語の追加変更機能は実装未定)


●表記の仕方

■文字列表現：名前やファイル名

"テキスト" -> "" で括る必要がある。
'\'文字は特別扱いになるので注意("\\"とする必要がある。面倒な場合は@"aaa\bbb\ccc"と@""で括ればOK)

string miku = "テキスト";       // 文字列 : string
string path = @"tex\a1.bmp";    // @を付けない場合は "tex\\a1.bmp"


■数値表現：データ値

1, 2, 10 etc -> 整数
1.0, 2.0, 10.0 -> 実数 

プラグイン内では実数はfloat(単精度実数)管理なので、1.0f, 2.0f, 10.0f と末尾に'f'を付ける必要がある。
尚、float指定の部分に整数を設定すると自動的に変換される。

※数値間の変換はキャスト構文によって可能
int n1;
float f1 = 10.5f;
n1 = (int)f1;	// n1:10になる


■複合数値表現：ベクトル ※旧仕様用

IPEVector3 p = args.Host.Builder.CreateVector3(0.0f, 1.0f, 2.0f);      // (x,y,z) = (0.0f, 1.0f, 2.0f)
IPEVector3 p = args.Host.Builder.SC.V3();          // 短絡形式 簡易形式の場合は bd.V3(0.0f, 1.0f, 2.0f) でもOK

p.X, p.Y, p.Z		// 使う場合


■複合数値表現：SlimDX接続

SlimDXへの橋渡しを行うための特殊クラス(構造体での値型ではないので注意)

[Plugin]   - [中継] - [SlimDX]
IPEVector4 -   V4   - Vector4／Color4
IPEVector3 -   V3   - Vector3／Color3
IPEVector2 -   V2   - Vector2
IPEMatrix  -    M   - Matrix
IPEQuaternion - Q   - Quaternion


○用例
V3 v1 = new V3(1,2,3);	// 初期化可能

IPEVector3 v2 = new V3();	// プラグインインターフェイスへの直接代入可能
Vector3 v3 = new V3(0,0,0);	// SlimDX側への直接代入可能

v2 = v1;	// プラグイン側への自動変換OK
v3 = v1;	// SlimDX側への自動変換OK

IPEVector3 v4 = new V3(v3);	// 中継生成でプラグインインターフェイスとSlimDX間の橋渡し可能(逆もOK)

float rad = Q.DegToRad(15);	// 15度をラジアン値に変換(固定機能)


※何故クラス実装？
SlimDX側では構造体(値型)により実装されていますが、
言語仕様により個別プロパティへの代入が制限される場合があり、
スクリプトとしての記述が煩雑になることも予想されるので、クラスとして実装されています。

尚、スクリプト上からもSlimDX内の機能は任意に扱えるので、橋渡しや一部の特化機能においての使用を想定しています。



■文字列と数値の変換

数値→文字列：ToString()
int i = 100;
i.ToString();		// "100" となる

float f = -2.5;
f.ToString();		// "-2.5" となる


文字列→数値:Parse()
string str = "100";
int i = int.Parse(str);	     // i = 100 となる
float f = float.Parse(str);  // f = 100.0f となる



●メッセージ表示

MessageBox.Show("Hello CSScript.");	// メッセージ表示

※詳細はC#及び.NETの解説書を参照してください。