工坊手册

主题

数据 Data ​

共 93 个类型。

  • Animation: Animation 用于封装动画资源的标识信息，将动画名称与资源 URI 绑定在一起。它作为动画数据的轻量载体，供 Animator 加载动画时使用。
  • Axes: Axes 是由名称字符串构造的轴/面布尔集合，可读取 x、y、z 与 Top、Bottom、Left、Right、Front、Back 是否启用。
  • BitMask: BitMask 是用于表示一组布尔标志的位掩码数据类型。
  • BoundingBox: 轴对齐包围盒数据结构，用最小点与最大点两个三维向量刻画一段轴对齐的空间范围。它提供获取区域中心点与三个轴向半尺寸的能力，并允许读写两端的边界点，便于在计算位置和尺寸时复用同一份数据。
  • CFrame: CFrame 用来描述三维空间中的位置与朝向，既可以表示物体在世界中的摆放，也可以表示相对某个坐标系的局部变换。它对外暴露位置分量、位置向量以及右向量、上向量、前方向量等三根基向量，并支持求逆、父子空间互转、插值、点与向量的坐标换算、欧拉角与轴角互转等运算，是摆放单位、计算朝向和做空间换算的基础载体。
  • Camp: Camp 表示游戏中的一个阵营，用于聚合同阵营的玩家并观察成员变化。通过 GetPlayers 返回的迭代器遍历当前阵营玩家，并通过 PlayerAdded、PlayerRemoved 监听成员加入或离开。
  • CollisionCallbackInfo: CollisionCallbackInfo 是 PhysicsUnit、WorldUnit 本地碰撞事件传入的回调数据，公开提供 OtherUnit，用于标识与当前单位开始或结束碰撞的另一方。该类型不可直接构造。
  • Color: Color 是 RGBA 颜色类型，用于表示带透明度的颜色值。它提供红、绿、蓝、不透明度四个分量，并支持颜色插值、分量极值比较等运算。
  • Color3: Color3 是 0 到 1 浮点分量的 RGB 颜色值，支持 RGB/HSV/十六进制构造、颜色空间转换和线性插值。
  • ColorSequence: ColorSequence 用于描述一段由关键帧组成的颜色渐变，能够在渐变区间内表达颜色随进度变化的过程。它通过 Keypoints 保存全部关键帧，并提供 New 函数完成构造，是特效、界面等需要颜色过渡的表现需求所共用的数据描述方式。
  • ColorSequenceKeypoint: 颜色序列关键帧用于定义颜色渐变序列中某一时刻的颜色值。它由时间位置和对应的颜色组成，是构建 ColorSequence 的基础元素。
  • CommodityInfo: CommodityInfo 是商品信息条目数据，用于承载商品 ID 与数量。
  • Connection: Connection 是事件订阅的句柄，代表一次有效的事件监听连接。它由 Signal:Connect() 返回，用于在不再需要时取消监听，防止内存泄漏。
  • CustomAppearance: CustomAppearance 是由主模型和若干 SubCustomAppearance 子模型组成的可复用外观数据，记录模型资源、皮肤、染色区域、材质、透明度、阴影、旋转与缩放等公开配置。
  • DataStore: 数据存储集合，用于在服务端持久化保存键值对数据，支持按键读取、写入、自增、原子更新与删除，并提供键列表遍历和历史版本查询、清理能力。它无法自行创建，只能由 DataStoreService:GetDataStore()、GetGlobalDataStore() 或 GetOrderedDataStore() 返回，是操作某一份持久化存储的入口对象。
  • DataStoreGetOptions: DataStoreGetOptions 是 DataStore:GetAsync 的可选参数容器，用于控制读取时是否返回 KeyInfo、是否排除已删除条目、是否使用缓存和更新时间排序。
  • DataStoreGetVersionOptions: DataStore:GetVersionAsync / GetVersionAtTimeAsync 的可选参数类型，可通过 DataStoreGetVersionOptions.New() 创建。
  • DataStoreIncrementOptions: DataStoreIncrementOptions 是 DataStore:IncrementAsync 的可选参数容器，用于设置自增初始值、元数据、用户 ID、KeyInfo 返回和前置版本依赖。
  • DataStoreInfo: DataStoreInfo 是 DataStoreService 列表接口返回的集合信息条目，包含集合名称、类型、创建/更新时间、键数量、占用大小和删除状态。
  • DataStoreInfoPages: DataStoreInfoPages 是 DataStoreService:ListDataStoresAsync 或 ListOrderedDataStoresAsync 返回的分页迭代器，GetCurrentPage() 返回 DataStoreInfo 数组。
  • DataStoreKeyBriefInfo: DataStoreKeyBriefInfo 是 DataStore:ListKeysAsync 返回的 key 摘要条目，包含 Scope、Key 和 IsDeleted。
  • DataStoreKeyBriefInfoPages: DataStoreKeyBriefInfoPages 是 DataStore:ListKeysAsync 返回的分页迭代器，GetCurrentPage() 返回 DataStoreKeyBriefInfo 数组。
  • DataStoreKeyInfo: DataStoreKeyInfo 是 DataStore 读写操作返回的键信息对象，包含创建/更新时间、版本号、scope、key、元数据、用户 ID 和删除状态。
  • DataStoreListKeyOptions: DataStoreListKeyOptions 是 DataStore:ListKeysAsync 的可选参数容器，用于控制列 key 时是否排除已删除条目。
  • DataStoreListOptions: DataStoreListOptions 是 DataStoreService 列表接口的可选参数容器，用于控制列 DataStore 集合时是否排除已删除集合。
  • DataStoreOptions: DataStoreOptions 是获取 DataStore 或 OrderedDataStore 句柄时传入的实例级默认选项，后续读写方法未传入自己的 options 时会使用这些默认值。
  • DataStoreRemoveOptions: DataStore:RemoveAsync 的可选参数类型，可控制删除时是否返回键元信息、是否永久删除，以及是否要求当前版本匹配指定前置版本。
  • DataStoreRemoveVersionOptions: DataStoreRemoveVersionOptions 是 DataStore:RemoveVersionAsync 的可选参数容器，可通过 DataStoreRemoveVersionOptions.New() 创建。
  • DataStoreSetOptions: DataStoreSetOptions 是 DataStore:SetAsync 的可选参数容器，用于设置 KeyInfo 返回、元数据保留策略、前置版本依赖、用户 ID 和自定义元数据。
  • DataStoreVersionInfo: DataStoreVersionInfo 是 DataStore:ListVersionsAsync 返回的历史版本条目，包含版本创建时间、版本号和删除状态。
  • DataStoreVersionInfoPages: DataStoreVersionInfo 分页迭代器
  • EUIManager: EUIManager 是当前玩家 PlayerGui 上的 UI 管理器，用于读取设备分辨率、获取 UI 根节点、查询 EUI 节点，以及创建包 UI 模块和场景 UI 节点。
  • EUITouchInfo: EUITouchInfo 描述界面节点上一次触摸交互的完整过程，记录触摸开始位置 BeganPosition、触摸移动位置 MovedPosition、触摸结束位置 EndedPosition，以及用于区分不同触点的 TouchID。作者可借助它获取触点在各个阶段的坐标，从而判断拖动距离、滑动方向或多指操作。
  • EffectBindData: EffectBindData 用于描述 EffectUnit 与目标单位的绑定方式，包括宿主提供的目标单位 ID、挂点、偏移和跟随类型。
  • EggyAppearance: 蛋形生物的外观数据，用于描述蛋仔的盲盒外观、染色、时装散件、配饰、脸型、表情、肤色与蛋皮等可换装信息。它同时提供运行时换装、将外观件挂接到骨骼插槽、以及显示头顶气泡与表情等表现能力，是角色外观表现的核心数据对象。
  • Faces: Faces 是面集合数据类型，用于用面名称字符串选择 Right、Top、Back、Left、Bottom、Front 六个方向中的一个或多个面。
  • InputObject: InputObject 是输入事件与查询接口传出的输入数据，包含 KeyCode、UserInputType、UserInputState、Position、Delta 和 Processed 等 Meta 公开属性，可在事件回调中判断按键、输入类型及处理状态。
  • JoinData: JoinData 封装了玩家进入当前地图时的传送上下文信息，包括来源地图编号、一同传送的其他玩家列表以及传送时携带的自定义数据。通过 Player:GetJoinData 获取该实例后，可读取这些字段来了解玩家是如何到达当前地图的。
  • LogRecord: LogRecord 是 LogService:GetLogHistory 返回的单条历史日志记录。
  • MaterialParam: MaterialParam 是 SkinUnit 的材质参数数据，用于配置粗糙度、金属度、自发光、水体、细节纹理和边缘光等外观表现。
  • Matrix: Matrix 是描述平移、旋转与缩放复合变换的数学数据结构，同时以 Translation、Rotation、Scale 三个分量和 Right、Up、Forward 方向向量暴露内部状态，并可通过 Pitch、Yaw、Roll 读取按 ZXY 顺序解释的欧拉角。它既提供 New、Identity、Zero、FromEulerAngles 等构造与工厂入口，也提供 Inverse、GetInverse、Transpose、Apply 等运算，用来求逆、转置以及把向量送入变换后的坐标系。借助 MakeOrient、MakeRotation、MakeRotationBetween 等函数，还可以直接由方向向量或旋转轴生成朝向与旋转分量。
  • Matrix3x3: Matrix3x3 表示一个三行三列的纯数值矩阵，用来承载三维空间中的线性变换数据，例如旋转与缩放关系。它支持求转置、求逆、求行列式与迹、按行或按列提取向量、把矩阵作用于三维向量，也能产出单位矩阵、零矩阵以及叉乘对应的反对称矩阵。矩阵既可以按九个分量一次性构造，也可以由克隆或各类代数运算的结果得到。
  • MemoryStoreHashMap: MemoryStoreHashMap 是内存级键值存储的哈希集合，提供快速的异步读写能力。它支持对单个键进行设置、获取、更新和删除操作，并能列出所有存储项或清空整个集合。
  • MemoryStoreHashMapPages: MemoryStoreHashMapPages 是 MemoryStoreHashMap:ListItemsAsync 返回的分页迭代器，GetCurrentPage() 返回 { Key = String, Value = Any } 数组。
  • MemoryStoreHashMapSetOptions: MemoryStoreHashMapSetOptions 用于配置 MemoryStoreHashMap:SetAsync 方法的可选行为，通过设置布尔条件、数值比较或生存时间等字段，精确控制键值对的写入策略。它支持存在性检查、值大小比较、累加操作以及键的过期管理，帮助开发者实现复杂的条件更新逻辑。
  • MemoryStoreHashMapUpdateOptions: MemoryStoreHashMapUpdateOptions 用于配置 MemoryStoreHashMap:UpdateAsync 的原子更新条件，支持基于旧值的阈值比较和键的生存时间控制。通过设置 LTT、GTET、EQT 等字段，可确保仅在满足指定条件时才执行更新，避免并发冲突。
  • MemoryStoreQueue: MemoryStoreQueue 是支持整数优先级的临时消息队列，通过 AddAsync 写入任务、ReadAsync 批量读取并暂时隐藏任务，再用 RemoveAsync 确认删除已处理批次。
  • MemoryStoreQueueAddOptions: MemoryStoreQueueAddOptions 用于配置向内存存储队列添加数据时的可选行为，支持设置条目过期时间与存在性前置条件。通过设置 MSXX 或 MSNX 字段，可控制仅在队列存在或不存在时才执行添加操作；EX、PX、EXAT、PXAT 字段则允许以秒或毫秒为单位指定条目的生存时间。
  • MemoryStoreQueueGetSizeOptions: MemoryStoreQueueGetSizeOptions 用于配置 MemoryStoreQueue:GetSizeAsync 方法的可选参数，控制是否在计算队列大小时排除不可见元素。通过设置 ExcludeInvisible 字段，可以灵活调整统计范围，满足不同业务场景的需求。
  • MemoryStoreQueueReadOptions: MemoryStoreQueueReadOptions 是 MemoryStoreQueue:ReadAsync 的读取配置，用于控制是否要求全部读取成功、空队列等待时间以及已读元素的不可见过期时间。
  • MemoryStoreSortedMap: MemoryStoreSortedMap 表示 MemoryStore 中的有序集合，条目按排序键优先、键其次的规则排列：数字排序键在最前，字符串排序键随后，没有排序键的条目排在最后。它支持用 SetAsync、GetAsync、RemoveAsync 增删改查单条数据，用 UpdateAsync 对指定键执行原子变换，借助 GetRangeAsync 按升序或降序成批读取条目，并可通过 GetSizeAsync 与 DeleteAsync 统计规模或整体清空。
  • MemoryStoreSortedMapGetRangeOptions: MemoryStoreSortedMapGetRangeOptions 是用于配置有序映射范围查询的参数字对象，通过 LowerBoundKey、UpperBoundKey、LowerBoundSortKey、UpperBoundSortKey 四个字段分别限定键与排序键的上下限。它自身不执行任何读取动作，只承载范围约束，未显式设置的字段保持默认行为。
  • MemoryStoreSortedMapPages: MemoryStoreSortedMapPages 是 MemoryStoreSortedMap:GetRangeAsync 返回的分页迭代器，当前页元素形如 { Key = String, Value = Any, SortKey = Any }。
  • MemoryStoreSortedMapSetOptions: MemoryStoreSortedMapSetOptions 用于配置 MemoryStoreSortedMap:SetAsync 的写入行为，支持条件更新、自增操作和键的生存时间设置。通过组合 XX、NX、LT、GT 等条件字段，可实现仅在满足特定条件时才执行写入；INCR 字段允许对数值型排序键进行原子累加；EX、PX 等字段则控制键的过期策略。
  • MemoryStoreSortedMapUpdateOptions: MemoryStoreSortedMapUpdateOptions 是 MemoryStoreSortedMap:UpdateAsync transform 回调返回的可选参数，用于约束旧 sortKey 条件和 TTL 行为。
  • NumberRange: NumberRange 表示一个由最小值和最大值构成的数值区间，用于限定范围或进行边界检查。通过 NumberRange.New(min, max) 或简写 NumberRange(min, max) 创建实例，可读取 Min 和 Max 属性获取区间端点。
  • NumberSequence: NumberSequence 表示一段随归一化时间变化的数值曲线，可用单个常量值或关键帧数组构造，并通过 Keypoints 读取生成的关键帧。
  • NumberSequenceKeypoint: 数值序列关键帧用于定义数值序列中的一个关键点，包含时间位置、数值和包络三个参数。它通常与 NumberSequence 配合使用，通过多个关键帧来描述数值随时间变化的曲线。
  • OrderedDataStore: 有序数据存储集合，用于存储键值对并支持按值排序检索。它继承自 DataStore，额外提供 GetSortedAsync 方法，可按升序或降序分页获取数据。写入的值必须是整数，适合排行榜、分数记录等需要排序的场景。
  • OrderedDataStoreKeyValueInfo: 有序数据存储键值对信息对象，用于承载排序查询结果中的单条记录，包含所属域、键名、整数值与更新时间四项信息。它通常成批出现在分页结果里，作者可据此读取排行榜名次或进行数据比对。该对象只读，反映查询时刻的数据快照。
  • OrderedDataStoreKeyValueInfoPages: OrderedDataStoreKeyValueInfoPages 是 OrderedDataStore:GetSortedAsync 返回的分页迭代器，GetCurrentPage() 返回 OrderedDataStoreKeyValueInfo 数组。
  • OverlapParams: OverlapParams 是空间重叠查询所用的过滤参数对象，配合 PhysicsService 的 GetPartBoundsInBox、GetPartBoundsInRadius 与 GetPartsInPart 使用。它通过 FilterType 与 FilterDescendantsInstances 决定包含还是排除指定 Unit，通过 CollisionGroup 按碰撞组筛选，并用 MaxParts 限制返回数量。
  • Pages: Pages 是分页数据的迭代器封装，用于把体量较大的列举结果拆成多页逐步读取。它对外提供当前页内容的读取、是否已迭代完毕的状态标记，以及异步推进到下一页的操作，实例由各类列表类接口在返回值中提供，业务侧不能自行创建。
  • PathHitInfo: PathHitInfo 描述一次导航网格射线检测的命中结果，包含射线起点 StartPosition、终点 EndPosition、是否命中 IsHit，以及命中点在射线上的插值参数 HitT 和命中的世界坐标 HitPosition。它把“是否挡住去路”与“挡在何处”打包成一个结果对象，便于在寻路或落点判断时一次性读取。
  • PathWaypoint: PathWaypoint 表示寻路结果中的单个途经路点，记录该点的世界坐标位置、到达时需要执行的动作类型以及可选的自定义标签。它通常成组出现，构成一条完整的移动路径，供角色或单位按顺序行进。
  • PhysicalProperties: PhysicalProperties 描述物理材质的密度、摩擦、弹性及其混合权重，用于配置物体碰撞和接触时的物理表现。
  • PlayerGui: PlayerGui 是当前玩家的客户端 UI 入口，提供 EUIManager 和 ScreenGui 两个常用 UI 控制对象。
  • Quaternion: 四元数用 x、y、z、w 四个分量描述三维旋转，同时提供 Euler、Pitch、Yaw、Roll 等角度属性，便于在分量表示与欧拉角表示之间切换。它既能从轴角、欧拉角或直接给定分量构造旋转，也支持单位化、求逆、求共轭、点积比较与插值过渡，并可取出前、上、右方向向量或转换为 Matrix3x3。需要校验旋转数据是否可用时，可通过 IsFinite、IsUnit、IsValid 判断。
  • Ray: Ray 是一个由起点和方向向量构成的几何数据结构，用来描述从起点沿给定方向延伸的一条射线。它提供 ClosestPoint 与 Distance 两个计算接口，可求出任意空间点在射线上的最近点以及该点到射线的距离；Unit 属性则给出方向向量归一化后的射线形式。
  • RaycastParams: RaycastParams 用于封装 PhysicsService 各物理检测函数的过滤条件，通过 FilterType 与 FilterDescendantsInstances 决定检测时包含或排除哪些 Unit，并可用 CollisionGroup 与 TargetCollisionGroupList 按碰撞组进一步筛选。它把过滤规则从单次检测调用中抽离成可复用的数据对象，让射线、球体、方块与形状检测能针对不同目标切换策略。
  • RaycastResult: 射线检测结果类型，承载 PhysicsService 各投射函数命中后返回的判定信息，可读取命中对象、命中点、命中面法线与命中距离。该类型无法自行创建，未命中时投射函数会返回 nil，因此使用前必须先做判空处理再访问其属性。
  • Rect: Rect 表示二维平面上的轴对齐矩形区域，由最小角点和最大角点定义边界，并提供 Width、Height 读取区域尺寸。
  • Region3: Region3 表示由两个 Vector3 对角点界定的轴对齐三维区域，并可按指定分辨率向外扩展到网格边界。
  • Region3int16: Region3int16 表示由两个 Vector3int16 角点界定的整数网格三维区域。
  • RemoteEvent: 远程事件，承担客户端与服务端之间的异步单向通信职责。它既支持服务端通过 FireClient 向指定客户端、FireAllClients 向所有客户端推送消息，也支持客户端通过 FireServer 向服务端上报请求，接收方分别用 OnServerEvent 与 OnClientEvent 监听。
  • ReserveServerResult: ReserveServerResult 用于承载服务端预留专属服务器所返回的结果，其核心内容是 ReservedServerAccessCode 这一访问码。借助该访问码，多个玩家可以被送往同一个事先预留好的服务器实例，而不必依赖自动匹配。它通常作为传送链路的中间产物，把预留动作与后续的实际传送连接起来。
  • ScreenGui: ScreenGui 是当前玩家本地屏幕 UI 的快捷控制对象，用于显示飘字、游戏结果、观战控件和个人/团队积分面板。
  • Signal: Signal 是同端事件信号，可通过 Connect 持续监听、Once 单次监听，并用 Fire 传递一个可选参数。跨客户端与服务端的通信使用 RemoteEvent。
  • SkinSlot: SkinSlot 描述多槽位皮肤配置中的单个槽位数据，包括皮肤资源标识与四个染色区域颜色。
  • SubCustomAppearance: SubCustomAppearance 描述 CustomAppearance 中一个子模型的公开外观数据，包括模型与皮肤资源、染色区域、挂点、相对变换、材质、透明度和阴影设置。
  • TeleportAsyncResult: 传送异步结果用于承载一次传送请求完成后可读取的预留服务器战场实例访问码，帮助开发者把同一批玩家引导到同一个服务器实例中。它不提供自理构造入口，只能由 TeleportService:TeleportAsync 的返回值产生，其核心内容集中在 ReservedServerAccessCode 属性上。
  • TeleportOptions: TeleportOptions 用于配置玩家跨服务器传送时的行为参数，可指定是否预留新服务器、目标实例标识以及携带的自定义数据。通过设置 ReservedServerAccessCode、ServerInstanceId 和 ShouldReserveServer 等属性，能够精确控制传送目标与方式，并利用 SetTeleportData 传递可序列化的上下文信息。
  • Timer: 计时器对象，用于在指定延迟后或按固定间隔重复执行回调函数。它由 TimerService 创建，提供启动、暂停、恢复、取消等控制能力，并可查询运行状态、间隔和剩余次数。
  • Transform: Transform 表示由位移、旋转与缩放组合而成的三维变换，可通过 Translation（或 Position）、Rotation、Scale 属性读写各分量，并借助 LookVector、UpVector、RightVector 获取变换后的坐标轴方向。它提供 Apply、ApplyDirection、PointToWorldSpace、VectorToWorldSpace 等函数在局部空间与世界空间之间转换点与方向，也支持 Inverse 与 GetInverse 求逆、Lerp 与 InterpolateTransforms 插值、ToMatrix 输出矩阵表示。构造上还提供 Identity、FromMatrix、FromEulerAngles、FromAxisAngle、LookAt 等辅助入口。
  • TriggerCallbackInfo: TriggerCallbackInfo 是 TriggerUnit 本地触发事件传入的回调数据，公开提供 OtherUnit，用于标识进入或离开触发区域的另一方单位。该类型不可直接构造。
  • TweenInfo: TweenInfo 是补间动画的配置对象，用于定义动画的持续时间、缓动风格、重复次数等参数。它通过 TweenService 创建补间时传入，控制动画的播放行为。
  • UDim: UDim 表示一维 UI 尺寸，由比例分量和像素偏移分量组成。它常用于定义界面元素的宽度或高度，允许同时按父容器比例和固定像素值来灵活布局。
  • UDim2: UDim2 表示二维 UI 的位置或尺寸，由水平方向和垂直方向的比例值与像素偏移组合而成。
  • Vector2: 二维向量数据类型，用 x 与 y 两个分量描述平面上的坐标、尺寸或方向。除原始分量外还提供 Magnitude、Unit 等派生量，并支持点积、叉积、夹角、线性插值、逐分量取整与近似比较等运算，是处理二维几何与界面布局计算的常用基础结构。
  • Vector2int16: Vector2int16 表示由两个 16 位整数构成的二维向量，常用于网格坐标、区块索引或离散位置表示。它提供简洁的 x、y 分量读写，并支持通过 New 方法快速构造实例。
  • Vector3: Vector3 表示三维空间中的向量数值，可用来描述位置、朝向、速度或缩放等三维量。它提供 x、y、z 三个分量，以及 Magnitude、Unit、Pitch、Yaw 等派生属性，并支持点积、叉积、归一化、插值、逐分量取整与夹角计算等运算。
  • Vector3int16: 三维整数向量，使用 16 位整数存储 X、Y、Z 分量。常用于表示网格坐标、区块索引或离散空间位置，确保数值为整数且范围受限于 16 位。
  • Vector4: Vector4 表示由 x、y、z、w 四个浮点分量构成的四维向量，常用来承载成组出现的四个数值，例如界面图片控件四边拉伸区域的边距。它提供 Length 计算长度、Dot 计算点积、GetMinValue 与 GetMaxValue 取出分量极值，并通过 GetUnit、GetAbsoluteVector 返回派生的向量结果。Magnitude 与 Unit 为只读属性，Normalize 则可对当前向量做就地归一化。

返回类型索引