クラウドバリアブル(Cloud Variables)
概要
クラウドバリアブルは、セッションをまたいで存続する変数です。 これらはダイナミックバリアブルと同様の性質で機能しますが、ペアレント化やワールド階層に依存する代わりに、パスとユーザー/グループの所有権に依存します。 お気に入りのゲームの設定ファイルや構成ファイルと同じように考えることができます。 クラウドバリアブルは、セッション、ワールド、さらにはNeos Dash間で同期されます。
クラウド変数は、次の2つの部分で構成されています。
- 定義 - 設定と構成; オーナー、名前、型、権限、デフォルト値。
- 値 - ユーザーごとの実際の値
クラウド変数の定義
クラウド変数の定義は、次の4つの部分で構成されています:
- パス/名前 例:
AwesomeGadget.Version
やPartyWorld.highQualityLights
- データ型
- 権限
- デフォルト値(デフォルト値は、To Stringノードの出力になります。例:、Colorで、文字列に変換すると以下のようになります。
[1; 1.23; 0; 1]
。)
定義は、ユーザーまたはグループに対して登録することもできます。 グループに対して定義を登録すると、次のようないくつかの利点があります。
デフォルト値
creating a definitionの際には、各コマンドの段階でデータや設定を与えます。コマンドを忘れたり、省略したりした場合のために、以下に定義の様々なプロパティのデフォルト値を示します。
- 読み/書きのパーミッションは標準で variable_owner になります。
- リスト・パーミッションは標準で definition_owner になります。
- デフォルト値が指定されていない場合、Neosはこのデータタイプのデフォルト値をC#で定義されたものとして返します。
クラウドバリアブルの値(Cloud Variable Values)
各クラウドバリアブルは複数の値を持つことができ、各値は個々のNeosユーザーかグループに関連付けられています。値にはその値が含まれているだけで、定義に関する詳細はありません。 これは、オーナIDと値の2つの列を持つ表のように考えることができます。
たとえば、クラウドバリアブル定義がstringのデータ型と"好きな果物"の名前で作成された場合、その値は次のようになります:
好きな果物 | |
---|---|
Variable Owner ID | 値 |
U-Frooxius | Strawberry |
U-Nexulan | Orange |
U-Shifty | Pineapple |
U-ProbablePrime | Blueberry |
G-MyGroup | Banana |
最後の行は、グループに固有の値を示しています。 これは、グループに属するクラウドバリアブルでのみ可能です。 スペースを含む可変所有者ID(ユーザーIDまたはグループID)は、ハイフンで記述する必要があります。
スペースを含む可変所有者ID(ユーザーIDまたはグループID)は、ハイフンで記述する必要があります。 例:グループ"My Group"は"G-My-Group"になります。 ユーザーIDとグループIDは、ユーザー/グループの表示名とは完全に異なる場合があることを常に確認してください。
クラウド変数の使用
クラウド変数を使用する前に、それを作成して登録する必要があります。 これは、さまざまなタイプのコマンドの送信をNeosボットに行うことで可能です。 これらのコマンドは、クラウドバリアブルの定義をNeosに登録します。 登録されたクラウド変数の値は、LogiXやコンポーネントを使用して、読み取り、書き込み、操作することができます。
使用上の注意/警告
- 変数定義は大量にキャッシュされ、通常、更新には数分かかります。 事前に完全に設定することをお勧めします。
- 読み取りと書き込みはバッファリングされ、バッチ処理され、キャッシュされ、伝播するのに少し時間がかかります。
- クラウド変数システムの現在の制限は、同じホスト/ユーザーで実行されない限り、異なるセッション間でリアルタイムに同期されないことです。 1つのヘッドレス(または自分のコンピューター)で複数のワールド/セッションをホストしている場合、クラウド変数への変更はそれらのセッション内でリアルタイムに同期されます。
- 異なるユーザーが同じワールドをホストしている場合、あるワールドでの変更が別のワールドにすぐに反映されることはなく、更新に数分かかります。 現在の計画では、SignalRをクラウドインフラストラクチャに統合することで、このような場合に完全なリアルタイム同期を追加します。これにより、アクティブセッションやメッセージングシステムなどの他のものに対してもクラウドのスケーリングが向上しますが、作業量は大きくなります。
- 現在の制限、権限、およびその他の側面は変更される可能性があります。
- データ型の変更は可能ですが、すでに保存されている値は影響を受けません。
制限
クラウドバリアブルはストレージを占有しませんが、制限があります。
Definition limits
タイプ | 制限数 |
---|---|
ユーザー | 256 |
グループ | 8192 |
これらの制限は、作成されたバリアブル定義にのみ適用され、その中に保存されている値には適用されません。 たとえば、「U-ProbablePrime.FavoriteColor」のバリアブル定義には、ユーザーのお気に入りの色ごとに無制限の数の値を含めることができます。
レート制限
クラウドバリアブルから読み取り/書き込みを行う場合、次の制限があります:
LogiX
LogiXでは、読み取りまたは書き込みはインパルスによってトリガーされるため、ノードがインパルスを受信するとすぐに読み取り/書き込み操作が発生します。
このため、読み取り/書き込みプロセスは1分間に最大30回実行できます。
コンポーネント
クラウドバリアブルコンポーネントはスケジュールに従って動作し、値を両方向に定期的に更新できます。これらの値は現時点ではそれほど高速ではありませんが、SignalRの使用がさらに強化されています。これらの値はより迅速に更新されます。現在:
- 読み取りは5分ごとに行われます
- 書き込みは遅延(バッファリング)され、30秒ごとに送信されます
- コンポーネントの値がより頻繁に変更される場合、書き込み時に最後に設定された値がクラウドに送信されます。
更新レート
上記のセクション制限をお読みください。
使用できるデータ型
クラウドバリアブルを作成するときは、それらの有効な型を指定する必要があります。 サポートされているデータ型を以下に示しますが、一般的にはすべてのプリミティブデータ型がサポートされています。 参照は1つの定義されたワールド/セッション内でのみ機能するため、参照データ型はサポートされていません。
- bool
- bool2
- bool3
- bool4
- string
- string:<max_length>
- データ型を設定するときに、文字列の最大長を指定できます。
- 形式は
string:<max_length>
です。 - デフォルトでは、文字列の長さは256文字です。最大長は8192です。
- ユーザーバリアブルとグループバリアブルの両方がこれらの制限の影響を受けます。
- float
- float2
- float3
- float4
- float2x2
- float3x3
- float4x4
- floatq
- doubleq
- color
- datetime
- timespan
- short
- ushort
- int
- int2
- int3
- int4
- uint
- uint2
- uint3
- uint4
- long
- long2
- long3
- long4
- ulong
- ulong2
- ulong3
- ulong4
- byte
- sbyte
- double
- double2
- double3
- double4
- double2x2
- double3x3
- double4x4
- decimal
列挙型(Enums)
列挙型も使用できるようになりました。正しく同期するには、クラウドバリアブルの定義を文字列(string)に設定する必要があります。 作成したら、LogiXやコンポーネントを使用して、データ型を使用する列挙型に設定できます。 たとえば、CloudValueField<ShadowType>
です。
より多くのデータ型が将来サポートされる予定です
権限(Permissions)
クラウド変数の権限は、次の2つの部分で構成されています。
- アクション許可 - 許可グループが実行できるアクションのタイプ。
- グループ/タイプ許可 - ユーザーのグループまたは分類。
権限セットを読んで決定するときは、 ほとんどの場合、各ユーザーがクラウドバリアブルに対して独自の値を持っていることを覚えておいてください。
次のコマンドの例として:/setUserVarPerms test.color read,write,list anyone
アクションは"読み取り、書き込み、リスト"で、権限のタイプ/グループは"anyone(誰でも)"です。
アクション権限
アクション権限 | 説明 |
---|---|
read
|
変数の値を読み取ることができるのは誰か |
write
|
変数の値に誰が書き込むことができるか |
list
|
変数の定義を誰が見ることができるか |
all
|
上記のすべての権限を一度に付与します |
複数の権限をコンマで区切って一度に複数の権限を指定することもできます。たとえば、/setUserVarPerms test.color read,write,list anyone
は、test.color
変数がvariable_owner
へに読み取り、書き込み、一覧表示の権限を付与します。
権限タイプ/グループ
一般的な定義のアクセス許可
これらの権限は、ユーザーとグループが所有する定義の両方で使用できます。
権限 | 説明 | 使用できる場所 | 制限 |
---|---|---|---|
anyone
|
誰でもこの変数を変数の読み取り/書き込みできます。これは、パブリックな変数を読むときにはお勧めですが、誰でも誰かの値を変更できるので、書き込みにはお勧めできません。 | どこでも | ユーザー所有の定義に対して「書き込み」権限として設定することはできません。 - ユーザー定義のlist権限では使用できません。 |
definition_owner_only
|
変数を定義したユーザー/グループのみが自分の変数の読み取り/書き込みできます。 アナウンス/バージョン管理システムに役立ちます。 | ユーザースペース/セーフコンテキストのみ | なし |
definition_owner_only_unsafe
|
変数を定義したユーザー/グループのみが自分の変数の読み取り/書き込みできます。 アナウンス/バージョン管理システムに役立ちます。 | どこでも | なし |
variable_owner
|
変数値を所有しているユーザーのみが、自分の 自分の値 を読み書きできます。 この場合、定義の所有者は他の人の値を読み書きできません。 | ユーザースペース/セーフコンテキストのみ | なし |
variable_owner_unsafe
|
変数値を所有するユーザーのみが、自分の 自分の値 を読み書きできます。 この場合、定義の所有者は他の人の値を読み書きできません。 | どこでも | なし |
ユーザー定義の権限
これらの権限設定は、ユーザーが定義した変数でのみ使用できます。
権限 | 説明 | 使用できる場所 | 制限 |
---|---|---|---|
definition_owner_only_contacts
|
ユーザースペース/安全なコンテキストのみ | なし | |
definition_owner_only_contacts_unsafe
|
どこでも | なし | |
variable_owner_only_contacts
|
ユーザースペース/安全なコンテキストのみ | なし | |
variable_owner_only_contacts_unsafe
|
どこでも | なし |
グループ定義の権限
これらの権限は、グループとして定義した変数(グループが所有する定義)でのみ使用できます。
権限 | 説明 | 使用できる場所 | 制限 |
---|---|---|---|
definition_owner
|
変数を定義したグループだけが、それを読み/書き表示できます | ユーザースペース/安全なコンテキストのみ | なし |
definition_owner_unsafe
|
変数を定義したグループだけが、それを読み/書き表示できます | どこでも | なし |
リストのアクセス許可
「リスト」権限は異なり、有効な権限が非常に限られているため、リストに許可されている権限を一覧表示する方が簡単です。
- anyone
- definition_owner
- definition_owner_unsafe
安全な状態
Neos内のほとんどの場合、誰でもあなたがしていることを観察したり操作したりすることができます。 これらは 安全でない(unsafe)状態です。 Neos Dashが配置されているユーザースペースなどの場所では、誰もあなたが行っていることを確認したり変更したりすることはできません。これは安全な状況です。
クラウドバリアブルのコマンド一覧
クラウド変数を作成、更新、変更するには、コマンドを使用する必要があります。 これらのコマンドは、Neos内の「Neosボット」に送信できます。ダッシュメニューのブレンドセクションで見つけることができます。
それぞれのコマンドで、引数の周りに()
が表示されている場合はオプションです。 それ以外の場合は 必須です。
定義の作成
ユーザー定義
/createUserVar <path>
- 指定されたパスで変数定義を作成します/setUserVarType <path> <type>
- バリアブル定義のデータ型を設定します/setUserVarDefaultValue <path> <value>
- 定義のデフォルト値を設定します/setUserVarPerms <path> <action permission> <permission type>
- 権限を設定します/setUserVarValue (<user>) <path> (<target user>) <value>
- 定義の個々のユーザーの値を設定します/setUserVarPerms <path> <action permission> <permission type>
- 定義の権限を設定します。
一度に定義を作成できるコマンドもあります:/createUserVar <path> <type> <default value> <read perms> <write perms> <list perms>
グループ定義
/createGroupVar <group> <path>
- 指定されたパスでバリアブル定義を作成します/setGroupVarType <group> <path> <type>
- バリアブル定義のデータ型を設定します/setGroupVarDefaultValue <group> <path> <value>
- 定義のデフォルト値を設定します/setGroupVarPerms <group> <path> <action permission> <permission type>
- 権限を設定します
一度に定義を作成できるコマンドもあります: /createGroupVar <group> <path> <type> <default value> <read perms> <write perms> <list perms>
オススメポイント
一般的に、定義全体を一度に作成するコマンドを使用することをお勧めします。これにより、変数が使用できなくなる原因となる手順や部分を忘れることがなくなります。
値を読む
LogiX / Componentsを使用した値の読み取りについては、この後のセクションを参照してください。
ユーザーで定義した変数
/getUserVar <path>
- 変数の定義を取得します(データ型、権限、デフォルト値)/getUserVarValue <definition_owner> <path> <target user>
- 定義に対するユーザーの値を取得します。 例:/getUserVarValue U-ProbablePrime testing.bool U-ProbablePrime
は、変数testing.boolのPrimeの値を取得します。/listUserVars (<user>)
- ユーザーの変数定義を一覧表示します(標準:yours)。list
権限が必要です。
グループで定義した変数
/getGroupVar <group> <path>
- 変数の定義を取得します(データ型、権限、デフォルト値)/getGroupVarValue <group> <path> (<target user>)
- 定義のユーザー(標準: yours)の値を取得します/listGroupVars <group>
- グループの変数定義を一覧表示します。list
権限が必要です。
値の書き込み
値を設定・書き込みする際には、権限が正しく設定されていることを確認してください。
LogiX / コンポーネントを使用した値の書き込みについては、このセクションの後の方を参照してください。
ユーザーで定義した変数への値の書き込み
/setUserVarValue (<user>) <path> (<target user>) <value>
- 定義に対して個々のユーザーの値を設定します。
次に例を示します。/setUserVarValue U-ProbablePrime testing.bool U-Frooxius true
は、ProbablePrimeの定義のFrooxiusの値に対してtesting.bool
の値をtrueに設定します。
グループで定義した変数への値の書き込み
/setGroupVarValue <group> <path> (<target user>) <value>
- 定義に対して、個々のユーザーの値を設定します。
次に例を示します。/setUserVarValue G-Cheese testing.bool U-Frooxius true
は、グループチーズの定義のFrooxiusの値に対してtesting.bool
の値をtrueに設定します。
複素数値の設定
複雑な値の場合、このコマンドに何を入力するかを理解するのに苦労する可能性があります。 これが役立つかもしれないいくつかの例です:
- 複雑な文字列の場合は、値を引用符(")で囲みます。例:"My Cool Value"
- float3の場合は、
[1; 0; 1]
- 色については、
[1; 0; 0; 1]
定義の削除
次のコマンドを使用して定義を削除できます。
- ユーザー変数の場合は
/deleteUserVar <path>
- グループ変数の場合は
/deleteGroupVar <group> <path>
このコマンドは、定義と、その定義にリンクされている すべての値の両方を削除します。 また、定義と値の値、キャッシュ、およびその他のシステムをクリアする必要があるため、このコマンドが完全に実行されるまでにはしばらく(約30分)かかります。
コマンドの例
ブール型のユーザ変数を作成
boolean
型のUser
数を作成します。この変数は、誰でも読み取り、所有者(各ユーザーが自分のコピーを作成)がユーザースペースとワールドスペースから書き込むことができます。
/createUserVar testing.enabled
/setUserVarType testing.enabled bool
/setUserVarPerms testing.enabled read anyone
/setUserVarPerms testing.enabled write variable_owner_unsafe
カラー型のユーザ変数を作成
所有者のみがユーザースペースから書き込み、どこからでも読み取ることができるcolor
型のUser
変数を作成します。
/createUserVar testing.myColor
/setUserVarType testing.myColor color
/setUserVarPerms testing.myColor read variable_owner_unsafe
/setUserVarPerms testing.myColor write variable_owner
ブール型のグループ変数を作成
boolean
型のGroup
変数を作成します。これは、所有者だけがどこからでも読み取り、書き込み、リスト表示できます。
/createGroupVar MyGroup testing.enabled
/setGroupVarType MyGroup testing.enabled bool
/setGroupVarPerms MyGroup testing.enabled read,write,list variable_owner_unsafe
クラウド変数の操作
コンポーネント
ActiveUserCloudField`1 (Component) - CloudValueFieldと同様ですが、OwnerIdをローカルユーザーで上書きします。
ActiveUserCloudValueVariable`1 (Component) - CloudValueVariableと同様ですが、OwnerIdをローカルユーザーで上書きします。
CloudValueField`1 (Component) - ターゲットフィールドを使用して値を格納しますが、それ以外はCloudValueVariableと同様です。
CloudValueVariable`1 (Component) - クラウド変数を表し、OwnerIdを手動で設定できます。
CloudValueVariableDriver`1 (Component) - 指定されたクラウド変数の値でターゲットフィールドをドライブします。 OwnerIdをローカルユーザーで上書きします。
LogiXノード
Write Cloud Variable`1 (LogiX node) - インパルス時に、指定された所有者に対して指定されたクラウド変数を書き込みます。
Read Cloud Variable`1 (LogiX node) - インパルス時に、指定された所有者の指定されたクラウド変数を読み取ります。
ヘッドレスサーバーの操作と自動起動ワールドオプション
クラウドバリアブルは、ヘッドレスセッションの設定ファイルやワールドの自動起動設定ファイルで使用できます。
- セッションのユーザー権限を構成します。
- ユーザーがセッションに参加できるか出来ないかを設定できます。
- ユーザーがセッションへのアクセスを拒否される理由について、カスタム拒否メッセージを提供します。
これらのオプションは Neos内のUIでは使用できません。ゲーム外から(変数の定義や設定ファイルの作成など、高度な)セットアップを行う必要があります。
権限要件があるため、これらの設定には グループバリアブルを使用することをお勧めします。 適切に構成されたユーザーバリアブルを使用して回避できる可能性がありますが、グループバリアブルを使用すると、ほとんどの制御が可能になります。
これらを設定するには、以下で説明するパラメーターをJSONファイルに追加する必要があります。
権限
クラウド変数を使用して権限を設定するには、ヘッドレスconfigにroleCloudVariable
パラメーターを追加します。 その値は、使用するクラウドバリアブルのフルパスである必要があります。ヘッドレスサーバーでそのセッションは、クラウドバリアブルを使用して、ユーザーが持つ権限を決定します。
これを行うときは、いくつかの点に注意する必要があります。
- 変数のデータ型はstringである必要があります。
- この変数には
definition_owner
権限グループを使用することを強くお勧めします。 他の権限グループでは、ユーザーが自分の役割を上書きできる場合があります。 - 変数とユーザーに値が設定されていない場合、権限を決定するための他の方法が使用されます。
設定の例:
G-Cheese.awesomeHeadless.userRoles | |
---|---|
Variable Owner ID | 値 |
U-Frooxius | Admin |
U-Nexulan | Builder |
U-Shifty | Guest |
U-ProbablePrime | Spectator |
U-Vegasx | Spectator |
追加する必要のある対応するJSONプロパティは次のとおりです。:
"roleCloudVariable": "G-Cheese.awesomeHeadless.userRoles"
アクセス(参加できる人)
ヘッドレスセッションへのアクセスを制御できるいくつかの変数と設定があります。
ユーザーのアクセスを許可する
ヘッドレスセッションへのアクセスを構成するには、クラウドバリアブルを使用して、allowUserCloudVariable
パラメーターをワールドスタートアップ/ヘッドレスセッションconfigに追加します。 その値は、使用するクラウド変数のフルパスである必要があります。セッションはクラウド変数を使用してセッションへのアクセス設定を提供します。
このオプションは、最大ユーザー数や可視性などの通常のセッション設定を含め、他のすべての設定よりも優先されます。
これを行うときは、いくつかの点に注意する必要があります。
- 変数のデータ型はboolである必要があります。
- trueに設定されている場合、ユーザーはセッションに参加できます。
- falseに設定されている場合、または値が存在しない場合は、アクセスを決定するための他の方法が使用されます。
- その値がtrueの場合、サーバーはユーザーへのアクセスを許可します。
- これは、ユーザーに招待(インバイト)を送信するのと同じです。
- ユーザーは、MaxUsers設定に関係なく参加できます。
- セッションがプライベートであっても、ユーザーは参加できます。 ただし、セッションへのリンクが必要になります。
セットアップの例は次の通りです:
G-Cheese.awesomeHeadless.userAccess | |
---|---|
Variable Owner ID | 値 |
U-Frooxius | true |
U-Nexulan | true |
U-BadGuy | false |
追加する必要のある対応するJSONプロパティは次のとおりです:
"allowUserCloudVariable": "G-Cheese.awesomeHeadless.accessControl"
ユーザーのアクセスを拒否する
allowUserCloudVariable
と同様に、denyUserCloudVariable
を使用して、ワールドスタートアップ/ヘッドレスセッションconfigでのユーザーアクセスを拒否できます。アクセスを拒否するには、代わりにdenyUserCloudVariable
を使用してください。ユーザーの値がtrue
の場合、ユーザーはアクセスを拒否されます。
trueの場合、このオプションは最大ユーザー数や可視性などの通常のセッション設定を含め、他のすべての設定よりも優先されます。
セットアップの例は次の通りです:
G-Cheese.awesomeHeadless.userAccess | ||
---|---|---|
バリアブルオーナーID | 値 | 説明 |
U-Frooxius | false | アクセス許可 |
U-Nexulan | false | アクセス許可 |
U-BadGuy | true | アクセス拒否 |
追加する必要のある対応するJSONプロパティは次のとおりです:
"denyUserCloudVariable": "G-Cheese.awesomeHeadless.userAccess"
参加のコントロール
上記のオプションに加えて、requiredUserJoinCloudVariable
を使用するオプションもあります。このオプションがワールドスタートアップ/ヘッドレスセッションconfigに追加されると、ワールドに参加するときにユーザーに対するその値がチェックされます。 trueの場合、ユーザーは参加できます。falseの場合、参加は許可されません。
このオプションは、他のセッション設定よりも優先されないことに注意してください。 この値がtrueに設定されていても、セッションがいっぱい(最大ユーザー数に達している)の場合、ユーザーは参加できません。
セットアップの例は次の通りです:
G-Cheese.awesomeHeadless.userAccess | |
---|---|
バリアブルオーナーID | 値 |
U-Frooxius | true |
U-Nexulan | true |
U-BadGuy | false |
追加する必要のある対応するJSONプロパティは次のとおりです:
"requiredUserJoinCloudVariable": "G-Cheese.awesomeHeadless.userAccess"
拒否メッセージ
'requiredUserJoinCloudVariable
を使用する場合、requiredUserJoinCloudVariableDenyMessage
を使って各ユーザーへの拒否メッセージを指定することも可能です。:
G-Cheese.awesomeHeadless.denyMessages | |
---|---|
バリアブルオーナーID | 値 |
U-Frooxius | 少し休んで |
U-BadGuy | 悪いことしたのであなたはバンされました |
これにより、requiredUserJoinCloudVariable
で定義された変数に、値がないまたはfalseであるために参加を制限されているユーザーに送信される単一のメッセージを指定することができます。
requiredUserJoinCloudVariableDenyMessage
が機能するには、requiredUserJoinCloudVariable
を使用する必要があります。これらは相互にリンクされています。 requiredUserJoinCloudVariableDenyMessage
を他のクラウド変数関連のアクセス制御と組み合わせることはできません。
これらオプションは最初は混乱するかもしれませんが、可視性や最大ユーザー数などの定期的なチェックをバイパスせずに、セッションアクセスを制御するのに役立ちます。登録制のイベントなどによく使われますね。
追加資料
詳細については、次のソースを確認してください:
- Neos Weekly update - このアップデートでは、機能が導入され、使用例と多くの追加情報が提供されました。
- クラウド変数の初期リリース
- クラウド変数の改善の最初のバッチ
- クラウド変数の改善の2番目のバッチ
- オーナー定義とユーザー定義に関する情報
標準のクラウドバリアブル
Neosには、内部で使用される、またはユーザーへ自動的に設定されるクラウドバリアブルがいくつかあります。以下の通りです。:
バリアブル | 説明 |
---|---|
G-Neos.CustomUserColor
|
標準のヘッドセットアバターの色を保存します。 |
G-Neos.common_avatar.current
|
ユーザーのお気に入りアバターを保存します。 |
G-Neos.cloud_home.current
|
ユーザーのお気に入りホームワールドを保存します。 |
G-Neos.virtual_keyboard.current
|
ユーザーのお気に入りキーボードを保存します。 |
G-Neos.interactive_camera.current
|
ユーザーのお気に入りカメラを保存します。 |
This article or section is a Stub. You can help the Neos Wiki by expanding it.