这个基础类提供了一个 API,用于处理 3D 空间查询和模拟的任何实例,例如 Workspace 和 WorldModel 。
概要
属性
继承自Model的属性将模型上的细节级别设置为启用实例流式传输的体验。
在启用实例流时控制模型传输行为在 Models 上,当实例流启用时。
Model 的主部分,或 nil 如果未明确设置。
仅用于编辑器的属性用于在模型周围缩放。设置此属性会将缩放移至如果 Model/ScaleTo 被调用在它上。
决定哪里是 Model 做 不 有设置 Model.PrimaryPart 的旋转点。
方法
如果任何给定的 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
是否触碰其他部件 返回 true,如果至少一个给定的 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 形状而不是射线。
与 WorldRoot:GetPartsInPart() 不同,此方法不检测 BaseParts 那 最初 交叉形状。
如果检测到命中,将返回 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 形状而不是射线。
与 WorldRoot:GetPartsInPart() 不同,此方法不检测 BaseParts 那 最初 交叉形状。
如果检测到命中,将返回 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)