此基礎類提供用於處理 3D 空間查詢和模擬的 API,例如 Workspace 和 WorldModel 。
概要
屬性
屬性 繼承自 Model為啟用實例傳輸的體驗設置模型的細節程度。
在啟用實例傳輸時,控制模型傳輸行為在 Models 上。
Model 的主要部分,或 nil 如果未明確設置。
僅用於編輯器的屬性,用於擴展模型周圍的旋轉點。設置此屬性會將比例移至如果 Model/ScaleTo 被呼叫在它上面。
決定哪裡是 不具有設置的 軸心所在的地方。
方法
如果任何給定的 BasePart 碰觸到任何其他部分,返回真值。
在給定的方向投射方塊形狀,並返回 RaycastResult 如果形狀擊中 BasePart 或 Terrain 細胞。
返回一個包含零件的陣列,其 綁定箱子 覆蓋給定的方塊子。
返回一個包含零件的陣列,其 綁定箱子 覆蓋給定球體。
返回一個集合的零件,其佔用空間與指定的零件共享。
- IKMoveTo(part : BasePart,target : CFrame,translateStiffness : number,rotateStiffness : number,collisionsMode : Enum.IKCollisionsMode):()
透過逆向動力學將指定零件移動到指定位置,而不是直接移動到那裡,以確保參與該零件的任何關節、限制或碰撞仍然物理上滿意。
使用起源、方向和可選 RaycastParams 來投射射線,然後返回 RaycastResult 如果資格對象或地形與射線交叉。
- Spherecast(position : Vector3,radius : number,direction : Vector3,params : RaycastParams):RaycastResult?
在給定的方向投射球形狀態,並返回 RaycastResult 如果形狀擊中 BasePart 或 Terrain 細胞。
基於指定的時間增量和可選的 BaseParts 集合,對世界上的零件進行模擬前進。
將此模型設為指定玩家的持久模型。ModelStreamingMode 必須設為PersistentPerPlayer 以便行為在添加後發生變更。
返回包含模型所有部分的卷的說明。
返回包含所有 BaseParts 在 Model 中最小綁定箱的尺寸,並與 Model.PrimaryPart 一起對齊,如果已設定。
返回此模型對象持有的所有 Player 對象。行為取決於此方法是否從 Script 或 LocalScript 中呼叫。
返回模型的正常比例,預設為新建模型的 1,並且在通過 Model/ScaleTo 縮放時會變更。
將 PrimaryPart 移動到指定位置。如果未指定主要零件,將使用模型的根部分。
使此模型對指定的玩家不再持久。ModelStreamingMode設為PersistentPerPlayer以便行為在移除後發生變更。
設置模型的縮放因子,調整所有子模塊的大小和位置,使其具有與初始大小和位置相關的縮放因子,當縮放因子為 1 時。
以給定的 Model 偏移移動 Vector3 ,保留模型的方向。如果另一個 BasePart 或 Terrain 已在新位置存在,那麼 Model 將覆蓋該對象。
獲得 PVInstance 的軸心。
將 以及所有其子孫 轉換為指定的 位置,使旋轉點現在位於指定的 位置。
屬性
方法
ArePartsTouchingOthers
ArePartsTouchingOthers 返回真如果給定的 BasePart 至少有一個正在觸碰其他零件。如果兩個部分在距離限制內,則會被視為「接觸」overlapIgnored。
如果沒有提供零件,將返回 false 。
參數
一個列表的零件檢查,以查看列表中的任何零件是否碰觸不在列表中的任何零件。
零件觸碰前忽略的零件重疊閾值,在零件被認為觸碰之前。
返回
範例程式碼
下面的代碼塊展示了如何使用 WorldRoot:ArePartsTouchingOthers() 來檢查列表中的零件是否碰觸列表中未列出的零件。
首先,腳本創建了兩個相互重疊 1 個單位的方塊:Part1 和 Part2 。然後,它在三種重疊值 partList 中印出由 ArePartsTouchingOthers() 返回的值:0、0.999 和 1 。第一次兩次呼叫 ArePartsTouchingOthers() 返回 false 因為重疊值小於 Part1 和 Part2 重疊的距離。第三次呼叫返回 true 因為重疊值與零件重疊的距離相等。
local part1 = Instance.new("Part")
part1.Name = "Part1"
part1.Anchored = true
part1.Transparency = 0.5
part1.Color = Color3.fromRGB(185, 100, 38)
part1.Size = Vector3.new(2, 2, 2)
part1.Position = Vector3.new(0, 4, 0)
part1.Parent = workspace
local part2 = Instance.new("Part")
part2.Name = "Part2"
part2.Anchored = true
part2.Transparency = 0.5
part2.Color = Color3.fromRGB(200, 10, 0)
part2.Size = Vector3.new(2, 2, 2)
part2.Position = Vector3.new(0, 5, 0)
part2.Parent = workspace
local partList = { part1 }
print(workspace:ArePartsTouchingOthers(partList, 0)) -- 真的
print(workspace:ArePartsTouchingOthers(partList, 0.999)) -- 真的
print(workspace:ArePartsTouchingOthers(partList, 1)) -- False
Blockcast
在給定的方向投射方塊形狀,並返回使用 BasePart 或 Terrain 細胞的第一次碰撞。這與如何 WorldRoot:Raycast() 在一個方向投射線以找到碰撞類似,但使用 3D 形狀而不是射線。
與 不同,此方法不會偵測到 初始上交叉形狀。
如果偵測到命中,將返回 RaycastResult 包含命中信息的。Distance 屬性代表形狀必須前往的距離才能找到一個命中點,而Position屬性代表造成命中點的交點點。
這個方法會在傳送無效的 CFrame 、尺寸或方向輸入時發出錯誤。
參數
投射方塊形狀的初始位置和旋轉。
投射方塊的形狀尺寸,以厘米為單位。最大尺寸為 512 厘米。
形狀投射的方向,其量表示形狀可以沿途經過的最大距離。最大距離為 1024 個單位。
返回
範例程式碼
Casts a block and returns the first collision with a BasePart or Terrain. Prints the properties of the RaycastResult if a result was hit.
local Workspace = game:GetService("Workspace")
local function castBlock()
-- The initial position and rotation of the cast block shape
local originCFrame = CFrame.new(Vector3.new(0, 50, 0))
-- The size of the cast block shape
local size = Vector3.new(6, 3, 9)
-- The direction the block is cast in
local direction = -Vector3.yAxis
-- The maximum distance of the cast
local distance = 50
-- Cast the block and create a visualization of it
local raycastResult = Workspace:Blockcast(originCFrame, size, direction * distance)
if raycastResult then
-- Print all properties of the RaycastResult if it exists
print(`Block intersected with: {raycastResult.Instance:GetFullName()}`)
print(`Intersection position: {raycastResult.Position}`)
print(`Distance between block's initial position and result: {raycastResult.Distance}`)
print(`The normal vector of the intersected face: {raycastResult.Normal}`)
print(`Material hit: {raycastResult.Material.Name}`)
else
print("Nothing was hit")
end
end
-- Continually cast a block every 2 seconds
while true do
castBlock()
task.wait(2)
end
BulkMoveTo
此功能將 BaseParts 表移動到 CFrames 表,而不一定發射預設屬性 Changed 事件。這樣可以大大加快移動大量零件的速度,因為您不需要為每個零件支付單獨的屬性集成本。
第三個參數允許您進一步優化運動操作。預設情況下,每個零件的 Changed 事件會發射到 Position , Orientation 和 CFrame 。然而,如果您指定 FireCFrameChanged 為第三個引數,只有 Changed 事件對 CFrame 屬性發觸發。
請注意,您只應使用此功能,如果您確定零件移動是您程式碼中的瓶頸。簡單設置個別零件和焊接模型的 CFrame 屬性即可在大多數情況下快速完成。
參數
返回
GetPartBoundsInBox
WorldRoot:GetPartBoundsInBox() 返回一個包含零件的數組,其 綁定箱子 覆蓋一個描述使用給定中心 ( CFrame ) 和尺寸 ( Vector3 ) 的盒子的音量的盒子。
如已強調,這個空間查詢方法有效地考慮零件的綁定盒子的體積,而不是它們實際上使用的體積。這可能在考慮圓筒、球、聯合和 MeshParts 非積木形狀時很重要。對於需要精確度特別重要的情況,請使用 WorldRoot:GetPartsInPart() 或自行過濾此方法的結果。
此方法使用 對象來描述可重複的空間查詢部分,例如包括或排除列表、最大要查詢的零件數量、要使用的 碰撞群 以及是否將查詢值優先於其值的交叉部分的 值。
參數
要查詢的盒子卷中心的位置。
要查詢的盒子體積的大小。
包含可重複使用的空間查詢參數部分。
返回
一個匹配空間查詢的 BaseParts 陣列。
GetPartBoundsInRadius
WorldRoot:GetPartBoundsInRadius() 返回一個包含零件的數組,其 綁定箱子 覆蓋一個屬於給定中心 ( Vector3 ) 和半徑 (number) 的球體的音量。
如已強調,這個空間查詢方法有效地考慮零件的綁定盒子的體積,而不是它們實際上使用的體積。這可能在考慮圓筒、球、聯合和 MeshParts 非積木形狀時很重要。對於需要精確度特別重要的情況,請使用 WorldRoot:GetPartsInPart() 或自行過濾此方法的結果。
此方法使用 對象來描述可重複的空間查詢部分,例如包括或排除列表、最大要查詢的零件數量、要使用的 碰撞群 以及是否將查詢值優先於其值的交叉部分的 值。
參數
要查詢的給定球體體積中心的位置。
要查詢的給定球體體積範圍。
包含可重複使用的空間查詢參數部分。
返回
一個匹配空間查詢的 BaseParts 陣列。
GetPartsInPart
WorldRoot:GetPartsInPart() 返回一個包含與給定部分共享空間的零件數組(必須存在於與要查詢的零件相同的 WorldRoot 中)。這個方法可以在 BasePart:GetTouchingParts() 的位置使用,通常是更好的選擇。
如已注意,這個空間查詢方法會考慮使用完整的幾何碰撞檢查來確定指定零件所佔的 準確體積 。舉例來說,凹/空心零件不會與內部的查詢零件匹配,除非它們實際上覆蓋/觸碰這樣的零件。對於簡單的音量,請考慮使用 WorldRoot:GetPartBoundsInBox() 或 WorldRoot:GetPartBoundsInRadius(),因為它們的準確度較低,但執行效率較高。
此方法使用 對象來描述可重複的空間查詢部分,例如包括或排除列表、最大要查詢的零件數量、要使用的 碰撞群 以及是否將查詢值優先於其值的交叉部分的 值。
參數
音量要與其他零件進行比較的零件。
包含可重複使用的空間查詢參數部分。
返回
一個匹配空間查詢的 BaseParts 陣列。
IKMoveTo
這個功能會將指定的零件移動到指定位置,通過 逆動力學 而不是直接移動到那裡,以確保參與其中的任何關節、constraints 或碰撞都能物理上滿足。目前此功能只能在 Studio 到 plugins 中使用,因為目前與運行中的遊戲的物理發生衝突。
翻譯剛度 是一個數字,介於 0 和 1 之間,指定要如何積極地將零件的位置匹配到目標 CFrame 的位置。 旋轉剛度 是一個數字,介於 0 和 1 之間,指定要如何積極地將零件的旋轉匹配到目標 CFrame 的旋轉部分。
例如:
- 如果翻譯剛度和旋轉剛度兩者都等於 1,則零件將準確移動到目標 CFrame,無論其上有何物理限制。
- 如果翻譯剛度和旋轉剛度兩者都等於 0.5,則零件將嘗試移動到準確的目標 CFrame,但可能會被物理限制推出路徑。
- 如果翻譯剛度和旋轉剛度兩者都等於 0,則目標 CFrame 將被忽略,物理限制將在位置上解決對象所在的位置。
參數
正在移動的零件。
移動指定零件的位置。
讓你指定物件應受物理解析度影響的範圍。
返回
Raycast
使用起源、方向和可選 RaycastParams 來投射射線。如果找到符合要求的 BasePart 或 Terrain 細胞,將返回包含操作結果的 RaycastResult。如果未提供任何 對象,則使用預設值 (所有零件都被考慮,水不被忽略)。
請注意,方向向量的長度(強度)很重要,因為距離超過其長度的物體/地形不會進行測試。如果您使用 CFrame 來幫助創建射線組件,請考慮使用 CFrame.LookVector 作為方向向量,並將其乘以所需的長度,如下圖所示。方向向量的最大長度為 15,000 個單位。
此方法不使用 不 使用 Ray 物件,但其起源和方向組件可以從 Ray.Origin 和 Ray.Direction 借用。
參數
射線的起點。
射線的方向向量。注意,這個向量的長度很重要,因為部件/地形比它的長度更遠,將不會進行測試。
一個用於在射線投射操作中指定命中資格的對象。如果未提供,將在所有零件被考慮的情況下使用預設值,並且不忽略 Terrain 水。
返回
範例程式碼
Casts a ray and returns the first collision with a BasePart or Terrain. Prints the properties of the RaycastResult if a result was hit.
local Workspace = game:GetService("Workspace")
local function castRay()
-- The origin point of the ray
local originPosition = Vector3.new(0, 50, 0)
-- The direction the ray is cast in
local direction = -Vector3.yAxis
-- The maximum distance of the ray
local distance = 50
-- Cast the ray and create a visualization of it
local raycastResult = Workspace:Raycast(originPosition, direction * distance)
if raycastResult then
-- Print all properties of the RaycastResult if it exists
print(`Ray intersected with: {raycastResult.Instance:GetFullName()}`)
print(`Intersection position: {raycastResult.Position}`)
print(`Distance between ray origin and result: {raycastResult.Distance}`)
print(`The normal vector of the intersected face: {raycastResult.Normal}`)
print(`Material hit: {raycastResult.Material.Name}`)
else
print("Nothing was hit")
end
end
-- Continually cast a ray every 2 seconds
while true do
castRay()
task.wait(2)
end
Shapecast
參數
返回
Spherecast
在給定的方向投射球形狀態,並返回使用 BasePart 或 Terrain 細胞的第一次碰撞。這與如何 WorldRoot:Raycast() 在一個方向投射線以找到碰撞類似,但使用 3D 形狀而不是射線。
與 不同,此方法不會偵測到 初始上交叉形狀。
如果偵測到命中,將返回 RaycastResult 包含命中信息的。Distance 屬性代表形狀必須前往的距離才能找到一個命中點,而Position屬性代表造成命中點的交點點。
這個方法會在傳送無效的半徑或方向輸入時發生錯誤。
參數
投射球形狀態的初始位置。
投射圓形形狀的範圍,以厘米為單位。最大範圍為 256 厘米。
形狀投射的方向,其量表示形狀可以沿途經過的最大距離。最大距離為 1024 個單位。
返回
範例程式碼
Casts a sphere and returns the first collision with a BasePart or Terrain. Prints the properties of the RaycastResult if a result was hit.
local Workspace = game:GetService("Workspace")
local function castSphere()
-- The initial position of the cast spherical shape
local originPosition = Vector3.new(0, 50, 0)
-- The radius of the cast spherical shape in studs
local radius = 10
-- The direction the sphere is cast in
local direction = -Vector3.yAxis
-- The maximum distance of the cast
local distance = 50
-- Cast the sphere and create a visualization of it
local raycastResult = Workspace:Spherecast(originPosition, radius, direction * distance)
if raycastResult then
-- Print all properties of the RaycastResult if it exists
print(`Sphere intersected with: {raycastResult.Instance:GetFullName()}`)
print(`Intersection position: {raycastResult.Position}`)
print(`Distance between sphere's initial position and result: {raycastResult.Distance}`)
print(`The normal vector of the intersected face: {raycastResult.Normal}`)
print(`Material hit: {raycastResult.Material.Name}`)
else
print("Nothing was hit")
end
end
-- Continually cast a sphere every 2 seconds
while true do
castSphere()
task.wait(2)
end
StepPhysics
基於指定的時間增量和可選的 BasePart 集合,對世界上的零件進行模擬前進。當指定一組零件時,只有這些零件會被模擬,世界上所有其他零件都會被視為已錨定。當此參數被忽略時,世界上所有的零件都會包含在模擬中。指定的時間增量可以是任何正數,大值會增加函數的運行時間。根據時間增量的值,物理系統可能會將其分解為多個獨立步驟來維持模擬的準確度和穩定性。即使函數執行多個替換步驟,模擬結果也只會在函數完成後才會被看到。要視覺化模擬的個別步驟,該功能可以通過 RunService.RenderStepped 事件每次渲染步驟呼叫一次。
參數
模擬的時間數量。此參數必須為正數。較大的值會增加此函數的運行時間。
可選擇的零件數組,將被模擬。此集必須包含類型 BasePart 的實例;其他類型將被忽略。
返回
範例程式碼
Simulates the parts in the workspace for a fixed period of time by calling the StepPhysics function once per frame until a specified time has elaspsed.
local RunService = game:GetService("RunService")
-- Optional array of parts to simulate; otherwise all parts will be simulated
local partsToSimulate = {
workspace.Part,
}
local function simulateParts(duration)
local time = 0.0
local stepJob
stepJob = RunService.RenderStepped:Connect(function(dt)
if time + dt > duration then
dt = duration - time
end
workspace:StepPhysics(dt, partsToSimulate)
time = time + dt
if time >= duration then
stepJob:Disconnect()
end
end)
end
-- Simulate workspace parts for 5 seconds, stepping the parts once per frame
simulateParts(5.0)