rpgjs-studio

RPGJS Studio API スキル

このスキルを使用して、RPGJS Studio インスタンスに対するコンテンツ管理タスクを実行します。

公開ゲームデータベースの読み取りでは、プロジェクトごとにアクターと敵の外見を一括で解決し、メディアリンクと明示的なオーバーライドを保持します。レスポンスの動作については、references/database.md を参照してください。

画像とシネマティックの生成

新しいキャラクターには、type: "spritesheet" と metadata.generationMode: "idle" を使用して、5 クレジットで 2×2 グリッドに配置された 4 つの静止ポーズ（下、左、右、上）を含む、透過背景の 1024×768 画像を作成します。Studio は /media/apps/character-editor/:id を開きます。そこで spritesheet.ai を通じて、アイドルシートを参照画像として使用し、ベースキャラクターに関連付けられた個別のメディアとして名前付きアニメーションを作成します。既存のスプライトシートアニメーションのリクエストは引き続き 15 クレジットです。references/media.md を参照してください。

Studio エディターで削除する場合は、references/media.md に記載されている、プロジェクトスコープのキャラクターアニメーションエンドポイントを使用してください。アニメーションの参照と保存済み画像をまとめて削除します。

Base64 の参照では MIME パラメーターを使用できます。text/xml を含め、MIME ヘッダーがない場合や誤っている場合でも、認識された PNG/JPEG/GIF/WebP のシグネチャが優先されます。無効な参照の場合は HTTP 400 を返し、起動時の引き落とし分を返金します。

メディア生成では、キューに追加する前に、実行時に従量課金制の API キークレジットを引き落とします。見積もりでは引き落としません。起動時の失敗は返金され、実行の最終的な失敗には永続化された返金手順が適用されます。queued レスポンスは受け付けを示すだけです。返されたインスタンスをポーリングしてください。課金と参照の保存動作については、references/media.md を参照してください。

イベントで動画を再生するには、show_cinematic を { "video": "media-id", "allowSkip": false, "bgm": "pause", "preload": true } とともに使用します。必須なのは video のみです。スキップと事前読み込みはデフォルトで true です。bgm のデフォルトは "duck"（音楽の音量を 15% にする）です。"pause" を指定すると、その後に音楽を再開します。隣接する動画ブロックは 1 つのオーバーレイを共有します。詳細は references/media.md を参照してください。マップと動画の関連付けは不要です。

マップの直接生成リリース

ユーザーが指定した言語で、希望するマップのビジュアルスタイルを objective に記述します。ジェネレーターはそのスタイルに従い、objective に指定がない場合に限り、高解像度のピクセルアートをデフォルトとして使用します。地形と壁の素材は、コンセプトアートの方向性を維持します。references/maps.md を参照してください。API ペイロードに別途 style フィールドを追加しないでください。

アシスタントを使わずに生成する場合は、references/maps.md の永続的なワークフローと直接進捗のセクションを読んでください。既存の prepare/execute エンドポイント、明示的なクレジット確認、プロジェクトスコープのステータス、中間プレビューを使用します。保存済みの結果を提示する前に、finalized: true と mapId があることを必ず確認してください。ワークフローのステータスだけから完了を推測しないでください。安全なスポーン地点は上流の RSamaium/RPG-JS#367 で追跡されています。ローカルで衝突回避の暫定対応を実装しないでください。

入力

• 現在の作業ディレクトリに RPGSTUDIO.md ファイルがあるか確認します。
• RPGSTUDIO.md がある場合は、ローカルプロジェクトのコンテキストとして扱い、最初に読みます。
• 以下のような永続的な値を復元するために使用します。
  • BASE_URL
  • API の使用に関する、その他のプロジェクト固有の指示
• projectId を復元、要求、または保存しないでください。API キーは RPGJS Studio プロジェクトにスコープされているため、ユーザーが要求したリソースを直接操作します。
• RPGSTUDIO.md がない場合は、通常どおり続行します。
• ユーザーから指定があれば、その値を BASE_URL として使用します。
• ユーザーが別のホストを指定していない場合は、BASE_URL を https://rpgjs.studio に設定します。
• API キーは環境変数 RPGSTUDIO_API_KEY から読み取ります。

必須の起動ワークフロー

1. API を呼び出す前に、RPGSTUDIO_API_KEY が存在するか確認します。
2. RPGSTUDIO_API_KEY を確認する際は、ターミナルに値を表示したり、応答にその値を含めたりしてはいけません。
3. 変数が存在しないか空の場合は処理を中止し、まず ${BASE_URL}/api-keys で API キーを作成してから、RPGSTUDIO_API_KEY をエクスポートするようユーザーに伝えます。
4. 次のヘッダーを使用して認証済みリクエストを構築します。

-H "x-api-key:$RPGSTUDIO_API_KEY"
-H "Content-Type: application/json"

5. HTTP 呼び出しには curl を優先します。明確な理由がある場合に限り、別の HTTP クライアントを使用します。
6. 認証エラーが発生した場合は、直ちに処理を中止します。API が無効なキーを示す応答、401、または 403 を返した場合は、キーを確認するかサポートに問い合わせるようユーザーに伝えます。
7. ユーザーのタスクに一致する参照ファイルだけを読み込みます。
   • references/database.md
   • references/maps.md
   • references/events.md
   • references/event-examples.md

• references/blocks.md
• references/media.md
• references/settings.md
• references/project-env.md
• references/mmorpg.md

ローカルメモリファイル

現在のプロジェクト用の軽量なローカルメモリファイルとして、RPGSTUDIO.md を使用します。

• ファイルが存在する場合は、最初に読み込みます。
• すでに保存されている値を再利用し、同じことを再度尋ねないようにします。
• タスク完了後、実行中に判明した、機密情報ではない安定したコンテキストを使って、ファイルを更新または作成します。

一般的な内容：

• 最後に使用した BASE_URL
• 今後の呼び出しに役立つ、プロジェクト固有の規約やメモ

プロジェクトの選択に RPGSTUDIO.md を使用してはいけません。現在の RPGSTUDIO_API_KEY が対象プロジェクトをすでに特定しているため、ユーザーのリクエストに直接取りかかります。

このファイルに秘密情報を保存してはいけません。

• RPGSTUDIO_API_KEY を保存してはいけません。
• RPGSTUDIO_API_KEY を表示してはいけません。
• 秘密情報の生の値をログ、ターミナル出力、または Markdown にコピーしてはいけません。

リクエストのパターン

ベースコマンドを一度定義し、繰り返し使用します。

BASE_URL="${BASE_URL:-https://rpgjs.studio}"
curl -sS \
  -H "x-api-key:$RPGSTUDIO_API_KEY" \
  -H "Content-Type: application/json"

書き込み操作では、次を優先します。

curl -sS -X POST "$BASE_URL/..." \
  -H "x-api-key:$RPGSTUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

実行ルール

• まずリソースのドメインを特定し、該当する参照ファイルを読み込みます。
• REST のセマンティクス（GET、POST、PUT、DELETE）を使用します。
• 作成または更新の前に、外部キーを解決します。
  • /api/media?query=<search> でメディアを検索します。
  • /api/database/:type?query=<search> でデータベースレコードを検索します。
  • 一致する依存レコードが見つかった場合は、返された _id を再利用します。
  • 見つからない場合は、先に作成してから、返された _id を使用して続行します。
• プロジェクトを選択するためだけに、プロジェクト一覧エンドポイントを呼び出してはいけません。API キーによってプロジェクトのコンテキストが決まります。
• ゲームオブジェクトの作成をユーザーが依頼した場合は、まず有効な最小限のペイロードを送信し、タスクでさらにフィールドが必要な場合に限り内容を追加します。
• 推測した ID ではなく、API が返した ID を再利用します。
• 読み取り、更新、または削除のタスクでユーザーからデータベースの _id が指定された場合は、ペイロードを決めたり内容を報告したりする前に、まず GET /api/database/:type/:id を呼び出して既存のレコードを確認します。
• エンドポイントの形式が不明な場合は、近い GET エンドポイントの応答を先に確認し、実際のペイロードに合わせて対応します。
• 認証エラー後に処理を続行してはいけません。
• 不足している依存データの用意に AI メディア生成が必要な場合は、必ず最初に統合メディア生成エンドポイントを action: "estimate" で呼び出します。
• 見積もり後、必要なクレジット数をユーザーに伝え、action: "execute" を呼び出す前に確認を求めます。
• この見積もりと確認の手順を踏まずに、AI メディア生成を開始してはいけません。
• POST /api/maps/generate では、AI マップ生成のワークフローとエンドポイント固有の失敗時の動作について、references/maps.md に従います。
• 最終応答では、作成、更新、または削除したレコードを正確に要約します。
• タスクを通じて BASE_URL やローカルの規約など、安定したプロジェクトのコンテキストが判明した場合は、今後の実行に備えて、その機密情報ではないコンテキストを RPGSTUDIO.md に保存します。

Common checks

• database task: read references/database.md
• map task: read references/maps.md
• event task: read references/events.md
• event example task: read references/event-examples.md
• event workflow block task: read references/blocks.md
• media task: read references/media.md
• settings task: read references/settings.md
• project env task: read references/project-env.md
• MMORPG publication task: read references/mmorpg.md

Current schema notes

• 認証済みの Studio セッションでは、POST /api/mmorpg/publish を使って現在のプロジェクトを公開できます。公開では、更新を送信する前にすべてのマップを準備します。失敗時には、安定した code、stage、および任意の resourceId が返されます。レスポンスの仕様については、references/mmorpg.md を参照してください。 GET /api/mmorpg/publication は、このプロジェクトの MMORPG が正常に公開されたかどうかを報告し、プレイ可能な URL を返します。 準備処理では、その公開中に限りソースの読み取りをキャッシュします。RPG-JS #374 に向けたバージョン管理された R2 公開とアクティブなルームのみに対する反映は、フレームワークの作業ツリーで実装済みであり、MMORPG_PUBLICATIONS を通じて Studio のローカル設定に統合されています。リリースと本番環境への統合は保留中です。統合する前に、references/mmorpg.md のフレームワーク API のセクションをお読みください。
• 動作が会話ひとつだけのキャラクターイベントでは、onAction トリガーの triggers[].typeData.dialogue に会話を直接保存できます。ブロックコレクションは必要ありません。先に graphic（spritesheet）と faceset のメディアを両方解決してください。いずれかのタイプに適切な結果がない場合は、確認を求めたうえでの生成を提案してください。faceset の生成を明示的に拒否された場合は、faceset を省略できます。ユーザーがすべてのアセット生成を明示的に禁止した場合は、検索で見つかった整合性のある外観 ID を使って機能するイベントを作成し、存在しない graphic または faceset は省略してください。
• データベースアイテムを販売するキャラクターには、正規のショップワークフローを使用してください。price が正の実際のアイテムを解決または作成してから、その _id を参照する call_shop ブロックをひとつ作成します。RPGJS のショップは、アイテムを付与する前に価格を請求します。手動で選択肢／ゴールド／アイテムの分岐を作成したり、仮のリソース識別子を使ったりしないでください。
• マップ生成の followUpPlan.events[] では、ピクセル単位の任意の position: { x, y } を指定できます。位置は width * 48 × height * 48 の範囲内でなければなりません。Studio は簡潔なイベントマップコンテキストを使って検証し、値がないか無効な場合はマップの開始位置にフォールバックします。
• 新しいアシスタントによるマップ生成には、保存される説明、任意のソース assistantConversationId、および { id, title, description, prompt } を含む followUpPlan.music の提案が含まれます。過去の API クライアントでは、会話 ID と音楽の提案を省略できます。
• show_text ブロックでは inputEnabled: true を設定できます。その場合は、送信された文字列または数値を格納するデータベース変数の _id である inputVariableId も指定する必要があります。入力がキャンセルされると null が格納されます。型付き入力のオプションについては、references/blocks.md を参照してください。
• マップ、イベント、ブロックコレクション、データベースレコードでは、既存の一覧エンドポイントに query を指定することで、多言語のセマンティック検索を利用できます。任意の minScore パラメーターは 0..1 を受け付け、デフォルトは 0.40 です。エンドポイント固有のフィルターとレスポンス形式については、該当するリソースのリファレンスを参照してください。
• プロジェクトの環境変数は、認証が必要なプロジェクトルートで管理します。 GET /api/projects/:projectId/env、 PUT /api/projects/:projectId/env/:name、および DELETE /api/projects/:projectId/env/:name。プレーン値はレスポンスに返されますが、シークレット値については isSet のみが公開されます。シークレット値をログに記録したり、出力したりしてはいけません。
• プレイ可能なキャラクターは、/api/database/actors 配下のデータベース Actor です。公開ランタイムデータベースには Actor が含まれ、公開プロジェクトでは mainActorId が公開されます。これにより、新しいゲームでプロジェクトのヒーローを事前選択できます。
• プレイ可能なアイデンティティは、/api/database/classes 配下のデータベース Class です。新しい Actor には有効な classId が必要です。これを持たない既存のレガシー Actor は、引き続き読み取り可能です。Class は name、description、icon、およびレベルで習得できる skills を所有し、Actor は外見、ステータス、インベントリ、装備を所有します。いずれかの Actor に割り当てられている Class は、それらの Actor を再割り当てするまで削除できません。
• キャラクターのスプライトシートのメタデータには illustration を含めることができます。これは、透過背景の 4:5 JRPG キャラクターイラストのメディア _id であり、そのスプライトシートを使用するすべての Actor に継承されます。AI 生成タイプ illustration のコストは 5 クレジットです。
• データベースの作成および更新時の検証では、非 nullable フォームフィールドの null は未指定値として扱われます。JSON Schema で default が宣言されている場合は、代わりにそのデフォルト値が適用されます。明示的な 0 と明示的に nullable なフィールドは保持されます。{ "hitbox": { "width": null, "height": null } } のように、未指定値だけを含む任意のオブジェクトグループも省略されます。検証エラー 400 では、最初の無効なフィールドが message 内のドット区切りパスで示されます。例： { "message": "parameters.pdef.start: Required" }。
• menus.characterSelect は、新規ゲームの Actor セレクターを設定します。settings.allActors: true ですべての Actor を対象にするか、settings.actorIds に Studio Actor の _id を順序付きリストで指定できます。選択内容はプレイヤー／セーブごとに保持され、mainActorId は変更されません。
• イベントワークフローでは call_character_select を使って同じセレクターを開き、change_class を使ってアクティブなプレイヤーに Class を割り当てられます。セレクターでは、すべての Actor または順序付きの一意なサブセットを表示でき、任意でキャンセルを許可できます。Actor の選択を適用しても、獲得済みの進行状況は保持されます。正確なペイロードについては、references/blocks.md を参照してください。
• マップでは、version: 1、mode: "control-texture"、ピクセル単位の width／height、tileSize、palette、および controlTexture のメタデータを含むシェーダー地形 terrainLayer オブジェクトを公開できます。コントロールテクスチャは RGBA8 です。地形パレットのインデックスは R + G * 256 でエンコードされ、任意のライトには B を使い、128 が中立値です。A はピクセルブラシのストロークに対する地形マスクのカバー範囲を格納します。ソフトエッジは、描画時にトランジション／ブレンドのメタデータから計算されます。従来のタイルグリッドは tileSize x tileSize ブロックに正規化されますが、ブラシ編集ではコントロールテクスチャ内の個々のワールドピクセルを更新できます。
• Studio の地形描画を再現する必要があるゲームやエディターとの統合では、@rpgjs/render-map2d を使用してください。ホスト側で地形画像とコントロール画像をデコードし、normalizeTerrainMap() と prepareTerrainMap() を呼び出してから、renderTerrainRegion() でワールドに位置合わせした領域を描画します。Angular、Pixi、または CanvasEngine のアダプターで、道路、カーペット、ナインスライス、水、またはモルフォロジーのピクセルを再実装しないでください。
• POST /api/map-generations は、マップの作成と編集に使う、プロジェクトスコープの確認済み Cloudflare Workflow です。任意の地形／エレメントセット参照を受け付け、不足しているアセットを生成し、セマンティックな地形パターンを抽出して地形／モルフォロジーを構築し、分離されたエレメント位置を保持したうえで、最終マップを保存します。prepare、明示的な確認、execute の順に実行し、返されたインスタンスが complete になるまでポーリングしてください。レスポンスには最終的な mapId が含まれます。失敗して終了したレスポンスでは、返金／再試行のフラグが公開されます。また、POST /api/map-generations/:instanceId/retry は、前回の試行が返金された場合にのみ新しいインスタンスを開始します。対象を絞った編集では正規化されたポリゴンを使用し、省略された場合は現在のアセットを継承します。詳細は references/maps.md を参照してください。
• マップでは、version: 1、mode: "terrain-morphology"、ピクセル単位の width／height、tileSize、および features[] を含む地形モルフォロジーレイヤー terrainMorphologyLayer オブジェクトを公開できます。各フィーチャーは { kind: "hole", params, strokes } または { kind: "wall", params, strokes } のいずれかです。ストロークにはワールドピクセル単位の points[] と radius が格納されます。穴のパラメーターでは、depth、roundness、roughness、任意の正面 textureId、任意の底面塗りつぶし fillTextureId、0..100 に制限される fillHeight、および穴ごとに任意指定できる waveIntensity、waveDirection、waveSpeed がサポートされます。波のフィールドを省略するとマップの waterAnimation 値が継承されますが、waveIntensity: 0 の場合、塗りつぶしは静止したままです。textureId は底面塗りつぶしの代替として使われません。壁のパラメーターでは、height、roundness、roughness、任意の正面 textureId、surfaceTextureId、trimTextureId、baseTextureId、および renderMode: "procedural" | "collision-only" がサポートされます。collision-only で生成された壁は移動を阻止しますが、見た目の描画は wallSurfaceLayer に委ねます。wallStyle: "rock" は、岩の縁と床面の接触影を備えた層状の岩肌を描画します。Studio で掘った洞窟では、マップ全体を覆い、消去操作で掘り抜かれた壁にこの設定が使われます。Studio は岩壁に rockTexture: "masonry" | "natural" も保存します（手続き型の壁面テクスチャ。デフォルトは masonry：切り石の層。natural：風化した不規則な岩肌）。textureId がない場合、ゲームはエディターと同様に壁マスクからこれらの岩肌をピクセルごとに描画します。上部は明るく、足元は暗くなり、開口部の下側は最大でも 55% まで描画され、壁の基部に接触影が付きます。エディターの壁の滑らかさコントロールは roughness = 1 - smoothness に対応します。レンダラーは、描画前に穴／壁マスクを符号付き地形レベルとして統合し、モルフォロジーのストロークを通行を妨げるセルとして地形コリジョンに統合します。Studio エディターでは壁と穴を描画時に相互に打ち消します。穴の上に壁を描くと、その部分の穴は消えて歩行可能な地面に戻り、壁の中に穴を描くと、その部分の壁は消えます。そのため、保存されるマップには通常の描画操作と消去操作だけが含まれます。
• 生成されたマップでは、version: 1、mode: "wall-surface"、マップピクセル単位の寸法、materials[]、および外部 RGBA8 controlTexture を含む wallSurfaceLayer を公開できます。R は 0 始まりのマテリアルインデックス、G は 0=void、1=top、2=face、3=trim、B は予約済み、A はカバー範囲です。各マテリアルは、専用の上面、壁面、縁取りのテクスチャ ID と、任意の基部 ID を参照します。Studio はこれらのマスクをピクセル単位で正確に描画し、壁のコリジョンのモルフォロジーとともに編集／取り消しを行います。PUT /api/maps/:mapId は、wallSurfaceLayer と base64 の wallSurfaceControlTexture から編集内容を保存します。API は PNG をマップドキュメントの外部に保存します。
• マップでは、マップレベルの液体アニメーションのデフォルト値として waterAnimation: { enabled, speed, intensity, direction } を公開できます。direction はスクリーン座標系で時計回りの角度を表し（0 は右、90 は下）、デフォルトは 90 です。塗りつぶされた穴は、パラメーターで上書きされない限りこれらのデフォルト値を継承します。波のハイライトは固定の青い色合いではなく、各塗りつぶしのローカルな色またはテクスチャから生成されます。
• PUT /api/maps/:mapId は、セクション単位の部分更新をサポートします。省略されたマップフィールドは保持されるため、変更したセクションだけを送信してください。開始位置には startX/startY、配置には events、生成された壁のジオメトリには terrainMorphologyLayer と任意の wallSurfaceLayer／wallSurfaceControlTexture、地形には地形フィールド、オブジェクトにはエレメントレイヤー配列、メディアの選択にはタイルセットのパラメーターを送信します。
• マップでは、トップレベルのライティング設定として lighting: { sun: { enabled: boolean, intensity: number } } を公開できます。太陽光の強度は 0..1 に制限されます。有効にすると、ランタイム／エディターとの統合で、壁、キャラクター、エレメントに自動的な影を表示できます。
• マップでは mapLoadBlockCollectionId: string | null を公開できます。設定すると、GET /api/game/maps/:mapId はそのコレクションを mapLoadBlocks にハイドレートします。RPGJS Studio ランタイムは、プレイヤーがマップに入ったときに、サーバーの map.onJoin(player, map) フックからこれらのブロックを実行します。このワークフローではプレイヤーとマップのコンテキストを利用できますが、現在のイベントのコンテキストはありません。
• イベントワークフローのビルダーでは、実行プロファイルを使用できます。eventBuilderProfiles.mapLoad は、プレイヤー対応のマップコンテキストに必要な requiredCapabilities を満たすブロックを公開し、互換性のあるスキーマから現在のイベントフィールドの選択肢を除外します。
• 地形メディアのメタデータでは、sourceTexture、直接指定する rows と columns、textureGrid: { columns, rows, tileSize? }、terrainTextures[]、および transitions[] を公開します。各 terrainTextures[] エントリーは { id, index, label, collision?, renderTileSize?, renderingStyle?: "pixel-art" | "hd-2d", defaultRenderMode? } です。index はアトラスセルの正式な参照元です。collision は、描画されたマップセルを通行不可としてマークします。renderTileSize は、マップエディターのワールドピクセル単位で繰り返しテクスチャのサイズを制御します。省略された場合、従来の 320 パターンサイズがデフォルトになります。renderingStyle: "hd-2d" を指定すると、マップエディターで滑らかな拡大縮小が有効になり、メタデータを省略すると従来のピクセルアート描画が維持されます。defaultRenderMode は hard、fade、nine-slice、water、custom をサポートします。hard はくっきりとしたエッジで、fade は width を使用します。UI の grass edge プリセットは width: 12、curve: "sharp" の fade として保存され、草の縁として描画されます。nine-slice はソースセルピクセル単位の center: { x, y, width, height } を保存し、その中央を繰り返しながら、描画済みの輪郭に沿って周囲の境界帯を投影し、フェードのにじみを常に防ぎます。water は汎用の液体モードとして保存され、アトラスのテクスチャを維持しながら、アトラスセルの色からクリップされた色合い、岸辺の深さ、静的な波紋、エッジのきらめきを生成するため、溶岩／沼地／酸／油に固定の青い輪郭が付きません。不明な custom モードは、shaderKey が液体に類するものでない限り、エッジのハイライトにフォールバックします。transitions[] には地形 ID 間の例外ルール { from, to, mode, priority? } が保存されます。これは生成された Wang トランジション行列ではありません。Studio での地形生成では、UI 上のデフォルトとして 4x4 のソーステクスチャアトラスが使われ、生成されたアトラスがそのまま保存されます。画像処理コンテナーを使った Wang／オートタイル出力の生成は行われなくなりました。生成リクエストでは metadata.sourceTextureColumns と metadata.sourceTextureRows を設定できます。Studio はさらに terrainAtlasColumns、terrainAtlasRows、terrainStyleId、terrainStylePrompt も送信するため、サーバープロンプトでシェーダー向けの継ぎ目のないマテリアルアトラスを構築できます。エレメントセット（tileset）の生成では metadata.terrainReferenceImage と metadata.terrainReferenceMediaId を渡し、既存の地形画像をスタイル互換性のガイドとして使用できます。画像データは実行時のみ使用し、保存してはいけません。
• プレイ可能なキャラクターの設定は、/api/database/actors 配下のデータベース Actor です。プロジェクトでは、選択された Actor の _id を mainActorId に保存します。メインヒーローの取得または変更には、GET /api/database/actors/main と PUT /api/database/actors/:id/main を使用してください。Actor は外見、ヒットボックス、進行状況、インベントリ、アニメーション、スキルを所有します。
• Actor の hitbox: { width, height } は、正の RPGJS ピクセル単位の寸法を使用します。省略された場合のデフォルトは 32 x 32 です。公開ゲームプロジェクトとオフラインエクスポートでは、mainActorId をランタイム互換の hero、animations、skills フィールドに解決します。
• データベースの Actor と敵は、animations で戦闘アニメーションのスプライトシートメディア ID をサポートします。対象は attack、hurt、die、castSpell です。
• cast、Cast Spell、castspell、castSpell、castSkill という名前のリンクされたキャラクターアニメーションは、正規の animations.castSpell フィールドに解決されます。Actor／敵に明示的な上書きが設定されている場合は、そちらが優先されます。
• Actor と敵は、選択されたキャラクタースプライトにリンクされた faceset と名前付き戦闘アニメーションを自動的に継承します。これらのデフォルトを上書きする場合にのみ、faceset または個々の animations メディア ID を設定してください。references/database.md を参照してください。
• RPGJS のスターターランタイムでは、アクションバトル時にこれらのスプライトシートが使われます。攻撃アクション、ダメージ／被弾フィードバック、遅延付きの死亡時削除、スキル／詠唱の使用時に、設定されたスプライトシートへ一時的に切り替わります。
• データベースの敵は、behavior の下でアクションバトル AI オプションをサポートします。対象は enemyType、attackCooldown、visionRange、attackRange、dodgeChance、dodgeCooldown、fleeThreshold、attackPatterns、patrolWaypoints、groupBehavior です。
• データベースの敵には、軽量なプレビューエンドポイントがあります。既知の敵 ID に対して _id、name、graphic だけが必要な場合は、敵レコード全体を一覧表示または読み取る代わりに GET /api/database/enemies/preview?ids=<id1,id2> を使用してください。1 リクエストあたり、異なる ID を最大 100 件まで指定できます。
• GET /api/events は、デフォルトで従来のイベント配列を返します。ページネーションされたレスポンスを使うには page または limit を追加します。GET /api/events?page=1&limit=24 は { data, meta } を返します。ページネーションされたイベント一覧のデフォルトは sortBy=createdAt&sortDirection=desc で、sortBy=createdAt|updatedAt|name、sortDirection=asc|desc、eventType=all|character|enemy|free、assignment=all|assigned|unassigned をサポートします。
• データベースの Actor と敵は、skills の下でレベルに応じたスキル習得をサポートします。形式は { skillId, level } です。
• データベースのスキルでは、icon、animation、sound にメディア ID を設定できます。
• プロジェクト設定では、すべてのネイティブメニューで共有される、グローバルな audio.ui のセマンティックキュー（navigate、confirm、cancel、open、close、error）をサポートします。一般的なアクションバトルのデフォルト値は combatAudio（battleMusic、attack、skill、hit、hurt、die）に格納されます。どちらのグループも、Project Audio タブで編集できます。
• タイトル画面の BGM と画像は、menus.titleScreen.settings.backgroundMusic と backgroundImage で設定します。マップで戦闘音声を上書きすることはありません。データベースの敵は、audio.combat で戦闘 BGM と発生時／反応時の効果音を上書きできます。データベースのスキルでは、詠唱に sound、衝撃に impactSound を使います。すべてのサウンド値は Studio のメディア ID です。
• メディア生成タイプ image を使って、タイトル画面またはゲーム内のシーン全体を描いたアートを生成できます。生成されるのは、不透明で中央をクロップした 16:9 横長のメディアレコードです。透過背景の 4:5 キャラクターポートレートである illustration とは異なります。生成されたメディアの _id を menus.titleScreen.settings.backgroundImage に使用してください。
• ゲーム／ランタイムのコードでは、GET /api/game/media/:mediaId を使って、ゲーム内で使用可能なメディアデータを読み取れます。詳細は references/media.md を参照してください。
• メディアタイプを変更する場合は、メタデータのみを変更する管理者用エンドポイントではなく、PUT /api/media/update/:mediaId を使用してください。これにより、metadata.type とルートの type フィールドが同期されます。
• GET /api/game/maps/:mapId のゲームマップレスポンスは、可能な場合、イベントの params.graphic、params.faceset、triggers[].graphic、triggers[].faceset をメディアオブジェクトとしてハイドレートし、アクティブページのヒットボックスを event.hitbox: { width, height } として公開します。ランタイムのレスポンス形式については、references/maps.md を参照してください。
• イベントワークフローのブロックでは、call_common_event と spawn_common_event を使って、再利用可能なゲームイベントを呼び出したり、生成したりできます。どちらも commonEventId を使用します。spawn_common_event は、位置を player、current_event、variable、fixed のいずれかから解決できます。
• イベントページのトリガーには、ページペイロードで trigger: "player_touch" と trigger: "event_touch" を使用します。ランタイムのトリガーペイロードでは、どちらも type: "onTouch" として保存され、typeData.touchTarget: "player" | "event" で区別されます。互換性のため、touchTarget がない場合はプレイヤータッチとして扱われます。イベント／イベントの接触ワークフローでは、変数およびスイッチのブロックがマップ変数を使用します。影響を受けるプレイヤーを明示的に指定する機能が追加されるまでは、プレイヤー専用のブロックに対して、マップ上にいる最初のプレイヤーが一時的なフォールバックとして使用されます。
• イベントページの hitbox は、RPGJS ピクセル単位の { width, height } をサポートします。ヒットボックスがない場合のランタイムのデフォルトは 32 x 32 です。メディア／グラフィックのスケール変更は表示されるスプライトのサイズだけに影響し、ヒットボックスの幅／高さを変えてはいけません。
• イベントページの options は、directionFix、through、alwaysOnTop、alwaysOnBottom をサポートします。描画レイヤーのフラグは同時にひとつだけ使用してください。alwaysOnTop は近くのキャラクターより上にイベントを描画し、alwaysOnBottom は近くのキャラクターより下に描画します。
• イベントワークフローのブロックでは set_hitbox を使って、$player、$this、またはマップイベント ID に対して target.setHitbox(width, height) を呼び出せます。width と height は正の RPGJS ピクセル単位の寸法であり、対象のグラフィックのスケールでは拡大縮小されません。
• イベントワークフローのブロックでは camera_follow を使って player.cameraFollow(target, { smoothMove }) を呼び出せます。対象は $player、$this、またはマップイベント ID を指定した eventId から解決されます。smoothMove のデフォルトは true です。任意の time と ease を指定すると、RPGJS がサポートする高度なスムーズ遷移オブジェクトが作成されます。ease フィールドは、linear、easeInQuad、easeOutQuad、easeInOutQuad など、一般的なイージング名のドロップダウン式列挙値です。
• イベントワークフローで変数を書き込む場合は、公開されている set_variable ブロックを使用してください。change_variable はレガシーランタイムとの互換性のためだけに存在し、新しいペイロードの生成には使用してはいけません。set_variable がサポートする valueSource の値は constant、variable、random、player_x、player_y、player_direction、map_id、gold、player_id、player_name、level、hp、sp です。 敵との戦闘のテンポを調整するには、references/database.md に記載されている、パターンごとの behavior.attackProfiles のタイミング上書きを使用します。省略した値はエンジンのデフォルトを継承するため、そのままにしてください。