--ひめしツールキット v3--

作成者：ひめし（Twitter: @himeshi_hob）
第3版：2021年4月
対応バージョン：r9539以降（OTRP v29_2以降）

1. ひめしツールキットとは？
hm_toolkit（ひめしツールキット）は，ワンクリック建設系のスクリプトツールをかんたんに書けるようにするためのライブラリです．アドオン制作におけるdatのような感覚で建設系スクリプトを書けるようになります．

2. ライセンス
MITライセンスとします．
ツール配布の際に本ライブラリのファイルをそのまま同梱して配布していただいて構いません．その際，このreadmeを同梱する必要はありません．

3. 導入方法
ツールのフォルダにhm_toolkit_v3.nutおよびhm_libフォルダを配置し，tool.nutを専用の書式で記述します．
tool.nutでは，下のようにhm_toolkit_v3をincludeした上で，hm_build()という関数のみ実装します．

include("hm_toolkit_v3") 
function hm_build() {
  //ここに実行したい処理を書く．
}

Simutransのスクリプト記述では本来init()やwork()といった関数を記述しますが，これらはhm_tookitによって全て代行されているので，tool.nutでは実装しないでください．
description.tabは通常のscripting toolと同様に書いてください．

4. 使えるコマンド
ひめしツールキットでは，以下の7種類のコマンドが利用できます．
座標は，ツール実行座標からの相対座標で，[x,y,z]の形で記述してください．
アドオン名は翻訳適用前の英数字の名前を記述してください．

a) スロープツール
書式 ... hm_slope_tl(スロープ形状, [設置座標])

スロープ形状は，以下のパラメータを利用できます．
hm_slope.UP, hm_slope.DOWN ... 1段上げる，1段下げる
hm_slope.E1, hm_slope.E2 ... 緩坂東向きスロープ，急坂東向きスロープ
hm_slope.W1, hm_slope.W2 ... 緩坂西向きスロープ，急坂西向きスロープ
hm_slope.N1, hm_slope.N2 ... 緩坂北向きスロープ，急坂北向きスロープ
hm_slope.S1, hm_slope.S2 ... 緩坂南向きスロープ，急坂南向きスロープ

例 ... hm_slope_tl(hm_slope.E1, [3,0,0])
↑相対座標(3,0,0)に緩坂東向きスロープを設置します．

b) 線路/道路建設ツール
書式 ... hm_way_tl("アドオン名",[起点座標],[終点座標])

線路/道路/運河など，waytypeに関わらず利用できます．
ctrlキーを押しながら線路建設をしたときの挙動になります．

例 ... hm_way_tl("np-wooden-sleeper-track",[4,0,0],[9,0,0])

c) 架線建設ツール
書式 ... hm_wayobj_tl("アドオン名",[起点座標],[終点座標])

このツールは，鉄道用架線でのみ利用できます．他のwaytypeでは利用できません．

例 ... hm_wayobj_tl("np-slow-overheadpower",[0,1,0],[13,1,2])

d) 駅建設ツール
書式 ... hm_station_tl("アドオン名",[設置座標])

鉄道用ホーム/道路用停留所など，waytypeに関わらず利用できます．

例 ... hm_station_tl("np-railstop-platform-1",[3,3,4])

e) 信号/標識設置ツール
書式 ... hm_sign_tl("アドオン名",ツール実行回数,[設置座標])

鉄道用信号/道路用標識など，waytypeに関わらず信号，標識ともに利用できます．
向きの設定は，手動で設置する時と同様にツールの実行回数により行います．

例 ... hm_sign_tl("np-rail-signals",3,[4,0,2])
この例では信号設置ツールを3回クリックすることになります．

f) 撤去ツール
書式 ... hm_remove_tl([撤去座標])

ワンクリックの撤去ツールです．挙動は手動で実行したときに準じます．

例 ... hm_remove_tl([9,6,0])

g) 線路/道路撤去ツール
書式 ... hm_wayremove_tl([起点座標],[終点座標])

起点座標にある線路や道路のwaytypeを見て，線路の撤去を行います．
起点および終点タイルの線路は残されます．

例 ... hm_wayremove_tl([3,0,1],[10,0,1])

h) プラットホームの回転
書式 ... hm_rotate_building_tl([回転させる座標])

指定した座標に，プラットホームの回転ツールを作用させます．

例 ... hm_rotate_building_tl([1,7,1])

i) チャットメッセージの表示
書式 ... hm_chat_message_tl("表示するメッセージ", [座標])

テキストをチャットメッセージとして表示します．表示されたメッセージはメッセージ表から確認できます．

例 ... hm_chat_message_tl("Welcome to my tool.", [0,0,1])

j) エラーメッセージの表示
書式 ... hm_error_message_tl("表示するメッセージ")

テキストをエラーメッセージとして表示します．
このコマンドを呼ぶとスクリプトツールの実行が終了するので，スクリプトの最後尾に記述してください．

例 ... hm_error_message_tl("All construction finished.")

k) 関数実行ツール
書式 ... hm_exec_func_tl(関数, パラメータ)

引数に(player, pos, パラメータ) を取る関数を実行します．関数の戻り値がnull以外の場合，エラーメッセージとして処理されます．

例 ... hm_exec_func_tl(((@pl, pos, str) gui.add_message_at(pl, str, pos)), "Hello, Simutrans!")
この例では関数をラムダ式で渡しています．

l) 橋建設ツール
書式 ... hm_bridge_tl("アドオン名",[起点座標],[終点座標])

線路/道路/運河など，waytypeに関わらず利用できます．
ドラッグで橋を建設したときの挙動になります．

例 ... hm_bridge_tl("np-slab-track-bridge",[4,0,0],[9,0,0])

m) トンネル建設ツール
書式 ... hm_tunnel_tl("アドオン名",[起点座標],[終点座標])

線路/道路/運河など，waytypeに関わらず利用できます．
ctrlを押しながらトンネルを建設したときの挙動になります．
起点が坂（地上）の場合，トンネルの入口があわせて建設されます．

例 ... hm_tunnel_tl("np-concrete-rail-tunnel-1",[4,0,0],[9,0,0])

5. 特定範囲のオブジェクトからのアドオン名抽出
マップ内の特定座標に軌道などを設置することで，アドオンを選択させることができます．アドオンやpakセットに依存しないため、高度の柔軟性を維持しつつ臨機応変に利用できます．

wayのアドオン選択を例に説明します．まず，アドオンを抽出するマップ領域を指定します．
書式 ... hm_find_way(文字列キー, [領域開始], [領域終了])
例 ... hm_find_way("0", [0,0,-10], [5,2,10])
この場合，マップの(0,0,-10)〜(5,2,10)の範囲でwayを探索し，見つかったwayのアドオンがキー"0"で利用できるようになります．
ここで指定される座標は，マップ内の絶対座標です．

探索したアドオンを利用するときは，アドオン名を，「"?f" + キー」にします．
例 ... hm_way_tl("?f0",[0,0,0],[4,0,2])
これで，キー"0"に対応するアドオン名が代入されます．

アドオンを抽出するマップ領域を指定関数は，オブジェクトごとに次のとおりです．
（橋とトンネルでは利用できません．）
道路/軌道 ... hm_find_way(文字列キー, [領域開始], [領域終了])
架線 ... hm_find_wayobj(文字列キー, [領域開始], [領域終了])
標識/信号 ... hm_find_sign(文字列キー, [領域開始], [領域終了])
駅 ... hm_find_station(文字列キー, [領域開始], [領域終了])
建設コマンドにおけるアドオン名は，オブジェクトの種類に関わらず「"?f" + キー」です．

6. 実行時にクリックでアドオンを抽出する
スクリプトツールを実行するとき，はじめにマップ内オブジェクトをクリックして選択し，選択されたオブジェクトのアドオンを建設に用いることができます．

wayのアドオン選択を例に説明します．ユーザーにオブジェクトを選択させるには，次のコマンドを呼び出します．
書式 ... hm_select_way("表示するテキスト")
例 ... hm_select_way("select the road.")
このコマンドは，複数回呼び出せます．テキストはユーザーがオブジェクトを選択する時に，チャットメッセージとして画面下部に表示されます．

選択されたオブジェクトのアドオンを利用するときは，アドオン名を，「"?s" + 番号」にします．
番号Xは，「X番目にクリックされたアドオン」を表します．番号は1からの連番です．（0スタートではありません．）
例 ... hm_way_tl("?s1",[0,0,0],[4,0,2])
番号は，オブジェクトの種類ごとに別で付番されます．

ユーザーにオブジェクトを選択させるコマンドは，オブジェクトごとに次のとおりです．
（橋とトンネルでは利用できません．）
道路/軌道 ... hm_select_way("表示するテキスト")
架線 ... hm_select_wayobj("表示するテキスト")
標識/信号 ... hm_select_sign("表示するテキスト")
駅 ... hm_select_station("表示するテキスト")
オブジェクトの選択は，道路/軌道→架線→標識/信号→駅の順に要求されます．

7. その他
・v1, v2向けに書かれたスクリプトはv3でもそのまま利用できます．
・hm_build()関数内で，ツールを実行しているplayerオブジェクトは，グローバル変数「player」で利用できます．
・マップ内のマーカーの値は，include("hm_lib/lib_obj_finder_v2") した上で，ObjFinder(player, [[探索起点座標], [探索終点座標]]).findLabel() で取得できます．

8. 既知の問題
simutrans standard 122.0上で動作させたときに観測している問題です．
・ツールb, c, gにおいて，建設経路が見つからなかった場合でもエラーが出ません．
・ツールeを踏切（同じタイルに線路と道路がある）上で動作させると正しく動作しないことがあります．
将来のsimutrans本体の仕様変更により，本ライブラリの挙動が変わる可能性があります．