defold-scripts-editing

Defold スクリプトファイルと Lua モジュールの編集

Defold には 4 種類の Lua スクリプトがあり（それぞれ異なるコンテキストで異なる API を使用します）、再利用可能なロジックのためのプレーンな .lua モジュールもあります。

API の詳細については defold-api-fetch スキルを使用してください。概念的なマニュアルについては defold-docs-fetch スキルを使用してください。このスキルでは、スクリプトの構造、制約、テンプレートを扱います。

Lua モジュール（.lua）

プレーンな .lua ファイルは、再利用可能なロジックをカプセル化する Lua モジュールです。頻繁に使う汎用ロジックは .lua モジュールに切り出し、重複を避けてスクリプトを簡潔に保ちます。モジュールは require("path.to.module")（ドットをパス区切りとして使用）で読み込みます。

Defold プロジェクトでは通常、Lua 共有状態（game.project の shared_state）を使用します。有効にすると、すべてのスクリプト、GUI スクリプト、レンダースクリプトが同じ Lua コンテキストで実行されます。任意のスクリプトから読み込まれた Lua モジュールは、単一の Lua インタープリターインスタンス内で、すべての利用者間で同じコンテキストと状態を共有します。モジュールレベルのローカル変数と package.loaded は、モジュールのすべての利用者間で共有されます。状態を持つモジュールはシングルトンのように動作します。

Lua モジュールの構造（.lua）

データと関数をローカルテーブルにカプセル化し、それを返します。

local M = {}

function M.hello()
    print("Hello")
end

return M

モジュールではグローバル変数を避けてください。状態を持つモジュールでは、内部状態がすべての呼び出し元間で共有されます（シングルトンのように動作します）。状態を持たないロジックでは、状態を明示的に渡すか、新しい状態テーブルを返すコンストラクターを使用してください。モジュールのマニュアルを参照してください。

スクリプトの種類

拡張子	コンテキスト	Lua ランタイム	go.property()	主な名前空間
.script	ゲームオブジェクトのコンポーネント	LuaJIT	はい	go、msg、vmath、timer、sys、コンポーネントの名前空間（sprite、label、factory、collectionfactory、collectionproxy、tilemap、model、sound、particlefx、buffer、resource、physics）
.gui_script	GUI コンポーネント	LuaJIT	いいえ	gui、msg、vmath、sys
.render_script	レンダーパイプライン（プロジェクトごとに 1 つ）	LuaJIT	いいえ	render、graphics、camera、msg、vmath、sys
.editor_script	Defold エディター	Lua 5.2 (luaj)	いいえ	editor、editor.ui、editor.prefs、editor.tx、http、json、zip、zlib

ファイル形式

すべてのスクリプトの種類と .lua モジュールは、プレーンな Lua ファイルです（Protobuf テキスト形式ではありません）。スクリプトには専用の拡張子（.script、.gui_script など）を使用し、モジュールには .lua を使用します。

ランタイム環境に関する注意事項（.script、.gui_script、.render_script）

プラットフォーム固有：html5 モジュールは HTML5 プラットフォームでのみ利用できます。

App Manifest による除外：一部の組み込みモジュール（liveupdate、image、types、profiler、sound、physics など）は、バイナリサイズを小さくするために App Manifest で除外できます。除外した場合、それらの API は実行時に利用できません。

utf8 モジュールはありません：ASCII 以外の文字列を扱う場合は、defold-utf8 依存関係（https://github.com/d954mas/defold-utf8/archive/refs/heads/master.zip）を使用してください。API リファレンス：utf8.script_api。

ランタイムスクリプトの一般的なパターン（.script、.gui_script、.render_script）

すべてのランタイムのライフサイクルコールバックは、最初のパラメーターとして self を受け取ります。これは、インスタンスの状態を保存するテーブルのように機能するユーザーデータです。

スクリプトの構造

1. モジュールの読み込み（任意） — local M = require("module")
2. ローカルのヘルパー関数（任意） — モジュールスコープに置く必要があり、他の関数内には置けません
3. 宣言（.script のみ：トップレベルの go.property()）
4. ライフサイクルコールバック

ライフサイクルコールバックの利用可否

コールバック	.script	.gui_script	.render_script
init(self)	✓	✓	✓
final(self)	✓	✓	—
fixed_update(self, dt)	✓	—	—
update(self, dt) / update(self)	✓（dt）	✓（dt）	✓（dt なし）
late_update(self, dt)	✓	—	—
on_message(self, message_id, message, sender)	✓	✓	✓（sender なし）
on_input(self, action_id, action)	✓	✓	—
on_reload(self)	✓	✓	—

主なルール

• インスタンスごとの状態はモジュールレベルのローカル変数ではなく、self に保存してください（モジュールレベルのローカル変数はすべてのインスタンスで共有されます）。
• 使用しないコールバックは省略してください。特に、空でもフレームごとに呼び出しコストが発生する update() と fixed_update() は省略してください。
• ローカルヘルパー関数はモジュールスコープに置き、他の関数の中には置かないでください。

ネイティブ拡張機能

ネイティブ拡張機能（C/C++/ObjC/Java）は、Lua C API（lua_register、luaL_openlib など）を使用して、Lua 関数をグローバルスコープに登録します。そのため、拡張機能は通常、新しいグローバルテーブル（例：myext）を追加し、すべての .script または .gui_script からアクセスできる関数や定数を格納します。

拡張機能は、エディターの自動補完用に *.script_api ファイル（YAML 形式）を使って API を記述します。このファイルは api/ ディレクトリに置きます。形式は次のとおりです。

- name: extension_name
  type: table
  desc: Extension description
  members:
  - name: function_name
    type: function
    desc: Function description
    parameters:
    - name: param_name
      type: string
      desc: Parameter description
    returns:
    - name: return_name
      type: number
      desc: Return value description

型：table、string、boolean、number、function。複数の型を指定する場合：[type1, type2]。

Lua の前処理

Defold は、Lua preprocessor extension を使った条件付きコンパイルをサポートしています（.lua モジュールを含むすべての Lua ファイルに適用されます）。

--#IF DEBUG
local lives = 999
--#ELSE
local lives = 3
--#ENDIF

キーワード：RELEASE、DEBUG、HEADLESS。

型固有のリファレンス

各スクリプトタイプ固有の制約、テンプレート、パターンについては、references/ ディレクトリを参照してください。

• references/script.md — go.property() のリファレンス（型、制約、オーバーライド）、テンプレート
• references/gui_script.md — GUI スクリプトの制約、テンプレートノードへのアクセス、テンプレート
• references/render_script.md — レンダーパイプラインのアーキテクチャ、システムメッセージ、完全な実用テンプレート
• references/editor_script.md — モジュール構造、コマンド、ライフサイクルフック、実行モード、テンプレート

ワークフロー

新しい Lua モジュール（.lua）の作成

1. 複数のスクリプトや画面でロジックを再利用する場合に使用します。
2. ローカルテーブルを作成し、関数を追加してから、それを返します。
3. 可能な限りモジュールの状態は持たせないでください。状態を持たせる場合は、その状態が共有されることを明記してください。
4. ドット記法で require します：require("main.utils")、require("screens.game.helpers")。

新しいスクリプトの作成

1. スクリプトタイプに適した拡張子を決定します。
2. 制約とテンプレートについて、references/ にある該当する型固有のリファレンスを読みます。
3. 構造パターンに従います：require → ヘルパー → 宣言 → コールバック。
4. 実際に必要なライフサイクルコールバックのみを追加します。

既存のスクリプトの編集

1. 現在のファイルを読みます。
2. 既存の宣言（例：go.property() の名前）とコールバックのシグネチャを保持します。
3. 必要に応じてコールバックを追加または変更します。
4. go.property() の名前や型を変更すると、.go ファイルや .collection ファイルのオーバーライドが壊れる可能性があります。