平台通知

全屏浏览 VibeHub

全屏浏览,获得更沉浸的体验。你可以随时通过菜单退出全屏。

返回《Sim World》

《Sim World》创意工坊

选择 Mod,下次启动自动加载

收藏用于稍后查找;“开启”决定下次启动时加载哪些 Mod。所有已开启 Mod 会一起进入游戏。

启动游戏

推荐方式 · 不需要懂编程

复制任务给 Agent,让它发布、更新或删除

Prompt 只注入作品、能力、依赖和你的 Mod ID,并要求 Agent 实时读取唯一官方 Skill;固定命令与规则不再复制到任务文本中。

作者允许的 Mod 能力

发布 Mod 时必须声明使用哪些能力。以下内容是作者约定,平台不会扫描或限制 Mod 代码;只安装你信任的内容。

联机策略:游戏进入联机前应禁用全部 Mod

神力工具power-tool

Mod 可通过 registerPower({id, cat, icon, name, fn}) 向左侧神力工具栏注册一个新的施法工具。fn 在被点击施法时收到 {x, y, r, world, api},可读写世界状态(改变地形、生成生物、伤害单位等)。不能访问私有 DOM、账号凭据或平台接口。

作者声明:只影响本地表现

生物特质trait-modifier

Mod 可通过 registerTrait({id, name, ic, color, desc, apply}) 注册新的生物特质,apply(u) 在游戏核心属性重算后运行,可继续改写单位的战斗/属性派生值。只影响本地模拟表现。

作者声明:只影响本地表现

科技分支tech-branch

Mod 可通过 registerBranch({id, name, ic, color, weapon, need, desc}) 为文明科技树添加一个新的现实科技分支(在顶层时代、知识达到 need 后解锁)。只影响本地模拟。

作者声明:只影响本地表现

自定义种族custom-race

Mod 可通过 registerRace({name, color, dark, emoji, desc, k, hp, atk, spd}) 添加一个可生成村庄的种族,并附带知识/生命/攻击/速度系数。只影响本地模拟。

作者声明:只影响本地表现

事件订阅event-hooks

Mod 可通过 on(name, fn) 订阅游戏事件:game-ready / tick / year / war / disaster / nuke / mod-error。回调只读取事件数据,用于联动展示或本地逻辑;不涉及网络与账号。

作者声明:只影响本地表现

自定义命令按钮custom-command

Mod 可通过 registerCommand({id, label, run}) 在游戏底部添加一个自己的按钮,点击时运行 run(api)。适合做开关面板、快速操作,不暴露内部函数。

作者声明:只影响本地表现

作者开发规范

Agent 会同时收到下面这份本游戏专属规范。

Sim World · 创意工坊 Mod 开发指南

本文件是作者与 Mod 创作者之间的开发约定。平台不会扫描或限制 Mod 代码, 以下规则靠创作者自觉遵守;违反约定的 Mod 可能让游戏崩溃或状态错乱。

游戏:Sim World · 现实纪元 —— 一个单文件 HTML5 Canvas 上帝模拟沙盒。 项目 slug:sim-world。


1. 玩家可以制作哪些 Mod

类型注册函数说明
神力工具registerPower往左侧工具栏加一个施法工具(新地形刷、新生物、新灾害、新武器……)
生物特质registerTrait加一个可挂在单位身上的特质,改写战斗/属性派生值
科技分支registerBranch给文明科技树加一个顶层分支(达到知识阈值后解锁)
自定义种族registerRace加一个可建村的种族,带知识/生命/攻击/速度系数
事件订阅on / off监听游戏事件做联动(不改变世界也能做 UI 增强、统计面板等)
自定义命令registerCommand在底部加一个自己的按钮,做开关/快捷操作

2. 公共对象、注册函数与事件

Mod 加载后,通过全局对象 window.SimWorldMod(即 MOD_API)访问全部能力。 它同时被暴露为 window.__SIM__.MOD_API。

2.1 注册函数

// 神力工具:fn 在玩家施法时被调用,收到 { x, y, r, world, api }
SimWorldMod.registerPower({
  id: 'my-power',        // 唯一 ID(必填,见 §6 命名规则)
  cat: 'MOD 扩展',        // 工具栏分组名(可选,默认 "MOD 扩展")
  icon: '✨',            // 图标 emoji(可选)
  name: '我的神力',        // 显示名(可选)
  wide: false,           // 是否占满一行(可选)
  fn: ({ x, y, r, world, api }) => { /* 做点什么 */ }
});

// 生物特质:apply(u) 在核心属性重算后调用,可继续改写派生值
SimWorldMod.registerTrait({
  id: 'my-trait',
  name: '我的特质', ic: '✦', color: '#4ea1ff', desc: '一句话说明',
  apply: (u) => { u.hpMul = (u.hpMul || 1) * 1.5; }   // 可改 hpMul/atkMul/spdMul/...
});

// 科技分支
SimWorldMod.registerBranch({
  id: 'my-branch', name: '我的科技', ic: '🔬',
  color: '#4ea1ff', weapon: '示例武器', need: 220, desc: '说明'
});

// 自定义种族
SimWorldMod.registerRace({
  name: '我的种族', emoji: '🐲', color: '#ff0000', dark: '#880000',
  desc: '说明', k: 1.0, hp: 1.0, atk: 1.0, spd: 1.0
});

// 自定义命令按钮
SimWorldMod.registerCommand({
  id: 'my-cmd', label: '⚙ 我的开关',
  run: (api) => { api.toast('被点击了'); }
});

注册时机:所有 register* 必须在 beforeStart 阶段完成 (即 Loader 的启动前阶段),这样游戏正式启动时才会带上你的内容。

2.2 事件

const off = SimWorldMod.on('war', (e) => {
  console.log(e.attackerName, '向', e.defenderName, '宣战');
});
// off();  // 取消订阅
事件名触发时机数据字段
game-ready游戏正式启动完成{ seed }
tick每个模拟步{ tick, year }
year每 4 步(年推进){ year }
war任意两国宣战{ attacker, defender, attackerName, defenderName }
disaster随机自然灾害触发{ type, x, y, radius, source }
nuke核裂变弹引爆{ x, y, radius }
mod-error事件回调抛错{ scope, message }

2.3 只读世界句柄(SimWorldMod 上的 getter)

world / units / villages / kingdoms / year / tick, 常量 TILE W H T RACES ERAS BRANCHES TRAITS POWERS TOOLS, 只读工具 kingdomOf powerOf resAt countRes materialsOf, 以及 log(msg, cls) / toast(msg) 用于输出到游戏内日志与提示。


3. 最小可运行 Mod

文件:vibehub.mod.json

{
  "title": "治疗神力",
  "summary": "加一个能把范围内单位回满血的神力工具。",
  "description": "演示 Sim World 的 MOD API:注册一个神力工具与一个特质。",
  "version": "1.0.0",
  "releaseNotes": "首个版本。",
  "entry": "main.js",
  "entryType": "classic",
  "styles": [],
  "loadPhase": "before-start",
  "dependencyIds": [],
  "capabilities": ["power-tool", "trait-modifier"]
}

文件:main.js

// 启动前阶段:此时 window.SimWorldMod 已就绪
(function () {
  const M = window.SimWorldMod;
  if (!M) { console.warn('Sim World MOD API 未就绪'); return; }

  // ① 一个神力工具:范围内的友方单位回满血
  M.registerPower({
    id: 'heal-pulse',
    cat: 'MOD 扩展', icon: '💚', name: '治疗波',
    fn: ({ x, y, r, api }) => {
      let n = 0;
      for (const u of api.units) {
        if (u.alive && Math.hypot(u.x - x, u.y - y) <= (r || 5)) { u.hp = u.maxHp; n++; }
      }
      api.toast('治疗波:' + n + ' 个单位');
    }
  });

  // ② 一个特质:生命上限 ×1.5
  M.registerTrait({
    id: 'sturdy', name: '结实', ic: '🪨', color: '#9aa7b6', desc: '生命 +50%',
    apply: (u) => { u.hpMul = (u.hpMul || 1) * 1.5; }
  });

  // ③ 事件:宣战时提示
  M.on('war', (e) => M.log('⚔️ [Mod] ' + e.attackerName + ' 对战 ' + e.defenderName, 'war'));
})();

把这两个文件放进同一个目录,用官方 CLI 发布即可。


4. 启动前 / 启动后加载的区分

游戏启动流程严格分两阶段:

  1. 启动前(loadPhase: "before-start") —— Loader 加载完这些 Mod 后, 游戏才 startGame()。所有 register*(神力/特质/分支/种族/命令)必须在这里做, 否则游戏已经开始,新内容不会进入当前世界。
  2. 启动后(loadPhase: "after-start") —— 游戏 markGameReady() 之后加载。 适合做纯观察型增强:订阅 tick/war 事件画统计面板、做音效提示、连接外部看板等。 启动后 Mod 不能再注册神力/特质/分支/种族(对当前世界无效)。

一句话:想改游戏内容 → before-start;只想看和响应 → after-start。


5. 可作为公共前置依赖的基础 Mod API

任何 Mod 都可以安全依赖以下基础 API(它们是游戏自带的稳定契约,跨版本尽量保持不变):

  • SimWorldMod.version(字符串,当前 "1.0.0")
  • registerPower / registerTrait / registerBranch / registerRace / registerCommand
  • on / off
  • 只读句柄:world / units / villages / kingdoms / tick / year / T / RACES / ERAS / BRANCHES / TRAITS / POWERS / TOOLS
  • 输出:log / toast

禁止的跨阶段依赖:

  • 启动后(after-start)Mod 不得被启动前 Mod 依赖为前置。
  • 不得依赖其他 Mod 的内部私有变量、DOM 结构、事件处理器顺序。
  • 不得依赖尚未在能力目录(WORKSHOP_CAPABILITIES.json)中声明的能力。

6. 多 Mod 同时启用:命名、去重与冲突

  • 唯一 ID:id 只能用小写字母、数字、点 .、横线 -、下划线 _,且首字符不能是符号。 推荐加 Mod 前缀避免撞车,例如 mymod.heal-pulse。
  • 去重(幂等):同一个 id 重复注册时,第二次及以后会被忽略(第一条生效), 不会产生重复条目、不会报错。因此请给每个注册项唯一且稳定的 ID。
  • 命名空间建议:registerPower 的 id、registerTrait 的 id、 registerBranch 的 id、registerCommand 的 id 都建议以 你的mod名. 开头; registerRace 用 name 作为键,建议用不会被其他 Mod 复用的独特名字。
  • 冲突处理:若两个 Mod 争抢同一个 id,先加载者生效。 请勿依赖"覆盖别人的条目"来生效——这属于未定义行为,可能随加载顺序变化。
  • 加载顺序:同一阶段内按平台返回顺序依次加载;不同阶段严格按 before-start → after-start。

7. 存档、联机、加载顺序与版本兼容

  • 存档:本游戏无持久化存档(每次刷新生成新世界),Mod 无需处理存档迁移。
  • 联机:本项目不提供联机。作品的联机策略为 mods-disabled: 游戏进入联机场景前会拒绝任何已启用 Mod。(当前游戏为纯本地沙盒,此策略作为前瞻性约定。)
  • 加载顺序:before-start Mod 全部加载完成后游戏才启动;after-start Mod 在 markGameReady() 之后加载。启动后 Mod 之间不保证相互可见。
  • 版本兼容:Mod 的 vibehub.mod.json 需声明其 capabilities 与 dependencyIds。 当游戏 API 主版本号变化时,请重新核对本文件与 WORKSHOP_CAPABILITIES.json。

8. 明确禁止使用的能力

以下行为一律禁止,违反者 Mod 可能被移除:

  • ❌ 访问、读取或传递账号凭据、Token、密钥、管理接口及其他秘密。
  • ❌ 访问或改写游戏私有 DOM 结构(如 #inspector 内部的未公开结构), 或直接覆盖、猴补(monkey-patch)游戏的内部函数。
  • ❌ 绕过 SimWorldMod 直接操作游戏内部闭包变量。
  • ❌ 发起未声明的网络请求、加载远程脚本/资源、内联 eval 用户输入。
  • ❌ 伪装或抢夺其他 Mod 的 ID、注册项与事件订阅。
  • ❌ 从事任何违法、侵权或危害他人的内容。

能力声明不是安全沙箱。平台不会阻止越权代码,本目录是作者与创作者的开发约定; 请创作者自律,也请玩家只启用可信作者发布的 Mod。

手动发布 Mod高级方式:手动填写资料并上传 ZIP 或入口脚本

发布你的 Mod

登录后可以上传完整 Mod 包或单脚本。

登录