From the Depths : LUA Help ドキュメントの雑なまとめ

この記事は

　From the Depthsの"LUA box"から閲覧できるHelpドキュメントの雑なまとめです。
エディタとヘルプを切り替えるのが辛かったし、ページ検索出来ないしでホント不便。
ていうか開発はdoxygenで自動生成したAPI 仕様書くらいは公開しろと。
ちょっとづつ書き足しながら更新していきますね

前提知識とか

左手系

手をフレミング左手の形にした時に

X : 親指
Y : 人差し指
Z : 中指

にそれぞれ対応する。
各軸の向き(指が向いてる方向)に沿うように左ねじの親指を当てはめた時の残り四本の指が向いてる方向を回転方向とする。
右手系 - Wikipediaに載っている図がわかりやすい。
普通、数学では右手系を使っているが、このゲームでは左手系であり、数学の知識をそのまま当てはめられるとは限らないので注意。

ワールド座標系

軸	向き
X	東
Y	頭上
Z	北

とする左手系の座標系。
原点はワールドのどこか。

ローカル座標系

軸	向き
X	自分自身の右
Y	自分自身の頭上
Z	自分自身の前

とする左手系の座標系。
原点座標は自分自身の「原点」。
原点はorigin blockの位置だったり最初にブロックが置かれた位置だったり重心だったり。

Indexについて

FtD LUA上ではパーツを一意に指定するためにIndexを指定することが多いのだが、これは、0からパーツの個数-1までの連番である。例えば、AI Mainframeが5つある乗り物なら0から4までの数字が振られる。

Basics

最小のコードは以下のようになっている

function Update(I)
-- put your code here
end

'I'はゲームとのインターフェースで、ゲームに関する全ての関数はこれを経由して呼び出す。
Update()関数は「ゲーム内時間で」１秒間に40回呼び出される'物理ステップ'ごとに呼び出される。
ここで言う物理ステップは物理エンジンの最小処理単位の事？

例えば、コンソールにHelloと表示するだけのサンプルなら

function Update(I)
  I:Log('Hello')
end

Syntax

LUAに関する構文の説明。
LUA自体の解説本とかを当たった方がいいかも。

Syntax : String Concatination

文字列及び変数は「..」で結合出来る。また、変数は自動的に文字列に変換される。

  I:Log('Hello'..'Player')

  hoge = 114514
  I:Log('hoge='..hoge)

Syntax : For loops

forによるループが可能

構文は「for <識別子>,開始値,終了値,増分値 do ... end」
[開始値, 終了値]であって[開始値, 終了値)では無い
「do done」じゃなくて「do end」

for ii=0, 10, 1 do
  I:Log('ii'..ii)
end

Calling Function

　関数を呼び出す時は「I:Log('Hello')」みたいに「:」で繋ぎましょう。「.」じゃないよ。

Comments

　「--」で始めるとその行はコメントになる。

Syntax : Global variables

　関数の外で変数を定義することで、Update()関数の呼び出しごとに初期化されない大域変数を定義できる。

If Statement

　条件分岐は「if <条件式> then ... end」書ける。if then fiじゃないよ。

if a>0 then
  -- your code here
end

Logging/Debugging

I:Log(message)

Message

[string] ログに流したいメッセージ

ログにメッセージを書き込む。ログはLUA　Editor画面の「Errors/Logs」の事。
ログは一般的なコンソールと違い、下端が過去、上端が最新であることに注意。

I:ClearLogs()

ログをクリアする。Update()関数の最初にクリアするといいんじゃないですかね？

I:LogToHud(message)

message

[string] HUDに流したいメッセージ

HUDというのはゲーム画面の事で、通常プレイ時とマップ画面で表示される。

Libraries

便利ライブラリがいろいろ使えますよ。

Mathf : 数学系一般
Vector3 : ３次元ベクトル
Quaternion : 四元数。回転によく使うやつ。

Propulsion

I:RequestControl(mode, type, drive)

in	mode	陸海空のモード選択
in	type	要求する制御の種類
in	drive	与える推進力。範囲は[-5,+5]

mode番号	説明
0	Water
1	Land
2	Air

type番号	説明
0	Left
1	Right
2	RollLeft
3	RollRight
4	Up
5	Down
6	Increase
7	Decrease
8	MainPropulsion

一般的な(陸海空の種別を問わない)推進、回転の要求を出す関数。

I:RequestThrustControl(type)

type

[int] 要求する制御の種類

type番号	説明
0	forwards
1	backwards
2	right
3	left
4	up
5	down
6	roll right
7	roll left
8	yaw right
9	yaw left
10	nose up
11	dose down

3軸の並進と3軸の回転による推進制御を要求する関数。
LUA以外で用意したトルク（回転）が発生しない推進システムを上書きしてしまうので注意。

I:RequestThrustControl(type, scale)

推進力の係数を指定出来る版の推進制御要求関数。引数sacaleが増えている以外は同様なので説明は割愛。

I:RequestWaterForwards(drive)

drive

範囲は[-5,+5]で、はみ出たらこの範囲に制限される

プロペラに対して前進/後退を要求する。
'Water Drive'の値を書き換える訳ではない。

I:RequestComplexControllerStimulus(stim)

stim

ComplexControllerのボタン？

Complex controllerのボタンを押す関数？
原文では刺激を送るという表現をしている。

Target Info

I:GetNumberOfMainframes()

[int]

乗り物に付いているMainFrameの個数

乗り物に付いているMainframeの個数を得る。
他の関数に渡す引数mainframeIndexは0から始まるこの個数未満の数字。

I:GetNumberOfTargets(mainframeIndex)

in	mainframeIndex	mainframeの番号
out	[int]	ターゲットの数

指定したmainframeが捕捉しているターゲットの数を得る関数。
ターゲットがいないか、そもそも指定のmainframeが存在しなければ0が返ってくる。

I:GetTargetInfo(mainframeIndex, targetIndex)

in	mainframeIndex	mainframe番号
in	targetIndex	ターゲット番号
out	[TargetInfo]	ターゲット情報オブジェクト

指定mainframeが捕捉している指定ターゲットの情報を得る。
ターゲット情報についての詳細は後述

I:TargetInfo

メンバ名	型
Valid	[bool]	正しく情報が得られて入ればtrue
Priority	[int]	Target prioritisation cardによって設定される0を最高とする優先度
Score	[float]	Target prioritisation cardによって設定されるスコア
AimPointPosition	[Vector3]	狙うべきブロックの座標(ワールド座標系)
Team	[int]	敵か味方か(どっちだよ？)
Protected	[bool]	falseならsalbage中(?)
Position	[Vector3]	ターゲットの座標(ゲーム座標系)
Velocity	[Vector3]	ターゲットの移動速度(m/s)
PlayerTargetChoice	[bool]	プレイヤーによってターゲット指定されているか(だからどっちだよ？)
Id	[int]	一意なターゲットのID

Validがflaseの場合はそのTargetInfoは無効ということ。
記述が足りていない部分がちょくちょくあるので要調査。

I:GetTargetPositionInfo(mainframeIndex, targetIndex)

in	mainframeIndex	mainframe番号
in	targetIndex	ターゲット番号
out	[TargetPositionInfo]	ターゲット位置情報オブジェクト

指定mainframeが捕捉している指定ターゲットの位置関連の情報を得る。

I:GetTargetPositionInfoForPosition(mainframeIndex, x, y, z)

in	mainframeIndex	mainframe番号
in	x	[float] 東/西の位置[m]
in	y	[float] 高さの位置(0で海面)[m]
in	z	[float] 北/南の位置[m]
out	[TargetPositionInfo]	ターゲット位置情報オブジェクト

メインフレームと座標を指定してターゲット位置情報を得る。
GetTargetInfo()と併用する？

TargetPositionInfo

Valid	[bool]	正しく情報が得られていればtrue
Azimuth	[float]	自分からみたターゲットの水平方向.時計回りを正.
Elevation	[float]	自分からみたターゲットの垂直方向. 下向きを正.(危ない値？)
ElevationForAltitudeComponentOnly	[float]	?(ロバスト)
Range	[float]	ターゲットとの距離
Direction	[Vector3]	ターゲットの向き(絶対値,正規化されていない)
GroundDistance	[float]	ターゲットと地面までの距離
AltitudeAboveSeaLevel	[float]	ターゲットとの距離
Position	[Vector3]	ターゲットの位置
Velocity	[Vector3]	ターゲットの速度[m/s]

ターゲットと自分自身の相対的な位置関係やターゲットの絶対的な位置関係などがまとめられている。

Misc

I:GetTerrainAltitudeForPosition(x, y, z)

in	x	[float] ワールド座標系での東/西の位置[m]
in	y	[float] ワールド座標系での高さ[m](重要でない)
in	z	[float] ワールド座標系での北/南の位置[m]
out		[float] 地形の高度[m](海面を0とする)

ワールド座標系で位置を指定し、地形の高度を取得する。
入力としてVector3を与えるオーバロード関数が存在する？
高さを指定できるが、これはおそらくオーバーロード関数とインターフェースを揃えるためのダミー引数。

I:GetTerrainAltitudeForLocalPosition(x, y, z)

in	x	[float] 自分自身を中心とした右方向を正とするオフセット位置[m]
in	y	[float] 自分自身を中心とした頭上方向を正とするオフセット位置[m]
in	z	[float] 自分自身を中心とした正面方向を正とするオフセット位置[m]
out		[float] 地形の高度[m](海面を0とする)

自分自身からの相対座標で位置を指定し、地形の高度を取得する。
入力としてVector3を与えるオーバロード関数が存在する？
高さを指定できるが、これはおそらくオーバーロード関数とインターフェースを揃えるためのダミー引数。

I:GetGravityForAltitude(alt)

指定高度における重力を得る。

I:GetTime()

時間を得る。時間ってなんだ？
単位は秒。

I:GetTimeSinceSpawn()

自分自身がスポーンしてからの時間を得る。
単位は秒。

I:GetGameTime()

ゲームが起動してからの経過時間を得る。
単位は秒。

Selfawareness

I:GetConstructPosition()

自分自身の位置をVector3で得る。
自分自身の位置の定義について何か言ってるけどよくわからない。

I:GetConstructForwardVector()

自分自身の前方を表す長さ1のベクトルを得る。

I:GetConstructRightVector()

自分自身の右方を表す長さ1のベクトルを得る。

I:GetConstructUpVector()

自分自身の上方を表す長さ1のベクトルを得る。

I:GetConstructMaxDimensions()

自分自身の座標系上で、原点からの正方向のサイズを得る。
自分自身と内接し、自分自身の座標系と平行な直方体について、原点から(x, y, z)全てについて正方向の頂点に向かうベクトルを返す。
I:GetConstructMaxDimensions()-I:GetConstructMinDimensions()で自分自身を内包する直方体の寸法が得られる。

I:GetConstructMinDimensions()

自分自身の座標系上で、原点からの負方向のサイズを得る。
自分自身と内接し、自分自身の座標系と平行な直方体について、原点から(x, y, z)全てについて正方向の頂点に向かうベクトルを返す。

I:GetConstructRoll()

自分自身の姿勢のロール角を得る。

I:GetConstructPitch()

自分自身の姿勢のピッチ角を得る。

I:GetConstructYaw()

自分自身の姿勢のヨー角を得る。

I:GetConstructCenterOfMass()

自分自身の重心座標をワールド座標系で得る。

I:GetAiPosition(mainframeIndex)

指定したmainframeの座標をワールド座標系で得る。
(0, 0, 0)が帰ってきた場合は指定したmainframeが存在していない。

I:GetVelocityMagnitude()

自分自身の速度を得る。
単位は[m/s]。

I:GetForwardsVelocityMagnitude()

自分自身の「正面方向の」速度を得る。
単位は[m/s]。
マイナス値は後ろ向きに進んでいることを表す。

I:GetVelocityVector()

自分自身の速度ベクトルを得る。
ワールド座標系。
単位は[m/s]。

I:GetVelocityVectorNormalized()

自分自身の速度ベクトルを正規化したベクトルを得る。
要するに進んでいる方向を表すベクトルのこと。
ワールド座標系。

I:GetAngularVelocity()

自分自身の角速度を得る。
ワールド座標系。
x, y, z回転どうなってんだこれ？
オイラー角での表現。

I:GetLocalAngularVeclocity()

自分自身の角速度を得る。
ローカル座標系。
x, y, xそれぞれ軸の回転で左手系？

I:GetAmmoFraction()

Ammo storageの残量を得る。
0.0が最大で空なら1.0。

I:GetFuelFraction()

Fuel storageの残量を得る。
0.0が最大で空なら1.0。

I:GetSparesFraction()

spare storageの残量を得る。
0.0が最大で空なら1.0。

I:GetHealthFraction()

I:IsDocked()

I:GetHealthFractionDifference(time)

Cpomponents / Types

Components types and their logic

番号	パラメータ型	対象パーツ	説明
0	[bool]	balloon	trueなら風船ON
1	[float]	drive	[-5.0, +5.0]の推力の強さの設定？
2	[bool]	air pump	trueで有効、falseで無効
	[float]	air pump	0.0から1.0で浮力を指定
3	[bool]	resource gatherer	trueで有効、falseで無効
5	[bool]	ammo processor	trueで有効、falseで無効。
6	[bool]	oil processor	trueで有効、falseで無効。
7	[bool]	tractor beam	trueで有効、falseで無効。
8	[float]	hydrofoils	-45[Deg]から-45[Deg]
9	[float]	propulsion	出力係数を0.0から1.0で指定
10	[int]	shield projector	0=off, 1=disrupt, 2=reflect
	[float]	shield projector	シールド強度

BlockInfo

Position	[Vector3]	ワールド座標系での位置
LocalPosition	[Vector3]	ローカル座標系での位置
LocalPositionRelativeToCom	[Vector3]	重心を原点とするローカル座標系での位置
Forwards	[Vector3]	ワールド座標系におけるブロックの正面方向
LocalForwards	[Vector3]	ローカル座標系におけるブロックの正面方向
Rotation	[Quaternion]	ワールド座標系におけるブロックの姿勢
LocalRotation	[Quaternion]	ローカル座標系(乗り物orタレット)におけるブロックの姿勢

I:Component_GetCount(type)

指定タイプのパーツが何個あるかを得る。

I:Component_GetLocalPosition(type, index)

in	type	パーツの種類
in	index	パーツのインデックス
out		[Vector3i] パーツの位置(整数座標)

ローカル座標系での指定パーツの位置を得る。
座標は整数ベクトルな点に注意。

I:Component_GetBlockInfo(type, index)

in	type	パーツの種類
in	index	パーツのインデックス
out		[BlockInfo] ブロック情報オブジェクト

指定パーツの情報オブジェクトを得る。

I:Component_GetBoolLogic(type, index)

指定パーツの[bool]パラメータを得る。

I:Component_SetBoolLogic(type, index, bool)

指定パーツの[bool]パラメータを設定する。

I:Component_GetFloatLogic(type, index)

指定パーツの[float]パラメータを得る。

I:Component_SetFloatLogic(type, index, float)

指定パーツの[float]パラメータを設定する。

I:Component_GetIntLogic(type, index)

指定パーツの[int]パラメータを得る。

I:Component_SetIntLogic(type, index, integer)

指定パーツの[int]パラメータを設定する。

I:Component_SetBoolLogicAll(type, bool)

指定種類パーツの[bool]パラメータを設定する。

I:Component_SetFloatLogicAll(type, float)

指定種類パーツの[float]パラメータを設定する。

I:Component_SetIntLogicAll(type, int)

指定種類パーツの[int]パラメータを設定する。

Weapons

I:GetWeaponCount()

兵器の数を得る。タレット上の兵器はカウントされないが、タレットは１つとしてカウントされる。

I:GetWeaponInfo(weaponIndex)

in	weaponIndex
out	[WeaponInfo] 兵器情報オブジェクト

指定兵器の情報を得る。

WeaponInfo

Valid	[bool]	正しく情報が得られていればtrue
LocalPosition	[Vector3]	ローカル座標系における兵器の位置
GlobalPosition	[Vector3]	ワールド座標系における兵器の位置
Speed	[float]	兵器の近似速度(?)で単位は[m/s]
CurrentDirection	[Vector3]	ワールド座標系における兵器の向き
WeaponType	[int]	兵器の種類
WeaponSlot	[int]	アサインされてるウェポンスロットで[0, 5]の値
PlayerCurrentlyControllingIt	[bool]	trueならプレイヤーが操作中

ID	WeaponType
0	cannon
1	missile
2	laser
3	harpoon
4	turret
5	missilecontrol
6	fireControlComputer

I:AimWeaponInDirection(weaponIndex, x, y, z, weaponSlot)

in	weaponIndex	[int] 兵器番号
in	x	[float] aim角度
in	y	[float] aim角度
in	z	[float] aim角度
in	weaponSlot	[int] 0ならALL、1から5で個別指定

兵器を指定の方向に向ける。
角度はワールド座標系で指定する。
角度は正規化されている必要はない。

I:FireWeapon(weaponIndex, weaponSlot)

in	weaponIndex	[int] 兵器番号
in	weaponSlot	[int] 0ならALL、1から5で個別指定

指定兵器を発射する。

I:GetTurretSpinnerCount()

タレットとspinnreの数を得る。

I:GetWeaponCountOnTurretOrSpinner(turretSpinnerIndex)

指定{タレット, spinner}上の兵器の数を得る

I:GetWeaponInfoOnTurretOrSpinner(turretSpinnerIndex, weaponIndex)

指定{タレット, spinner}上の指定兵器の情報を得る。

I:AimWeaponInDirectionOnTurretOrSpinner(turretSpinnerIndex, weaponIndex, x, y, z, weaponSlot)

指定{タレット, spinner}上の指定兵器の狙う向きを指定する。
詳細はI:AimWeaponInDirection()を参照。

I:FireWeaponOnTurretOrSpinner(turretSpinnerIndex, weaponIndex, weaponSlot)

指定{タレット, spinner}上の指定兵器を発射する。

Missile Warning

I:GetNumberOfWarnings(mainframeIndex)

現在警告している敵ミサイルの数を得る。
問い合わせ先mainframeを指定する。

I:GetMissileWarning(mainframeIndex, missileIndex)

指定mainframeの警告している指定敵missileのミサイル警告情報を得る。

MissileWarningInfo

Valid	[bool]	正しく情報が得られていればtrue
Position	[Vector3]	ミサイルの位置(座標系不明)
Velocity	[Vector3]	ミサイルの速度ベクトル[m/s]
Range	[Vector3]	自分自身の重心とミサイルとの距離
Azimuth	[float]	自分自身の正面方向からミサイルに対する水平角度[Deg]
Elevation	[float]	自分自身の正面方向からミサイルに対する垂直角度[Deg]
TimeSinceLaunch	[float]	ミサイルが発射されてからの経過時間
Id	[float]	ミサイルの一意なID

Missile Guidance

I:GetLuaTransceiverCount()

LUA Transceiverの個数を得る。
Transceiverはそれぞれ何個かの制御可能なミサイルを持っている。

I:GetLuaControlledMissileCount(luaTransceiverIndex)

指定のLUA transceiverが制御しているミサイルの数を得る。
luaTransceiverIndexは0から始まる。

I:GetLuaTransceiverInfo(luaTransceiverIndex)

in	luaTransceiverIndex	[int] Transceiver番号
out		[BlockInfo] Transceiverの情報オブジェクト

指定のLUA TransceiverのLaunchPadの情報を得る。
情報はBlockInfoとして返却される。
LaunchPadがなければLuaTransceiverのBlockInfoを返却する？

I:GetLuaControlledMissileInfo(luaTransceiverIndex, missileIndex)

in lluaTransciverIndex	[int] Transceiver番号
in	missileIndex	[int] ミサイル番号
out		[MissileWarningInfo] ミサイル情報

指定LUA Transceiverの制御する指定ミサイルの情報を得る。
luaTransceiverIndexとmissileIndexは0から始まる。
ミサイル情報はMissileWarningInfoオブジェクトで返却される。

I:SetLuaControlledMissileAimPoint(luaTransceiverIndex, missileIndex, x, y, z)

指定LUA Transceiverの指定ミサイルの誘導先点(着弾点)を設定する。
指定座標はワールド座標系。
ガイダンスモジュール(赤外線シーカーとかのこと？)が無い場合は、この誘導点を使う？
LUA ResceiverがONになっていないとこの関数の呼び出しは無効になる。

I:DetonateLuaControlledMissile(luaTransceiverIndex, missileIndex)

指定LUA Transceiverの指定ミサイルを起爆する。
LUA ResceiverがONになっていないとこの関数の呼び出しは無効になる。

I:IsLuaControlledMissileAnIterceptor(luaTransceiverIndex, missileIndex)

指定LUA Transceiverの指定ミサイルが迎撃能力を持つか調べる。
trueなら迎撃能力あり。

I:SetLuaControlledMissileInterceptorTarget(luaTransceiverIndex, missileIndex, mainframeIndex, targetIndex)

in	luaTransciverIndex	[int]
in	missileIndex	[int]
in	mainframeIndex	[int]
in	target index	[int]

自身のコントロール下の迎撃ミサイルの迎撃ターゲットを指定する。
これはIntercepterによる自動誘導のターゲットを指定する。
自分でガイダンスしたい場合はI:SetLuaControlledMissileInterceptorStandardGuidanceOnOff()で自動誘導を切ること。