retrodiffusion

Retro Diffusion — 本格的なピクセルアート生成

テキストプロンプトや参照画像を使って、Retro Diffusion API から本格的なピクセルアートのスプライト、タイルセット、アニメーションを生成します。出力は、ぼやけた拡散モデルの画像をピクセル化したものではなく、きれいな整数ピクセルのグリッドと限られたパレットを備えた、本物のピクセルアートです。そのため、リリース可能な 2D ゲームアートや迅速なプロトタイピングに最適な AI オプションです。

有料サービスです。 Retro Diffusion の利用には、https://www.retrodiffusion.ai のアカウントとクレジット付きの API キーが必要です。生成を始める前に、Retro Diffusion の有料アカウントが必要であることを必ずユーザーに伝え、各呼び出しで残高が差し引かれることを理解しているか確認してください。

参照ファイル

ファイル	説明
api-reference.md	API エンドポイント、モデル、prompt_style の値、レスポンス形式、料金、エラーコードの完全なリファレンス

使用する場面

• 手早いプロトタイプ — 16×16 の配列を手作業でコーディングする代わりに、1 分で数十種類のスプライトを生成できます
• 動作するゲームの仕上げ — 仮の図形を、選んだスタイルにすでに合った統一感のあるピクセルアートに置き換えられます
• タイルセット — すべての遷移タイルを手作業で描かずに、wang スタイルの地面／壁セットを作成できます
• スプライトアニメーション — 歩行、待機時の揺れ、攻撃を、透過 GIF またはスプライトシートとして生成できます

次の場合は add-assets（コードのみのピクセルアート）よりこちらを選んでください： ユーザーが AI 生成アートを希望している、Retro Diffusion のキーを持っている、またはゲームに手作業でコーディングしたマトリックスでは合理的な時間で実現できない視覚的な多様性が必要な場合です。2 つのスキルは相性よく組み合わせられます。主人公のスプライトやタイルセットには Retro Diffusion を使い、すぐに使える簡易素材には無料のコードのみのマトリックスを使えます。

次の場合は使用しないでください： 3D モデル（meshyai を使用）、3D ワールド（worldlabs を使用）、音声（game-audio を使用）、またはユーザーがすべてコードで生成する手続き型ピクセルアートを明示的に希望している場合（add-assets を使用）。

認証

ユーザーに確認する前に、キーがすでに存在するか確認します。

test -f .env && grep -q '^RETRODIFFUSION_API_KEY=.' .env && echo "found"

見つかった場合は、set -a; . .env; set +a でエクスポートし、確認を省略します。

キーが設定されていない場合は、料金体系を説明して、すぐにユーザーに確認してください。

Retro Diffusion を使って本格的なピクセルアートを生成します。リリース可能なゲームスプライトに最適な、ピクセルアート専用モデルです。

ご注意ください：有料サービスです。 クレジット付きの Retro Diffusion アカウントが必要です。各画像の料金は通常、$0.015（RD_FAST）から $0.18（RD_PRO）です。60 秒でキーを取得できます。

1. https://www.retrodiffusion.ai でサインアップします
2. クレジットを購入します（プロトタイプなら最小パックで十分です）
3. Account → API → Generate API key を選択します

次の形式でキーを貼り付けてください：RETRODIFFUSION_API_KEY=rdpk-... （.env に保存され、この会話では伏せ字になります。）

または「skip」と入力すると、無料の手作業によるピクセルアートに切り替え、/add-assets を使います。

ユーザーがキーを提供した場合は、.env に保存し、set -a; . .env; set +a && node scripts/retrodiffusion-generate.mjs ... で使用します。

ユーザーがスキップした場合は、そこで停止して /add-assets に引き継いでください。伝えずに別のアートスタイルへ切り替えてはいけません。

CLI スクリプト — scripts/retrodiffusion-generate.mjs

依存関係なしで動作する Node.js スクリプトです。生成、img2img、アニメーション、タイルセット、編集、残高確認の 6 つすべてのモードに対応しています。

生成（テキストからピクセルアート）

# Single 64×64 sprite, RD_FAST (cheapest)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate \
  --prompt "a cute green slime with big eyes" \
  --model RD_FAST --style retro \
  --width 64 --height 64 \
  --output public/assets/sprites/ --slug slime

# Higher quality with RD_PRO (flat $0.18, supports up to 256×256)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate \
  --prompt "a heroic knight, full body, side view" \
  --model RD_PRO --style fantasy \
  --width 128 --height 128 \
  --output public/assets/sprites/ --slug knight

# Transparent background for game sprites
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "a treasure chest, closed" \
  --model RD_FAST --style game-asset \
  --width 64 --height 64 --remove-bg \
  --output public/assets/sprites/ --slug chest

# Seamless tiling texture (e.g., grass, water)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "lush grass texture, top down" \
  --model RD_PLUS --style top-down \
  --width 64 --height 64 --tile-x --tile-y \
  --output public/assets/tiles/ --slug grass

# Estimate cost before paying for it
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode generate --prompt "..." --check-cost

画像から画像へ（参照画像を調整）

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode img2img \
  --image ./concept-art/hero-sketch.png \
  --prompt "a heroic knight in shining armor" \
  --model RD_FAST --style retro \
  --width 64 --height 64 --strength 0.75 \
  --output public/assets/sprites/ --slug hero

--strength は、入力から AI がどれだけ変更するかを制御します（0 = 同一、1 = 入力を無視）。実用的な範囲は 0.5～0.8 です。

アニメーション（歩行、待機、攻撃）

# Walk cycle — returns spritesheet PNG or transparent GIF (style-dependent)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode animate \
  --prompt "a knight walking" \
  --model RD_PRO --style walk-cycle \
  --width 64 --height 64 \
  --output public/assets/sprites/ --slug knight-walk

# Idle bob from an existing character
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode animate --image public/assets/sprites/knight.png \
  --prompt "knight idle breathing" --style idle \
  --output public/assets/sprites/ --slug knight-idle

アニメーションの料金は種類に応じて $0.07～$0.25 です。スタイルの一覧は api-reference.md を参照してください。

タイルセット

# Wang-style tileset (auto-tiling ground/wall sets)
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode tileset \
  --prompt "stone dungeon floor, mossy" \
  --model RD_PLUS --style wang-tile \
  --width 96 --height 96 \
  --output public/assets/tiles/ --slug dungeon-floor

# Single detailed tile
RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode tileset --prompt "wooden bridge plank" --style single-tile \
  --width 64 --height 64 --output public/assets/tiles/ --slug bridge

編集（段階的な調整）

編集 1 回あたり一律 $0.06 です。最初から生成し直さずに、生成済みスプライトを微調整する場合に使用します。

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs \
  --mode edit --image public/assets/sprites/knight.png \
  --prompt "give the knight a red cape" \
  --output public/assets/sprites/ --slug knight-red

残高確認

RETRODIFFUSION_API_KEY=<key> node scripts/retrodiffusion-generate.mjs --mode balance

モデル選択ガイド

モデル	コスト	サイズ	最適な用途
RD_FAST	$0.015–0.04	64×64～384×384	大量のプロトタイピング、シンプルなスプライト、アイテム
RD_PLUS	$0.025–0.08	16×16～192×192	タイルセット、トップダウン、水彩画、Minecraft風
RD_PRO	$0.18 固定	64×64～256×256	主役のスプライト、アイソメトリックのシーン、仕上げの調整（17 種類以上のスタイル、最大 9 枚の参照画像に対応）
RD_MINI	変動	非常に小さいサイズ	小さな拾得アイテムには PLUS／FAST を使用

プロトタイピングでは RD_FAST をデフォルトにしてください。プロトタイプをリリースする段階で、主役となる個々のスプライトを RD_PRO にアップグレードしてください。

モデルごとの prompt_style の一覧は、api-reference.md を参照してください。

ピクセルアートのプロンプトエンジニアリング

良いプロンプトは短く、シルエットとパレットを具体的に指定し、遠近法を明記します。

目的	プロンプト	理由
ゲームキャラクター	"a cute green slime, big eyes, side view"	被写体が 1 つで、遠近法を明示
アイテム	"a glowing red potion bottle"	形と色を具体的に指定
タイル	"lush grass texture, top down, seamless"	遠近法とタイル化の意図を明示
敵	"a skeleton warrior, hunched, side view"	シルエットの手がかり（「前かがみ」）

避けること：

• 1 つのプロンプトに複数の被写体を入れること — 個別に生成し、ゲーム内で合成してください
• 抽象的な概念（「恐怖感」など）— 見た目を説明してください
• 遠近法の不一致（「トップダウンの騎士、サイドビュー」など）— どちらか 1 つを選んでください

Phaser ゲームとの統合

Retro Diffusion の出力は通常の PNG なので、Phaser のローダーにそのまま読み込めます。

// In a preload scene:
this.load.image('slime', 'assets/sprites/slime.png');
this.load.spritesheet('knight-walk', 'assets/sprites/knight-walk.png', {
  frameWidth: 64,
  frameHeight: 64,
});

// In create():
const slime = this.physics.add.sprite(100, 100, 'slime');
this.anims.create({
  key: 'knight-walk',
  frames: this.anims.generateFrameNumbers('knight-walk', { start: 0, end: 7 }),
  frameRate: 12,
  repeat: -1,
});

ピクセルパーフェクトな描画 — AI ピクセルアートを使用する場合は、スプライトがくっきり表示されるよう、Phaser ゲームで鮮明なスケーリングを設定してください。

// In main.js, Phaser config:
const config = {
  type: Phaser.AUTO,
  pixelArt: true,           // disables antialiasing, preserves hard pixel edges
  roundPixels: true,        // snaps sprite positions to integers
  scale: { mode: Phaser.Scale.FIT, autoCenter: Phaser.Scale.CENTER_BOTH },
  // ...
};

pixelArt: true を指定しないと、ブラウザーが PNG を滑らかに拡大縮小するため、ピクセルアートの見た目が失われます。

スプライトシートの分割

アニメーションスタイルでは、透明 GIF または横並びのスプライトシートが返されます（スタイルによって異なります。出力 PNG のサイズを確認してください）。スプライトシートの場合は、frameWidth = imageWidth / frameCount から推定し、this.load.spritesheet() で読み込みます。各出力と同じ場所に書き込まれる .meta.json ファイルには、要求した幅と高さが記録されるため、フレーム数を特定できます。

コスト管理

呼び出しごとに、ユーザーの残高から実際に料金が発生します。無駄を避けるため、以下をデフォルトとして適用してください。

1. 不慣れなサイズで生成する場合や RD_PRO を使用する場合は、まず --check-cost を使用します。
2. プロトタイプでは RD_FAST + 64×64 をデフォルトにします。特定の主役スプライトのみアップグレードしてください。
3. プロンプトを調整する際は --seed を使用します。同じシードと同じプロンプトなら同じ画像が生成されるため、ランダムなバリエーションを引き直さずにプロンプトの変更を A/B テストできます。
4. 出力をキャッシュします — 生成された PNG は public/assets/sprites/ にコミットされます。ユーザーが新しいバリエーションを求めていない限り、既存のアセットを再生成しないでください。
5. 大量生成の前に --mode balance を実行し、ユーザーに残りのクレジットを確認できるようにします。

出力規約

public/assets/sprites/
  slime.png            # generated image
  slime.meta.json      # prompt, model, style, cost, balance, timestamps
  knight-walk.png      # animation spritesheet or GIF
  knight-walk.meta.json
public/assets/tiles/
  grass.png            # tiling texture
  grass.meta.json

後でプロンプトとシードを確認して再生成できるよう、各 PNG と同じ場所に必ず .meta.json を書き込んでください。

トラブルシューティング

問題	原因	対処法
RETRODIFFUSION_API_KEY が設定されていない	キーがありません	ユーザーにキーを尋ねます（https://www.retrodiffusion.ai → Account → API）。.env に保存します。
HTTP 401 Unauthorized	ヘッダーが正しくない、またはキーが無効です	ヘッダーは X-RD-Token: <key> である必要があります。Authorization: Bearer ではありません。ダッシュボードでキーを確認します。
HTTP 400 "insufficient credits"	アカウント残高がありません	再試行する前に、ダッシュボードで残高をチャージするようユーザーに伝えます。--mode balance を実行して確認します。
Phaser でスプライトがぼやけて表示される	ブラウザーが PNG をスムーズスケーリングしています	Phaser の設定で pixelArt: true と roundPixels: true を設定します。
出力がプロンプトの詳細を反映しない	プロンプトが自動的に別の内容へ拡張されています	--bypass-prompt-expansion を試して、プロンプトをそのまま送信します。
タイルセットの端が一致しない	スタイルが wang/tile スタイルではありません	自動タイルセットには --style wang-tile、シームレスな単一テクスチャには --tile-x --tile-y を使用します。
img2img の出力が参照を反映しない	Strength が高すぎます	--strength を 0.4～0.6 に下げます。Strength が 0 の場合は入力を維持し、1 の場合は入力を無視します。
バッチ内でスタイルに一貫性がない	シードが異なり、プロンプトにわずかな違いがあります	--seed を固定し、関連するスプライト（同じキャラクターファミリー）にはまったく同じプロンプト構成を再利用します。

チェックリスト

• 有料サービスであることをユーザーに伝えた — Retro Diffusion アカウントとクレジットが必要です
• .env または環境変数で RETRODIFFUSION_API_KEY を確認し、見つからない場合は入力を求めた
• 予算に応じてモデルとスタイルを選択した（プロトタイピングには RD_FAST、メインのスプライトには RD_PRO）
• 新しいサイズで初めて呼び出す際に --check-cost を使用した
• プロンプトで対象、視点、シルエットを具体的に指定した
• 関連するスプライト（例：同じキャラクターの歩行と待機）を生成する際に --seed を固定した
• ゲームのスプライトに --remove-bg を使用した（透明 PNG）
• テクスチャには --tile-x/--tile-y、自動タイル化には --style wang-tile を使用した
• PNG を public/assets/sprites/（または tiles/）に .meta.json とともに保存した
• Phaser の設定で pixelArt: true と roundPixels: true が設定されている
• スプライトシートの frameWidth/frameHeight が指定した幅と高さに一致している
• バッチ処理後に残高をユーザーに提示した