キャラクターコントローラライブラリ

キャラクターコントローラライブラリ（CCL）は、属性とLuauスクリプトを通じてキャラクターの動きや動作を構築するためのモジュラーフレームワークです。このアーキテクチャは、堅牢なHumanoid状態マシンを、キャラクターメカニクスのための柔軟で拡張可能なシステムに置き換えます。

CCLを有効にする

CCLは、Studioのアバター設定ウィンドウを通じてオプトインです。これを有効にするには：

1. ファイル ⟩ ベータ機能 ⟩ AvatarAbilities キャラクターコントローラーライブラリを通じてCCLベータを有効にします。

2. アバタータブから、アバター設定を開きます。

   

3. ウィンドウの左側にある移動タブを選択し、能力セクションでキャラクター コントローラー ライブラリを選択します。

   

4. 走る、ジャンプする、登るなどの標準的な能力はデフォルトで有効になっています。ランタイム中にそれらのいずれかを無効にするには、関連するボックスのチェックを外します。

   走るを無効にすることは推奨されません。なぜなら、そうするとキャラクターが地面を移動できなくなるからです。さらに、落ちるが有効になっている場合は、起き上がるを常に有効にしておくべきです。なぜなら、不一致があるとキャラクターが倒れる（つまずく）ことはあっても、決して起き上がれなくなるからです。

能力

能力は、キャラクターができること、たとえば走る、ジャンプする、登る、泳ぐといった能力を評価します。Enum.HumanoidStateTypeのようなエンジン定義の固定されたキャラクター状態に依存するのではなく、CCLの能力はキャラクターができることと、プレイヤーの入力にどのように反応すべきかを動的に決定します。

構造的には、能力は主に以下を指定する自己完結型のLuauテーブルです。

ラベル

ラベルは、能力間の調整バスとして機能する共有64ビットマスク内の名前付きビットです。基本的には：

• アクティブな能力は、そのLabelsとTimedLabelsを世界マスクにブロードキャストします。
• 能力の条件（StartsWhen, RunsWhile）は、世界マスクをテストして反応します。
• 能力の衝突は、アクティブ化時にどの他の能力がブロック、停止、または一時停止されるかを定義します。

次のセットアップでは、Runningがアクティブなときに"CanFallDown"ラベルが世界マスクにブロードキャストされます。FallingDown能力は、その条件がStartsWhen = All( "CanFallDown", "Stunned" )であるため、自動的に候補になりますが、FallingDownが発生する前に"Stunned"も世界マスクにブロードキャストされる必要があります。

local AvatarAbilities = require("@rbx/AvatarAbilities")

local Identifiers = AvatarAbilities.Identifiers
local Ability = Identifiers.Ability
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not

local Running: AvatarAbilities.AbilityDefinition = {
	Name = Ability.Running,
	Labels = { "CanFallDown" }, -- 能力がアクティブなときにブロードキャストされるラベル
	StartsWhen = Sensor.Ground,
	RunsWhile = Sensor.Ground,
}

local AvatarAbilities = require("@rbx/AvatarAbilities")

local Identifiers = AvatarAbilities.Identifiers
local Ability = Identifiers.Ability
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not

local FallingDown: AvatarAbilities.AbilityDefinition = {
	Name = Ability.FallingDown,
	StartsWhen = All( "CanFallDown", "Stunned" ), -- 能力を開始するために必要なラベル
	Blocks = { Ability.Running }
}

ラベルは、TimedLabels辞書を使用してタイムド方式でブロードキャストまたは消費することもできます。

local AvatarAbilities = require("@rbx/AvatarAbilities")

local Identifiers = AvatarAbilities.Identifiers
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not

local Dash: AvatarAbilities.AbilityDefinition = {
	Name = "Dash",
	StartsWhen = All( Sensor.Ground, Not("DashCooldown") ),
	RunsWhile = "Dashing",
	TimedLabels = {
		OnStart = { Dashing = 1 },
		OnStop = { DashCooldown = 2 },
	},
}

条件

条件は、StartsWhenおよびRunsWhileで使用される1つ以上のラベル、センサー、または入力参照です。条件は、実行時にビットマスク操作にコンパイルされ、評価は整数演算です — テーブルウォークや文字列比較はありません。

条件評価は、より複雑なロジックのために組み合わせることができ、たとえば、センサーがアクティブである必要があり、ラベルが存在しないことを示すためにAll()チェーンとNot()を使用できます：

local AvatarAbilities = require("@rbx/AvatarAbilities")

local Identifiers = AvatarAbilities.Identifiers
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not

local Dive: AvatarAbilities.AbilityDefinition = {
	Name = "Dive",
	StartsWhen = All( Sensor.WaterSurface, Not("Recovering") ),
}

衝突

一部の能力は、他の能力がアクティブなときにはアクティブにできません。たとえば、キャラクターは泳いでいるときにジャンプできず、落下中に走ることもできません。エンジンは、能力の定義内でこれらの衝突を宣言的に解決します。

もう1つのユニークな衝突キーはExclusiveGroupで、複数の能力をグループに配置し、それぞれにPriority値を持たせます。グループ内では1つの能力のみがアクティブになり、高い優先度のものが勝ちます。ただし、挑戦者が保持者の名前/ラベルをターゲットにしたStopsを宣言すると、優先度に関係なく勝ちます。

次のセットアップでは、3つの能力（Sprinting、Crouching、Stagger）がLocomotion排他的グループに追加されます。Sprintingは最高の優先度（200）を持っているため、Crouching（100）よりも勝ち、2つは同時に実行されることはありません。ただし、Staggerはスプリントを強制的に停止させるため（Stops = { Ability.Sprinting }）、その優先度（150）が低くてもSprintingを中断して上書きすることができます。

local AvatarAbilities = require("@rbx/AvatarAbilities")

local Identifiers = AvatarAbilities.Identifiers
local Ability = Identifiers.Ability
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not

local Sprinting: AvatarAbilities.AbilityDefinition = {
	Name = Ability.Sprinting,
	ExclusiveGroup = { Name = "Locomotion", Priority = 200 },
}
local Crouching: AvatarAbilities.AbilityDefinition = {
	Name = Ability.Crouching,
	ExclusiveGroup = { Name = "Locomotion", Priority = 100 },
}
-- 優先度の低い能力が優先度の高い能力を停止させることができます
local Stagger: AvatarAbilities.AbilityDefinition = {
	Name = "Stagger",
	ExclusiveGroup = { Name = "Locomotion", Priority = 150 },
	Stops = { Ability.Sprinting },
}

入力

能力のInput定義は、能力をアクティブ化しようとするために使用される入力を指定します。入力の動作、アクションスロット、およびオプションのタッチボタンアイコンを構成するキーと値のペアを取ります。

local AvatarAbilities = require("@rbx/AvatarAbilities")

local Identifiers = AvatarAbilities.Identifiers
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not

local Dash: AvatarAbilities.AbilityDefinition = {
	Name = "Dash",
	Input = { InputName = "Dash", Mode = "Press", ActionSlot = 5 }
}

• InputNameは論理名であり、キーではありません。CCLは入力センサーを生成し、常にStartsWhenにANDします。

• Modeは、この入力が能力をどのように開始および停止するかを定義します。RunsWhileは入力自体を含むことはなく、地面にいることや水中にいることなどの世界の条件のみを保持します。したがって、Modeは入力駆動の開始と停止の唯一のソースです：

  モード	開始	入力から停止
  Press	押したとき。	決して。能力は、衝突、自身のRunsWhile、またはStop()を呼び出すことで自ら終了します。
  Hold	押したとき。	放したとき。
  HoldとRepeats	押したとき。	放すと再発火が終了し、すでに飛行中のサイクルは終了しません。
  Toggle	トグルオンのとき。	トグルオフのとき。

  Pressはダッシュ、攻撃、投げなどの離散的なアクションに適しています。HoldとToggleはスプリント、狙い、ブロック、しゃがみ、浮遊などの持続的なアクションに適しています。HoldとRepeatsは、保持中に自己停止し再発火するアクション（たとえば、繰り返しジャンプ）に適しています。

• Repeats（ブール値、Holdのみ）は、能力が各サイクルで自己終了し、入力が保持されている間に再発火するようにします。全体の保持の間に継続的に実行されるのではありません。

• OutlivesInputWhile（Hold/Toggleのみ）は、能力がリリースまたはトグルオフを超えて実行され続ける条件です。特定の世界条件の下で入力を超えて能力が持続する必要がある場合に使用します。

• ActionSlotは、入力アクションシステム内のInputActionsおよびInputBindingsのリストに関連付けられたアクションスロットを定義します。

  Several action slot input bindings are predefined by Roblox and, in the future, the Input Action Manager will allow you to reconfigure default input bindings for action slots as desired. Setting ActionSlot to 0 will choose the next available empty slot. On mobile devices, slots 1-7 populate to buttons on the screen (see diagram below).

  スロット	キーボード & マウス	ゲームパッド	タッチ	デフォルト割り当て
  1	Space	ButtonA	①	ジャンプ
  2	LeftShift	ButtonL1	②	スプリント
  3	LeftControl	ButtonB	③	しゃがむ
  4	R	ButtonX	④
  5	MouseLeftButton	ButtonR2	⑤
  6	Q	ButtonY	⑥
  7	X	ButtonR1	⑦
  8	C	ButtonL2
  9	F	DPadLeft
  10	G	DPadRight
  11	V	DPadDown

  

• CustomIcon、CustomIconActive、およびCustomIconInvalidは、能力がアイドル状態、アクティブ状態、または利用できない状態のときのタッチボタンのRobloxアセットIDを指定します。

RunsWhileは世界の条件のみを保持します。コンパイラは、Modeに基づいて入力の効果を能力の実際の継続に組み込みます。したがって、入力自体をStartsWhenやRunsWhileに入れるとエラーが発生します（そこにRule.Inputを参照しないでください）。HoldとToggleの能力は、デフォルトでリリースまたはトグルオフで停止するため、RunsWhileにそれを重複させる必要はありません：

local AvatarAbilities = require("@rbx/AvatarAbilities")

local Rule = AvatarAbilities.Rule
local Sensor = AvatarAbilities.Identifiers.Sensor
local All, Any, Not = Rule.All, Rule.Any, Rule.Not

local Glide: AvatarAbilities.AbilityDefinition = {
	Name = "Glide",
	Input = { InputName = "Glide", Mode = "Hold", ActionSlot = 6 },
	StartsWhen = Not(Sensor.Ground),
	RunsWhile = Not(Sensor.Ground),
}

HoldまたはToggleの能力が特定の世界条件の下で入力を超えて持続するようにするには、RunsWhileに入力を追加するのではなく、OutlivesInputWhileを設定します。次のCrouching能力は、プレイヤーがしゃがみ入力を放した後も、何かが上に残っている限りしゃがみ続けます：

local AvatarAbilities = require("@rbx/AvatarAbilities")

local Identifiers = AvatarAbilities.Identifiers
local Sensor = Identifiers.Sensor

local Crouching: AvatarAbilities.AbilityDefinition = {
	Name = "Crouching",
	Input = { InputName = "Crouch", Mode = "Hold", OutlivesInputWhile = Sensor.Ceiling, ActionSlot = 3 },
	RunsWhile = Sensor.Ground,
}

センサー

センサーは、エンジンがあなたのために読み取る世界に関する名前付き値です。通常、センサーを読み取ることが多く、書き込むことは少ないです。便利なことに、いくつかのセンサーが事前に登録されています：

コールバック

能力のコールバック関数を使用すると、特定の動作をスクリプト化できます：

カスタム能力をサーバーで登録しますが、そのコールバックは予測されたクライアントシミュレーションと権限のあるサーバーシミュレーションの両方で実行されます。コールバックの動作は決定論的である必要があり、両方のシミュレーションが同じ結果を生成するようにします。

各コールバック関数の最初のパラメータmanagerCtxは、共有キャラクターおよびマネージャーのプロパティを持つManagerContextオブジェクトです：

• managerCtx.AbilityOwner — キャラクターのModelで、managerCtx.AbilityOwner.PrimaryPartがルートパートです。
• managerCtx.AbilityManager — 能力が自身のコールバック内で能力を追加、削除、クエリできるようにするためのマネージャーの簡略化されたビューです。
• managerCtx.BodyParts — キャラクターの体の部分で、各肢の衝突をオンまたはオフにするためのヘルパーがあります。
• managerCtx.ControllerManager — キャラクターのControllerManagerで、物理制御を行います。物理を必要とする登録された能力がない場合はnilになることがあります。
• managerCtx.RootCFrame — ルートパートのCFrameで、フレームの開始時に1回スナップショットされ、コールバックがそれぞれ自分で取得しないようにします。
• managerCtx.RootLookVector — キャラクターのルートパートが向いている方向。
• managerCtx.RootUpVectorY — ルートパートの上向きベクトルのY成分。
• managerCtx.TaskSynchronize() — 並列コールバックサポートが有効な場合、DataModelアクセスの前にコールバックを同期します。現在、OnUpdateは並列コンテキストで実行されないため、この関数は効果がありません。完全な並列Luauサポートは将来のアップデートで計画されています。

2番目のパラメータabilityCtxは、現在の能力登録のためのエンジン管理テーブルを持つAbilityContextオブジェクトです：

• abilityCtx.Config — この能力登録の読み取り専用構成値。
• abilityCtx.State — DataModelを通じて複製される可変状態。サーバー権限は、ロールバックおよび再シミュレーション中にこれらの値を復元します。
• abilityCtx.Local — 複製されず、ロールバックに参加しない可変のスクラッチ状態。

カスタムコールバックデータはabilityCtx.StateまたはabilityCtx.Localに保存します。abilityCtxに直接カスタムフィールドを書き込むことはエラーです。