Thư viện Điều khiển Nhân vật

Thư viện Điều khiển Nhân vật (CCL) là một khung mô-đun để xây dựng chuyển động và hành vi của nhân vật thông qua các thuộc tính và kịch bản Luau. Kiến trúc này thay thế các máy trạng thái cứng nhắc Humanoid bằng một hệ thống linh hoạt, có thể mở rộng cho các cơ chế của nhân vật.

Khả năng

Khả năng đánh giá những gì một nhân vật có thể làm, chẳng hạn như khả năng chạy, nhảy, leo trèo và bơi lội. Thay vì dựa vào một tập hợp cố định các trạng thái nhân vật được định nghĩa bởi engine như trong Enum.HumanoidStateType, các khả năng CCL xác định động một cách linh hoạt những gì một nhân vật có thể làm và cách nó nên phản ứng với đầu vào của người chơi.

Cấu trúc, một khả năng là một bảng Luau tự chứa chủ yếu xác định các thông tin sau:

Nhãn

Một nhãn là một bit được đặt tên trong một mặt nạ 64-bit chia sẻ, hoạt động như một bus phối hợp giữa các khả năng. Về cơ bản:

• Một khả năng đang hoạt động phát sóng các Labels và TimedLabels của nó đến mặt nạ thế giới.
• Các điều kiện khả năng (StartsWhen, RunsWhile) kiểm tra mặt nạ thế giới và phản ứng.
• Các xung đột khả năng xác định các khả năng khác nào bị chặn, dừng lại hoặc tạm dừng khi kích hoạt.

Trong thiết lập sau, nhãn "CanFallDown" được phát sóng đến mặt nạ thế giới khi Running đang hoạt động. Khả năng FallingDown với điều kiện StartsWhen = All( "CanFallDown", "Stunned" ) tự động trở thành một ứng cử viên, nhưng "Stunned" cũng phải được phát sóng đến mặt nạ thế giới trước khi FallingDown xảy ra.

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

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

local Running: AvatarAbilities.AbilityDefinition = {
	Name = Ability.Running,
	Labels = { "CanFallDown" }, -- Nhãn phát sóng khi khả năng đang hoạt động
	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, Not = Rule.All, Rule.Not

local FallingDown: AvatarAbilities.AbilityDefinition = {
	Name = Ability.FallingDown,
	StartsWhen = All( "CanFallDown", "Stunned" ), -- Nhãn cần thiết để khả năng bắt đầu
	Blocks = { Ability.Running }
}

Các nhãn cũng có thể được phát sóng hoặc tiêu thụ theo cách có thời gian bằng cách sử dụng từ điển TimedLabels.

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

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

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

Điều kiện

Một điều kiện là một hoặc nhiều nhãn, cảm biến, hoặc một tham chiếu đầu vào, được sử dụng bởi StartsWhen và RunsWhile. Các điều kiện biên dịch thành các phép toán bitmask tại thời gian chạy và đánh giá là toán học số nguyên — không có việc đi bộ bảng và không có so sánh chuỗi.

Đánh giá điều kiện có thể được kết hợp để có logic phức tạp hơn, chẳng hạn như chuỗi All() cộng với Not() để chỉ ra rằng một cảm biến phải hoạt động trong khi một nhãn phải không tồn tại:

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

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

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

Xung đột

Một số khả năng không thể hoạt động khi một khả năng khác đang hoạt động; ví dụ, nhân vật không thể nhảy khi đang bơi, và họ không thể chạy khi đang ngã. Engine giải quyết những xung đột này một cách tuyên bố bên trong định nghĩa của một khả năng:

Một khóa xung đột độc đáo khác là ExclusiveGroup mà đặt nhiều khả năng vào một nhóm, mỗi khả năng có một giá trị Priority. Chỉ một khả năng mỗi nhóm có thể hoạt động và ưu tiên cao hơn sẽ thắng. Tuy nhiên, nếu một đối thủ tuyên bố Stops nhắm vào tên/nhãn của người giữ, nó sẽ thắng bất kể ưu tiên.

Trong thiết lập sau, ba khả năng (Sprinting, Crouching, Stagger) được thêm vào một nhóm độc quyền Locomotion. Sprinting có ưu tiên cao nhất (200) nên nó thắng Crouching (100) và hai khả năng này không bao giờ hoạt động cùng lúc. Tuy nhiên, Stagger buộc dừng chạy (Stops = { Ability.Sprinting }), vì vậy nó có thể ngắt quãng và vượt qua Sprinting mặc dù ưu tiên của nó (150) thấp hơn.

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

local Identifiers = AvatarAbilities.Identifiers
local Ability = Identifiers.Ability
local Rule = AvatarAbilities.Rule
local Sensor = Identifiers.Sensor
local All, Not = Rule.All, 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 },
}
-- Một khả năng có ưu tiên thấp hơn có thể ghi đè một khả năng có ưu tiên cao hơn bằng cách dừng nó
local Stagger: AvatarAbilities.AbilityDefinition = {
	Name = "Stagger",
	ExclusiveGroup = { Name = "Locomotion", Priority = 150 },
	Stops = { Ability.Sprinting },
}

Đầu vào

Định nghĩa Input của một khả năng xác định đầu vào được sử dụng để cố gắng kích hoạt khả năng. Nó nhận các cặp khóa-giá trị cấu hình hành vi đầu vào, khe hành động và các biểu tượng nút chạm tùy chọn.

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

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

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

• InputName là một tên logic, không phải một khóa. CCL tạo ra một cảm biến đầu vào và luôn thêm nó vào StartsWhen. Đừng thêm Rule.Input vào StartsWhen tự mình.

• Mode xác định cách mà đầu vào này sẽ được diễn giải:

  Chế độ	Hành vi	Trường hợp sử dụng
  Press	Kích hoạt khả năng được cố gắng khi đầu vào được nhấn. Tự động tiêm vào điều kiện StartsWhen.	Các hành động rời rạc như dash, tấn công và ném.
  Hold	Khả năng chạy trong khi đầu vào được giữ; thả ra dừng nó khi cảm biến đầu vào được tạo là điều kiện RunsWhile.	Các hành động kéo dài như chạy, nhắm và chặn.
  Toggle	Mỗi lần nhấn sẽ chuyển đổi khả năng bật hoặc tắt khi cảm biến đầu vào được tạo là điều kiện RunsWhile.	Các tư thế hoặc chuyển động có thể bật/tắt như cúi hoặc lơ lửng.
  Repeat	Giống như Hold, nhưng kích hoạt lại mỗi chu kỳ.	Các hành động tự dừng và có thể kích hoạt lại trong khi giữ.

• ActionSlot xác định một khe hành động liên kết với một danh sách InputActions và InputBindings trong Hệ thống Hành động Đầu vào.

  Một số liên kết đầu vào khe hành động được định nghĩa trước bởi Roblox và, trong tương lai, Trình quản lý hành động đầu vào sẽ cho phép bạn cấu hình lại các liên kết đầu vào mặc định cho các khe hành động theo ý muốn. Đặt ActionSlot thành 0 sẽ chọn khe trống tiếp theo có sẵn. Trên các thiết bị di động, các khe 1-7 sẽ được điền vào các nút trên màn hình (xem sơ đồ bên dưới).

  Khe	Bàn phím & Chuột	Gamepad	Cảm ứng	Gán mặc định
  1	Space	ButtonA	①	Nhảy
  2	LeftShift	ButtonL1	②	Chạy nhanh
  3	LeftControl	ButtonB	③	Ngồi xổm
  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, và CustomIconInvalid xác định các ID tài sản Roblox cho nút chạm khi khả năng đang ở trạng thái nhàn rỗi, hoạt động hoặc không khả dụng, tương ứng.

Khi bạn bỏ qua RunsWhile, CCL sử dụng cảm biến đầu vào được tạo làm điều kiện tiếp tục. Khi bạn định nghĩa RunsWhile, nó thay thế điều kiện mặc định đó. Đối với một khả năng Hold hoặc Toggle phải dừng khi đầu vào của nó trở nên không hoạt động, hãy bao gồm tín hiệu Rule.Input trực tiếp trong điều kiện tùy chỉnh. Rule.Input là một giá trị, không phải một hàm:

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

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

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

Cảm biến

Một cảm biến là một giá trị được đặt tên về thế giới mà engine đọc cho bạn. Bạn thường sẽ đọc các cảm biến thay vì viết chúng. Để tiện lợi, một số cảm biến đã được đăng ký trước:

Callback

Các hàm callback khả năng cho phép bạn lập trình hành vi cụ thể:

Mặc dù bạn đăng ký các khả năng tùy chỉnh trên máy chủ, các callback của chúng chạy trong cả mô phỏng khách hàng dự đoán và mô phỏng máy chủ có thẩm quyền. Giữ hành vi callback có tính xác định để cả hai mô phỏng sản xuất cùng một kết quả.

Tham số đầu tiên của mỗi hàm callback, managerCtx, là một đối tượng ManagerContext với các thuộc tính chia sẻ của nhân vật và quản lý, bao gồm:

• managerCtx.AbilityOwner — Nhân vật Model mà managerCtx.AbilityOwner.PrimaryPart là phần gốc.
• managerCtx.AbilityManager — Một cái nhìn cắt giảm của quản lý để một khả năng có thể thêm, xóa và truy vấn các khả năng từ bên trong các callback của nó.
• managerCtx.BodyParts — Các bộ phận cơ thể của nhân vật, với các trợ giúp để bật và tắt va chạm cho từng chi.
• managerCtx.ControllerManager — ControllerManager của nhân vật để kiểm soát vật lý. Nó có thể là nil khi không có khả năng đã đăng ký nào yêu cầu vật lý.
• managerCtx.RootCFrame — CFrame của phần gốc, được chụp một lần tại đầu khung để các callback không phải tự đi và lấy nó.
• managerCtx.RootLookVector — Hướng mà phần gốc của nhân vật đang đối diện.
• managerCtx.RootUpVectorY — Thành phần Y của vector lên của phần gốc.
• managerCtx.TaskSynchronize() — Đồng bộ hóa một callback trước khi truy cập DataModel khi hỗ trợ callback song song được bật. Hiện tại, OnUpdate không chạy trong ngữ cảnh song song, vì vậy hàm này không có tác dụng. Hỗ trợ Luau song song đầy đủ được lên kế hoạch cho một bản cập nhật trong tương lai.

Tham số thứ hai, abilityCtx, là một đối tượng AbilityContext với các bảng do engine quản lý cho đăng ký khả năng hiện tại:

• abilityCtx.Config — Các giá trị cấu hình chỉ đọc cho đăng ký khả năng này.
• abilityCtx.State — Trạng thái có thể thay đổi được sao chép qua DataModel. Quyền kiểm soát máy chủ khôi phục các giá trị này trong quá trình quay ngược và mô phỏng lại.
• abilityCtx.Local — Trạng thái tạm thời có thể thay đổi không được sao chép hoặc tham gia vào việc quay ngược.

Lưu trữ dữ liệu callback tùy chỉnh trong abilityCtx.State hoặc abilityCtx.Local. Việc ghi các trường tùy chỉnh trực tiếp vào abilityCtx là một lỗi.