AddEventHandlerとは
1. はじめに
AddEventHandler関数は、システム内や他のスクリプトで「特定の出来事(イベント)」が発生した際に、あらかじめ決めておいた処理を実行するための 「待ち受け役(イベントリスナー)」 を登録する役割を持つ。
FiveMはイベント駆動で動作し、「プレイヤーが死んだとき」「リソースが開始されたとき」といったタイミングをこの関数でキャッチして処理を動かす。
2. 基本構文とパラメータ
AddEventHandlerの基本的な書き方は以下の通り
AddEventHandler('イベント名', function(引数1, 引数2, ...)
-- イベントが発生した時に実行したい処理
end)
例
例えば、my_script:helloというイベントが発生した時、挨拶をする場合
AddEventHandler('my_script:hello', function(name)
print('こんにちは,' .. name .. 'さん!')
end)
3. 同一リソース内での利用例
AddEventHandlerで待ち受けている処理を動かすには、TriggerEventという関数を使いイベントを「発行(トリガー)」する必要がある。
同じスクリプトファイル、あるいは同じリソースフォルダ内にあるファイル間で処理を呼び出す際の基本的な流れは以下の通りです。
実装例
以下のコードでは、コマンドを入力したときに独自のイベントを発生させ、それを AddEventHandler でキャッチしています。
-- 1. イベントが発生した時の処理を登録しておく
AddEventHandler('my_script:greet', function(message)
print('受け取ったメッセージ: ' .. message)
end)
-- 2. コマンドなどでイベントを発生させる
RegisterCommand('testevent', function()
-- ここでイベントを呼び出す
TriggerEvent('my_script:greet', 'Hello FiveM!')
end)
4. FiveM組み込みイベントの受信
AddEventHandler は、自分で名前を決めたイベントだけでなく、FiveMシステム側があらかじめ用意している「組み込みイベント（システムイベント）」を受け取るためにも使用されます。
これらは特定の操作（リソースの開始、停止、プレイヤーの参加など）が行われた際に、システムによって自動的に発行されます。
代表的な組み込みイベントの例
1. リソースが開始されたとき (onResourceStart)
スクリプトが読み込まれた直後に初期化処理を行いたい場合に便利です。
AddEventHandler('onResourceStart', function(resourceName)
if GetCurrentResourceName() == resourceName then
print('リソース ' .. resourceName .. ' が正常に起動しました。')
end
end)
2. プレイヤーがサーバーに参加したとき (playerConnecting)
AddEventHandler('playerConnecting', function(playerName, setKickReason, deferrals)
print(playerName .. ' さんが接続を試みています。')
end)
システムイベントの特徴
自分で Trigger する必要がない: 条件を満たせばシステムが勝手に実行してくれます。
引数が決まっている: 各イベントごとに渡されるデータ（引数）が決まっているため、公式ドキュメント（Cfx.re Docs）で確認しながら利用します。
5. 重要な注意点：ネットワークの壁
AddEventHandler を使う上で、最も注意すべきなのは 「スコープ（有効範囲）」 です。
これだけでは「通信」はできない
AddEventHandler 単体では、同じ側（クライアントならクライアント、サーバーならサーバー）の中だけでしかイベントを受け取ることができません。
-
クライアント側で
AddEventHandlerしたものは、別のプレイヤーやサーバーからのTriggerServerEventなどでは反応しません。 - ネットワーク越し（クライアント ⇔ サーバー間）にイベントを飛ばしたい場合は、必ず
RegisterNetEventを併用して「このイベントはネットワーク越しに受け取ってもいいよ」と許可を出す必要があります。
あくまで AddEventHandler は「イベントが起きた時の処理内容を定義するもの」
6. まとめ
- AddEventHandler は、イベントが発生した際の「予約」をする関数。
- 自分で作ったイベント（TriggerEvent）も、システムが作ったイベント（onResourceStartなど）も受け取れる。
- 同じリソース内や同じサイド（サーバー/クライアント内）での処理の受け渡しに使う。
- ネットワークを跨ぐ場合は、別の設定（RegisterNetEvent）が必要。