SuperAPI AI 工具集

tinyworld-integrations

编程与开发

查看项目

更新于 10-30 12:08

技能介绍

Tiny World Integrations 是 Tiny World Builder 仓库中面向集成点的开发说明,用于在改动该应用的 API、Webhook、SSE、MCP、插件或自动化示例时参考。资料主要描述各集成面的职责、约定与注意事项,未提供独立产品页面或安装包信息。

一、账户与后端函数 账户、个人资料与云存档逻辑位于 netlify/functions/ 下,profile.mjs、builds.mjs、share.mjs、assets.mjs 通过各函数导出的 config.path 分别路由到 /api/profile、/api/builds、/api/share、/api/assets。认证使用 Netlify Identity,浏览器端通过自托管的 vendor/tinyworld-auth.js 与 import map 引入 vendored 依赖。资料强调:认证辅助逻辑应从与部署来源一致的链路解析可信站点/Identity 基址(含 TINYWORLD_SITE_URL),不得从请求可控的来源推导 Identity 验证目标;在无法提供 Identity 的宿主上,应把 404/405 视为“认证不可用”,隐藏登录/账户命令并保持本地静态构建可用。账户 API 请求应携带 Authorization: Bearer <nf_jwt> 与 credentials: 'same-origin'。

二、云世界与分享 云端世界以完整 TinyWorld JSON 存储在 Netlify Database 的 builds 行中,已有行通过 PUT /api/builds?id=<id> 更新,避免重复创建。公开分享链接在 world_shares 中创建行,并通过同源 ?share=<id> / /api/share?id=<id> 加载。

三、多人协作(PartyKit) 多人/共享建造使用 PartyKit,独立于 Netlify Functions。partykit.json 指向 party/index.js,本地开发用 npm run party:dev(端口 1999),浏览器房间仅在 URL 含 ?party=、?room= 或 ?collab= 时连接。协作链接应复用 /api/share 的 id 作为世界快照 id 与 PartyKit 房间 id:/tiny-world-builder?share=<id>&party=<id>。共享房间默认公开可观察,后来连接者作为 viewer 加入而非进入等待大厅;公共可见性不授予编辑权,编辑仍需主机分配角色加服务端区域校验。关闭共享建造分两层:主机发送 room.close 给 PartyKit,并向 /api/collabs 提交 { action: 'close', roomId } 写入短期墓碑;被墓碑标记的房间心跳须返回 { closed: true } 而非重建列表。/collabs 页面提供管理员隐藏(hide)与 adminClose 操作。协作建造区域(zones)是 PartyKit 房间的临时权限数据,非保存的世界单元格,非主机 cell.set 必须经过分配的活动区域校验。

四、钱包、玩家与社区 wallet.mjs 校验 Phantom 签名的 Solana 钱包挑战并从 RPC 读取 $TINYWORLD 余额/活动;wallet-payments.mjs 创建 Solana Pay 支付意图;players.mjs 跟踪在线状态、搜索、聊天请求与队伍;livekit-token.mjs 在配置 LIVEKIT_URL、LIVEKIT_API_KEY、LIVEKIT_API_SECRET 后签发 LiveKit 房间令牌。钱包登录必须保持挑战/应答模式,不接受直接提交钱包地址作为所有权证明。community.mjs 支撑 /community 页面(房间、私信、成员、封禁、拉黑、邀请),频道名强制小写,仅 staff 或房间所有者可创建/删除频道与封禁;成员须通过反 AI 人类验证并在资料中填写强制 Twitter/X 句柄(GitHub 可选)才能发帖/私信/加入。头像为 assets/avatars/*.png 白名单预设,不支持用户上传;用户文本经 checkTextSafety 双层过滤。社区审核 webhook 为 community-webhook.mjs,使用共享密钥 HMAC 签名,可执行封禁/拉黑/隐藏/恢复/删除消息/清理垃圾/删除房间等操作,且 community.mjs 会向外发出 message.created 事件。

五、Tinyverse 与经济核心 Tinyverse 已发布世界导航不再使用 tinyverse-nexus 枢纽,/api/worlds 应隐藏该 slug,发布世界数据归一化为一个中心星门(dest: '__world-picker')。Tinyverse/大厅访问锁定在 Jason 账户白名单(netlify/functions/lib/tinyverse-access.mjs),lobby_access 默认 false。房间加入/刷新载荷使用紧凑单元格:[x,z,terrain] 或 [x,z,terrain,kind],渲染校验需兼容两种长度。显式资源自定义资产使用对象形式单元格,economy: { resource, charges?, label? },实时资源为 fish、ore、plants、meat,统一经 packages/tinyworld-mmo-core/normalizeWorldResourceSpec(...) 归一化。经济/多人提取逻辑位于 packages/tinyworld-mmo-core/,为无依赖 ESM 包,提供共享 GOLD 额度、资源税、账本、加入命令与利息快照契约。Tinyverse 多人房间仅作为运行时/游玩/审核界面,不应加入岛屿建造控制、adminSave、建造角色席位或 world.refresh 棋盘替换。

六、浏览器端集成与示例 出站 webhook 位于 tiny-world-builder.html 的 API / webhooks / SSE 桥接段:fireWebhook(event, payload) 批量收集编辑器变更并 POST { source: 'tiny-world-builder', events } 到配置的 webhook URL。入站自动化通过 EventSource 连接配置的 SSE URL,每条 data: 须为 applyRemoteCommand 接受的单个 JSON 命令,支持 place / set_cell、clear、reset,以及仅运行时的 vehicle_spawn、vehicle_set_goal、vehicle_controls、vehicle_remove、vehicle_clear。运行时车辆不得互相穿过,需保持碰撞半径与让行半径、阻塞时刹车并在存在替代路径时绕行;路径上的已放置对象是实时交通障碍,应在世界编辑路径调用 refreshVehiclesForWorldObstacleChange 使车辆立即改道。示例位于 plugins/examples/:webhook-receiver.js(捕获出站批次)、sse-command-relay.js(为浏览器提供 /sse、为外部客户端提供 /command)、send-command.js(中继 CLI)、mcp-stdio-bridge.js(无依赖 MCP stdio 服务器,调用中继并读取 webhook 日志)、vehicle-road-demo.js(无依赖 MCP 客户端/演示)。应用支持浏览器原生可分享车辆演示 URL:?demo=vehicles&seed=tide-ridge-428 为小型默认演示;?demo=vehicles-large&seed=metro-culdesac-20&stats=1 为 20×20 规模测试(含主干道/环路/桥/尽端路与 36 辆自动驾驶车辆)。大型演示参数 size/mapSize/grid/gridSize 接受 12、16、20,cars/carCount/vehicles/vehicleCount 接受 1..120。

七、数据与本地环境 数据库模式变更应放在 netlify/database/migrations/*.sql。本地 Netlify Database 不可用时,应把 503 转换为友好的账户/云状态提示而非生产风格红色错误;钱包/玩家社交表缺失时用 isMissingRelations(...) 识别 PostgreSQL 42P01 并返回面向配置的 503。本地账户/函数调试运行 npx netlify dev 并使用 http://localhost:8888/tiny-world-builder;真实 Identity + DB 验证应使用预览部署。可选浏览器探针须显式开启以保持静态应用控制台干净:Cluso 内嵌页面仅限本地开发并由 tools/dev-server.js 注入;模型戳 API 端点仅在 ?modelApi=1、?modelStampApi=1、window.TWB_MODEL_STAMP_API_ENABLED = true 或 localStorage['tinyworld:features:model-stamp-api']='1' 时加载。修改命令结构时需同步更新应用桥接与这些示例。