最終更新日時：2010年04月18日 (日) 21時11分16秒
プラグイン
プラグインとは
FreeTrainEX Avは、マイクロカーネル方式で、本体にはほんのわずかの機能しか組み込まれておらず、残りはプラグインによって機能を拡張する、という方式になっています。
様々な新しい列車や建物、機能がプラグインとして公開されており、それらを追加することで、FreeTrain EX Avの世界はますます広がっていきます。
プラグインの位置と内容
プラグインの位置
すべてのプラグインは、標準でFreeTrain EX Avがインストールされているディレクトリの下にあるpluginsディレクトリの中に配置されます。
各々のプラグインは、さらに、そのプラグイン名と同じ名前のディレクトリの中に配置されています。
例えば、org.kohsuke.freetrain.trains プラグインは、
FreeTrain EX Avのディレクトリ/plugins/org.kohsuke.freetrain.trains
ディレクトリ中に配置されます。
非標準のプラグインディレクトリ
プラグインを開発する場合、自作のプラグインを別なディレクトリに配置したくなることがよくあります。このような場合、-
プラグインプロファイルを使うことによって、複数のディレクトリから選択的にプラグインをロードすることが出来ます。
プラグインの内容
各プラグインのディレクトリには、plugin.xmlというファイルと、プラグインに必要なBMPなどのデータファイルが納められています。
プラグインの内容は、plugin.xmlファイルで定義されています。
プラグインを追加する
公開されているプラグインを追加するには、pluginsディレクトリ内に、そのプラグインのディレクトリを配置します。
具体的には、配布ファイル中のプラグインディレクトリを、pluginsディレクトリにコピーまたは移動します。
この作業は、FreeTrainが実行されていないときに行います。次にFreeTrainが起動するときに、追加したプラグインが読み込まれます。
プラグインを作成する
プラグインを作成するには、定められた書式でplugin.xmlを記述する必要があります。
プラグインの構成
プラグインは、１つ以上のコントリビューションをまとめたものです。
コントリビューションとは、プラグインとして追加される様々な「もの」のことであり、例えば、建物や列車などが挙げられます。
プラグインの製作
プラグインを製作するには、以下の作業が必要です。
コントリビューションを作成する
作成するプラグインで追加するコントリビューションを作ります。また、そのコントリビューションに必要な画像などのファイルも作成します。
この作業は、追加するコントリビューションによって異なります。詳しくは、コントリビューションを参照してください。
plugin.xml を作成する
作成するプラグインの plugin.xml を記述します。xmlファイルはテキストファイルの一種なので、メモ帳やワードパッドなどの一般的なテキストエディタを使用して記述できます。
plugin.xml は、XMLの記法で記述します。XMLの書き方については、簡易XML入門などを参照してください。
plugin.xml の書式は以下の通りです。
<?xml version="1.0" encoding="Shift_JIS"?>
<plug-in>
<title>プラグインのタイトル</title>
<author>制作者名</author>
<homepage>連絡先</homepage>
コントリビューション1のXML
コントリビューション2のXML
...
</plug-in>
プラグインのタイトルは、プラグインの内容を簡潔に表した文字列を指定します。
制作者名には、プラグイン制作者であるあなたの名前（ハンドル）を記述してください。
連絡先には、あなたの連絡先（ホームページのアドレスや、メールアドレスなど）を記述してください。
コントリビューションのXMLの部分に、追加するコントリビューションの定義を記述します。
プラグイン名を決定する
プラグイン名を決定します。この名前は、プラグインのタイトルとは別で、プラグインごとに一意でなければなりません。
プラグインを配置する
先のプラグイン名と同じ名前のディレクトリを作成し、plugin.xmlと必要な画像その他のファイルをその中に入れます。
プラグインの完成!
以上の手順で、プラグインは完成です。
FreeTrain EX Avを起動して、新しいプラグインが正しく登録されているか、正しい動作をするかを確認しましょう。
plugin.xmlの例
<?xml version="1.0" encoding="Shift_JIS"?>
<plug-in>
<title>プラグインの例プラグイン</title>
<author>名無しさん</author>
<homepage>http://www.kohsuke.org/freetrain/wiki/</homepage>
<contribution type="GenericStructure" id="{nanashisan-structure-4982-80D2-87342DC760DA}">
<group>建物プラグイン</group>
<price>150</price>
<size>1,1</size>
<height>2</height>
<sprite origin="0,0" offset="24">
<picture src="sample_house.bmp" />
</sprite>
<population>
<class name="freetrain.contributions.population.ResidentialPopulation"/>
<base>10</base>
</population>
</contribution>
</plug-in>
プラグインの実例
FreeTrain にはあらかじめいくつかのプラグインが組み込まれています。FreeTrainをインストールしたディレクトリのpluginsディレクトリを参照してください。
すでにあるプラグインを参考にするのも、プラグイン製作には役立ちます。
ただし、すでにあるプラグインのいくつかは、FreeTrain EX以前の古い記述方法を取っていたり、上記の
プラグイン作成のルールや、現在推奨されている
プラグイン作成のマナーに従っていないこともしばしば見られます。
最新の情報を収集して、古い部分は読み替えて参考にしましょう。
プラグイン間の依存性
あるプラグインを利用するのに他のプラグインが必要、という事がよくあります。例えば、あるプラグインで画像(PictureContrib)を定義して、別なプラグインでそれを参照する、といったような場合です。このような時は、<depend>タグを使います。
例えば、今書いているプラグインがプラグイン「org.abc.def」に依存する場合、
<plug-in>
<title> ... </title>
...
<depend on="org.abc.def"/>
...
</plug-in>
というように、<plug-in>要素の下に<depend>要素を書いてください。なお、全てのプラグインは自動的にsystemプラグインに依存するものとして扱われます。<depend on="system" />という明示的な指定は必要ありません。
プラグイン開発についての指針（案）
主に、セーブデータの互換性を損なわないための注意点などを述べますので、参考にしてください。
一度公開したプラグインを更新するとき、同じプラグインであるにもかかわらず内部の情報が異なっていると、セーブデータとの間でデータの不一致が生じます。
- 建物の大きさを変える
- コントリビューションIDを変える
- 別のコントリビューションとして認識され、互換性を損ないます。
- plugin名（フォルダ名）を変える
- インストールしたプレイヤー側でフォルダが新旧2つ存在してしまい、プラグインが衝突します。
以下のような変更は問題ないとされています。
- 画像を差し替える
- 画像ファイルの変更や、それに伴うスプライトの切り出しの変更、オーバーライドなどは影響がないと思われます。
- 建物や列車などの情報を変更する
- 建物の価格、人口、列車の定員といった情報は変更しても大丈夫だと思われます。
プラグインの配布
作成したプラグインは、自由に配布することができます（後述の、「ライセンスについて」もご覧ください）。
ご自身のホームページなどwebスペースをお持ちなら、そちらで公開して頂くのがよいでしょう。
専用のwebスペースがない場合は、2つあるアップローダのうち適当と思われる方を選んでアップロードし、アップロード下旨を公開しましょう。
新しいプラグインをアップロードしたら、鉄道経営系ゲーム製作スレッドにご報告ください。
2chに書き込めない場合は、本wikiの代理投稿依頼スペース、SoueceForge.jpフォーラムの「プラグイン」板などに書き込むのもよいでしょう。
ライセンスについて
FreeTrain EX Av本体はLGPLで配布しています。プラグインはLGPLとは異なるライセンスを適用することができますが、その場合はその旨明記してください。再配布などを極力簡単にするため、できるだけLGPLを使ってくださるようお願いします。
最終更新：2010年04月18日 21:11
