MapData

MapData 地图数据服务（编辑期），命名与运行时对齐。通过 GetService 获取。

概览

编辑器地图数据服务，通过 editor:GetService("MapData") 获取。自定义数据分为相互独立的 runtime 与 editor 命名空间：省略 scope 时使用 runtime，随地图发布后可由游戏运行时读取；editor 数据仅用于编辑器，不随地图发布。同名 key 不跨命名空间回退。

Get by:

-- @runtime editor
local service = editor:GetService("MapData")

函数

GetCustomMapData

读取指定命名空间中的 key；不存在时返回 nil。省略 scope 使用 runtime，也可显式传入 runtime 或 editor。

注意： 示例先确认专用测试键没有存量值，存在时退出并更换自己预留的空键；仅写入临时示例数据，结束后恢复为空键。不把 nil 当作写入示例值。

参数

参数	类型	说明
key	String	数据键名
scope	String	可选，runtime（默认）或 editor，只读取指定命名空间，不做跨命名空间回退

返回值

类型	说明
Any	键对应的数据值；不存在时返回 nil

省略 scope 读取临时 runtime 数据

-- @runtime editor
local mapData = editor:GetService('MapData')
local key = '__se_doc_mapdata_get_example'
local previous = mapData:GetCustomMapData(key, 'runtime')
if previous ~= nil then
    print('测试键已有值，请换用自己预留的空键；本次未修改数据')
    return
end
local ok, err = pcall(function()
    mapData:SetCustomMapData(key, 'temporary-value', 'runtime')
    local value = mapData:GetCustomMapData(key)
    assert(value == 'temporary-value', '省略 scope 应读取 runtime 命名空间')
    print('读回临时值:', value)
end)
mapData:RemoveCustomMapData(key, 'runtime')  -- 恢复原先为空的测试键
if not ok then error(err) end

SetCustomMapData

将非 nil 示例值写入指定命名空间；可选 scope 为 runtime（默认）或 editor，同名 key 的两份数据相互独立。

注意： 只使用自己预留且两命名空间都没有存量值的测试键；已有值时不写入。示例分别读回两份临时值，最后恢复两个命名空间的空键状态；不调用地图保存或发布。

参数

参数	类型	说明
key	String	数据键名
data	Any	要写入的数据（任意类型）
scope	String	可选，runtime（默认）或 editor；同名 key 在两个命名空间中相互独立

在空测试键中分别写入两个命名空间

-- @runtime editor
local mapData = editor:GetService('MapData')
local key = '__se_doc_mapdata_set_example'
local previousRuntime = mapData:GetCustomMapData(key, 'runtime')
local previousEditor = mapData:GetCustomMapData(key, 'editor')
if previousRuntime ~= nil or previousEditor ~= nil then
    print('测试键已有值，请换用自己预留的空键；本次未修改数据')
    return
end
local ok, err = pcall(function()
    mapData:SetCustomMapData(key, 'runtime-value', 'runtime')
    mapData:SetCustomMapData(key, 'editor-value', 'editor')
    local runtimeValue = mapData:GetCustomMapData(key)
    local editorValue = mapData:GetCustomMapData(key, 'editor')
    assert(runtimeValue == 'runtime-value', 'runtime 读回不匹配')
    assert(editorValue == 'editor-value', 'editor 读回不匹配')
    print('两个命名空间:', runtimeValue, editorValue)
end)
mapData:RemoveCustomMapData(key, 'runtime')
mapData:RemoveCustomMapData(key, 'editor')
if not ok then error(err) end

RemoveCustomMapData

删除指定命名空间中的 key；可选 scope 为 runtime（默认）或 editor，仅删除指定命名空间的数据。

注意： 先确认自己预留的 editor 测试键为空，再写入和删除临时值。已有存量值时直接退出，不删除现有地图数据；空键或早退不代表已验证一次删除行为。

参数

参数	类型	说明
key	String	数据键名
scope	String	可选，runtime（默认）或 editor

只删除自己刚写入的 editor 临时值

-- @runtime editor
local mapData = editor:GetService('MapData')
local key = '__se_doc_mapdata_remove_example'
local previous = mapData:GetCustomMapData(key, 'editor')
if previous ~= nil then
    print('测试键已有值，请换用自己预留的空键；本次未删除数据')
    return
end
local ok, err = pcall(function()
    mapData:SetCustomMapData(key, 'remove-me', 'editor')
    assert(mapData:GetCustomMapData(key, 'editor') == 'remove-me', '临时值未写入')
    mapData:RemoveCustomMapData(key, 'editor')
    assert(mapData:GetCustomMapData(key, 'editor') == nil, '临时值未删除')
    print('已删除自己写入的临时值')
end)
mapData:RemoveCustomMapData(key, 'editor')  -- 失败时同样清理自有临时键
if not ok then error(err) end