限时活动是限时的节日：玩家赚取活动代币，沿着里程碑奖品的进度条前进。 活动可以只办一次、按计划重复或按链条进行，VIP 通行证会在每个里程碑上增加第二份奖品。
玩家看到什么
- 每个进行中的活动都是一个标签页，带有名称和计时。
- 通往下一个奖品的代币进度条和里程碑进度条。
- 里程碑上的VIP 第二份奖品；之后购买的通行证会补发已经领取过的里程碑。
- “全部领取”，以及说明代币获取方式和每日上限的弹窗。
活动
12 450
320
星星节2
周末
星星：340 / 500
3d 08:00100
200
300
500
如何获得星星
全部领取
开通 VIP
1每个进行中的活动都是一个带计时的标签页。
2里程碑进度条；VIP 通行证在每一步额外增加一份奖品。
3“全部领取”一次完成；代币的获取方式和每日上限。
如何运作
步骤 01把系统加入项目
告诉 AI 编程助手：“加一个有奖品的每周活动”。它会安装现成的系统，附带一个每周的“星星节”，有五个里程碑，每个都有 VIP 奖品。
步骤 02在后台中设置
打开后台，选择你的项目，进入 实时运营 → v2 → 限时活动。
- 创建活动：计划（一次、循环或链条）和代币。
- 添加代币来源及其每日上限。
- 搭建里程碑进度条：门槛、奖励和 VIP 奖品。
页面上的 AI 按钮会打开助手：描述你的需求，它会提出修改，你检查后点击保存。
步骤 03测试并发布
在应用的测试版中检查系统。设置通过单独的操作发送到正式应用，请看发布与链接。
开发者须知
限时活动通过 @idosgames/core 中的 client.timedEvent 工作。
// 打完一局：为每个进行中活动的 'play_round' 行为发放代币
const res = await client.timedEvent.getActiveEvents()
for (const e of res.ok ? (res.data.ActiveEvents ?? []) : [])
if (e.CanEarn !== false && e.Type && e.TimedEventID)
await client.timedEvent.grantTokens(e.Type, e.TimedEventID, 'CustomAction', undefined, undefined, {
ActionName: 'play_round',
})
// 一次调用领取所有活动中所有待领取的里程碑
await client.timedEvent.claimAllMilestones()- 游戏只能通过活动上设置的来源发放代币；上限由服务器执行。
- 从
getActiveEvents()读取进度条：已领取的里程碑保存在那里。
每个字段都在技能 timed-event-system 中有说明，由 SDK 的 MCP 服务器提供。
常见问题
活动可以每周重复吗？
可以。活动可以只举办一次、按计划重复，或作为一串阶段进行。
玩家怎么获得代币？
从你设置的来源获得：游戏中的行为、购买、任务等，每种来源都有自己的每日上限。