迷你世界UGC3.0脚本WikiMenuOn this pageSidebar Navigation快速入门欢迎MOD、组件介绍什么是Lua编程组件介绍组件说明组件互相操作组件函数组件属性事件触发器事件管理组件事件管理函数库服务模块世界模块管理接口 World对象模块管理接口 GameObject角色模块管理接口 Actor玩家模块管理接口 Player生物模块管理接口 Monster方块模块管理接口 Block道具模块管理接口 Item背包模块管理接口 Backpack界面模块管理接口 CustomUI图文信息模块管理接口 Graphics区域模块管理接口 Area容器模块管理接口 WorldContainer资源模块管理接口 Mod计时器模块管理接口 Timer状态模块管理接口 Buff消息模块管理接口 Chat普通变量数据管理接口 Data数组变量数据管理接口 Array二维表变量数据管理接口 TableKV表变量数据管理接口 Map全局函数全局函数枚举枚举库脚本常见问题开发者常见问题进阶指南全局函数触发器脚本交互对象介绍KV排行榜介绍二维表介绍道具实例更新日志更新日志kv排行榜介绍​注意3.0中kv和排行榜仅支持Data.Map 接口不再支持2.0的CloudSever接口调用千万不要混合使用会造成数据丢失。3.0中kv和排行榜仅支持Data.Map 接口不再支持2.0的CloudSever接口调用千万不要混合使用会造成数据丢失。3.0中kv和排行榜仅支持Data.Map 接口不再支持2.0的CloudSever接口调用千万不要混合使用会造成数据丢失。排行榜、K/V数据介绍​排行榜和K/V数据存储功能将为开发者开发具有网络化、功能更加丰富的地图提供更有力的保障。开发者不仅可以对玩家个人数据还可以对地图维度的全局数据如战力排行榜竞速时间排行榜等进行管理、保存、使用。K/V数据​为一般普通的数据存储其如同一张表而表里面可以存任何类型的数据并且可以存储多个不同关键字Key的表。存储中的每个值(value)都由一个独特的键(key)索引可以往里面添加任意值。一个key只能对应一个valuevalue类型可以是数值可以是字符串也可以是json字符串等。例如玩家相关数据可如下所示存取键 (KEY) 值 (VALUE)level 50attr { flowers: 100, level: 6, vip: 3,played_count: 13, label: 超神}coin 78000通过相同的数据集名称和键key就可以针对数据进行存/取操作。排行榜数据​为有序数据集合其数据存储的类型为数值类型系统会按照数值自动进行排序故我们把它简称为排行榜数据其可以存储多个维度的数据进行自动排序。排行榜可以实现地图排名前1000位玩家的数据实现全图排行榜功能排行榜默认排序方式为升序从小到大使用get数据时正数代表升序负数代表降序排行榜只能存正整数存入的小数会进行取整数部分排行榜基本格式如下键KEY)玩家迷你号 值 (VALUE)10000 51000085 1010000354 12数据保存的有效期​地图审核通过且状态属于有效中其所存储的数据即处于有效中。地图取消上传数据将会继续保留30天如果30天内未重新上传数据将会彻底清除无法恢复。地图开发者主动调取删除接口或者地图删除则数据将会彻底清除无法恢复。注意在联机或单机情况下该功能只能实现当前地图当前房间数据的临时存储房间关闭后数据就会丢失。验证数据存储的正确性必须在**云服环境下确保在云服房间内**才可正确的获取到所存储的数据在单机或者联机下将无法获取到云服下的全部数据。如何开启K/V存储和排行榜​开发者可以在开发者工具-触发器-变量库-全局变量中通过选择排行榜或者表来进行存储两种类型的数据。如图所示针对排行榜及表进行存取操作开发者可在Lua中选择需要执行的操作动作具体的操作动作如下图所示序号 函数名 函数描述1 SetValueAndCallBack(...) 回调设置kv、排行榜数据2 SetValueAndBlock(...) 阻塞设置kv、排行榜数据3 RemoveValueAndCallBack(...) 回调删除指定key的数据4 RemoveValueAndBlock(...) 阻塞删除指定key的数据5 UpdateValueAndCallback(...) 更新指定key的数据6 GetValueAndCallBack(...) 回调获取kv、排行榜数据7 GetValueAndBlock(...) 阻塞获取kv、排行榜数据8 GetIndexValueAndCallback(...) 获取排行榜指定排名索引的值9 GetIndexValueAndBlock(...) 获取排行榜指定排名索引的值10 GetNumValuesAndCallback(...) 获取排行榜指定前num个值11 GetRangeValuesAndCallback(...) 获取排行榜值为min~max区间的所有值12 SetRankValueAndBlock(...) 阻塞设置排行榜的值13 ClearData(...) 清空kv表/排行榜存储限制​系统为保障存/取数据过程顺利会对数据存储设定一些限制以便给与玩家最好的体验。如果超过设定的限制玩家数据将会存在丢失的风险。每个游戏内的请求服务器的上限系统会根据同时在线的玩家数量来动态调配允许一定数量的数据存/取请求更多的玩家意味有更高的配额更多的数据具体的如下表请求类型 函数 每分钟请求上限 备注设置 SetValueAndCallBack(...)SetValueAndBlock(...)RemoveValueAndCallBack(...)RemoveValueAndBlock(...)UpdateValueAndCallback(...) 30 numPlayers × 10 每分钟该函数允许被请求的次数超过上限将会被限制请求获取 GetValueAndCallBack(...)GetValueAndBlock(...) 30 numPlayers × 10 所有列出的函数共享此限制 每分钟这些函数被请求的次数之和不能超过上限否则请求将会被限制有序数据集(排行榜) GetIndexValueAndBlock(...)GetNumValuesAndCallback(...)GetRangeValuesAndCallback(...)ClearData(...) 5 numPlayers × 2 所有列出的函数共享此限制 每分钟这些函数被请求的次数之和不能超过上限否则请求将会被限制数据长度限制​除了请求频率数据存储同时也会限制每个条目可使用的数据量。其中键key、名称和数据都需要在一定的字符长度内存储的数据量也有限制。具体的限制如下表组成 最大字符数 备注l键key 50 键key建议控制在50字符以内名称 50 名称建议控制在50字符以内数据 2,000,000 数据建议控制在2,000,000字符以内由于键、名称是字符串因此可以使用 string.len() 检查它们的长度。数据也保存为数据存储中的字符串不管其初始类型如何我们都可以使用 Lua 数据转换为序列化 JSON 表的 JSONEncode() 函数检查数据的大小。全局KV数据并发读写​**全局KV数据并发读写主要保证了多个玩家同时对一个KEY进行读写操作时的唯一性确保读写成功并且获取最新值。****应用场景 包括但不仅限于宗门系统拍卖行系统抢购系统等开发者可根据自己的业务需要选择使用。**普通的[SetValueAndBlock] 和[SetValueAndCallBack] 接口已经满足KV数据的绝大多数存取需求但是当需要实现全服共同宗门系统(全局属性例如总人数和贡献值等)、全服共同拍卖行售卖物品的剩余数量等大型跨游戏房间功能的时候容易出现数据的彼此覆盖没法保证全局唯一性。为保证全局唯一性我们特意设计了全新的UpdateValueAndCallback(...)接口。使用该接口开发者仅需自己处理一个回调函数在函数中处理自己的数据的逻辑。接口底层会自动重试直至数据修改成功。注意此接口只在云服有效不要单机或联机测试这个接口注意**此**接口只在云服有效不要单机或联机测试这个接口注意**此**接口只在云服有效不要单机或联机测试这个接口若遇到冲突、失败的情况接口会自动回传最新的数据值并调用开发者的回调函数按照开发者自己设定的逻辑进行更新数据确保了数据不出错不会被其他玩家覆盖。callback函数示例说明UpdateValueAndCallback(...)参数及类型varId:stringkv表变量IDplayerId:number玩家uinkey:string键值数值会转换成字符串value:string,number,boolean具体值返回值及类型ret:bool是否成功 (全局云KV变量可用)该方法的主要作用 安全更新表中某个key下的值并发存取数据确保Key下的值唯一性具体使用案例如下lua-- ret只有0和2两种值-- callback至少会调用两次首次调用ret必然为0用于设置数值-- 第2次或第2次以上调用callback时如果设置失败会再次调用callback此时ret为0如果设置成功则ret为ErrorCode.OK不会再次设置local function GlobalKVCallback(code,key,value)Chat:SendChat(table.concat({UpdateValueAndCallback code ,tostring(code), key ,tostring(key), value ,tostring(value)}, ))value json.decode(value) or valueprint(code, code , key, key, value, value)if code ErrorCode.KV_UPDATE_SET then -- 需要返回更新设置的最终值value value or {}value.updatevalue 999return json.encode(value) -- 需要返回更新设置的最终值 并且序列化结构elseif code ErrorCode.KV_UPDATE_GET thenprint(获取到的当前最新的值:, value)elseif code ErrorCode.OK thenprint(更新完成)elseprint(更新失败)endendlocal result Data.Map:UpdateValueAndCallback(GlobalKV, nil, GlobalKV_Key2, GlobalKVCallback)if result thenprint(调用成功)elseprint(调用失败)end普通KV存储 VS 全局KV数据并发读写​普通KV存储set操作时执行速度更快一些。直接保存key对应的数据只会有写入时的每分钟请求次数限制。但是在多服同时对同一个KEY进行写数据的时候容易造成数据不一致。全局KV数据并发读写UpdateValueAndCallback(...)执行更慢因为修改之前会读取最新的值然后尝试写入。因此该接口同时受到读取和写入的每分钟请求次数限制。另外它第一次操作某个key时因为数据不存在会返回空值此时依然是在callback里面处理并提交首次有效数据给底层。注意事项​1.UpdateValueAndCallback(...)接口无需事先设置key对应的数据因为数据都在callback里面提交从无到有的第一次数据也是这里提交。这样才能避免同时对同一个KEY的数据操作时彼此冲突覆盖问题2.非必要慎用UpdateValueAndCallback(...)接口性能降低。只有业务场景必须要对同一个key的数据进行写操作时保证唯一性、正确性的场景和功能时才推荐使用该接口3.使用UpdateValueAndCallback(...)修改过的数据请勿使用普通SetValueAndBlock接口去设置新值因为会直接覆盖掉原来数据没法保证唯一、正确性而且有可能导致其它问题4.对同一个key,**禁止混用****普通SetValueAndBlock和UpdateValueAndCallback(...)去存数据**5.此接口只在云服有效不要单机或联机测试这个接口6.每个key只能设置一个回调设置后不能随意修改7.Update接口操作的数据其set操作只能在callback里面并采用返回最新value进行修改千万别基于自己调用get拿到的数据进行操作容易导致数据覆盖出错。最佳实践​**Q****执行set操作出现请求失败****A**1、避免出现服务器CD限制相同key的set操作需要间隔6s避免同一秒多次set相同key的情况导致数据没有保存成功。2、避免无变化的数据仍不停去执行set操作。给需要保存的数据设置needSave之类的布尔值标签数据变化了设置为true定时保存中根据needSave为true时候发送set请求保存否则没必要发送到服务器。3、避免绑定玩家行走、碰撞等高频行为而触发实时读写操作否则一个玩家有可能一秒内触发数百个数据读写请求。4、避免触发每分钟请求数QPM限制。5、妥善处理set或get返回失败的情况可以创建请求失败列合理安排时机重试几次一旦成功就从失败列表移除。**Q****一个游戏可以设置多个排行榜****A**1、一个游戏可以包括多个维度的排行榜如得分排行榜击杀Boss次数排行榜速度排行榜时长排行榜技能点数排行榜等。2、如果游戏里有多个排行榜每个榜的刷新时间要错开。**Q****排行榜最多可以设置多少位排名****A**1、单个排行榜最多可存储1万名。2、建议排行榜展示名次最好不要超过TOP 30最多展示前100名。展示的名次越多参与排行的人数越多越影响性能导致响应变慢设计的时候需要做合理的取舍。**Q****如何合理的进行setget操作****A**1、避免零值(或初始值)参与排行榜会出现所有玩家都进行set操作了一次。2、避免低于排行榜最后一名的数据也set操作。假设你的排行榜展示前50名如果第50名已经有100分了那么对于分数低于100分的玩家就无需添加到排行榜里面去。3、参与排行的数值比如经验等级杀怪数量等这几个数值可以序列化成json字符串保存在一个kv中避免多次拉取数据的情况。4、假设某游戏有经验等级杀怪数3个排行榜那么可以一个玩家一个json保存在kv表里面key为玩家uin,value为json:lua{exp: 888999,lvl: 7,kmonster: 39}5、区分游戏商店购买、任务、成就等模块的配置和需要持久化的状态数据。**Q****配置文件建议不设置到数据储存中**A 通用配置可以放脚本或另外一个全局表里没有必要存储在kv表里。luaFindMaHongJun_5:{questName:FindMaHongJun_5,questProg:0,questProgAll:1,questSta:no}这种可以简化假设TaskID:10086表示该任务那么lua10086:[0,1,0]数组第1个元素表示questProg第2个元素表示questProgAll第三个元素表示questSta。排行榜案例​参考2.0文档 https://dev-wiki.mini1.cn/wiki/673b36153ffc6baf0859d33aLast updated: 2025/9/16 11:53PagerPrevious page对象介绍Next page二维表介绍