Skip to content

排行榜 ​

给卡加一个高分榜,做法和 Steam 游戏的排行榜一样:卡给榜起个名字、提交分数,平台记住每个玩家的最好成绩并排好名次。榜长什么样完全由卡自己画:放在哪、配色、字体、头像、奖杯、上榜动画,都跟着卡的风格走。平台不会在卡外面另加一个榜。

适合有分数、用时、连胜、通关层数的卡:弹球、跑酷、答题、生存天数、解谜用时都行。

跟创作助手说 ​

最简单的做法是直接说,比如:

  • 「加个排行榜,一局结束时显示我的名次和前十名」
  • 「做一个通关用时榜,越快越靠前,标题画面也能看」
  • 「榜上加好友那一栏,排名前三用金银铜」

助手会写好提交和读榜的代码,并按卡现有的样子画榜。想改样子,像改别的界面一样跟它说就行。

自己写的话 ​

在界面代码里(面板 → 界面代码)用 useYumina() 拿到 api:

  • api.leaderboard.submit(榜名, 分数, { details?, order? }):一局结束时提交。每人每个榜只留最好的一次,返回 { ok, best, rank, total, improved }。
  • api.leaderboard.get(榜名, { range?, limit? }):读榜。range 是 "top"(前几名)、"around"(自己上下几名)或 "friends"(自己和好友)。返回的每一行是 { rank, name, image, score, details, me },me 为 true 的那行是玩家自己;board.me 是玩家自己的名次,即使不在这一页里。
tsx
const BOARD = "最高分";

export default function Game() {
  const api = useYumina();
  const [range, setRange] = React.useState("top");
  const [board, setBoard] = React.useState(null);
  const [result, setResult] = React.useState(null);

  const load = React.useCallback(async (r) => {
    setBoard(await api.leaderboard.get(BOARD, { range: r, limit: 10 }));
  }, [api]);
  React.useEffect(() => { void load(range); }, [range, load]);

  // 一局结束时调用
  const finish = async (score) => {
    const r = await api.leaderboard.submit(BOARD, score, { details: { hero: "钢珠" } });
    setResult(r);           // { ok, best, rank, total, improved }
    void load(range);
  };

  return (
    <div>
      {/* 榜长什么样完全由你画:配色、字体、头像、奖杯、动画都随卡的风格 */}
      {result?.ok && <div>{result.improved ? "新纪录!" : `你的最好成绩 ${result.best}`} · #{result.rank} / {result.total}</div>}
      {["top", "around", "friends"].map((r) => <button key={r} onClick={() => setRange(r)}>{r}</button>)}
      {board?.ok && board.entries.map((e) => (
        <div key={e.rank + e.name} style={{ fontWeight: e.me ? 800 : 400 }}>
          {e.rank}. {e.name} {e.score}
        </div>
      ))}
      {board && !board.ok && board.reason === "sign-in" && <div>登录后才能上榜</div>}
    </div>
  );
}

设计上的几个建议 ​

  • 在一局结束的地方显示:分数、是不是新纪录、第几名。标题画面也可以放一个小榜。
  • 高亮自己那一行(me)。玩家不在前十名时,在底下单独写一行 board.me。
  • details 用来放分数旁边的小信息:用了哪个角色、第几关、每秒几下。最多 500 字符的 JSON。
  • 越少越好的榜(用时、步数)第一次提交时传 { order: "asc" },这个榜从此按从小到大排。
  • 没登录的玩家会拿到 { ok: false, reason: "sign-in" },显示一句「登录后才能上榜」就好,别让游戏卡住。
  • 一张卡可以有好几个榜,比如「最高分」和「最快通关」,最多 20 个。

规则 ​

  • 同一张卡的各个语言版本共用一套榜。
  • 每人每分钟最多提交 30 次;榜名 1 到 40 个字符;分数的绝对值不超过 1e15。
  • 只有已发布的卡能上榜;作者在自己没发布的卡上也能测试。
  • 分数是卡在玩家浏览器里算的,所以不要拿名次发奖励或者兑换东西。
  • Studio 预览里看到的是一个示例榜,方便看排版;真实的榜在玩的时候才有。

方法签名见 API 参考。