---
title: "ランキング"
description: "api.leaderboard でカード独自のハイスコアボードを作ります。スコアの保存と順位付けはプラットフォーム、見た目はカードが描きます。"
---
<div v-pre>

# ランキング

カードにハイスコアボードを付けます。Steam のゲームのランキングと同じで、カードがボードに名前を付けてスコアを送ると、プラットフォームが各プレイヤーのベストを覚えて順位を付けます。**ボードの見た目はすべてカードが描きます**。置く場所、色、フォント、アイコン、トロフィー、ランクインしたときの演出まで、カードの雰囲気に合わせられます。プラットフォームがカードの外に別のボードを足すことはありません。

スコア、タイム、連勝、到達階層があるカードに向いています。ピンボール、ランゲーム、クイズ、生存日数、パズルのタイムなど。

## 制作アシスタントに頼む

いちばん簡単なのは、そのまま頼むことです。たとえば：

- 「ランキングを付けて。1 プレイ終わったら自分の順位とトップ 10 を出して」
- 「クリアタイムのボードを作って。速い順で、タイトル画面でも見られるように」
- 「フレンドのタブを足して、上位 3 人は金銀銅にして」

アシスタントが送信と読み込みのコードを書き、カードの今の見た目に合わせてボードを描きます。見た目を変えたいときは、ほかの画面と同じように頼んでください。

## 自分で書く場合

画面コード（**パネル → 画面コード**）で `useYumina()` から `api` を取ります。

- `api.leaderboard.submit(ボード名, スコア, { details?, order? })`：1 プレイが終わったら送ります。各プレイヤーはボードごとにベストだけが残り、`{ 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]);

  // 1 プレイが終わったときに呼ぶ
  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>
  );
}
```

## デザインのヒント

- **1 プレイが終わる場所に出す**：スコア、新記録かどうか、順位。タイトル画面に小さなボードを置くのもおすすめです。
- **自分の行を目立たせる**（`me`）。トップ 10 の外にいるときは、下に `board.me` を 1 行添えます。
- **`details` にはスコアの横に出す小さな情報を**：使ったキャラ、ステージ、1 秒あたりの回数など。500 文字までの JSON です。
- **小さいほど良いボード**（タイム、手数）は最初のスコアで `{ order: "asc" }` を渡します。以後そのボードは小さい順に並びます。
- **未ログインのプレイヤー**には `{ ok: false, reason: "sign-in" }` が返ります。「ログインするとランキングに載ります」と出して、ゲームは止めないでください。
- 1 枚のカードに「ハイスコア」と「最速クリア」のように複数のボードを持てます。最大 20 個です。

## ルール

- 同じカードの各言語版は同じボードを共有します。
- 1 人あたり毎分 30 回まで送れます。ボード名は 1〜40 文字、スコアの絶対値は 1e15 まで。
- 公開済みのカードだけがランキングに載ります。作者は自分の未公開カードでもテストできます。
- スコアはプレイヤーのブラウザでカードが計算するので、順位で報酬や景品を出さないでください。
- Studio のプレビューではレイアウト確認用のサンプルボードが表示されます。本物のボードはプレイ中に出ます。

メソッドのシグネチャは [API リファレンス](../08-api-reference.md) にあります。

</div>
