Humanoid

顯示已棄用項目

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

人形是一種特殊物件,可讓模型獲得人物的功能。它授予模型以能夠

R6

  • 一個基本的角色網格,可以使用 6 個零件來表示手臂。
  • 頭部零件必須附在名為 Torso 的零件上,否則人形會立即死亡。
  • 身體零件外觀是使用 CharacterMesh 對象來應用。
  • 某些屬性,例如 Humanoid.LeftLegHumanoid.RightLeg,只與 R6 工作。

R15

  • 比 R6 更複雜,但也更靈活和穩定。
  • 對於手臂使用 15 個零件。
  • 頭部零件必須附在名為 UpperTorso 的零件上,否則人形將立即死亡。
  • BodyPart 外觀必須直接組裝。
  • 可以使用特殊 NumberValue 對象來動態重新縮放。
  • 人形會自動創建 Vector3Value 對象,名為 OriginalSize 內的每個手臂。
  • 如果數值值在人形體內有父輩,並且被命名為以追蹤中其中一個,它將被用來控制人形體的尺寸變更功能:
    • 身體深度規模
    • 身體高度
    • 身體寬度
    • 頭部

範例程式碼

This LocalScript makes the camera bobble as the player's character walks around, utilizing both the Humanoid's CameraOffset and MoveDirection. It should be parented inside of the StarterCharacterScripts so that it is distributed into a player's character as expected.

Walking Camera Bobble Effect

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 -- Is the character walking?
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
-- Scale down the CameraOffset so that it shifts back to its regular position.
humanoid.CameraOffset = humanoid.CameraOffset * 0.75
end
end
RunService.RenderStepped:Connect(updateBobbleEffect)

概要

屬性

方法

活動

屬性

AutoJumpEnabled

平行讀取

自動跳轉啟用設定是否啟用 Humanoid 跳向障礙時自動跳轉。

當前屬性只適用於下列條件:

  • 人形的角色模型是 Player.Character 的 Class.Player 。
  • 該玩家使用了觸摸控制。

當玩家的角色重生時,屬性的值與玩家的 Player.AutoJumpEnabled 屬性相符 - 這在 turn 與 StarterPlayer.AutoJumpEnabled 屬性。

範例程式碼

This code sample is meant for a TextButton. It allows the player to toggle the auto-jumping behavior while on a mobile device.

Auto-Jump Toggle

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local button = script.Parent
local function update()
-- Update button text
if player.AutoJumpEnabled then
button.Text = "Auto-Jump is ON"
else
button.Text = "Auto-Jump is OFF"
end
-- Reflect the property in the player's character, if they have one
if player.Character then
local human = player.Character:FindFirstChild("Humanoid")
if human then
human.AutoJumpEnabled = player.AutoJumpEnabled
end
end
end
local function onActivated()
-- Toggle auto-jump
player.AutoJumpEnabled = not player.AutoJumpEnabled
-- Update everything else
update()
end
button.Activated:Connect(onActivated)
update()

AutoRotate

平行讀取

自動旋轉屬性描述是否設定人形會自動旋轉以面向他們所走的方向。當設為真,角色模型會隨著人形走動而逐漸旋轉。當設為假,角色模型將保持在其旋轉方向的當前旋轉中,直到旋轉力量被適用到HumanoidRootPart

如果角色模型是玩家的角色,則人形的旋轉方式會受到 UserGameSettings 的 RotateType 屬性的影響。

設定自動旋轉屬性為真時,旋轉類型屬性會對人形體的旋轉產生以下效果:


<tbody>
<tr>
<td>移動相對</td>
<td />
<td />
</tr>
<tr>
<td>相機關係</td>
<td>角色會旋轉面向相攝影機的方向。</td>
<td>玩家有其鏡頭放大為第一人稱,或者他們處於 Shift 鎖定模式。</td>
</tr>
</tbody>
旋轉類型行為上下文

範例程式碼

This script adds the functionality of a button to a part, which switches the AutoRotate property of whoever touches it.

AutoRotate Button

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() .. " can no longer auto-rotate!")
humanoid.AutoRotate = false
else
print(humanoid:GetFullName() .. " can now auto-rotate!")
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

平行讀取

人形有六個子層級別,其中包括 BodyDepthScaleBodyHeightScaleBodyProportionScale 、 2> BodyTypeScale2> 、 5> HeadScale5> 。變更任何

BreakJointsOnDeath

平行讀取

決定人形的關節在 Enum.HumanoidStateType.Dead 狀態下是否斷裂。預設為 true。

CameraOffset

平行讀取

CameraOffset 屬性指定攝影機頭的主題位置時的 Offset 對鏡頭的主題位置 Class.Camera.CameraSubject 是設置為此 Class.Humanoid 。

偏移在對象空間中,與人形的 人形根部 的方向相對。例如,一個 Vector3 值的 (0、10、0) 將玩家的相機提升 10 格。

範例程式碼

This LocalScript makes the camera bobble as the player's character walks around, utilizing both the Humanoid's CameraOffset and MoveDirection. It should be parented inside of the StarterCharacterScripts so that it is distributed into a player's character as expected.

Walking Camera Bobble Effect

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 -- Is the character walking?
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
-- Scale down the CameraOffset so that it shifts back to its regular position.
humanoid.CameraOffset = humanoid.CameraOffset * 0.75
end
end
RunService.RenderStepped:Connect(updateBobbleEffect)
平行讀取

顯示距離類型 屬性控制人形名稱和健康顯示的距離行為。此屬性使用 Enum.HumanoidDisplayDistanceType 枚表示,並且有三個可用值,每個值都有自己的規則集:

  • 當設為 Viewer 時,人形會在範圍內的其他人形名稱/健康值,並且在 NameDisplayDistanceHealthDisplayDistance 中顯示。
  • 當設為 Subject 時,人形會在其自己的名稱和健康顯示上通過其 NameDisplayDistanceNameDisplayDistance 值來取得完全控制。
  • 當設為 None 時,人形的名稱和健康狀態條不會在任何情況下顯示。

有關控制角色名稱和生命值欄的顯示方式,請參閱 角色名稱/生命值顯示

範例程式碼

This example demonstrates how to set a Humanoid's Humanoid.DisplayerDistanceType, Humanoid.HealthDisplayDistance, and Humanoid.NameDisplayDistance properties. These properties determine how a humanoid's healthbar and name are rendered for a player.

First, we change the DisplayDistanceType to Viewer using Enum.HumanoidDisplayDistanceType. When set to viewer, the humanoid's Name and healthbar will be displayed based on the distance settings of the humanoid viewing them.

Then, the humanoid's HealthDisplayDistance is set to 0. Setting the property to 0 hides the healthbar completely. It is not displayed at any distance.

Finally, the humanoid's NameDisplayDistance is set to 100. This means that the humanoid's name will be visible to other humanoid's within 100 studs.

This example should work as expected when placed inside a Script that is a child of the humanoid.

Displaying a Humanoid's Health and Name

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

DisplayName

平行讀取

DisplayName 是一個決定人形顯示時人形名稱顯示值的屬性。 預設情況下,新的人形會有空字串的值。如果DisplayName是空字串,人形的名稱顯示會預設為人形的父元素的名稱。

玩家角色載入

玩家載入他們的角色時,會自動或通過使用 LoadCharacter() 創建的人形會設置為玩家的 DisplayName 屬性。

新手角色和新手人形

HumanoidStarterHumanoid 為父字串,或者當 StarterPlayer

EvaluateStateMachine

平行讀取

FloorMaterial

唯讀
未複製
平行讀取

這是一個只能讀取的屬性,描述 Enum.Material 正在踩踏的 Humanoid。它與常常使用的 Parts 和 2>Class.Terrain2> 模型協作。

下面的代碼示範了如何在使用 Object:GetPropertyChangedSignal() 來聆聽當這個屬性變更時。當材料站在人形上時,它會列出一個訊息,表示新材料正在上面。


local Humanoid = route.to.humanoid
Humanoid:GetPropertyChangedSignal("FloorMaterial"):Connect(function()
print("New value for FloorMaterial: " .. tostring(Humanoid.FloorMaterial))
end)

洞穴

  • Humanoid 不在地板上時,此屬性的值將設置為 Air
    • 這是因為枚列的屬性不能有空值。
    • 如果零件的材料設為空氣,這可能會導致一些混亂,但在實際上,零件不應該使用這種材料。
  • Humanoid 的角色模型必須能夠與地面碰撞,否則它不會被偵測到。

Health

未複製
平行讀取

此屬性代表 Humanoid 的當前健康狀況。值是由 0 到 MaxHealth 之間的範圍來設定的。如果人形死亡,此屬性將一直設置為 0。

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

生命值恢復

預設情況下,一個被動的生命值恢復指令將自動插入到人形體中。這會導致非死玩家角色每秒重生 1% 的 MaxHealth 。若要停用此恢復行為,請將空白 Script 命名為 生命值 並將其添加到

健康狀態顯示

Health 小於 MaxHealth 時,會在體驗中顯示健康條。 顯示健康條的顯示方式取決於 HealthDisplayDistance 和 1> Class.Humanoid.HealthDisplayType|HealthDisplay

有關控制角色名稱和生命值欄的顯示方式,請參閱 角色名稱/生命值顯示

死亡

當角色的生命值達到 0 時,Humanoid 會自動切換到Enum.HumanoidStateType.Dead 狀態。在此狀態中,Health 鎖定在 0 ;但在設置死亡人形到正向非零值的

HealthDisplayDistance

平行讀取

此屬性是 DisplayDistanceType 屬性的數字,用於控制人形的健康狀態條可以從哪裡查看。

有關控制角色名稱和生命值欄的顯示方式,請參閱 角色名稱/生命值顯示

平行讀取

此屬性控制人形的生命值顯示。 預設值為 DisplayWhenDamaged ,以顯示人形的生命值只是

注意,此屬性與人形的 HealthDisplayDistance 屬性,負責使健康條在特定距離消失。如果 Humanoid.HealthDisplayType|HealthDisplayType 設為 Enum.HumanoidHealthDisplayType

有關控制角色名稱和生命值欄的顯示方式,請參閱 角色名稱/生命值顯示

HipHeight

平行讀取

決定在地面上RootPart 的距離,當人形站立時。RigType 會影響此屬性的行為。

對於 R15 裝備,預設的腳踝高度是可以確保 RootPart 的高度正確。腳踝高度不是使用。人形體的總高度可以在以下方程式中描述:


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

對於 R6 網格,HipHeight 代表相對偏移值。人形高度可以在以下方程式中描述:


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

Jump

未複製
平行讀取

如果 true 跳躍時,上向力與 HumanoidHumanoid.JumpPower 的值等同,取決於 2>Class.Humanoid.UseJumpPower2> 的值。

JumpHeight

平行讀取

提供對 Humanoid 跳躍的高度的控制,以 StarterPlayer.CharacterJumpHeight 的價格。這個屬性的起始值是 Class.StarterPlayer.CharacterJumpHeight 的值,預設為 7.2。

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

此屬性只在 屬性 視窗中可見,如果 Humanoid.UseJumpPower 設為 關閉 ,因為它不適合其他情況 (而是在 1> Class.Humanoid.JumpPower1> 的情況下使用)。

JumpPower

平行讀取

決定向上力的應用對 Humanoid 跳躍時會應用的力量。 啟始值此屬性的值是由 StarterPlayer.CharacterJumpPower 的值決定,其預設值為 50 並受到 0 和 1000 之間的限制。 注意跳躍會受到 Class.Workspace

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

此屬性只在 屬性 視窗中可見,如果 Humanoid.UseJumpPower 設為 true ,因為它不適合其他情況 (而是在 1> Class.Humanoid.JumpHeight1> 是使用)。

MaxHealth

平行讀取

人形的 Health 的最大值。

此屬性的值與 Health 屬性用於調整預設健康條顯示。當人形的 Health 達到 MaxHealth 時,其健康條可能不會顯示,這取決於

MaxSlopeAngle

平行讀取

此屬性決定人形可以攀爬的最大斜角。如果斜角的角度大於人形的最大斜角,人形就會向下溜滑。

當角色重生時,此屬性會依據 StarterPlayer.CharacterMaxSlopeAngle 的值設定。

此屬性的值是受到 0° 和 89° 之間的值限制。它的預設值是 89°,因此人形可以爬攀任何他們想要的斜坡。

範例程式碼

The example below demonstrates the effect of the MaxSlopAngle property by limiting the maximum slope the Players.LocalPlayer can walk up to 30°. The local player will slide down any slope greater than 30°.

This code below works as expected when placed in a LocalScript.

Limiting The Slope a Humanoid Can Walk Up

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

MoveDirection

唯讀
未複製
平行讀取

移動方向 是一個只有讀取的屬性,用於描述 Humanoid 走入的方向,作為單位向量或零長度向量力。方向在世界空間中描述。

因為此屬性只能由 ScriptLocalScript 設置,因此無法由 Class.Script 或 1>Class.LocalScript1> 設置。

範例程式碼

This LocalScript makes the camera bobble as the player's character walks around, utilizing both the Humanoid's CameraOffset and MoveDirection. It should be parented inside of the StarterCharacterScripts so that it is distributed into a player's character as expected.

Walking Camera Bobble Effect

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 -- Is the character walking?
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
-- Scale down the CameraOffset so that it shifts back to its regular position.
humanoid.CameraOffset = humanoid.CameraOffset * 0.75
end
end
RunService.RenderStepped:Connect(updateBobbleEffect)

NameDisplayDistance

平行讀取

名稱顯示距離 屬性是用於與 Humanoid.DisplayDistanceType 屬性配合使用,以控制人形的名稱在哪裡可以看到的距離。

有關控制角色名稱和生命值欄的顯示方式,請參閱 角色名稱/生命值顯示

NameOcclusion

平行讀取

控制人形體的名稱和健康狀況條可以在牆壁或其他物體後面顯示。此屬性是 Enum.NameOcclusion 值,可以設定所有名稱、敵名或停用 occlusion 全部。

LocalPlayer 沒有 Humanoid 時,此屬性適用於 Humanoid 的主題。

有關控制角色名稱和生命值欄的顯示方式,請參閱 角色名稱/生命值顯示

範例程式碼

In the below example, Player|Players will not be able to see each other's Player.Character names when they are obscured behind BasePart|BaseParts.

Occlude Player Names

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 狀態。當 是 時,人形會在一個徹底落下的狀態,無法移動工具。這種狀態與坐下相似,但跳躍會從人形狀態中解開。

RequiresNeck

平行讀取

允許開發人員停用玩家 Character|character 死亡,如果 Motor6D 被移除或斷開,甚至是暫時。此屬性預設為 true。

平行讀取

RigType 描述是否使用 Humanoid 或是否使用新的 R15 角骨架 R6 網骨架。

R6 裝備使用 6 個可見的 Parts 而 R15 裝備使用 15 個可見的 Parts。R15 裝備的關節比 R6 裝備多,使它們在動畫時更靈活。

注意,如果此屬性設置不正確,Humanoid 將無法正確運作。例如,如果 R15 的 機甲型號 設置為 R6,Humanoid 將死亡,因為沒

RootPart

唯讀
未複製
平行讀取

一個人形根的 人形根 對物件,是控制人形移動的 3D 世界的根頂部分。此部分通常隱藏。

注意,玩家角色的情況下, RootPartModel.PrimaryPart 模型的 Player.Character 相同。

SeatPart

唯讀
未複製
平行讀取

SeatPart 是一個引用座椅的座椅,如果有的話。這個屬性的值可以是 Humanoid ,或 Seat。如果沒有人坐在座椅上,它將是 VehicleSeat。 如果 2>Class.Humanoid2> 未坐在座椅上,它將是 5>Class.VehicleSeat

注意:

Sit

平行讀取

The Sit 屬性是一個Boolean,指示是否有Humanoid正在坐下。Humanoids 可以通過設置此屬性的值為Humanoid強制坐下。如果2> Class.Humanoid

注意:

TargetPoint

平行讀取

不要使用 此屬性只適用於啟用實驗性模式的,此模式已全面停止。

此屬性描述在空間中的 3D 位置,其中 Player 正在使用此 Humanoid 最後點擊時,裝備了 Tool

此屬性主要由類型工具用來確定人形標籤時,人形正在瞄準的目標是什麼。如果您給 NPC 一個經典火箭發射器,設定他們的 目標點 ,然後呼叫工具的 Tool:Activate() 函數,NPC 就會發射火箭到目標點。

UseJumpPower

平行讀取

當角色重生時,這個屬性會依據 StarterPlayer.CharacterUseJumpPower 的值設定,其預設值為 true。

跳躍時,將這個設為真,Humanoid.JumpHeight 值將用於確保人形跳躍到達那個高度。將它設為Humanoid.JumpPower 值,Class.Humanoid.JumpPower(向上) 值將用於應用向上的力。

WalkSpeed

平行讀取

此屬性描述Humanoid 每秒鐘能步行的速度,以每秒StarterPlayer.CharacterWalkSpeed (16) 的值預設。 它預設值為Class.Humanoid 每秒2>Class.StarterPlayer.CharacterWalkSpeed2> (16),意味著玩家角色每秒能移動12個學校。

注意

  • 當在移動設備或遊戲控制器上控制時,人形可以比其 WalkSpeed 慢,如果控制握柄暢度從中心移動,就可以達到一個傾斜度。
  • 您可以將人形凍結在原位,設置 WalkSpeed 為 0;這會防止控制玩家移動它通過預設移動機制。
  • 預設動畫腳本會根據人形的移動速度(相對於 16 個/秒的預設速度)來調整人形的移動動畫。
  • Class.Humanoid 目前走路的速度可以使用 Running 事件來取得。

WalkToPart

平行讀取

WalkToPart 是指人形正在嘗試達到的部分。這個屬性通常設置為人形的第 2 個參數,當人形的 Humanoid:MoveTo() 函數傳送為第 2 個參數。

當 WalkToPart 設定和人形正在嘗試達到零件時,它會繼續更新其 Vector3 目標為零件的位置,並且在對零件的旋轉相對於零件的旋轉。

這可以在 Lua 中描述為:


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

洞穴

  • 設定 WalkToPart 的值不足以在零件後執行人形化。
  • 人形會提示開始嘗試達到目標,當 WalkToPoint 的值變更。
  • 這可能會在未來變更。
  • 人形體的 達到目標 狀態將在 8 秒後過時,如果它沒有達到目標。
  • 這是為了讓 NPC 不會被卡住等待 Humanoid.MoveToFinished 發觸發。
  • 如果您不想發生此情況,您應該重複地呼叫 MoveTo 以確保時間到達後將會重置。

WalkToPoint

平行讀取

WalkToPoint 描述人形正在嘗試達到的 3D 位置,後者由人形的 Humanoid:MoveTo() 函數提示所做。

如果設設定了 Humanoid.WalkToPart ,目標是由變形 WalkToPoint 相對位置和旋轉來設置。如果未設設定 WalkToPart,則會嘗試直接將 3D 位置指定為 WalkToPoint 所指定位置。

洞穴

  • WalkToPoint 的值必須變更為其他值,才能讓人形向它開始走路。
  • 如果您想要使用 0,0,0 的人形漫步,您應該使用人形的 MoveTo 功能。
  • 這可能會在未來變更。
  • 人形體的 達到目標 狀態將在 8 秒後過時,如果它沒有達到目標。
  • 這是為了讓 NPC 不會被卡住等待 Humanoid.MoveToFinished 發觸發。
  • 如果您不想發生此情況,您應該重複地呼叫 MoveTo 以確保時間到達後將會重置。

範例程式碼

This code sample includes a function that avoids the 8 second timeout on Humanoid:MoveTo() by calling Humanoid:MoveTo() again before the timeout elapses. It also includes an optional andThen parameter where developers can pass a function to be called when the humanoid reaches its destination.

Humanoid MoveTo Without Time out

local function moveTo(humanoid, targetPoint, andThen)
local targetReached = false
-- listen for the humanoid reaching its target
local connection
connection = humanoid.MoveToFinished:Connect(function(reached)
targetReached = true
connection:Disconnect()
connection = nil
if andThen then
andThen(reached)
end
end)
-- start walking
humanoid:MoveTo(targetPoint)
-- execute on a new thread so as to not yield function
task.spawn(function()
while not targetReached do
-- does the humanoid still exist?
if not (humanoid and humanoid.Parent) then
break
end
-- has the target changed?
if humanoid.WalkToPoint ~= targetPoint then
break
end
-- refresh the timeout
humanoid:MoveTo(targetPoint)
task.wait(6)
end
-- disconnect the connection if it is still connected
if connection then
connection:Disconnect()
connection = nil
end
end)
end
local function andThen(reached)
print((reached and "Destination reached!") or "Failed to reach destination!")
end
moveTo(script.Parent:WaitForChild("Humanoid"), Vector3.new(50, 0, 50), andThen)

方法

AddAccessory

void

此方法將指定的 Accessory 附加到人形的父父元素。

當此方法呼叫時,會在人形的父親搜尋<a href="/reference/engine/databases/databases.md

如果找不到要求的 Attachment,則 Accessory 將繼續與人形的父親關聯,但將不會被分離。

一般來說,配件焊接在服務伺服器上創建,但在某些情況下,它們可以在客戶端上作品建。在這些情況下,客戶端對 AddAccessory() 的呼叫可能無法產生預期的行為,您可以使用 Class.Humanoid:BuildRigFromAttachments

參數

accessory: Instance

Class.Accessory 可附加。


返回

void

範例程式碼

This script generates the "Clockwork's Shades" Accessory from scratch, and then attaches it to the player's character using Humanoid.AddAccessory You should paste this code into a regular script, and then parent it inside of the StarterPlayer's StarterCharacterScripts folder.

[Humanoid] AddAccessory Example

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)

BuildRigFromAttachments

void

此方法組合 Motor6D 樹的關節以獲得 HumanoidMotor6D 關節需要用於播放 2>Class.Animation|Animations2> 。

從人形的 RootPart 開始,此方法會收集所有 Attachments 在當前零件的名稱以結尾以 Rig附件

Humanoid:BuildRigFromAttachments() 也會調整角色大小和設定身體顏色。


返回

void

範例程式碼

A Lua port of the Humanoid's BuildRigFromAttachments function, so that the recursive behavior of the function can be seen.

Lua Port of 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
-- first, loop thru all of the part's children to find attachments
for _, attachment in pairs(part:GetChildren()) do
if attachment:IsA("Attachment") then
-- only do joint build from "RigAttachments"
local attachmentName = attachment.Name
local findPos = attachmentName:find("RigAttachment")
if findPos then
-- also don't make double joints (there is the same named
-- rigattachment under two parts)
local jointName = attachmentName:sub(1, findPos - 1)
if not part:FindFirstChild(jointName) then
-- try to find other part with same rig attachment name
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 has no 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)

A script that generates an R15 character from scratch using a package's assetId.

R15 Package Importer

local AssetService = game:GetService("AssetService")
local InsertService = game:GetService("InsertService")
local MarketplaceService = game:GetService("MarketplaceService")
local PACKAGE_ASSET_ID = 193700907 -- Circuit Breaker
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

void

此功能會使 Humanoid 進入提供的 Enum.HumanoidStateType,描述 Humanoid 目前正在執行的活動。

請查看 Enum.HumanoidStateType 頁面獲取更多關於特定狀態的資訊,因為有些有不直觀的名稱。例如, Enum.HumanoidStateType.Running 描述人體的腳踝在地上,包括站立時。

因為 Humanoid 的預設行為,一些狀態將在設定時自動變更。例如:

也 see Humanoid:SetStateEnabled() 以啟用或啟用特定狀態,和 Humanoid:GetState() 以取得當前狀態。

參數

Class.Humanoid 要執行的 Humanoid

預設值:"None"

返回

void

範例程式碼

This code, when placed inside a LocalScript in StarterPlayer.StarterCharacterScripts, will allow the player's character to perform a double jump.

Double Jump

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

void

此功能使 Humanoid 裝備指定的 Tool

下面的例子會導致 Player 裝備 Workspace 中的工具,名為 'Tool'


local Players = game:GetService("Players")
local player = Players:FindFirstChildOfClass("Player")
if player and player.Character then
local humanoid = player.Character:FindFirstChildWhichIsA("Humanoid")
if humanoid then
local tool = workspace:FindFirstChild("Tool")
if tool then
humanoid:EquipTool(tool)
end
end
end

當此函數呼叫時,人形會自動卸下其目前裝備的任何 Tools

雖然它們將被裝備,Tools 對於 Tool.RequiresHandle 的使用 Class.Tool.ToolRequiresHandle 將無法手把作,無論是否使用此功能來裝備它們

也看:

參數

tool: Instance

裝備 Tool


返回

void

GetAccessories

此函數將返回人形的父親目前穿著的 Class.Accessory 對象的陣列。所有此類 Class.Accessory 對象將包含,無論是否附加。

如果 Humanoid 沒有 Accessory 對象,將返回空陣。

也 see Humanoid:AddAccessory() 以將 Accessory 附加到人形的父元素。


返回

一個 Accessory 對象,是人形的父元素級。

範例程式碼

This code sample will wait for accessories to fully load, print out how many there are, and then destroy them all.

Remove Accessories After Loading

local Players = game:GetService("Players")
local function onPlayerAddedAsync(player)
local connection = player.CharacterAppearanceLoaded:Connect(function(character)
-- All accessories have loaded at this point
local humanoid = character:FindFirstChildOfClass("Humanoid")
local numAccessories = #humanoid:GetAccessories()
print(("Destroying %d accessories for %s"):format(numAccessories, player.Name))
humanoid:RemoveAccessories()
end)
-- Make sure we disconnect our connection to the player after they leave
-- to allow the player to get garbage collected
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

此功能返回 Enum.BodyPartR15Part 的實際體部名稱,或 Enum.BodyPartR15.Unknown 如果體部不是 R15 體部。此功能允許開發人員擷取玩家的身體部位,無論其實際身體部位名稱是什麼,而是擷回一個枚數。

它可以與 Humanoid:ReplaceBodyPartR15() 一起使用。例如,如果玩家的身體部位碰到某個東西,此功能將返回獲取零件實個體、實例。開發人員可以然後查看哪個部位是身體的,例如頭或手臂。然後,根據那個部位是什麼,開發人員可以執行一些遊戲操作或替換其

此功能可能對於遊戲中,重要的擊中位置。例如,它可以用來決定玩家是否在腿上受傷,並根據傷害慢他們。

參數

part: Instance

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


返回

指定零件的 R15 身體零件類型或未知,如果零件不是身體零件。

GetLimb

此功能返回與指定 Enum.Limb 遊戲機器板相關的 Part 枚列表,作為 R15 和 R6 遊戲機器板的預設值。它對於 R15 和 R6 遊戲機器板的兩個版本都有效:


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

注意, Humanoid:GetLimb() 將會發生錯誤,如果零件的父親沒有設為人形的父父元素。

參數

part: Instance

Class.Part 的 Enum.Limb 將要取回。


返回

enum.Limb 與零件對應。

範例程式碼

Put this in a LocalScript. The output will vary based on if the humanoid is R6 or R15.

Getting a Humanoid's Limbs

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 .. " is part of limb " .. limb.Name)
end
end

GetMoveVelocity


返回

平行寫入

此函數返回人形的當前 Enum.HumanoidStateType,描述人形正在執行的活動,例如跳躍或游泳。

也 see Humanoid:SetStateEnabled() 以啟用或啟用特定狀態,和 Humanoid:ChangeState() 變更當前人形狀態。


返回

Class.Humanoid 的當前 Humanoid

範例程式碼

This code, when placed inside a LocalScript in StarterPlayer.StarterCharacterScripts, will allow the player's character to perform a double jump.

Double Jump

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.HumanoidStateTypeHumanoid 是否啟用。

人狀態描述人目前正在執行的活動。

當特定 Enum.HumanoidStateType 被禁用時,人形將永遠無法進入此狀態。這是無論使用 Humanoid:ChangeState() 或 Roblox 內部人形代碼來變更狀態都是如此。

也看:

參數

枚數.HumanoidStateType 。


返回

是否啟用 Enum.HumanoidStateType 指定的類型。

範例程式碼

The code below sets the value of the humanoid jumping state to false using Humanoid:SetStateEnabled() and then retrieves and prints the value of this state (false) using Humanoid:GetStateEnabled().

Setting and Getting Humanoid States

local humanoid = script.Parent:WaitForChild("Humanoid")
-- Set state
humanoid:SetStateEnabled(Enum.HumanoidStateType.Jumping, false)
-- Get state
print(humanoid:GetStateEnabled(Enum.HumanoidStateType.Jumping)) -- false

Move

void

此功能使 Humanoid 走在指定的 Vector3 方向。

由預設情況下,方向是以世界單條款,但如果 relativeToCamera 參數是 true,方向是相對於 CFrame 的 2>Class.Workspace.CurrentCamera|CurrentCamera2> 的方


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

當此功能呼叫時,Humanoid會移動直到此功能再次呼叫。但如果使用預設控制指令碼,則Characters會在呼叫此功能時被覆蓋。這可以通過使用預設控制指令碼或使用 RunService:BindToRenderStep() (見示例) 來

此功能可以在服務伺服器上呼叫,但這只能在服務器擁有 人形網路擁有 的裝配時執行。

也看 Humanoid:MoveTo() 使 Humanoid 走到一個點,和 Player:Move() 這個基本上會呼叫此函數的方法。

參數

moveDirection: Vector3

走路的方向。

relativeToCamera: bool

true 設定為 moveDirection 參數,如果 CurrentCamera 的參數應該與相對位置 2> Class.Workspace.CurrentCamera|CurrentCamera2> 設定。

預設值:false

返回

void

範例程式碼

This code sample uses the Humanoid:Move() function to make the player's Character walk in the direction of the Camera. RunService:BindToRenderStep() is required here as the default control scripts will overwrite the player's movement every frame.

To run this sample, place it inside a LocalScript parented to StarterCharacterScripts.

Moving a Humanoid Forwards

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

void

此功能會導致 Humanoid 嘗試走向指定位置,並設定 Humanoid.WalkToPointHumanoid.WalkToPart 屬性。

位置 和 零件 參數與 Humanoid.WalkToPoint 和 1>Class.Humanoid.WalkToPart1> 設定的相關。

如果 零件 參數指定,Humanoid 仍會嘗試走到點。但如果零件移動,Humanoid 將會移動到同一位置1>相對於零件1>。如果 4>零

達到目標州 的人形會在 8 秒後到達目標,否則將在 10 秒後到達目標。這是為了讓 NPC 不會被困在等待 Humanoid.MoveToFinished 發觸發。如果您不想這樣發生,您應該重複地呼叫 MoveTo 以使時間延遲重置。

MoveTo() 會結束,如果任何以下情況適用:

  • 角色抵達目的地。

  • 角色卡住,八秒計時器過期。

  • Class.Humanoid.WalkToPoint 或 Humanoid.WalkToPart 的值。

  • 一個腳本使用 Humanoid:Move() 並且使用新的 moveDirection 參數。

  • 一個腳本會改變 CFrameRootPart 屬性。

參數

location: Vector3

設置 Humanoid.WalkToPoint 的位置。

part: Instance

Class.BasePart 設置 Humanoid.WalkToPart

預設值:"nil"

返回

void

範例程式碼

This code sample includes a function that avoids the 8 second timeout on Humanoid:MoveTo() by calling Humanoid:MoveTo() again before the timeout elapses. It also includes an optional andThen parameter where developers can pass a function to be called when the humanoid reaches its destination.

Humanoid MoveTo Without Time out

local function moveTo(humanoid, targetPoint, andThen)
local targetReached = false
-- listen for the humanoid reaching its target
local connection
connection = humanoid.MoveToFinished:Connect(function(reached)
targetReached = true
connection:Disconnect()
connection = nil
if andThen then
andThen(reached)
end
end)
-- start walking
humanoid:MoveTo(targetPoint)
-- execute on a new thread so as to not yield function
task.spawn(function()
while not targetReached do
-- does the humanoid still exist?
if not (humanoid and humanoid.Parent) then
break
end
-- has the target changed?
if humanoid.WalkToPoint ~= targetPoint then
break
end
-- refresh the timeout
humanoid:MoveTo(targetPoint)
task.wait(6)
end
-- disconnect the connection if it is still connected
if connection then
connection:Disconnect()
connection = nil
end
end)
end
local function andThen(reached)
print((reached and "Destination reached!") or "Failed to reach destination!")
end
moveTo(script.Parent:WaitForChild("Humanoid"), Vector3.new(50, 0, 50), andThen)

RemoveAccessories

void

此功能移除所有 Accessory 穿著人父元素的家長所穿著的對象。對於玩家 Characters,這會移除所有帽子和其他配件。

此功能會在 Instance:Destroy() 上呼叫 Parent ,意味著配件的上級將設置為 1>nil1> 並且鎖定。

也 see Humanoid:AddAccessory() 以附加 Accessory ,和 Humanoid:GetAccessories() 以取得所有屬於 1> Class.Accessory1> 對象。


返回

void

範例程式碼

This code sample will wait for accessories to fully load, print out how many there are, and then destroy them all.

Remove Accessories After Loading

local Players = game:GetService("Players")
local function onPlayerAddedAsync(player)
local connection = player.CharacterAppearanceLoaded:Connect(function(character)
-- All accessories have loaded at this point
local humanoid = character:FindFirstChildOfClass("Humanoid")
local numAccessories = #humanoid:GetAccessories()
print(("Destroying %d accessories for %s"):format(numAccessories, player.Name))
humanoid:RemoveAccessories()
end)
-- Make sure we disconnect our connection to the player after they leave
-- to allow the player to get garbage collected
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

Class.Part Instance 將會成為角色的親級。


返回

SetStateEnabled

void

此功能設定是否啟用 Enum.HumanoidStateType 中的 Humanoid 。當特定 Enum.HumanoidStateType 被禁用時, 2>Class.Humanoid2> 無法進碼該��

注意,使用 SetStateEnabled() 在服務器上複製變更對於客戶端也不會重複。

參數

enum.humanoidstate type 以啟用或禁用。

enabled: bool

true 如果 state 要啟用,false 如果 0> state0> 要禁用。


返回

void

範例程式碼

The following sample will require a one second cooldown after a Humanoid has landed before it is able to jump again.

To try this sample, place it inside a LocalScript in StarterCharacterScripts|StarterPlayer.StarterCharacterScripts.

Jump Cooldown

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

void

此功能將 Humanoid.HealthHumanoid 降低給予的 number 如果未受到 2>Class.ForceField2> 保護

此函數接受 數量 參數的負值。這將增加人形的 Humanoid.Health。但是此只會有效,如果沒有 ForceField 存在。

ForceFields 如何防止 TakeDamage

Class.Humanoid 被視為受到保護,如果 ForceField 達到以下條件之一:

無論任何 Humanoid 現有,設置 ForceFields 直接。

了解有關 ForceFields 保護 Humanoids 的更多信息,請參閱 ForceField 頁面

參數

amount: number

傷害,或從 Humanoid.Health 中減去的金額。


返回

void

範例程式碼

This code, put in a LocalScript, would make the local player take 99 damage only if a ForceField wasn't present.

Damaging a 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

void

此功能已裝備 Tool 的任何 Humanoid 裝備

未裝備的 Tool 將會在 BackpackPlayer 與 1> Class.Humanoid1> 中屬性給予 。

如果沒有 Tool 裝備,此功能將無法執行。

雖然 Tools 可以裝備 NPC (非玩家角色),但此功能只適用於 Humanoids 與相應的 Player 。這是因為需要一個 1> Class.Backpack1> 對未裝備的 4> Class.Tool

也看:


返回

void

範例程式碼

The following sample will bind the U key to unequip any Tool|Tools the Player currently has equipped.

To use this sample, place it inside a LocalScript within StarterPlayerScripts|StarterPlayer.StarterPlayerScripts.

Unequip Tool Keybind

local Players = game:GetService("Players")
local ContextActionService = game:GetService("ContextActionService")
local player = Players.LocalPlayer
ContextActionService:BindAction("unequipTools", function(_, userInputState)
if userInputState == Enum.UserInputState.Begin then
if player.Character then
local humanoid = player.Character:FindFirstChildOfClass("Humanoid")
if humanoid then
humanoid:UnequipTools()
end
end
end
end, false, Enum.KeyCode.U)

ApplyDescription

void
暫停

這個輸出函數使角色的外觀與通過 HumanoidDescription 中的匹配。複製傳來的 HumanoidDescriptionHumanoidDescription 對於 1> Class.Human1> 的 4> Class.HumanoidDescription4> 。

此功能最佳化通過假設只有此功能可以變更角色的外觀,並且在其他方式之間沒有更改。如果在更改之後對角色進行更改。 此功能可能無法準確地反射傳送到角色之間的更新。如果您想要與其他方式一起使

也看看

參數

humanoidDescription: HumanoidDescription

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

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

返回

void

ApplyDescriptionReset

void
暫停

這個輸出函數使角色看起來與通過 HumanoidDescription 中的傳來的相同,即使是外部變更。一個傳來的 HumanoidDescription 副本是複製為 HumanoidDescription 為 1> Class.Human1> 的。

此功能將始終確保角色反映通過 HumanoidDescription

參數

humanoidDescription: HumanoidDescription

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

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

返回

void

PlayEmote

暫停

如果 emote 無法播放,因為人形描述中找不到 emoteName,這個 API 將發生錯誤。API 將以真返回,表示 emote 成功播放。

參數

emoteName: string

玩 遊玩放的表情的名稱。


返回

成功播放。

活動

ApplyDescriptionFinished

參數

description: HumanoidDescription

Climbing

發射 Humanoid 的速度,當它在攀爬時變化的速度。

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

Humanoids 在 70% 的速度 Humanoid.WalkSpeed 上攀爬。

此事件不會一直以0的速度發射,當Humanoid停止攀爬時。

也看:

參數

speed: number

Class.Humanoid 目前正在上升的速度。


範例程式碼

Humanoid.Climbing

local Players = game:GetService("Players")
local function onCharacterClimbing(character, speed)
print(character.Name, "is climbing at a speed of", speed, "studs / second.")
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 的後代。如果 Dead2>枚數.HumanoidStateType2> 已停用,它就不會發觸發。


範例程式碼

The code below would print the player's name, followed by "has died!", whenever a player dies. For example, if the player was named "Shedletsky", "Shedletsky has died!" would be printed to the output when they died.

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, "has died!")
end
humanoid.Died:Connect(onDied)
end
player.CharacterAdded:Connect(onCharacterAdded)
end
Players.PlayerAdded:Connect(onPlayerAdded)

FallingDown

下降事件發生當 Humanoid 進入和離開 FallingDown``Enum.HumanoidStateType

Class.Humanoid 將在啟用 GettingUp 狀態後的 3 秒後進入 FallingDown 狀態。當發生這個事件時,發生器會發出一個 1> 有效值為 4>4> 的 <

參數

active: bool

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


FreeFalling

此事件發生,當 Humanoid 進入或離開 Freefall``Enum.HumanoidStateType

active參數代表是否要進入或離開Humanoid 參數。

雖然 Freefall 狀態通常會在 Humanoid 達到地面時結束,但此事件可能會在 啟用 與 <

參數

active: bool

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


GettingUp

這個事件會發生當 Humanoid 進入或離開 Enum.HumanoidStateType.GettingUp 狀態,這是一個啟動於 Humanoid 進入 1>Container.HumanoidStateType.FallingDown|Falling

Humanoid 嘗試重新起來時,這個事件會先以 active 參數的 true 發射,然後稍後以 2>active2> 參數的 5>force5> 發射,再重新以 8>force8> 參數的 Humanoid1> 發射。

要強制 Humanoid 掉落,請使用 Humanoid:ChangeState() 函數,並且使用 Enum.HumanoidStateType.FallingDown

參數

active: bool

Class.Humanoid 是否正在進入或離開 GettingUp``Enum.HumanoidStateType


HealthChanged

此事件發生當 Humanoid.Health 變更時。但不會發生如果生命值增加到等值或大於 Humanoid.MaxHealth 的值。

Humanoid.Health 達到零時, Humanoid 會死觸發,並且發生 Humanoid.Died 事件。這個事件會發生於零值。

參數

health: number

Class.Humanoid.Health 的新值。


範例程式碼

The following example determines the change in health, printing it to the output. It will only work in a 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("The humanoid's health", (currentHealth > health and "decreased by" or "increased by"), change)
currentHealth = health
end
humanoid.HealthChanged:Connect(onHealthChanged)
end
player.CharacterAdded:Connect(onCharacterAdded)

This code sample allows you to create a simple color-changing health bar using two nested Frames. Paste this into a LocalScript on the inner frame.

Health Bar

local Players = game:GetService("Players")
local player = Players.LocalPlayer
-- Paste script into a LocalScript that is
-- parented to a Frame within a Frame
local frame = script.Parent
local container = frame.Parent
container.BackgroundColor3 = Color3.new(0, 0, 0) -- black
-- This function is called when the humanoid's health changes
local function onHealthChanged()
local human = player.Character.Humanoid
local percent = human.Health / human.MaxHealth
-- Change the size of the inner bar
frame.Size = UDim2.new(percent, 0, 1, 0)
-- Change the color of the health bar
if percent < 0.1 then
frame.BackgroundColor3 = Color3.new(1, 0, 0) -- black
elseif percent < 0.4 then
frame.BackgroundColor3 = Color3.new(1, 1, 0) -- yellow
else
frame.BackgroundColor3 = Color3.new(0, 1, 0) -- green
end
end
-- This function runs is called the player spawns in
local function onCharacterAdded(character)
local human = character:WaitForChild("Humanoid")
-- Pattern: update once now, then any time the health changes
human.HealthChanged:Connect(onHealthChanged)
onHealthChanged()
end
-- Connect our spawn listener; call it if already spawned
player.CharacterAdded:Connect(onCharacterAdded)
if player.Character then
onCharacterAdded(player.Character)
end

Jumping

這個事件發生當 Humanoid 進入和離開 Jumping``Enum.HumanoidStateType

Humanoid 跳躍時,這個事件會在 active 參數的 true 後發生,之後再次發生在 2>

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

參數

active: bool

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


MoveToFinished

這個事件發生 when the Humanoid 完成走到目標所指定的 Humanoid.WalkToPointHumanoid.WalkToPart 屬性。

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

如果 Humanoid 在 8 秒內達到目標,此事件將以 已達到 作為真的返回。如果目標未達到 8 秒,Humanoid 將停止走路並且變成 2> 已達到2> 作為錯誤。此時間延遲可

參數

reached: bool

指向 Class.Humanoid 是否為目標。是的 如果 Humanoid 為目標,1> 是否為 false 或 false1> 如果目標倒數結束,4> 是否為 false4> 如果目標倒數結束,7> 是否為 false7> 如果目標倒數結束,0> 是否為 false0> 如果目標倒數結束,3>Class.


範例程式碼

This code sample includes a function that avoids the 8 second timeout on Humanoid:MoveTo() by calling Humanoid:MoveTo() again before the timeout elapses. It also includes an optional andThen parameter where developers can pass a function to be called when the humanoid reaches its destination.

Humanoid MoveTo Without Time out

local function moveTo(humanoid, targetPoint, andThen)
local targetReached = false
-- listen for the humanoid reaching its target
local connection
connection = humanoid.MoveToFinished:Connect(function(reached)
targetReached = true
connection:Disconnect()
connection = nil
if andThen then
andThen(reached)
end
end)
-- start walking
humanoid:MoveTo(targetPoint)
-- execute on a new thread so as to not yield function
task.spawn(function()
while not targetReached do
-- does the humanoid still exist?
if not (humanoid and humanoid.Parent) then
break
end
-- has the target changed?
if humanoid.WalkToPoint ~= targetPoint then
break
end
-- refresh the timeout
humanoid:MoveTo(targetPoint)
task.wait(6)
end
-- disconnect the connection if it is still connected
if connection then
connection:Disconnect()
connection = nil
end
end)
end
local function andThen(reached)
print((reached and "Destination reached!") or "Failed to reach destination!")
end
moveTo(script.Parent:WaitForChild("Humanoid"), Vector3.new(50, 0, 50), andThen)

PlatformStanding

此事件發生,當 Humanoid 進入或離開 PlatformStanding``Enum.HumanoidStateType

HumanoidPlatformStanding 狀態時,Humanoid.PlatformStand 屬性會是 1> 真的1> 。

雖然 Humanoid.PlatformStand 設為 true ,但 Humanoid 無法移動工具。 為了獲得更多資訊,請參閱 2>Class.Humanoid.PlatformStand2> 頁面。

PlatformStand Enum.HumanoidStateType 與現在已禁用的 Platform 零件關聯。 雖然如此,它仍然可以由開發人員使用。

參數

active: bool

Class.Humanoid 是否正在進入或離開 PlatformStanding``Enum.HumanoidStateType


Ragdoll

這個事件發生,當 Humanoid 進入或離開 Ragdoll``Enum.HumanoidStateType

active 參數會有 truefalse 值來表示輸入或離開。

使用 Humanoid:SetStateEnabled() 來禁用取得狀態,以保持 Ragdoll 狀態。

也看:

參數

active: bool

Class.Humanoid 是否正在進入或離開 Ragdoll``Enum.HumanoidStateType


Running

此事件發生,當 Humanoid 正在執行變更的速度。

在執行 Humanoids 覆蓋時,平均每秒 Humanoid.WalkSpeed 在 studs 上。

Humanoid 停止執行此事件時,會以 0 的速度發射此事件。

也看:

參數

speed: number

Class.Humanoid 的速度。


範例程式碼

Demonstrates connecting to the Humanoid.Running event. The event is connected to every player's humanoid that joins.

The function connected will print whether or not the humanoid is running based on the speed.

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} is running`)
else
print(`{localPlayer.Name} has stopped`)
end
end
humanoid.Running:Connect(function(speed: number)
onRunning(speed)
end)

Seated

此事件發生,當 HumanoidSeatVehicleSeat 的任何一個坐下或起來。

當一個角色與座椅接觸時,他們會被附在座椅上,並且會播放一個坐下動畫。有關更多資訊,請參閱 Seat 頁面。

  • 如果角色坐下來,active參數將會是 ,而currentSeatPart將會是他們目前坐下的座位。
  • 如果角色從座上起來,active 參數會是 錯誤 ,而 currentSeatPart 將是零。

也看:

參數

active: bool

是的,如果 Humanoid 正在坐下。

currentSeatPart: BasePart

座椅上坐下如果坐下。


範例程式碼

This code sample demonstrates when the local player's Character sits down or stands up. It should be placed inside a LocalScript within StarterCharacterScripts in order to run when the player's character spawns in.

Finding a Player's Seat

local character = script.Parent
local humanoid = character:WaitForChild("Humanoid")
local function onSeated(isSeated, seat)
if isSeated then
print("I'm now sitting on: " .. seat.Name .. "!")
else
print("I'm not sitting on anything")
end
end
humanoid.Seated:Connect(onSeated)

StateChanged

此事件發生當狀態 Humanoid 變更時。

由於沒有 "閒置" 的人形狀態,因此您應該使用 Humanoid.Running 事件或聽取 RootPart 零件的 Velocity 來計算當 1> Class.Humanoid1> 站立時的工作時間。

也看看

參數

人形體的前一個狀態輸入。

人形當前狀態類輸入。


範例程式碼

Emits particles from the local player's Player.Character when they jump. To try this code sample, place it inside a LocalScript parented to StarterCharacterScripts.

Jumping Particles

local character = script.Parent
local primaryPart = character.PrimaryPart
-- create particles
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
-- listen to humanoid state
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)

The following sample will require a one second cooldown after a Humanoid has landed before it is able to jump again.

To try this sample, place it inside a LocalScript in StarterCharacterScripts|StarterPlayer.StarterCharacterScripts.

Jump Cooldown

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:SetStateEnabled() 被呼叫時,狀態變更變更事件會發生。

參數包括 Enum.HumanoidStateType 以及指示此狀態是否啟用的Boolean。

也看:

參數

isEnabled: bool

啟用狀態的話,則為真。


範例程式碼

When a humanoid state changes for the Players.LocalPlayer, the code below prints whether the state has been enabled or disabled.

This code should work as expected when placed in a LocalScript.

Humanoid State Change Detector

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 .. " has been enabled")
else
print(state.Name .. " has been disabled")
end
end
humanoid.StateEnabledChanged:Connect(onStateEnabledChanged)

Strafing

此事件不會發生,當 Humanoid 正在掃射時,不應該使用它

此事件發生,當 Humanoid 進入或離開 StrafingNoPhysics``Enum.HumanoidStateType

Humanoid 進入 StrafingNoPhysics 狀態時,此事件會以 有效 的 2> true2> 參數發射。 事件會再次發射,直到 5>Class.Humanoid5> 離

這個事件與 StrafingNoPhysics Humanoid 狀態和 發生火焰,當 1>Class.Humanoid1> 正在移動與方向相對時。此狀態目前未使用,如果使用

參數

active: bool

Class.Humanoid 是否正在進入或離開 StrafingNoPhysics``Enum.HumanoidStateType


Swimming

這個事件會在 Humanoid 水變化時發生時 Terrain 游泳速度改變時發生。

Humanoids 在 87.5% 的他們的 Humanoid.WalkSpeed 上游泳。

這個事件不會一直以 0 的速度發生,當 Humanoid 停止游泳。

也看:

參數

speed: number

Class.Humanoid 正在游泳的速度。


Touched

當人形的其中一個手臂與另一個 BasePart 接觸時發生此事件。發生的 BasePart 與發出的 Class.BasePart 以及發出的 2>Class.BasePart2> 將被提供。

Humanoid 的手臂接觸到自己時不會發生此事件。

替代方案

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

注意

參數

touchingPart: BasePart

Class.BasePart 與 Humanoid 已接觸。

humanoidPart: BasePart

已經被觸摸的 Humanoid 的手臂。


範例程式碼

When placed inside a Player.Character model this code will give a player the 'Midas touch'. Everything their character touches will change to gold.

When the Humanoid dies, this change is undone and the golden BasePart|BaseParts are returned to their original state.

To test this out, place this code inside a Script and place it in StarterCharacterScripts|StarterPlayer.StarterCharacterScripts.

Midas Touch

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
-- undo all of the gold
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)