PrimitiveService

概览

字段	值
Kind	Service · 服务 Service
Realm	client

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • [PrimitiveService]（3 函数）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

PrimitiveService 是客户端图元绘制的统一入口，负责创建图元句柄、按句柄绘制抛物线轨迹以及销毁不再使用的图元。CreatePrimitive 返回整数句柄作为后续操作的凭据，DrawParabola 依据句柄与配置表绘制抛物线并给出布尔值与 Vector3 结果，DestroyPrimitive 用于释放句柄对应的图元。

适用场景

适合在客户端绘制临时性的图元表现，例如为投掷或跳跃预览抛物线轨迹、标记一段可视线条，或为技能释放提供快速的视觉反馈。

使用要点

在客户端通过 game:GetService("PrimitiveService") 获取服务。先用 CreatePrimitive 取得句柄，再调用 DrawParabola 绘制抛物线；它依次返回是否命中（Bool）和终点世界坐标（Vector3），最后用 DestroyPrimitive 回收句柄。

注意事项

该服务只能通过 game:GetService 获取，不能自行构造实例；句柄必须来自 CreatePrimitive 的返回值，并在 DestroyPrimitive 调用后失效，应避免继续使用已销毁的句柄。绘制所需的具体内容由函数参数传入，句柄本身不代表可长期持有的资源。

代码示例

绘制抛物线并读取两个返回值

-- @runtime client
local primitiveService = game:GetService("PrimitiveService")
local handle = primitiveService:CreatePrimitive()
if handle == nil then return end
local hit, endPos = primitiveService:DrawParabola(handle, {
    startPos = Vector3.New(0, 2, 0),
    velocity = Vector3.New(12, 10, 0),
    gravity = Vector3.New(0, -20, 0),
})
print("是否命中:", hit, "终点:", endPos)
primitiveService:DestroyPrimitive(handle)

关联类型

• Unit

函数 (3)

CreatePrimitive

签名：CreatePrimitive() -> Int (图元句柄 handle)

在场景中创建一个图元，并以整数句柄的形式返回该图元的标识；后续对图元的绘制与销毁等操作都围绕该句柄进行。

返回值 Int (图元句柄 handle)

示例代码

创建并安全释放图元句柄

-- @runtime client
local primitiveService = game:GetService("PrimitiveService")
local handle = primitiveService:CreatePrimitive()
if handle == nil then return end
print("图元句柄:", handle)
primitiveService:DestroyPrimitive(handle)

DrawParabola

签名：DrawParabola(handle: Int, opts: Table) -> Bool (是否命中障碍), Vector3 (终点世界坐标)

按选项绘制抛物线，依次返回是否发生 raycast 命中（Bool）和终点世界坐标（Vector3）。

参数	类型	说明
handle	Int	图元句柄
opts	Table	可选参数 { startPos: Vector3(必填), velocity: Vector3(必填), gravity: Vector3(必填), totalTime: Float?(默认2.0), stepTime: Float?(默认0.08), width: Float?(默认0.3), raycastParams: RaycastParams? }

返回值 Bool (是否命中障碍), Vector3 (终点世界坐标)

示例代码

读取抛物线命中状态和终点

-- @runtime client
local primitiveService = game:GetService("PrimitiveService")
local handle = primitiveService:CreatePrimitive()
if handle == nil then return end
local hit, endPos = primitiveService:DrawParabola(handle, {
    startPos = Vector3.New(0, 2, 0),
    velocity = Vector3.New(12, 10, 0),
    gravity = Vector3.New(0, -20, 0),
})
print("是否命中:", hit, "终点:", endPos)
primitiveService:DestroyPrimitive(handle)

DestroyPrimitive

签名：DestroyPrimitive(handle: Int) -> void

销毁指定句柄对应的图元，将其从场景中移除并清理相关资源。

参数	类型	说明
handle	Int	图元句柄

返回值 void

示例代码

安全销毁已创建的图元

-- @runtime client
local primitiveService = game:GetService('PrimitiveService')
local handle = primitiveService:CreatePrimitive()
if handle == nil then return end
primitiveService:DestroyPrimitive(handle)
print('图元已销毁')