~~NOTOC~~
====== ExportMessage(メッセージ通信) ======
<WRAP center round important 80%>

このページは過去の情報となります。\\
新しいスクリプトリファレンスは**[[https://developer.virtualcast.jp/vci-docs/api/|こちら]]**になります。
</WRAP>
メッセージと呼ばれるデータを指定の名前に紐づけて、ローカルの他のVCIや、他のクライアントのVCIとも通信することができます。

想定用途は2種類あります。\\
ひとつは [[#EmitWithId]] で **自分自身のVCIのネットワーク同期のため** です。\\
もうひとつは [[#Emit]] で **空間内の異なるVCIへのイベントの発出のため** です。\\

具体的な活用例としては以下が挙げられます。\\
 [[#EmitWithId]] を使えば色の変化などのVCIの状態変化をネットワーク同期できます。\\
[[#Emit]] を使えばリモコンなど他のVCIを操作したり、文字表示VCIに表示する文字を伝えることができます。

制限としては、送信出来るデータ量は約 ''4000 byte'' です。

またネットワーク同期を行う機能として他に[[vci/script/reference/syncvariable|同期変数]]があります。

^ 名前 ^ 説明 ^ バージョン ^
| [[vci/script/reference/message#Emit]] | メッセージを全体に送信| |
| [[vci/script/reference/message#EmitWithId]] | IDを指定してメッセージを送信 | 2.0.0b以降 |
| [[vci/script/reference/message#On]] | メッセージを受信 | |

===== Emit =====
**Emit fun(messageName: string, value: usertype)**

  * 空間(スタジオ・ルーム)にあるすべてのVCIに対してメッセージを送信します。
  * ローカルのみならず、他のクライアントにもメッセージを送信します。
  * 異なるVCIに対する通信など、空間全体にメッセージを発する必要がある時に使用します。\\ **用途に合致しない限り使用を避けてください**。
  * 受信側は誰からのメッセージなのか区別することができないため、**他のVCIを誤動作させる**可能性があります。**メッセージ名にありふれた名前を使わないでください**。
  * 空間全体にメッセージを発するため、ネットワーク負荷が非常に重いです。\\ updateイベントなど**高頻度で呼ばないでください**。

<file lua sample.lua>
function onUse(objectName)
    vci.message.Emit("my_special_vci_protocol_display_text", "こんにちは")
end
</file>
===== EmitWithId =====
**EmitWithId fun(messageName: string, value: usertype, targetId: string)**

  * 特定のVCIに対してメッセージを送信します。
  * ローカルのみならず、他のクライアントにもメッセージを送信します。
  * 同じVCIを複数出したときも、自分自身のVCIにのみメッセージを届けることができます。


<file lua sample.lua>
function onUse(objectName)
    -- 自分自身のVCIに対してメッセージを送信
    vci.message.EmitWithId("color", 3, vci.assets.GetInstanceId())
end
</file>
===== On =====
**On fun(messageName: string, callback: usertype)**
  * メッセージを受信します。
  * メッセージを送信したのと同じVCIでも、別のVCIでもOK。
  * Onの第1引数と Emitの第1引数 が一致したものを受け取ります。
  * 受け取ったメッセージを第2引数の関数に渡します。
  *  **Onは第2引数で指定した関数よりも後に定義してください。受信関数よりも前に定義するとエラーとなります。**

=== 引数 ===

以下、3つの引数をとります。senderはシステムによって設定される送信者情報のtableです。

^ 引数                 ^ 内容                                      ^
| sender.type          | ''vci'' という文字列。                    |
| sender.name          | 送信元のVCIのTitle。                      |
| sender.commentSource | 空文字列。                                | 
| name                 | メッセージの名前。Emit 関数の第1引数です。|
| message              | メッセージの内容。Emit 関数の第2引数です。|

==== サンプル ====

**送信側**
<file lua send.lua>
function onUse(self)
    -- 第１引数にメッセージの種類 第２引数にメッセージの内容
    -- 今回は受信側のSubItemをジャンプさせるメッセージとその強さを指定
    vci.message.Emit("message_jump",3000)
end
</file>

**受信側**
<file lua get.lua>
local receiver = vci.assets.GetTransform("Cube")
 
    -- sender: 送信者情報(システムが設定します)
    -- name: メッセージの名前。Emit 関数の第1引数です。
    -- message: メッセージの内容。Emit 関数の第２引数です。
function Jump(sender, name, message)
 
    for k, v in pairs(sender) do
        print(k .. ":" .. v)
    end
 
    -- nameにメッセージの種類　messageにメッセージの内容が入ってます    
    print(name)
    print(message)

    --messageに入っているジャンプの強さでSubItemを飛ばします
    receiver.AddForce(message*receiver.GetUp())
    
end

--シーンでメッセージ名が"message_jump"のvci.message.Emitが実行されたときにJump関数が呼び出される
vci.message.On("message_jump", Jump)
</file>

** EmitWithIdで特定のVCIに対して送信する **
<file lua get.lua>
function GetMessage(sender, name, message)
    print(message.abc)
end

vci.message.On("123", GetMessage)
function update()
    -- vci.assets.GetInstanceIdを指定して自分自身にだけ送信する
    vci.message.EmitWithId("123", { abc = "ハロー" }, vci.assets.GetInstanceId())
end 
</file>

**送信側がやっている事**\\
基本的に送りたいメッセージをEmit()を実行して送るだけです。\\
ただし、受信側とどのようなメッセージをやり取りするかは事前に決めておく必要があります。\\
\\
**受信側がやっている事**\\
1.vci.message.On() で受信したいメッセージの種類を登録します。\\
　Emit()でメッセージが送信された時にOn()で登録されたメッセージを読み込むことができます。\\
2.この例では、送られてきたメッセージはJump()に渡されます。\\
　メッセージの内容がJump()の引数として与えられます。\\
3.Jump()の引数の内容がメッセージの内容なので、\\
　送信するメッセージの内容を変化させることで、受信側の挙動を変えることができます。

===== 解説 =====

  * [[vci/script/reference/messagecomment]]
  * [[vci/script/reference/messagenotification]]

===== サンプル =====

  * [[vci:sample:message:no2|複数のVCI間で変数をやり取りする]]