MapData

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

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

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

MapData 是地图自定义数据读取服务，通过 game:GetService("MapData") 取得唯一实例，用于按字符串键查询地图作者预先配置的自定义数据。它当前只公开 GetCustomMapData 一个入口，返回值可以是任意类型的数据，当目标键不存在时返回空值，因此读取后需要先做空值判断再使用。

适用场景

在客户端或服务端需要读取地图作者预先配置的自定义数据时，通过 game:GetService("MapData") 获取服务实例，再按约定的字符串键查询数据。

使用要点

先调用 game:GetService("MapData") 获取服务实例，再以 GetCustomMapData("键名") 读取对应键的数据；拿到结果后先判断是否为空值，只有在非空时才把它作为参数交给后续逻辑使用。

注意事项

MapData 当前公开入口只有 GetCustomMapData。键不存在时返回 nil，读取后应先做空值判断；返回数据用于读取配置，不能当作可写回的编辑器配置。

代码示例

按键读取地图自定义数据

-- @runtime client
local mapData = game:GetService('MapData')
local value = mapData:GetCustomMapData('level_config')
if value ~= nil then
    print('地图配置:', value)
else
    print('未配置 level_config')
end

关联类型

• Unit

函数 (1)

GetCustomMapData

签名：GetCustomMapData(key: String) -> Any | nil (用户自定义地图数据，不存在时返回 nil)

获取地图自定义数据中指定键对应的值。传入字符串键 key，返回该键存储的用户自定义地图数据；当该键不存在时返回 nil。

参数	类型	说明
key	String	用户自定义地图数据的 key

返回值 Any | nil (用户自定义地图数据，不存在时返回 nil)

示例代码

读取单个自定义地图数据键

-- @runtime client
-- 获取地图数据服务，它是读取当前地图配置的唯一入口
local mapData = game:GetService("MapData")
-- 自定义数据的键由地图作者约定，需与地图内写入时保持一致
local customKey = "spawn_interval"
-- 调用目标接口读取数据，键不存在时会返回 nil
local customValue = mapData:GetCustomMapData(customKey)
-- 返回值为 nil 表示该键没有配置，必须先判断再使用
if customValue == nil then
	print("未找到自定义地图数据:", customKey)
else
	print("自定义地图数据", customKey, "=", tostring(customValue))
end