Humanoid

顯示已棄用項目

*此內容是使用 AI(Beta 測試版)翻譯,可能含有錯誤。若要以英文檢視此頁面,請按一下這裡

Humanoid 是一個特殊對象,為模型提供角色功能。它賦予模型實際行走和互動的能力,並能與各種 Roblox 體驗的組件互動。Humanoid 通常被放在 Model 內,並且該模型預期由 BasePartMotor6D 組成;組件的根部預期命名為 HumanoidRootPart。還要求一個名為 Head 的部件連接到角色的軀幹部件上,可以是直接或間接連接。預設情況下,Roblox 提供兩種類型的角色裝置,各自有自己的規則:

R6

  • 一個基本的角色裝置,使用 6 個部件作為四肢。
  • Head 部件必須連接到名為 Torso 的部件,否則 Humanoid 會立即死亡。
  • 身體部件的外觀使用 CharacterMesh 對象設置。
  • 某些屬性,如 Humanoid.LeftLegHumanoid.RightLeg,僅在 R6 中有效。

R15

  • 比 R6 更複雜,但也更加靈活和穩健。
  • 使用 15 個部件作為四肢。
  • Head 部件必須連接到名為 UpperTorso 的部件,否則 Humanoid 會立即死亡。
  • 身體部件的外觀必須直接組裝。
  • 可以通過使用特殊的 NumberValue 對象在 Humanoid 內動態重新調整大小。
  • Humanoid 將自動在每個四肢內創建名為 OriginalSizeVector3Value 對象。
  • 如果 NumberValue 被放置在 Humanoid 中,並且名稱是以下之一,則將用於控制縮放功能:
    • BodyDepthScale
    • BodyHeightScale
    • BodyWidthScale
    • HeadScale

範例程式碼

此 LocalScript 使相機在玩家角色行走時搖擺

,利用 Humanoid 的 CameraOffset 和 MoveDirection。

它應該被放置在 StarterCharacterScripts 裡,以便按預期分配到玩家的角色中。

行走相機搖擺效果

local RunService = game:GetService("RunService")
local playerModel =
script.Parent
local humanoid = playerModel:WaitForChild("Humanoid")
local function updateBobbleEffect()
local now = tick()
if humanoid.MoveDirection.Magnitude > 0 then -- 角色正在行走嗎?
local velocity = humanoid.RootPart.Velocity
local bobble_X = math.cos(now * 9) / 5
local bobble_Y = math.abs(math.sin(now * 12)) / 5
local bobble = Vector3.new(bobble_X, bobble_Y, 0) * math.min(1, velocity.Magnitude / humanoid.WalkSpeed)
humanoid.CameraOffset = humanoid.CameraOffset:lerp(bobble, 0.25)
else
-- 調整 CameraOffset 的大小,使其回到正常位置。
humanoid.CameraOffset = humanoid.CameraOffset * 0.75
end
end
RunService.RenderStepped:Connect(updateBobbleEffect)

概要

屬性

方法

活動

屬性

AutoJumpEnabled

平行讀取

AutoJumpEnabled 設定 Humanoid 是否會試圖自動跳過它正在走向的障礙物。

當前,此屬性僅在以下條件為真時有效:

當玩家的角色生成時,該屬性的值與玩家的 Player.AutoJumpEnabled 屬性相匹配,這反過來又與 StarterPlayer.AutoJumpEnabled 屬性相匹配。

範例程式碼

此代碼範例適用於 TextButton。它允許玩家在移動設備上切換自動跳躍的行為。

自動跳躍切換

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local button = script.Parent
local function update()
-- 更新按鈕文字
if player.AutoJumpEnabled then
button.Text = "自動跳躍已開啟"
else
button.Text = "自動跳躍已關閉"
end
-- 在玩家的角色中反映屬性,如果他們有角色
if player.Character then
local human = player.Character:FindFirstChild("Humanoid")
if human then
human.AutoJumpEnabled = player.AutoJumpEnabled
end
end
end
local function onActivated()
-- 切換自動跳躍
player.AutoJumpEnabled = not player.AutoJumpEnabled
-- 更新其他所有內容
update()
end
button.Activated:Connect(onActivated)
update()

AutoRotate

平行讀取

AutoRotate 屬性描述 Humanoid 是否會自動旋轉以面對它們移動的方向。當設置為 true 時,角色模型將隨著 Humanoid 的行走而逐漸轉向它們的移動方向。當設置為 false 時,角色模型將保持固定於其當前旋轉,除非對 HumanoidRootPart 應用旋轉力量。

如果角色模型恰好是玩家的角色,那麼 Humanoid 的旋轉行為會受到 UserGameSetting 的 RotateType 屬性的影響。

當 AutoRotate 屬性設置為 true 時,RotateType 屬性對 Humanoid 的旋轉有以下影響:

RotationTypeBehaviorContext
MovementRelative
CameraRelative角色將旋轉以面對攝像機的方向。玩家將攝像機縮放至第一人稱,或者他們處於 shift-lock 模式。

範例程式碼

此腳本為一個部件添加了按鈕的功能,能切換 觸摸它的物件的 AutoRotate 屬性。

自動旋轉按鈕

local button = script.Parent
local enabled = true
local ON_COLOR = BrickColor.Green()
local OFF_COLOR = BrickColor.Red()
local function touchButton(humanoid)
if enabled then
enabled = false
button.BrickColor = OFF_COLOR
if humanoid.AutoRotate then
print(humanoid:GetFullName() .. " 無法再自動旋轉!")
humanoid.AutoRotate = false
else
print(humanoid:GetFullName() .. " 現在可以自動旋轉!")
humanoid.AutoRotate = true
end
task.wait(1)
button.BrickColor = ON_COLOR
enabled = true
end
end
local function onTouched(hit)
local char = hit:FindFirstAncestorWhichIsA("Model")
if char then
local humanoid = char:FindFirstChildOfClass("Humanoid")
if humanoid then
touchButton(humanoid)
end
end
end
button.Touched:Connect(onTouched)
button.BrickColor = ON_COLOR

AutomaticScalingEnabled

平行讀取

Humanoid 擁有六個子比例值包括 BodyDepthScaleBodyHeightScaleBodyProportionScaleBodyTypeScaleBodyWidthScaleHeadScale。更改這些中的任何一個的值將導致角色的身體部件和配件改變大小,但前提是 AutomaticScalingEnabled 為 true。

BreakJointsOnDeath

平行讀取

確定 Humanoid 是否在 Enum.HumanoidStateType.Dead 狀態下關節斷裂。預設為 true。

CameraOffset

平行讀取

CameraOffset 屬性指定當其 Camera.CameraSubject 設置為此 Humanoid 時,相機主題位置的偏移量。

偏移量在物件空間中應用,相對於 Humanoid 的 HumanoidRootPart 的方向。例如,DataType.Vector3 的偏移量 (0, 10, 0) 將相機偏移至玩家的 Humanoid 上方 10 studs。

範例程式碼

此 LocalScript 使相機在玩家角色行走時搖擺

,利用 Humanoid 的 CameraOffset 和 MoveDirection。

它應該被放置在 StarterCharacterScripts 裡,以便按預期分配到玩家的角色中。

行走相機搖擺效果

local RunService = game:GetService("RunService")
local playerModel =
script.Parent
local humanoid = playerModel:WaitForChild("Humanoid")
local function updateBobbleEffect()
local now = tick()
if humanoid.MoveDirection.Magnitude > 0 then -- 角色正在行走嗎?
local velocity = humanoid.RootPart.Velocity
local bobble_X = math.cos(now * 9) / 5
local bobble_Y = math.abs(math.sin(now * 12)) / 5
local bobble = Vector3.new(bobble_X, bobble_Y, 0) * math.min(1, velocity.Magnitude / humanoid.WalkSpeed)
humanoid.CameraOffset = humanoid.CameraOffset:lerp(bobble, 0.25)
else
-- 調整 CameraOffset 的大小,使其回到正常位置。
humanoid.CameraOffset = humanoid.CameraOffset * 0.75
end
end
RunService.RenderStepped:Connect(updateBobbleEffect)
平行讀取

DisplayDistanceType 屬性控制 Humanoid 的名稱和生命值顯示的距離行為。此屬性使用 Enum.HumanoidDisplayDistanceType 列舉設置,具有三個可用值,每個值均有其自己的規則:

  • 當設置為 Viewer 時,Humanoid 能在自己 NameDisplayDistanceHealthDisplayDistance 的範圍內查看其他 Humanoid 的名稱/健康。
  • 當設置為 Subject 時,Humanoid 透過其 NameDisplayDistanceHealthDisplayDistance 的值完全控制自己的名稱和生命值顯示。
  • 當設置為 None 時,Humanoid 的名稱和生命值條將在任何情況下不顯示。

詳情請參見 角色名稱/生命值顯示

範例程式碼

'這個範例展示如何設定一個 HumanoidHumanoid.DisplayerDistanceTypeHumanoid.HealthDisplayDistance,和 Humanoid.NameDisplayDistance 屬性。這些屬性決定 一個人形的生命條和名稱是如何為玩家渲染的。

首先,我們將 DisplayDistanceType 更改為 Viewer,使用 Enum.HumanoidDisplayDistanceType。當設定為 viewer 時,人形的名稱 和生命條將根據查看它們的人形的距離設定顯示。

然後,人形的 HealthDisplayDistance 設定為 0。將屬性 設定為 0 將完全隱藏生命條。在任何距離都不會顯示。

最後,人形的 NameDisplayDistance 設定為 100。這意味著 人形的名稱在 100 studs 內對其他人形可見。

當這個範例放置在作為人形子物件的 Script 中時,應該按預期工作。'

顯示一個人形的生命值和名稱

local humanoid = script.Parent
humanoid.DisplayDistanceType = Enum.HumanoidDisplayDistanceType.Viewer
humanoid.HealthDisplayDistance = 0
humanoid.NameDisplayDistance = 100

DisplayName

平行讀取

DisplayName 是一個確定當可見時 Humanoid 名稱顯示的屬性。預設情況下,新的 Humanoid 將有一個空字符串的值。如果 DisplayName 是空字符串,則 Humanoid 的名稱顯示將默認為 Humanoid 的父對象名。

玩家角色加載

當玩家加載其角色時,無論是自動還是通過使用 LoadCharacter(),引擎創建的 Humanoid 將有其 DisplayName 屬性設置為玩家的 DisplayName 屬性。

StarterCharacter 和 StarterHumanoid

當一個名為 StarterHumanoidHumanoid 被放入 StarterPlayer 中,或當一個 Humanoid 存在於名為 StarterCharacter 的模型中時,當角色由遊戲中的玩家加載時,DisplayName 屬性將被尊重。只有當 Humanoid.DisplayNameStarterHumanoid 是空字符串時,引擎才會用玩家的 DisplayName 屬性覆蓋 Humanoid的 DisplayName 屬性。

EvaluateStateMachine

平行讀取

用於禁用 Humanoid 的內部物理和狀態機。

關閉此功能的效果是?

  • 無物理 - Humanoid 不會對任何部件施加力量。Humanoid 不會以任何方式移動角色。
  • 無傳感器 - Humanoid 不會運行任何空間查詢以檢測地板、梯子或其他障礙物(如自動跳躍)。
  • 無碰撞變化 - Humanoid 不會改變任何角色部件的碰撞狀態。預設情況下,只有軀幹和頭部有啟用的 Part.CanCollide
  • 無狀態轉換或複製 - Humanoid 將不會自動更新其狀態。您仍然可以使用腳本設置 Humanoid 狀態,但它不會自動複製。

關閉此功能不會做什麼?

  • 狀態事件 - 如果手動設置 Humanoid 狀態,則 Humanoid 的每個狀態的事件和 StateChanged 仍然會觸發,這意味著動畫腳本仍會接收它們並根據其當前 Humanoid 狀態進行動畫。
  • 外觀 - HumanoidDescription、衣服、配飾和其他 Humanoid 渲染行為。
  • 攝像機和玩家腳本 - Humanoid 仍然與 Players 和攝像機腳本鏈接,確保攝像機將繼續跟隨 Humanoid.RootPart
  • 玩家輸入處理 - Humanoid.MoveDirection 屬性仍然會通過 Humanoid:Move() 函數和 PlayerScripts 更新。

FloorMaterial

唯讀
未複製
平行讀取

這是一個只讀屬性,描述 Humanoid 當前所站的 Enum.Material。它可以與普通 PartsTerrain 体素一起使用。

下面的代碼示例演示如何使用 Object:GetPropertyChangedSignal() 監聽此屬性何時變更。當 Humanoid 所站的材質發生變化時,將打印出一條消息,指示新的材質。


local Humanoid = route.to.humanoid
Humanoid:GetPropertyChangedSignal("FloorMaterial"):Connect(function()
print("新值為 FloorMaterial: " .. tostring(Humanoid.FloorMaterial))
end)

限制條件

  • Humanoid 沒有站在地面上時,該屬性的值將設置為 Air
    • 這是因為 Enum 屬性不能有空值。
    • 如果某個部件的材料設置為 Air,則可能會造成一些混淆,但實際上部分不應使用該材料。
  • Humanoid 的角色模型必須能夠與地面碰撞,否則不會被檢測到。

Health

未複製
平行讀取

該屬性代表 Humanoid 的當前生命值。該值限制在 0 和 MaxHealth 之間。如果 Humanoid 死亡,則該屬性的值將持續設置為 0。

請注意,可以使用 TakeDamage() 函數從 Health 中減去,而不是直接設置該屬性。

生命值再生

預設情況下,一個被動生命值再生腳本會自動插入到 Humanoid 中。這使非死亡的玩家角色每秒再生 MaxHealth 的 1%。要禁用此再生行為,請添加一個名為 Health 的空 ScriptStarterCharacterScripts

生命值條顯示

Health 小於 MaxHealth 時,將顯示一個生命值條。在體驗中,生命值條的顯示行為取決於 HealthDisplayDistanceHealthDisplayType

詳情請參見 角色名稱/生命值顯示

死亡

當角色的生命值達到 0 時,Humanoid 將自動轉變為 Enum.HumanoidStateType.Dead 狀態。在此狀態下,Health 鎖定在 0;然而,將 Health 設置為死去 Humanoid 的正非零值不會出現錯誤或警告。

HealthDisplayDistance

平行讀取

該屬性是一個數字,用於與 DisplayDistanceType 屬性結合使用以控制 Humanoid 的生命值條可以被看到的距離。

詳情請參見 角色名稱/生命值顯示

平行讀取

此屬性控制 Humanoid 的生命值條何時可以顯示。預設情況下,此屬性設置為 DisplayWhenDamaged,這使得生命值條僅在 Humanoid 的 Health 小於其 MaxHealth 時顯示。它還可以設置為 AlwaysOn,這使生命值條總是顯示,或 AlwaysOff,這將防止其顯示。

請注意,此屬性獨立於 Humanoid 的 HealthDisplayDistance 屬性運作,後者負責在某些距離上使生命值條淡出。如果 Humanoid.HealthDisplayType|HealthDisplayType 設置為 AlwaysOn,則其仍將根據 HealthDisplayDistance 的配置淡出。

詳情請參見 角色名稱/生命值顯示

HipHeight

平行讀取

確定當 Humanoid 站立時,RootPart 應離地的距離(以 studs 為單位)。RigType 會影響此屬性的行為。

對於 R15 裝置,預設的髖部高度會確保 RootPart 的高度正確。腿的高度不會被使用。Humanoid 的整體高度可以用以下公式描述:


Height = (0.5 * RootPart.Size.Y) + HipHeight

對於 R6 裝置,HipHeight 則描述相對偏移。Humanoid 的整體高度可以用以下公式描述:


Height = LeftLeg.Size.Y + (0.5 * RootPart.Size.Y) + HipHeight
未複製
平行讀取

如果為 true,則 Humanoid 將使用等於 Humanoid.JumpPowerHumanoid.JumpHeight 的值的向上力量進行跳躍,具體取決於 Humanoid.UseJumpPower 的值。

JumpHeight

平行讀取

提供控制 Humanoid 跳躍高度的能力,以 studs 為單位。該屬性的起始值由 StarterPlayer.CharacterJumpHeight 的值決定,預設值為 7.2。

雖然將此屬性設置為 0 將有效防止 Humanoid 跳躍,但建議通過禁用 Enum.HumanoidStateType.Jumping 狀態來禁用跳躍,方法是使用 Humanoid:SetStateEnabled()

只有在 Humanoid.UseJumpPower 設置為 false 時,該屬性才會在 Properties 窗口中顯示,因為在其他情況下它將不相關(相反,使用 Humanoid.JumpPower)。

JumpPower

平行讀取

確定跳躍時對 Humanoid 應用的向上力量。該屬性的起始值由 StarterPlayer.CharacterJumpPower 的值決定,預設值為 50,並限制在 0 和 1000 之間。請注意,跳躍也受 Workspace.Gravity 屬性的影響,該屬性決定了重力導致的加速度。

雖然將此屬性設置為 0 將有效防止 Humanoid 跳躍,但建議通過禁用 Enum.HumanoidStateType.Jumping 狀態來禁用跳躍,方法是使用 Humanoid:SetStateEnabled()

只有在 Humanoid.UseJumpPower 設置為 true 時,該屬性才會在 Properties 窗口中顯示,因為在其他情況下它將不相關(相反,使用 Humanoid.JumpHeight)。

MaxHealth

平行讀取

Humanoid 的 Health 的最大值。

此屬性的值與 Health 屬性一起用於設置默認生命值條顯示的大小。當 Humanoid 的 Health 達到 MaxHealth 時,其生命值條可能不會顯示,具體取決於其 HealthDisplayType 屬性。

MaxSlopeAngle

平行讀取

此屬性決定 Humanoid 可以攀爬的最大坡度角度。如果坡度的角度大於 Humanoid 的 MaxSlopeAngle,則其將沿坡度滑下。

當角色生成時,此屬性根據 StarterPlayer.CharacterMaxSlopeAngle 的值設置。

此屬性的值限制在 0° 和 89° 之間。預設為 89°,因此 Humanoid 預設可以攀爬幾乎任何坡度。

範例程式碼

下面的例子展示了 MaxSlopeAngle 屬性的效果,通過 將 Players.LocalPlayer 最大攀爬坡度限制為 30°。 當坡度大於 30° 時,本地玩家將會滑下去。

將下面的代碼放置在 LocalScript 中時,它會如預期那樣工作。

限制人型可以攀爬的坡度

local player = game.Players.LocalPlayer
local char = player.CharacterAdded:wait()
local h = char:FindFirstChild("Humanoid")
h.MaxSlopeAngle = 30

MoveDirection

唯讀
未複製
平行讀取

MoveDirection 是一個只讀屬性,描述 Humanoid 行走的方向,以單位向量或零長度向量表示。其方向在世界空間中描述。

由於此屬性是只讀的,因此無法通過 ScriptLocalScript 設置。

範例程式碼

此 LocalScript 使相機在玩家角色行走時搖擺

,利用 Humanoid 的 CameraOffset 和 MoveDirection。

它應該被放置在 StarterCharacterScripts 裡,以便按預期分配到玩家的角色中。

行走相機搖擺效果

local RunService = game:GetService("RunService")
local playerModel =
script.Parent
local humanoid = playerModel:WaitForChild("Humanoid")
local function updateBobbleEffect()
local now = tick()
if humanoid.MoveDirection.Magnitude > 0 then -- 角色正在行走嗎?
local velocity = humanoid.RootPart.Velocity
local bobble_X = math.cos(now * 9) / 5
local bobble_Y = math.abs(math.sin(now * 12)) / 5
local bobble = Vector3.new(bobble_X, bobble_Y, 0) * math.min(1, velocity.Magnitude / humanoid.WalkSpeed)
humanoid.CameraOffset = humanoid.CameraOffset:lerp(bobble, 0.25)
else
-- 調整 CameraOffset 的大小,使其回到正常位置。
humanoid.CameraOffset = humanoid.CameraOffset * 0.75
end
end
RunService.RenderStepped:Connect(updateBobbleEffect)

NameDisplayDistance

平行讀取

NameDisplayDistance 屬性是一個數字,用於與 Humanoid.DisplayDistanceType 屬性結合使用以控制 Humanoid 的名稱可以被看到的距離。

詳情請參見 角色名稱/生命值顯示

NameOcclusion

平行讀取

控制 Humanoid 的名稱和生命條是否可以在牆壁或其他物體後面看到。此屬性是 Enum.NameOcclusion 值,可以設置為遮蔽所有名稱、敵人名稱或完全禁用遮蔽。

LocalPlayer 沒有與之關聯的 Humanoid 的情況下,此屬性則適用於主題 Humanoid

詳情請參見 角色名稱/生命值顯示

範例程式碼

在下面的示例中,Player|Players 將無法看到彼此的

Player.Character 名稱,當它們被隱藏在

BasePart|BaseParts 背後時。

隱藏玩家名稱

local Players = game:GetService("Players")
local function onCharacterAdded(character)
local humanoid = character:WaitForChild("Humanoid")
humanoid.NamOcclusion = Enum.NameOcclusion.OccludeAll
end
local function onPlayerAdded(player)
player.CharacterAdded:Connect(onCharacterAdded)
end
Players.PlayerAdded:Connect(onPlayerAdded)

PlatformStand

平行讀取

確定 Humanoid 是否當前處於 Enum.HumanoidStateType.PlatformStanding 狀態。當該為 true 時,Humanoid 處於自由下落且無法移動的狀態。此狀態的行為類似於坐著,除了跳躍不會使 Humanoid 從此狀態中解放。

RequiresNeck

平行讀取

允許開發者禁用行為,即當 Neck 的 Motor6D 被移除或斷開,即使只是片刻,玩家的 Character|character 會死亡。此屬性預設為 true。

平行讀取

RigType 描述 Humanoid 是否使用舊的 R6 角色裝置或較新的 R15 角色裝置。

R6 裝置使用 6 個可見的 Parts,而 R15 裝置使用 15 個可見的 Parts。R15 裝置比 R6 裝置有更多的關節,使它們在動畫方面更加多功能。

請注意,如果此屬性設置不正確,Humanoid 將無法正常工作。例如,如果 R15 Humanoid 的 RigType 設置為 R6,則因為沒有連接到名為 TorsoBasePart 和名為 HeadBasePart 而導致 Humanoid 死亡。

RootPart

唯讀
未複製
平行讀取

指向 Humanoid 的 HumanoidRootPart 對象的引用,該對象是 Humanoid 控制在 3D 世界中 Humanoid 移動的根部驅動部件。該部件通常是無形的。

對於 R15 角色,Model.PrimaryPartPlayer.Character 模型設置為 HumanoidRootPart

對於 R6 角色,Model.PrimaryPart 設置為 Head 部件。

SeatPart

唯讀
未複製
平行讀取

SeatPart 是指向 Humanoid 目前坐著的座位的引用(如果有)。該屬性的值可以是 SeatVehicleSeat。如果 Humanoid 目前不在座位上,則值將為 nil

注意:

平行讀取

Sit 屬性是一個布爾值,表示 Humanoid 是否當前坐著。Humanoids 可以通過將此屬性的值設置為 true 強制進入坐著狀態。如果 Humanoid 在其坐著狀態下未連接到座位,則將絆倒而腿部無碰撞。Humanoid 可以通過跳躍逃離坐著狀態。

注意:

TargetPoint

平行讀取

請勿使用 此屬性僅在啟用實驗模式時有效,而該模式已完全停止使用。

此屬性描述當控制此 HumanoidPlayer 最後使用已裝備的 Tool 點擊的 3D 位置。

此屬性主要用於經典工具,以確定當啟動工具時 Humanoid 的目標。如果您給 NPC 一個經典火箭發射器,設置其 TargetPoint,然後調用工具的 Tool:Activate() 函數,您可以使 NPC 向目標點發射火箭。

UseJumpPower

平行讀取

當角色生成時,此屬性根據 StarterPlayer.CharacterUseJumpPower 的值設置,預設為 true。

當跳躍時,如果設置為 true,則使用 Humanoid.JumpHeight 值確保 Humanoid 爬升到該高度。如果設置為 false,則使用 Humanoid.JumpPower 值施加向上力量。

WalkSpeed

平行讀取

此屬性描述 Humanoid 能夠行走的速度,以每秒 studs 為單位。其預設值為 StarterPlayer.CharacterWalkSpeed 的值(16),這意味著玩家角色可以每秒向任何方向移動 16 studs。

注釋

  • 當在移動設備或手柄上控制時,如果控制的拇指杆稍微偏離中心,Humanoid 可以行走得比其 WalkSpeed 更慢。
  • 您可以通過將 WalkSpeed 設置為 0 將 Humanoid 冻結在原地;這將阻止控制的玩家通過預設的移動機制將其移動。
  • 預設動畫腳本根據相對於預設速度 16 studs/秒 如何快的移動來縮放 Humanoid 的移動動畫。
  • 可以使用 Running 事件獲得 Humanoid 當前行走的速度。

WalkToPart

平行讀取

WalkToPart 是一個指向 Humanoid 正在嘗試到達的部件的引用。此屬性通常在 Humanoid 的 Humanoid:MoveTo() 函數的第二個參數中指定部件時設置。

當 WalkToPart 設置且 Humanoid 正在主動嘗試到達該部件時,將持續將其 Vector3 目標更新為該部件的位置,加上相對於該部件的移動點 Humanoid.WalkToPoint 的位置。

這可以用 Luau 描述為:


goal = humanoid.WalkToPart.CFrame:pointToObjectSpace(humanoid.WalkToPoint)

限制條件

  • 僅設置 WalkToPart 的值是不夠的,無法使 Humanoid 開始跟隨某個部件。
  • 當 WalkToPoint 的值更改時,Humanoid 開始嘗試到達目標。
  • 這可能會在將來更改。
  • 如果 Humanoid 在 8 秒內未能到達目標,則其 “到達目標” 狀態會超時。
  • 這是為了防止 NPC 卡住,等待 Humanoid.MoveToFinished 觸發。
  • 如果您不想發生這種情況,則應重複調用 MoveTo,這樣超時將持續重置。

WalkToPoint

平行讀取

WalkToPoint 描述應用於 Humanoid 的 3D 空間中的目標位置,在其被 Humanoid:MoveTo() 函數提示後。

如果 Humanoid 的 Humanoid.WalkToPart 設置,則目標通過相對於該部件的位置和方向轉換 WalkToPoint 來設置。如果 WalkToPart 沒有設置,則 Humanoid 將嘗試直接到達指定的 WalkToPoint 的 3D 位置。

限制條件

  • 必須將 WalkToPoint 的值更改為其他值,才能使用 Humanoid 開始朝向它走。
  • 如果您想使 Humanoid 到達 0,0,0 的位置,應使用 Humanoid 的 MoveTo 函數。
  • 這可能會在將來更改。
  • 如果 Humanoid 在 8 秒內未能到達目標,則其 “到達目標” 狀態會超時。
  • 這是為了防止 NPC 卡住,等待 Humanoid.MoveToFinished 觸發。
  • 如果您不想發生這種情況,則應重複調用 MoveTo,這樣超時將持續重置。

範例程式碼

此代碼範例包含一個函數,通過在超時之前再次調用 Humanoid:MoveTo() 來避免 8 秒的超時。它還包括一個可選的 andThen 參數,開發者可以傳遞一個函數,當人形到達目的地時將其調用。

無限時限的人形移動

local function moveTo(humanoid, targetPoint, andThen)
local targetReached\ = false
-- 監聽人形到達其目標
local connection
connection = humanoid.MoveToFinished:Connect(function(reached)
targetReached\ = true
connection:Disconnect()
connection = nil
if andThen then
andThen(reached)
end
end)
-- 開始行走
humanoid:MoveTo(targetPoint)
-- 在一個新線程上執行以避免使函數暫停
task.spawn(function()
while not targetReached do
-- 人形仍然存在嗎?
if not (humanoid and humanoid.Parent) then
break
end
-- 目標是否已更改?
if humanoid.WalkToPoint ~= targetPoint then
break
end
-- 刷新超時
humanoid:MoveTo(targetPoint)
task.wait(6)
end
-- 如果連接仍然連接則斷開連接
if connection then
connection:Disconnect()
connection\ = nil
end
end)
end
local function andThen(reached)
print((reached\ and "目的地已達!") or "無法到達目的地!")
end
moveTo(script.Parent:WaitForChild("Humanoid"), Vector3.new(50, 0, 50), andThen)

方法

AddAccessory

()

此方法將指定的 Accessory 附加到 Humanoid 的父對象。

當調用此方法時,將通過在 Humanoid 的父對象中查找與附件的 Handle Part 共享相同名稱的 AttachmentAccessory 附加到角色。如果找到一個,則 Handle 部件將使用 Weld 連接到 Attachment 的父對象,並且焊接將配置為 Attachments 佔據相同的空間。

如果無法找到所需的 Attachment,則 Accessory 將保持附加到 Humanoid 的父對象,但將保持未附加狀態。

通常,配件焊接是在伺服器上創建的,但在某些情況下,它們可以在客戶端創建。在這些情況下,對 AddAccessory() 的客戶端調用可能不總是會產生預期的行為,您可以使用 BuildRigFromAttachments() 強制進行預期的焊接創建。

參數

accessory: Instance

要附加的 Accessory


返回

()

範例程式碼

這段腳本從零開始生成 "Clockwork的眼鏡" 配飾,然後使用 Humanoid.AddAccessory 將其附加到玩家的角色上。您應該將這段代碼粘貼到常規腳本中,然後將其放置在 StarterPlayerStarterCharacterScripts 文件夾內。

[Humanoid] 添加入飾範例

local playerModel = script.Parent
local humanoid = playerModel:WaitForChild("Humanoid")
local clockworksShades = Instance.new("Accessory")
clockworksShades.Name = "ClockworksShades"
local handle = Instance.new("Part")
handle.Name = "Handle"
handle.Size = Vector3.new(1, 1.6, 1)
handle.Parent = clockworksShades
local faceFrontAttachment = Instance.new("Attachment")
faceFrontAttachment.Name = "FaceFrontAttachment"
faceFrontAttachment.Position = Vector3.new(0, -0.24, -0.45)
faceFrontAttachment.Parent = handle
local mesh = Instance.new("SpecialMesh")
mesh.Name = "Mesh"
mesh.Scale = Vector3.new(1, 1.3, 1)
mesh.MeshId = "rbxassetid://1577360"
mesh.TextureId = "rbxassetid://1577349"
mesh.Parent = handle
humanoid:AddAccessory(clockworksShades)

ApplyDescription

()
暫停

此等待方法使角色的外觀與傳入的 HumanoidDescription 匹配。傳入的 HumanoidDescription 複製將被緩存在 HumanoidHumanoidDescription

此方法是基於假設僅使用此方法來更改角色的外觀,並且在調用之間不會通過其他方式進行更改。如果在調用之間對角色進行更改,則此方法可能無法準確顯示傳入的 HumanoidDescription。如果您想將此方法與其他更新角色的方式一起使用,則 Humanoid:ApplyDescriptionReset() 將始終確保角色反映傳入的 HumanoidDescription

參見

參數

humanoidDescription: HumanoidDescription

您想要設置角色匹配的 HumanoidDescription 實例。

assetTypeVerification: Enum.AssetTypeVerification
預設值:"Default"

返回

()

ApplyDescriptionReset

()
暫停

此等待方法使角色的外觀與傳入的 HumanoidDescription 匹配,即使在外部變更後。傳入的 HumanoidDescription 複製將被緩存在 HumanoidHumanoidDescription

此方法將始終確保角色反映傳入的 HumanoidDescription,即使角色根據非使用 HumanoidDescription 系統的方式進行了更改(例如不使用 ApplyDescriptionReset()ApplyDescription())。這與 ApplyDescription() 相比,後者已優化,若角色已通過其他方式改變,可能會不正確地應用 HumanoidDescription

參數

humanoidDescription: HumanoidDescription

您想要設置角色匹配的 HumanoidDescription 實例。

assetTypeVerification: Enum.AssetTypeVerification
預設值:"Default"

返回

()

BuildRigFromAttachments

()

此方法為 Humanoid 組合一棵 Motor6D 關節樹。Motor6D 關節是播放 Animations 所必需的。

從人類的 RootPart 開始,此方法收集當前部件中所有名稱以 RigAttachment 結尾的 Attachments。然後,它在角色中尋找與該附件同名的匹配附件。使用這兩個附件,根據與兩個附件相關聯的部件以及附件的 CFrame 生成 Motor6D 關節。

Humanoid:BuildRigFromAttachments() 也會縮放角色並設置身體顏色。


返回

()

範例程式碼

對 Humanoid 的 BuildRigFromAttachments 函數的 Lua 移植,以便可以看到該函數的遞歸行為。

Lua 版本的 BuildRigFromAttachments

local function createJoint(jointName, att0, att1)
local part0, part1 = att0.Parent, att1.Parent
local newMotor = part1:FindFirstChild(jointName)
if not (newMotor and newMotor:IsA("Motor6D")) then
newMotor = Instance.new("Motor6D")
end
newMotor.Name = jointName
newMotor.Part0 = part0
newMotor.Part1 = part1
newMotor.C0 = att0.CFrame
newMotor.C1 = att1.CFrame
newMotor.Parent = part1
end
local function buildJointsFromAttachments(part, characterParts)
if not part then
return
end
-- 首先,遍歷 此部件的所有子項以查找附件
for _, attachment in pairs(part:GetChildren()) do
if attachment:IsA("Attachment") then
-- 只從 "RigAttachments" 進行關節建立
local attachmentName = attachment.Name
local findPos = attachmentName:find("RigAttachment")
if findPos then
-- 也不要製作重複的關節(同名的
-- rigattachment 在兩個部件下)
local jointName = attachmentName:sub(1, findPos - 1)
if not part:FindFirstChild(jointName) then
-- 嘗試查找其他具有相同 rig attachment 名稱的部件
for _, characterPart in pairs(characterParts) do
if part ~= characterPart then
local matchingAttachment = characterPart:FindFirstChild(attachmentName)
if matchingAttachment and matchingAttachment:IsA("Attachment") then
createJoint(jointName, attachment, matchingAttachment)
buildJointsFromAttachments(characterPart, characterParts)
break
end
end
end
end
end
end
end
end
local function buildRigFromAttachments(humanoid)
local rootPart = humanoid.RootPart
assert(rootPart, "Humanoid 沒有 HumanoidRootPart。")
local characterParts = {}
for _, descendant in ipairs(humanoid.Parent:GetDescendants()) do
if descendant:IsA("BasePart") then
table.insert(characterParts, descendant)
end
end
buildJointsFromAttachments(rootPart, characterParts)
end
local humanoid = script.Parent:WaitForChild("Humanoid")
buildRigFromAttachments(humanoid)

一個從零開始生成 R15 角色的腳本,使用套件的 assetId。

R15 套件導入器

local AssetService = game:GetService("AssetService")
local InsertService = game:GetService("InsertService")
local MarketplaceService = game:GetService("MarketplaceService")
local PACKAGE_ASSET_ID = 193700907 -- 電路斷路器
local function addAttachment(part, name, position, orientation)
local attachment = Instance.new("Attachment")
attachment.Name = name
attachment.Parent = part
if position then
attachment.Position = position
end
if orientation then
attachment.Orientation = orientation
end
return attachment
end
local function createBaseCharacter()
local character = Instance.new("Model")
local humanoid = Instance.new("Humanoid")
humanoid.Parent = character
local rootPart = Instance.new("Part")
rootPart.Name = "HumanoidRootPart"
rootPart.Size = Vector3.new(2, 2, 1)
rootPart.Transparency = 1
rootPart.Parent = character
addAttachment(rootPart, "RootRigAttachment")
local head = Instance.new("Part")
head.Name = "Head"
head.Size = Vector3.new(2, 1, 1)
head.Parent = character
local headMesh = Instance.new("SpecialMesh")
headMesh.Scale = Vector3.new(1.25, 1.25, 1.25)
headMesh.MeshType = Enum.MeshType.Head
headMesh.Parent = head
local face = Instance.new("Decal")
face.Name = "face"
face.Texture = "rbxasset://textures/face.png"
face.Parent = head
addAttachment(head, "FaceCenterAttachment")
addAttachment(head, "FaceFrontAttachment", Vector3.new(0, 0, -0.6))
addAttachment(head, "HairAttachment", Vector3.new(0, 0.6, 0))
addAttachment(head, "HatAttachment", Vector3.new(0, 0.6, 0))
addAttachment(head, "NeckRigAttachment", Vector3.new(0, -0.5, 0))
return character, humanoid
end
local function createR15Package(packageAssetId)
local packageAssetInfo = MarketplaceService:GetProductInfo(packageAssetId)
local character, humanoid = createBaseCharacter()
character.Name = packageAssetInfo.Name
local assetIds = AssetService:GetAssetIdsForPackage(packageAssetId)
for _, assetId in pairs(assetIds) do
local limb = InsertService:LoadAsset(assetId)
local r15 = limb:FindFirstChild("R15")
if r15 then
for _, part in pairs(r15:GetChildren()) do
part.Parent = character
end
else
for _, child in pairs(limb:GetChildren()) do
child.Parent = character
end
end
end
humanoid:BuildRigFromAttachments()
return character
end
local r15Package = createR15Package(PACKAGE_ASSET_ID)
r15Package.Parent = workspace

ChangeState

()

此方法使 Humanoid 進入給定的 Enum.HumanoidStateType,描述 Humanoid 當前在做的活動。

請查看 Enum.HumanoidStateType 頁面以獲得有關特定狀態的更多信息,因為某些名稱可能不直觀。例如,Enum.HumanoidStateType.Running 描述了人類的腿部在地面上時的狀態,包括靜止時。

由於 Humanoid 的默認行為,某些狀態在設置時會自動更改。例如:

請注意,為了使用此方法設置 Humanoid 狀態,必須從 LocalScript 中進行,並且客戶端必須對 Player.Character 擁有 網絡擁有權。或者,您可以從服務器端的 Script 調用此方法,但服務器必須擁有玩家角色的網絡擁有權。

另請參閱 Humanoid:SetStateEnabled() 以啟用或禁用特定狀態,以及 Humanoid:GetState() 以獲取當前人類狀態。

參數

預設值:"None"

返回

()

範例程式碼

這段程式碼當放置在 LocalScript 中,位於 StarterPlayer.StarterCharacterScripts,會讓玩家的角色執行雙重跳躍。

雙重跳躍

local UserInputService = game:GetService("UserInputService")
local character = script.Parent
local humanoid = character:WaitForChild("Humanoid")
local doubleJumpEnabled = false
humanoid.StateChanged:Connect(function(_oldState, newState)
if newState == Enum.HumanoidStateType.Jumping then
if not doubleJumpEnabled then
task.wait(0.2)
if humanoid:GetState() == Enum.HumanoidStateType.Freefall then
doubleJumpEnabled = true
end
end
elseif newState == Enum.HumanoidStateType.Landed then
doubleJumpEnabled = false
end
end)
UserInputService.InputBegan:Connect(function(inputObject)
if inputObject.KeyCode == Enum.KeyCode.Space then
if doubleJumpEnabled then
if humanoid:GetState() ~= Enum.HumanoidStateType.Jumping then
humanoid:ChangeState(Enum.HumanoidStateType.Jumping)
task.spawn(function()
doubleJumpEnabled = false
end)
end
end
end
end)

EquipTool

()

此方法使 Humanoid 裝備給定的 Tool

當調用此方法時,Humanoid 將首先自動卸下所有當前裝備的 Tools

雖然它們將被裝備,但如果 Tool.RequiresHandletrue 且沒有手柄,則 Tools 將無法運作,無論此方法是否被用來裝備它們。

另請參閱 Humanoid:UnequipTools()

參數

tool: Instance

要裝備的 Tool


返回

()

GetAccessories

此方法返回 Accessory 對象的數組,該對象是人類的父母當前穿著的。所有這些 Accessory 對象都將被包含,無論它們是否已附加。

如果 Humanoid 沒有 Accessory 對象,將返回一個空數組。

另請參閱 Humanoid:AddAccessory() 來將 Accessory 附加到人類的父母。


返回

當前與人類父母關聯的 Accessory 對象的數組。

範例程式碼

此代碼範例將等待配件完全加載,然後打印出有多少個配件,最後將它們全部銷毀。

加載後移除配件

local Players = game:GetService("Players")
local function onPlayerAddedAsync(player)
local connection = player.CharacterAppearanceLoaded:Connect(function(character)
-- 此時所有配件都已加載
local humanoid = character:FindFirstChildOfClass("Humanoid")
local numAccessories = #humanoid:GetAccessories()
print(("銷毀 %d 個配件給 %s"):format(numAccessories, player.Name))
humanoid:RemoveAccessories()
end)
-- 確保在玩家離開後斷開我們的連接 -- 以允許玩家被垃圾收集器收集
player.AncestryChanged:Wait()
connection:Disconnect()
end
for _, player in Players:GetPlayers() do
task.spawn(onPlayerAddedAsync, player)
end
Players.PlayerAdded:Connect(onPlayerAddedAsync)

GetAppliedDescription

此方法返回人類的緩存 HumanoidDescription 的副本,描述其當前外觀。這可用於快速確定角色的外觀並使用 Humanoid:ApplyDescription() 方法將其外觀分配給其他角色。

另請參閱


返回

GetBodyPartR15

此方法返回一個 Part 是什麼 Enum.BodyPartR15,或者如果該部件不是 R15 身體部件則返回 Enum.BodyPartR15.Unknown。此方法允許開發人員獨立於實際的身體部件名稱檢索玩家身體部件,而是返回一個枚舉。

它可以與 Humanoid:ReplaceBodyPartR15() 一起使用。例如,如果玩家的身體部件碰觸到某物,這個函數將返回獲得一個部件的實例。開發人員可以查找該部件是哪個身體部件,比如頭部或手臂。然後根據該部件是什麼,開發人員可以執行一些遊戲操作或用某個其他部件替換該部件 - 也許顯示損壞。

此方法在擊中位置很重要的遊戲中會很有用。例如,它可以用於確定玩家是否在腿部受到擊中,然後根據受傷的情況減慢他們的速度。

參數

part: Instance

被檢查是否為 R15 身體部件的指定部件。


返回

指定部件的 R15 身體部件類型,或如果該部件不是身體部件則為未知。

GetLimb

此方法返回與給定 Part 相關聯的 Enum.Limb 枚舉。它適用於 R15 和 R6 角色,例如:


-- 對於 R15
print(humanoid:GetLimb(character.LeftUpperLeg)) -- Enum.Limb.LeftLeg
print(humanoid:GetLimb(character.LeftLowerLeg)) -- Enum.Limb.LeftLeg
print(humanoid:GetLimb(character.LeftFoot)) -- Enum.Limb.LeftLeg
-- 對於 R6
print(humanoid:GetLimb(character:FindFirstChild("Left Leg"))) -- Enum.Limb.LeftLeg

請注意,如果部件的父級沒有設置為人類的父級,則 Humanoid:GetLimb() 將引發錯誤。

參數

part: Instance

對於要檢索 Enum.LimbPart


返回

部件對應的 Enum.Limb

範例程式碼

將此放入 LocalScript 中。輸出將根據人形是 R6 還是 R15 而有所不同。

獲取人形的肢體

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local humanoid = character:WaitForChild("Humanoid")
for _, child in pairs(character:GetChildren()) do
local limb = humanoid:GetLimb(child)
if limb ~= Enum.Limb.Unknown then
print(child.Name .. " 是肢體的一部分 " .. limb.Name)
end
end

GetMoveVelocity


返回

平行寫入

此方法返回人類當前的 Enum.HumanoidStateType,描述 Humanoid 當前在做的活動,比如跳躍或游泳。

另請參閱 Humanoid:SetStateEnabled() 以啟用或禁用特定狀態,以及 Humanoid:ChangeState() 以更改當前人類狀態。


返回

範例程式碼

這段程式碼當放置在 LocalScript 中,位於 StarterPlayer.StarterCharacterScripts,會讓玩家的角色執行雙重跳躍。

雙重跳躍

local UserInputService = game:GetService("UserInputService")
local character = script.Parent
local humanoid = character:WaitForChild("Humanoid")
local doubleJumpEnabled = false
humanoid.StateChanged:Connect(function(_oldState, newState)
if newState == Enum.HumanoidStateType.Jumping then
if not doubleJumpEnabled then
task.wait(0.2)
if humanoid:GetState() == Enum.HumanoidStateType.Freefall then
doubleJumpEnabled = true
end
end
elseif newState == Enum.HumanoidStateType.Landed then
doubleJumpEnabled = false
end
end)
UserInputService.InputBegan:Connect(function(inputObject)
if inputObject.KeyCode == Enum.KeyCode.Space then
if doubleJumpEnabled then
if humanoid:GetState() ~= Enum.HumanoidStateType.Jumping then
humanoid:ChangeState(Enum.HumanoidStateType.Jumping)
task.spawn(function()
doubleJumpEnabled = false
end)
end
end
end
end)

GetStateEnabled

平行寫入

GetStateEnabled 方法返回指定的 Enum.HumanoidStateType 是否對 Humanoid 啟用。

人類狀態描述了人類當前在做的活動。

當特定的 Enum.HumanoidStateType 被禁用時,人類將永遠無法進入該狀態。這是正確的,無論是通過 Humanoid:ChangeState() 嘗試改變狀態還是 Roblox 內部的人類代碼。

另請參閱:

參數


返回

指定的 Enum.HumanoidStateType 是否已啟用。

範例程式碼

以下代碼將 人形跳躍狀態 的值設置為 false,使用 Humanoid:SetStateEnabled(),然後使用 Humanoid:GetStateEnabled() 獲取並打印這個狀態的值 (false)。

設定與獲取人形狀態

local humanoid = script.Parent:WaitForChild("Humanoid")
-- 設置狀態
humanoid:SetStateEnabled(Enum.HumanoidStateType.Jumping, false)
-- 獲取狀態
print(humanoid:GetStateEnabled(Enum.HumanoidStateType.Jumping)) -- false

Move

()

此方法使 Humanoid 向給定的 Vector3 方向行走。

默認情況下,該方向是以世界座標系為準,但如果 relativeToCamera 參數為 true,則方向是相對於 CurrentCameraCFrame。由於負 Z 方向在 Roblox 中被視為“前進”,以下代碼將使人類朝著 CurrentCamera 的方向行走。


humanoid:Move(Vector3.new(0, 0, -1), true)

當調用此方法時,Humanoid 將移動,直到再次調用此方法。但是,此方法將在下一幀中被 Roblox 的默認角色控制腳本覆蓋。這可以通過使用 RunService:BindToRenderStep() 每幀調用此函數(見範例)或覆蓋 StarterPlayerScripts 中的控制腳本來避免。

此方法可以在服務器上調用,但應僅在服務器對人類的組件擁有 網絡擁有權 時進行。

另請參閱 Humanoid:MoveTo() 使 Humanoid 行走到某一點,以及 Player:Move(),該方法有效地調用此函數。

參數

moveDirection: Vector3

行走的方向。

relativeToCamera: boolean

若將 true 設置為 relativeToCamera,則 moveDirection 參數應視為相對於 CurrentCamera

預設值:false

返回

()

範例程式碼

此代碼示例使用 Humanoid:Move() 函數使玩家的 CharacterCamera 的方向行走。需要使用 RunService:BindToRenderStep(),因為默認的控制腳本會在每一幀覆蓋玩家的移動。

要運行此示例,請將其放置在親屬於 StarterCharacterScriptsLocalScript 中。

向前移動一個人形

local RunService = game:GetService("RunService")
local Players = game:GetService("Players")
local player = Players.LocalPlayer
RunService:BindToRenderStep("move", Enum.RenderPriority.Character.Value + 1, function()
if player.Character then
local humanoid = player.Character:FindFirstChild("Humanoid")
if humanoid then
humanoid:Move(Vector3.new(0, 0, -1), true)
end
end
end)

MoveTo

()

此方法使 Humanoid 嘗試通過設置 Humanoid.WalkToPointHumanoid.WalkToPart 屬性來走向給定位置。

locationpart 參數對應於將設置為 Humanoid.WalkToPointHumanoid.WalkToPart 的內容。

如果指定了 part 參數,即使如此 Humanoid 還是將嘗試走向該點。然而,如果部件移動,則 Humanoid 正在走向的點將相對於該部件改變位置。如果未指定 part 參數,則 Humanoid 正在走向的點將不會改變。

如果人類在 8 秒內未達到 reach goal 狀態,則將會超時。這樣做是為了避免 NPC 等待 Humanoid.MoveToFinished 被觸發。如果您不想這樣,您應該重複調用 MoveTo,以便超時保持重置。

MoveTo() 在以下情況下結束:

參數

location: Vector3

設置 Humanoid.WalkToPoint 的位置。

part: Instance
預設值:"nil"

返回

()

範例程式碼

此代碼範例包含一個函數,通過在超時之前再次調用 Humanoid:MoveTo() 來避免 8 秒的超時。它還包括一個可選的 andThen 參數,開發者可以傳遞一個函數,當人形到達目的地時將其調用。

無限時限的人形移動

local function moveTo(humanoid, targetPoint, andThen)
local targetReached\ = false
-- 監聽人形到達其目標
local connection
connection = humanoid.MoveToFinished:Connect(function(reached)
targetReached\ = true
connection:Disconnect()
connection = nil
if andThen then
andThen(reached)
end
end)
-- 開始行走
humanoid:MoveTo(targetPoint)
-- 在一個新線程上執行以避免使函數暫停
task.spawn(function()
while not targetReached do
-- 人形仍然存在嗎?
if not (humanoid and humanoid.Parent) then
break
end
-- 目標是否已更改?
if humanoid.WalkToPoint ~= targetPoint then
break
end
-- 刷新超時
humanoid:MoveTo(targetPoint)
task.wait(6)
end
-- 如果連接仍然連接則斷開連接
if connection then
connection:Disconnect()
connection\ = nil
end
end)
end
local function andThen(reached)
print((reached\ and "目的地已達!") or "無法到達目的地!")
end
moveTo(script.Parent:WaitForChild("Humanoid"), Vector3.new(50, 0, 50), andThen)

PlayEmote

暫停

如果由於在 HumanoidDescription 中找不到 emoteName,則無法播放表情,該方法將報錯。該方法將返回 true,表示表情播放成功。

參數

emoteName: string

要播放的表情名稱。


返回

成功播放。

RemoveAccessories

()

此方法移除人類的父母所穿的所有 Accessory 對象。對於玩家的 Characters,這將移除所有帽子和其他配件。

此方法通過對它們調用 Instance:Destroy() 來移除 Accessory 對象,這意味著這些配件的 Parent 設置為 nil 並鎖定。

另請參閱 Humanoid:AddAccessory() 以附加 Accessory,以及 Humanoid:GetAccessories() 獲取所有屬於 HumanoidAccessory 對象。


返回

()

範例程式碼

此代碼範例將等待配件完全加載,然後打印出有多少個配件,最後將它們全部銷毀。

加載後移除配件

local Players = game:GetService("Players")
local function onPlayerAddedAsync(player)
local connection = player.CharacterAppearanceLoaded:Connect(function(character)
-- 此時所有配件都已加載
local humanoid = character:FindFirstChildOfClass("Humanoid")
local numAccessories = #humanoid:GetAccessories()
print(("銷毀 %d 個配件給 %s"):format(numAccessories, player.Name))
humanoid:RemoveAccessories()
end)
-- 確保在玩家離開後斷開我們的連接 -- 以允許玩家被垃圾收集器收集
player.AncestryChanged:Wait()
connection:Disconnect()
end
for _, player in Players:GetPlayers() do
task.spawn(onPlayerAddedAsync, player)
end
Players.PlayerAdded:Connect(onPlayerAddedAsync)

ReplaceBodyPartR15

動態替換 R15/Rthro 身體部件與不同的部件。該部件將自動正常縮放。

此方法對於在遊戲中修改角色或從基礎裝配構建角色非常有用。相關的方法 GetBodyPartR15 在使用此方法時非常方便。

傳入的部件名稱應與傳入的 BodyPartR15 枚舉名稱匹配。

參數

要替換的身體部件。Enum.BodyPartR15.Unknown 無效。

part: BasePart

將要作為角色父項的 Part Instance


返回

SetStateEnabled

()

此方法設置是否對 Humanoid 啟用給定的 Enum.HumanoidStateType。當特定的 Enum.HumanoidStateType 被禁用時,Humanoid 將永遠無法進入該狀態。這是正確的,無論是通過 Humanoid:ChangeState() 嘗試改變狀態還是 Roblox 內部的 Humanoid 代碼。

請注意,在服務器上使用 SetStateEnabled() 並不會將更改復制到客戶端,反之亦然。

參數

要啟用或禁用的 Enum.HumanoidStateType

enabled: boolean

true 如果要啟用 statefalse 如果要禁用 state


返回

()

範例程式碼

'以下範例要求在 Humanoid 降落後需要一秒的冷卻時間 之後才能再次跳躍。 若要嘗試此範例,請將其放置在 LocalScript 中 在 StarterCharacterScripts|StarterPlayer.StarterCharacterScripts。'

跳躍冷卻

local character = script.Parent
local JUMP_DEBOUNCE = 1
local humanoid = character:WaitForChild("Humanoid")
local isJumping = false
humanoid.StateChanged:Connect(function(_oldState, newState)
if newState == Enum.HumanoidStateType.Jumping then
if not isJumping then
isJumping = true
humanoid:SetStateEnabled(Enum.HumanoidStateType.Jumping, false)
end
elseif newState == Enum.HumanoidStateType.Landed then
if isJumping then
isJumping = false
task.wait(JUMP_DEBOUNCE)
humanoid:SetStateEnabled(Enum.HumanoidStateType.Jumping, true)
end
end
end)

TakeDamage

()

此方法在沒有受到 ForceField 保護的情況下,將 Humanoid.Health 減少指定的 amount

此方法接受 amount 參數的負值。這將增加人類的 Humanoid.Health。但是這僅在沒有存在 ForceField 時才會生效。

ForceFields 如何防止受傷

如果 Humanoid 受到 ForceField 保護,則會滿足以下標準之一:

若要對 Humanoid 造成傷害而不考慮任何存在的 ForceFields,請直接設置 Humanoid.Health

有關 ForceFields 如何保護 Humanoids 的更多信息,請參見 ForceField 頁面。

參數

amount: number

要從 Humanoid.Health 中扣除的傷害或數量。


返回

()

範例程式碼

此代碼放在一個 LocalScript 中,將使本地玩家受到 99 點傷害


_僅有_ 在沒有 ForceField 的情況下。
對一個 Humanoid 造成傷害

-- 本地玩家將會受到傷害
local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local humanoid = character:WaitForChild("Humanoid")
humanoid:TakeDamage(99)

UnequipTools

()

此方法卸下目前由 Humanoid 裝備的任何 Tool。被卸下的 Tool 將被父級設置為與 Humanoid 相關的 PlayerBackpack

如果沒有裝備任何 Tool,此方法將不會執行任何操作。

雖然 Tools 可以由 NPC 裝備,但此方法僅適用於有相應 PlayerHumanoids,因為需要一個 Backpack 對象來將卸下的 Tool 裝配到。

另請參閱 Humanoid:EquipTool()


返回

()

活動

ApplyDescriptionFinished

參數

description: HumanoidDescription

Climbing

Humanoid 爬升的速度改變時觸發。

Humanoids 可以爬上由 PartsTrussParts 製成的梯子。

Humanoids 的爬升速度為其 Humanoid.WalkSpeed 的 70%。

Humanoid 停止爬升時,該事件不一定會以 0 的速度觸發。

另請參見:

參數

speed: number

當前 Humanoid 攀爬速度。


範例程式碼

人形.攀爬

local Players = game:GetService("Players")
local function onCharacterClimbing(character, speed)
print(character.Name, "正在以", speed, "個 studs / 秒的速度攀爬.")
end
local function onCharacterAdded(character)
character.Humanoid.Climbing:Connect(function(speed)
onCharacterClimbing(character, speed)
end)
end
local function onPlayerAdded(player)
player.CharacterAdded:Connect(onCharacterAdded)
end
Players.PlayerAdded:Connect(onPlayerAdded)

Died

此事件在 Humanoid 死亡時觸發,通常是當 Humanoid.Health 下降為 0。這可能是因為將其頭部與 Humanoid.Torso 斷開連接,或直接設置健康屬性造成的。

此事件僅在 HumanoidWorkspace 的子代時觸發。如果禁用 Dead Enum.HumanoidStateType,則不會觸發此事件。


範例程式碼

以下代碼會在玩家死亡時打印玩家的名字,後面跟著「已經死亡!」。例如,如果玩家名為「Shedletsky」,則在他們死亡時輸出中會打印「Shedletsky 已經死亡!」。

Humanoid.Died

local Players = game:GetService("Players")
local function onPlayerAdded(player)
local function onCharacterAdded(character)
local humanoid = character:WaitForChild("Humanoid")
local function onDied()
print(player.Name, "已經死亡!")
end
humanoid.Died:Connect(onDied)
end
player.CharacterAdded:Connect(onCharacterAdded)
end
Players.PlayerAdded:Connect(onPlayerAdded)

FallingDown

FallingDown 事件在 Humanoid 進入和離開 FallingDown Enum.HumanoidStateType 時觸發。

Humanoid 進入 GettingUp 狀態時,會在 FallingDown 狀態啟用 3 秒後發生。當發生這種情況時,此事件將以 active 值為 false 觸發,而 Humanoid.GettingUp 將以 active 值為 true 觸發。

參數

active: boolean

描述 Humanoid 是否正在進入或離開 FallingDown Enum.HumanoidStateType


FreeFalling

此事件在 Humanoid 進入或離開 Freefall Enum.HumanoidStateType 時觸發。

active 參數表示 Humanoid 是否正在進入或離開 Freefall 狀態。

儘管 Freefall 狀態通常在 Humanoid 降落到地面時結束,但如果在 Humanoid 正在掉落時更改狀態,此事件可能會觸發 active 等於 false。因此,您應該使用 Humanoid.StateChanged 並監聽 Landed 狀態以確定 Humanoid 何時著陸。

參數

active: boolean

Humanoid 是否正在進入或離開 Freefall Enum.HumanoidStateType


GettingUp

此事件在 Humanoid 進入或離開 Enum.HumanoidStateType.GettingUp 狀態時觸發,這是一個過渡狀態,在 Humanoid 進入 FallingDown(3 秒)或 Ragdoll(1 秒)狀態後激活。

Humanoid 嘗試站起來時,該事件將首先以 active 參數為 true 觸發,然後很快再次以 active 參數為 false 觸發。

要強制 Humanoid 摔倒,請使用 Humanoid:ChangeState() 函數與 Enum.HumanoidStateType.FallingDown 一起使用。

參數

active: boolean

描述 Humanoid 是否正在進入或離開 GettingUp Enum.HumanoidStateType


HealthChanged

此事件在 Humanoid.Health 改變時觸發。然而,如果健康從等於或大於 Humanoid.MaxHealth 的值增加,則不會觸發。

Humanoid.Health 降為零時,Humanoid 將死亡,並將觸發 Humanoid.Died 事件。此事件將以零的值觸發。

參數

health: number

Humanoid.Health 的新值。


範例程式碼

以下範例會判斷健康值的變化,並將其輸出到

輸出中。它只會在 LocalScript 中運作。

Humanoid.HealthChanged

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local function onCharacterAdded(character)
local humanoid = character:WaitForChild("Humanoid")
local currentHealth = humanoid.Health
local function onHealthChanged(health)
local change = math.abs(currentHealth - health)
print("人形的健康值", (currentHealth > health and "降低了" or "增加了"), change)
currentHealth = health
end
humanoid.HealthChanged:Connect(onHealthChanged)
end
player.CharacterAdded:Connect(onCharacterAdded)

此代碼範例允許您使用兩個嵌套的 Frames 創建一個簡單的顏色變化健康條。

將此內容粘貼到內部框架的 LocalScript 中。

健康條

local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- 將腳本粘貼到一個 LocalScript 中,該 LocalScript
-- 被放置到一個 Frame 內部的 Frame 中
local frame = script.Parent
local container = frame.Parent
container.BackgroundColor3 = Color3.new(0, 0, 0) -- 黑色
-- 當人形的健康值變化時調用此函數
local function onHealthChanged()
local human = player.Character.Humanoid
local percent = human.Health / human.MaxHealth
-- 更改內部條的大小
frame.Size = UDim2.new(percent, 0, 1, 0)
-- 更改健康條的顏色
if percent < 0.1 then
frame.BackgroundColor3 = Color3.new(1, 0, 0) -- 黑色
elseif percent < 0.4 then
frame.BackgroundColor3 = Color3.new(1, 1, 0) -- 黃色
else
frame.BackgroundColor3 = Color3.new(0, 1, 0) -- 綠色
end
end
-- 當玩家生成時調用此函數
local function onCharacterAdded(character)
local human = character:WaitForChild("Humanoid")
-- 模式:現在更新一次,然後在健康變化時隨時更新
human.HealthChanged:Connect(onHealthChanged)
onHealthChanged()
end
-- 連接我們的生成監聽器;如果已經生成則調用它
player.CharacterAdded:Connect(onCharacterAdded)
if player.Character then
onCharacterAdded(player.Character)
end

Jumping

此事件在 Humanoid 進入和離開 Jumping Enum.HumanoidStateType 時觸發。

Humanoid 跳躍時,此事件將首先以 active 參數為 true 觸發,然後不久後再次以 active 參數為 false 觸發。第二次觸發並不對應於 Humanoid 着陸;要做到這一點,請使用 Humanoid.StateChanged 監聽 Landed Enum.HumanoidStateType

您可以使用 Humanoid:SetStateEnabled() 函數禁用跳躍。

參數

active: boolean

是否 Humanoid 正在進入或離開 Jumping Enum.HumanoidStateType


MoveToFinished

此事件在 Humanoid 完成朝著由 Humanoid.WalkToPointHumanoid.WalkToPart 屬性定義的目標走去時觸發。

Humanoid.WalkToPointHumanoid.WalkToPart 屬性可以單獨設置,或使用 Humanoid:MoveTo() 函數設置。

如果 Humanoid 在 8 秒內到達其目標,則該事件將返回 reached 為 true。如果目標在 8 秒內未到達,Humanoid 將停止行走,並且 reached 將為 false。此超時可以通過在超時期間再次調用 Humanoid:MoveTo() 重置。

參數

reached: boolean

一個布爾值,表示 Humanoid 是否到達目標。如果 Humanoid 到達了目標,則 true,如果在目標到達之前行走超時則為 false


範例程式碼

此代碼範例包含一個函數,通過在超時之前再次調用 Humanoid:MoveTo() 來避免 8 秒的超時。它還包括一個可選的 andThen 參數,開發者可以傳遞一個函數,當人形到達目的地時將其調用。

無限時限的人形移動

local function moveTo(humanoid, targetPoint, andThen)
local targetReached\ = false
-- 監聽人形到達其目標
local connection
connection = humanoid.MoveToFinished:Connect(function(reached)
targetReached\ = true
connection:Disconnect()
connection = nil
if andThen then
andThen(reached)
end
end)
-- 開始行走
humanoid:MoveTo(targetPoint)
-- 在一個新線程上執行以避免使函數暫停
task.spawn(function()
while not targetReached do
-- 人形仍然存在嗎?
if not (humanoid and humanoid.Parent) then
break
end
-- 目標是否已更改?
if humanoid.WalkToPoint ~= targetPoint then
break
end
-- 刷新超時
humanoid:MoveTo(targetPoint)
task.wait(6)
end
-- 如果連接仍然連接則斷開連接
if connection then
connection:Disconnect()
connection\ = nil
end
end)
end
local function andThen(reached)
print((reached\ and "目的地已達!") or "無法到達目的地!")
end
moveTo(script.Parent:WaitForChild("Humanoid"), Vector3.new(50, 0, 50), andThen)

PlatformStanding

此事件在 Humanoid 進入或離開 PlatformStanding Enum.HumanoidStateType 時觸發。

Humanoid 處於 PlatformStanding 狀態時, Humanoid.PlatformStand 屬性將為 true

Humanoid.PlatformStand 設置為 true 時,Humanoid 將無法移動。欲了解更多信息,請參見 Humanoid.PlatformStand 頁面。

PlatformStand Enum.HumanoidStateType 與現在已被禁用的 Platform 部件相關聯。儘管如此,開發者仍可使用它。

參數

active: boolean

描述 Humanoid 是否正在進入或離開 PlatformStanding Enum.HumanoidStateType


Ragdoll

此事件在 Humanoid 進入或離開 Ragdoll Enum.HumanoidStateType 時觸發。

active 參數值將為 truefalse,以指示進入或離開。

使用 Humanoid:SetStateEnabled() 禁用 GettingUp 狀態以保持在 Ragdoll 狀態。

另請參覽:

參數

active: boolean

描述 Humanoid 是否正在進入或離開 Ragdoll Enum.HumanoidStateType


Running

此事件在 Humanoid 跑步的速度改變時觸發。

Humanoids 跑步時,它們平均速度為其 Humanoid.WalkSpeed 每秒多少學分。

Humanoid 停止跑步時,此事件將以 0 的速度觸發。

另請參見:

參數

speed: number

Humanoid 的運行速度。


範例程式碼

演示如何連接到 Humanoid.Running 事件。該事件與每個加入的玩家的人形角色相連接。 連接的函數將根據速度印出人形角色是否在跑步。

人形角色跑步

local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local character = localPlayer.Character or localPlayer.CharacterAdded:Wait()
local humanoid = character:WaitForChild("Humanoid")
local function onRunning(speed: number)
if speed > 0 then
print(`{localPlayer.Name} 在跑步`)
else
print(`{localPlayer.Name} 停止了`)
end
end
humanoid.Running:Connect(function(speed: number)
onRunning(speed)
end)

Seated

此事件在 Humanoid 坐在 SeatVehicleSeat 中或站起來時觸發。

當角色接觸到座位時,他們會附著到座位上,並開始播放坐下的動畫。欲了解更多信息,請參閱 Seat 頁面。

  • 如果角色坐下,則 active 參數將為 true,而 currentSeatPart 將為他們當前坐著的座位。
  • 如果角色從座位上站起,則 active 參數將為 false,而 currentSeatPart 將為 nil

另請參閱:

參數

active: boolean

如果 Humanoid 正在坐下則為真。

currentSeatPart: BasePart

如果坐著,則 Humanoid 正在坐的座位。


範例程式碼

這段代碼範例展示了當本地玩家的

Character 坐下或站起時的情況。它應該放置

LocalScript 內的 StarterCharacterScripts 中,以便

在玩家角色重生時運行。

找到玩家的座位

local character = script.Parent
local humanoid = character:WaitForChild("Humanoid")
local function onSeated(isSeated, seat)
if isSeated then
print("我現在坐在: " .. seat.Name .. "!")
else
print("我現在沒有坐在任何地方")
end
end
humanoid.Seated:Connect(onSeated)

StateChanged

此事件在 Humanoid 的狀態改變時觸發。

由於不存在“閒置”人類狀態,您應該使用 Humanoid.Running 事件或監聽 RootPart 部分的 Velocity 來確定 Humanoid 是否靜止。

另請參閱

參數

人類的先前狀態類型。

人形目前的狀態類型。


範例程式碼

'當本地玩家的Player.Character跳躍時,發射粒子。要嘗試這段代碼示例,將其放在一個屬於StarterCharacterScriptsLocalScript中。'

跳躍粒子

local character = script.Parent
local primaryPart = character.PrimaryPart
-- 創建粒子
local particles = Instance.new("ParticleEmitter")
particles.Size = NumberSequence.new(1)
particles.Transparency = NumberSequence.new(0, 1)
particles.Acceleration = Vector3.new(0, -10, 0)
particles.Lifetime = NumberRange.new(1)
particles.Rate = 20
particles.EmissionDirection = Enum.NormalId.Back
particles.Enabled = false
particles.Parent = primaryPart
local humanoid = character:WaitForChild("Humanoid")
local isJumping = false
-- 監聽人類狀態
local function onStateChanged(_oldState, newState)
if newState == Enum.HumanoidStateType.Jumping then
if not isJumping then
isJumping = true
particles.Enabled = true
end
elseif newState == Enum.HumanoidStateType.Landed then
if isJumping then
isJumping = false
particles.Enabled = false
end
end
end
humanoid.StateChanged:Connect(onStateChanged)

'以下範例要求在 Humanoid 降落後需要一秒的冷卻時間 之後才能再次跳躍。 若要嘗試此範例,請將其放置在 LocalScript 中 在 StarterCharacterScripts|StarterPlayer.StarterCharacterScripts。'

跳躍冷卻

local character = script.Parent
local JUMP_DEBOUNCE = 1
local humanoid = character:WaitForChild("Humanoid")
local isJumping = false
humanoid.StateChanged:Connect(function(_oldState, newState)
if newState == Enum.HumanoidStateType.Jumping then
if not isJumping then
isJumping = true
humanoid:SetStateEnabled(Enum.HumanoidStateType.Jumping, false)
end
elseif newState == Enum.HumanoidStateType.Landed then
if isJumping then
isJumping = false
task.wait(JUMP_DEBOUNCE)
humanoid:SetStateEnabled(Enum.HumanoidStateType.Jumping, true)
end
end
end)

StateEnabledChanged

當在 Humanoid 上調用 Humanoid:SetStateEnabled() 時會觸發 StateEnableChanged 事件。

參數包括有關的 Enum.HumanoidStateType 和一個布爾值,以指示該狀態是否現在已啟用。

另請參閱:

參數

已更改的啟用狀態的 Enum.HumanoidStateType

isEnabled: boolean

如果狀態現在已啟用,則為 True。


範例程式碼

Players.LocalPlayer 的人形狀態發生變更時,下面的代碼

打印該狀態是否已啟用或禁用。

當放置在 LocalScript 中時,此代碼應該能正常運作。

人形狀態變更檢測器

local Players = game:GetService("Players")
local player = Players.LocalPlayer
\
local character = player.Character or player.CharacterAdded:Wait()
local humanoid\
= character:WaitForChild("Humanoid")
local function onStateEnabledChanged(state,\
enabled)
if enabled then
print(state.Name .. " 已啟用")
\ else
print(state.Name .. " 已禁用")
end
end
humanoid.StateEnabledChanged:Connect(onStateEnabledChanged)

Strafing

Humanoid 進入或離開 StrafingNoPhysics Enum.HumanoidStateType 時會觸發此事件。

Humanoid 進入 StrafingNoPhysics 狀態時,此事件將以 active 參數為 true 觸發。當 Humanoid 離開 StrafingNoPhysics 狀態時,該事件將再次觸發,並且 active 等於 false

此事件與 StrafingNoPhysics Humanoid 狀態相關,並且 會在 Humanoid 垂直於其面向方向移動時觸發。此狀態目前未使用,如果使用 Humanoid:ChangeState() 設置,狀態將恢復為 RunningNoPhysics

參數

active: boolean

Humanoid 是進入還是離開 StrafingNoPhysics Enum.HumanoidStateType


Swimming

HumanoidTerrain 水中游泳的速度發生變化時,此事件會觸發。

Humanoids 以其 Humanoid.WalkSpeed 的 87.5% 游泳。

Humanoid 停止游泳時,該事件不一定會以 0 的速度觸發。

另請參閱:

參數

speed: number

Humanoid 當前游泳的速度。


Touched

當人形的某一肢體與另一個 BasePart 接觸時,該事件會觸發。給出接觸的肢體及其接觸的 BasePart

Humanoid 的肢體與自身接觸時,該事件不會觸發。

替代方案

雖然 Humanoid.Touched 事件非常有用,但您應該考慮是否有更適合您需求的替代方案。

注意事項

參數

touchingPart: BasePart

Humanoid 接觸的 BasePart

humanoidPart: BasePart

被觸摸的 Humanoid 的肢體。


範例程式碼

'當放置在 Player.Character 模型內時,這段代碼將給予玩家


''彌達斯的觸碰''。他們角色觸碰的所有東西都會變成
黃金。
`Humanoid` 死亡時,此變化將被撤銷,並且金色的
`BasePart|BaseParts` 將回到其原始狀態。
要測試這個,將此代碼放在 `Script` 中,並將其放在
`StarterCharacterScripts|StarterPlayer.StarterCharacterScripts`'
彌達斯的觸碰

local character = script.Parent
local humanoid = character:WaitForChild("Humanoid")
local partInfo = {}
local debounce = false
local function onHumanoidTouched(hit, _limb)
if debounce then
return
end
if not hit.CanCollide or hit.Transparency ~= 0 then
return
end
if not partInfo[hit] then
partInfo[hit] = {
BrickColor = hit.BrickColor,
Material = hit.Material,
}
hit.BrickColor = BrickColor.new("Gold")
hit.Material = Enum.Material.Ice
debounce = true
task.wait(0.2)
debounce = false
end
end
local touchedConnection = humanoid.Touched:Connect(onHumanoidTouched)
local function onHumanoidDied()
if touchedConnection then
touchedConnection:Disconnect()
end
-- 撤銷所有的金色
for part, info in pairs(partInfo) do
if part and part.Parent then
part.BrickColor = info.BrickColor
part.Material = info.Material
end
end
end
humanoid.Died:Connect(onHumanoidDied)