跳到主要内容

第 10 期 · M2 角色与游戏接口:游戏里终于能看到皮肤了

· 阅读需 4 分钟

M2 第二部分完成了从"上传"到"在游戏里看见"的最后一段:用户创建角色、给角色穿上衣柜里的皮肤和披风,CustomSkinLoader、UniSkinMod 和只认固定图片地址的客户端都能按角色名拿到皮肤。

本期完成​

  • 角色(internal/player):创建(扣积分)、改名、删除(按积分流水退还当时支付的积分)、穿戴。名字由唯一索引判重、不区分大小写;名字规则沿用 BS 的 official / cjk / utf8 / custom,另外在任何规则下都禁止空格和 / \ ? # %。
  • UUID:创建时就分配。v3 与离线服算法相同(md5("OfflinePlayer:" + 名字)),改名随之变化;v4 随机,改名不变。用 Notch 的离线 UUID b50ad385-829d-3141-a216-7e7d7539ba7f 做了校验。
  • 穿戴:只能穿自己衣柜里的材质,皮肤只能是皮肤、披风只能是披风(修 BS C07);材质删除后角色自动脱下。
  • 游戏接口:CustomSkinLoader(/{名字}.json、/csl/)、UniSkinMod(/usm/)、Legacy(/skin/、/cape/),格式逐字段对照 BS 与插件源码;名字不区分大小写、返回库内写法;主人封禁 403;可选的 204;默认缓存 60 秒,支持 If-Modified-Since。
  • 前端:/user/player 角色页(衣柜选择器、UUID 复制、角色数据链接),材质页的"穿到角色上"。
  • 设计记录:ADR 0018 角色、UUID 与游戏皮肤接口。

本地实测(skinloom up --dev)​

  1. 上传纤细皮肤、经典皮肤、披风;在角色页输入 bad name! → 提示"角色名不符合要求";创建 Steve → 积分 997 → 897,显示带连字符的 UUID。
  2. 点"选择皮肤",从衣柜选择器里选纤细皮肤,再选披风:卡片上出现预览。
  3. 用 curl 当游戏客户端:/steve.json 返回 {"username":"Steve","skins":{"slim":"…"},"cape":"…"},Cache-Control: public, max-age=60,带 Last-Modified;/usm/STEVE.json 返回 model_preference: ["slim"];/skin/Steve.png、/cape/Steve.png 返回图片;/Nobody.json 404。
  4. 在经典皮肤的材质页选择角色并"穿上这个皮肤":/Steve.json 的模型变成 default、哈希随之改变。
  5. 删除角色:积分退回 997。服务端日志没有警告。

测试​

  • 名字规则(四种规则、长度、禁止字符、数据库上限)、两种 UUID(含 Notch 的已知值、v4 版本位)。
  • 角色:创建扣分、大小写不同的重名、积分不足、改名时 v3/v4 的 UUID 行为、改到已被占用的名字、他人的角色、删除退还当时价格、免费角色不退分;四个用户同时用不同大小写抢注同一个名字,只有一个成功、只扣一次分。SQLite 与 PostgreSQL。
  • 穿戴:披风当皮肤、皮肤当披风、不在衣柜、不存在的材质、脱下、材质删除后自动脱下;资料查询的大小写、封禁、注销。
  • HTTP:角色管理接口全流程;CSL / USM 的逐字节 JSON、空皮肤时的 null、不同大小写、If-Modified-Since 返回 304、204 开关、Legacy 返回的就是材质文件、封禁 403、删除后不再出现。汉字名分别用大写与小写十六进制百分号编码请求——去掉解码那一行,小写编码的请求就会失败,测试能抓到。
  • 前端:UUID 格式化;类型检查、单元测试、生产构建、bun audit。
  • 全量回归:go test ./...(含 PostgreSQL 18)、vet、staticcheck、govulncheck;生成代码无差异、迁移无漂移。MySQL 迁移为手写,由 CI 验证。

问题与风险​

  • 每次请求游戏接口要查三次数据库(角色、皮肤、披风,都走索引);进程内缓存与失效等压测(M5)证明需要时再做。
  • 注册时直接用角色名(BS 的 register_with_player_name)与后台角色管理还没有做。

下期计划​

M2 第三部分:收藏与取消收藏(积分与上传者奖励)、材质编辑(改名、改类型时重新校验尺寸并处理穿着它的角色、公开↔私有的对称计费)、删除材质(引用计数删除文件、孤儿文件清理)、签到与用户仪表盘。