> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livlive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This is livlive's documentation. An agent reaches livlive from outside through the `livlive` CLI or the livlive MCP server (see /developers/install, /developers/cli and /developers/mcp). The person links it to livlive once, in the browser: `livlive login`, the local MCP's `livlive_login` tool, or the remote MCP at https://backstage.livlive.ai/api/mcp signing in by OAuth; a personal token made in livlive's settings is for CI. Pages marked 準備中 describe parts not decided yet: do not guess their behaviour.

# はじめてのステージ

> AI エージェントと一緒に、最初のステージを作り、リハーサルで確かめるまでの流れです。

ステージは、決まった道を通ってできあがります。エージェントは報告のたびに、いま道のどこにいるか、いま何が済んだか、次に何をするか、誰の番かを伝えます。いま開くとよい頁と、そこで見ることも伝えます。PC で入ってみるあいだは開発用の頁(`livlive stage dev` が出したアドレス)、提案のはいのあとは livlive のステージの頁(`/stages/<id>`)と、道のりの頁でのそのステージの場所(`/stages/new?stage=<id>`)、リハーサルではスタジオです。

この頁は、その道の場所を順に、あなたがすることとエージェントがすることに分けて書いています。順番は、キットだけを持ったエージェントと実際にステージを作ったとき([ギャラリー](https://docs.livlive.ai/developers/stage-kit/gallery.md)の駄菓子屋)に通った順です。

> [!WARNING]
>
> いまは招待制βの準備中です。CLI と MCP は npm から入れられますが、使うには livlive のアカウント(招待制)が要ります。スキル(`npx skills add`)は、livlive-kit の公開とともに使えるようになります。

ステージ開発キットも、この livlive-kit に入っています。用意のしかたは、[クイックスタート](https://docs.livlive.ai/developers/quickstart.md)の「CLI で始める」と[インストールと連携](https://docs.livlive.ai/developers/install.md)にあります。

## 道の場所

| 場所 | ここですること | 次へ進むとき |
| - | - | - |
| 伝える | あなたが、作りたいものを伝える | エージェントが言い直したことに、あなたがそうだと言ったとき |
| 提案 | 作れるもの、作れないもの、いちばん近い形 | あなたが、はいと言ったとき |
| PC で入ってみる | 作りかけのステージを、開発用の頁で見る | あなたが、キャラクターとして中に入ったとき |
| 直す | 見たことや、検査で見つかったことを直す | 直したいことが残っておらず、登録の前の検査を通ったとき |
| 登録 | livlive に登録する。一枚絵・ひとこと・色・世界観も一緒に | 登録されたとき。断られたら、直すへ戻る |
| リハーサル | スタジオで、キャラクターがステージで過ごす | キャラクターがそこで過ごしたとき。足りなければ、直すへ戻る |

道は戻ることもあります。新しい望みは提案へ、見たことや検査で見つかったことは直すへ戻ります。戻るときもエージェントはそう伝え、済んだままのことも伝えます。

## 道のりに沿って

**1. 伝える**

**あなた:** 作りたいものを、自分の言葉で伝えます。キャラクターがそこで何をして、どう過ごしてほしいか。それを見て、何がうれしいか。どのキャラクターを考えているか。ゲームがあるなら、そのどこが大事か。持っている道具やファイル、自分で決めたいことと任せたいことも伝えます。色や大きさ、置く場所、素材、自分の絵など、細かく指示してもかまいません。エージェントはそれを、あなたが決めたこととして、自分の案より先に置きます。

**エージェント:** スキルとエンジンのリファレンスを読み、あなたの望みを、あなたの言葉で言い直します。決まった質問を順に聞くことはしません。全部を伝えたなら、提案に要ることだけを聞きます。話しながら形にしたいなら、一つずつ決め、そのたびに見て答えられるものを出します。

どちらでも、作る前に次の三つは決めます。もう伝えたことは聞き直さず、言い直して確かめます。

* **見た目。** ステージは、基本的にアニメ調で作ります。どんな雰囲気にしたいかを聞きます。
* **道具。** 品質のために、あなたのキーで参考の絵と 3D の模型を作れることを伝えます(この頁の下の「自分のキーで、絵と 3D を作る」)。
* **ゲーム。** まだ話に出ていなければ、ステージだけのゲームも作れることを、一度だけ伝えます。

**2. 提案**

**エージェント:** 作り始める前に、望みのすべてをリファレンスに照らします。そして、作れるもの、作れないものとその理由、作れないものごとにいちばん近い形を伝えます。近い形は、あなたが名前を挙げたものではなく、それで何をしたかったかに近い形です。黙って落としたり、取り替えたりはしません。読むだけでは決められないことは、まだ分からないと言い、PC で小さく試してから答えます。

何が見えるかも伝えます。選び方によっては、絵そのものが変わるからです(この頁の下の「絵のこと」)。

**あなた:** はいと言うか、変えたいことを伝えます。エージェントは、はいを聞くまで作り始めません。あとから出た望みも、作る前にもう一度照らします。ステージの名前も、ここで決めます。

**エージェント:** はいを聞いたら、その名前で livlive にステージを作ります(無料です)。このときから、ステージは livlive のステージの一覧に「制作中」で出ます。

作れるものの見当は、[作れるもの・作れないもの](https://docs.livlive.ai/developers/stage-kit/limits.md)にあります。

**3. PC で入ってみる**

**エージェント:** `livlive stage new <フォルダ> --name <名前>` でフォルダを作ります。CLI が livlive と連携していれば、同じコマンドがステージも livlive に作り、フォルダの `livlive.json` にそのステージを覚えます。それからの登録は、いつもこのステージに行きます。まだ連携していなければ、フォルダだけを作り、ステージは最初の登録のときにできます。自分のキーで絵と 3D を作るなら、あなたがキーを書いたあと、まずステージ全体の絵を一枚見せ、その絵で見た目をあなたと決めます(この頁の下の「自分のキーで、絵と 3D を作る」)。そのあとすぐ、その絵に沿って、見て、中に立てるだけのものを作ります。これから作る物の場所には、仮の形を置きます。キーを使わないなら、全体の絵は作らず、仮の形から始めます。まだできていないことと、あなたに見てほしいことを伝え、開発用の頁を開くコマンドを渡します。

**あなた:** 自分のキーで絵と 3D を作るなら、フォルダができたところで、その `.env` にキーを書きます(この頁の下の「自分のキーで、絵と 3D を作る」)。全体の絵を見て、これでよいか、変えたいことがあるかを伝えます。

渡されたコマンドを、自分のターミナルで動かしたままにします。

```bash theme={null}
livlive stage dev <フォルダ>
```

livlive の開発用の頁が、ブラウザに開きます。livlive にログインしたブラウザで開いてください。頁の「キャラクター」で、あなたのキャラクターを選びます。「乗り移り」では、あなたがそのキャラクターになり、並んだ行から選んで動かします。並ぶ行は、そのキャラクターがいまそこでできることです。

エージェントに伝えるのは、気づいたこと、したかったのにできなかったこと、おかしいと感じたことです。直すことは、ここから生まれます。

**4. 直す**

**エージェント:** あなたが見たことと、検査で見つかったことを直します。登録の前に、PC で確かめられることを確かめます。ファイルの形と数の上限、`livlive game check`(ルールを livlive で試す)、巡回です。直したら、その検査をもう一度かけます。

提案のはいのときにステージを作ること、livlive で確かめる検査(`livlive stage check`・`livlive game check`)と登録には、CLI と livlive の連携が要ります。まだなら、エージェントがそのときに頼みます。ブラウザで一度「連携する」を押すだけです([インストールと連携](https://docs.livlive.ai/developers/install.md))。

見つかったことのうち、エージェントが直さずに残したいものは、あなたが決めます。エージェントは、どれを、なぜ残すか、それで何が見えるかを伝え、あなたがはいと言ったときだけ登録します。

**あなた:** 直ったものを、開発用の頁でもう一度見ます。保存されたファイルは、頁が数秒で描き直します。

**5. 登録**

**エージェント:** 登録の前に、ステージの一枚絵・ひとこと・色・世界観を用意します。ステージの頁とステージの一覧に出るものと、キャラクターが読むものです。一枚絵は、自分のキーを使うなら、あなたと決めたステージ全体の絵です。キーを使わないなら、エージェントが Blender で描いた部屋の絵か、あなたがステージの頁で入れる絵です。色は、ステージの頁の色の一覧から選びます。一つずつ見せ、あなたがよいと言ったものだけを、登録と一緒に送ります。無くても登録はでき、足りないものはステージの頁に出ます。

そして `livlive stage push` で livlive に登録します。登録すると、そのステージの中身はすぐに置き換わります。一枚絵・ひとこと・色・世界観は、ステージでまだ空いている所にだけ入ります。あなたがステージの頁で入れたものは、そのまま残ります。置き換えたいときは、エージェントに頼んでください。断られたときは、何も変わりません。エージェントは断られた理由をあなたの言葉で伝え、直すへ戻ります。

**あなた:** 登録したステージは、livlive のステージの頁(`/stages/<id>`)で確かめられます。エージェントが、そのアドレスを伝えます。

**6. リハーサル**

リハーサルには、このステージを使うコンテンツが要ります。そのキャストに、あなたのキャラクターが入っていることも要ります。

**エージェント:** コンテンツを用意します。要望、企画書、構成表を書き、このステージをコンテンツに設定します。外からのこの用意では、クレジットを使いません。構成表は、キャラクターがこのステージのものを使えるように書きます。そのあと、スタジオで押すものと、リハーサルがクレジットを使うことを伝えます。

**あなた:** パソコンでスタジオを開き(コンテンツの頁の「リハで見る」か「スタジオへ」から開けます)、リハーサルをします。

1. 「リハを準備する →」を押します。押せないときは、横の行に、キャストの何が足りないか(声、ソウル、体、デビュー)と、どこで直すかが出ます。
2. 「動く」にチェックが入ったまま、「▶ リハを開始」を押します。始めたタブがステージを描くので、閉じないでください。
3. 「リハ本編を開始 ▶」が押せるようになったら、押します。

見たことを、エージェントに伝えます。キャラクターがそこで過ごしたら、できあがりです。足りなかったことは直し、もう一度登録して、もう一度リハーサルをします。

## 自分のキーで、絵と 3D を作る

ステージに置く物は、あなた自身のキーで、二つのサービスに作らせることもできます。品質のために、エージェントは作る前にこれをすすめます。使うかどうかは、あなたが決めます。

| サービス | 作るもの | キーの名前 |
| - | - | - |
| gpt-image(OpenAI) | 参考の絵。はじめにステージ全体の絵を一枚、次に置く物の絵を一つずつ描きます。どう見えるかを、形にする前にあなたとエージェントで決めるための絵です | `OPENAI_API_KEY` |
| Tripo | 3D の模型。物を一つずつ、その物だけを描いた絵から作ります | `TRIPO_API_KEY` |

できた模型は、エージェントがあなたの PC の Blender で、ステージに合わせます。ステージ全体が[数の上限](https://docs.livlive.ai/developers/stage-kit/limits.md)に収まるように、形の細かさを減らし、画像を小さくして、大きさと向きを直します。

### 料金とキー

* **料金は、あなたのアカウントにかかります。** 絵はあなたの OpenAI のアカウントに、模型はあなたの Tripo のアカウントに、それぞれのサービスの料金でかかります。livlive のクレジットは使いません。
* **キーは、ステージのフォルダの `.env` に書きます。** キーは、OpenAI と Tripo のそれぞれで作る、あなたの API キーです。エージェントが `livlive stage new` でフォルダを作ったら、そのフォルダの `.env.example` をコピーして `.env` という名前にし、使うキーを `OPENAI_API_KEY=` と `TRIPO_API_KEY=` のあとに書きます。使わないほうは、空のままでかまいません。`.env` で空のキーは、同じ名前の環境変数があれば、そのキーが使われます。
* **キーは、そのサービスにだけ行きます。** キーを読むのは、`livlive picture make`(絵)と `livlive model make`(模型)だけです。それぞれのキーは、そのサービスにだけ送られ、livlive には届きません。フォルダの `.gitignore` が、`.env` を git に入れないようにしています。
* **キーは、エージェントに渡しません。** 会話にも書かないでください。エージェントも、キーを聞かず、`.env` を開きません。

### 作る前に聞き、一つずつ見せる

料金のかかるものを作る前に、エージェントは何を作るか(全体の絵、どの物の絵、どの模型)を伝えます。作るのは、あなたがはいと言ったものだけです。もっと作るときは、もう一度聞きます。

キーを使うときは、次の順で作ります。

1. **ステージ全体の絵。** あなたがフォルダの `.env` にキーを書いたら、エージェントはまず、ステージ全体を描いた絵を一枚作ります。物を一つずつ描いた絵ではなく、部屋をまるごと一枚に描いた絵です。見た目は、この絵であなたと決めます。よいと思えるまで、あなたに聞いてから描き直します。あとで見た目を変えるときも、まずこの絵から描き直します。
2. **仮の形。** あなたがこの絵でよいと言ったら、エージェントはすぐに、その絵に沿って部屋の形を作り、これから作る物の場所に仮の形を置きます。模型を作るのは、あなたが開発用の頁で中を歩いてからです。
3. **物の絵。** 置く物の絵を、全体の絵をもとに一つずつ描きます。もとが同じ絵なので、物の見た目がそろいます。
4. **模型。** 模型は、物を一つずつ描いた絵から作ります。全体の絵からは作りません。できた模型は Blender でステージに合わせ、あなたがよいと言った物から、仮の形と入れ替えます。

部屋そのもの(壁や床、備え付けのもの、照明の器具や光る面)も、全体の絵に合わせて作ります。物を模型にしたときに、部屋だけが仮の形のまま残ることはありません。照明は、絵のとおりの場所と色にし、明るさはキャラクターのために決めます(下の「絵のこと」の照明)。できあがりと言う前に、エージェントはあなたに、全体の絵を開発用の頁の横に開いてもらい、両方を見比べてもらいます。

絵は、できたファイルをそのまま見せます。模型は、Blender で描いた正面と斜めの絵で見せ、置いたあとは開発用の頁で見せます。そのたびに、エージェントは分からないことを聞きます。

絵は一分もかからず、模型は数分でできます。できた絵と模型はフォルダの `art/` に入り、PC に残ります。登録で送るのは、ステージのパッケージのファイルだけです。

模型を見せる絵には、アニメ調の線がありません。線は模型に描き込まず、ステージの見た目の調子のうちの線と色の段(`look.ink`)として、エンジンが部屋全体に描くからです。エージェントは、決めた雰囲気に合わせてそれを書きます。線は、模型を置いたあと、開発用の頁で見えます。

### キーを使わないとき・断られたとき

キーを使わないなら、エージェントは絵も模型も作らず、Blender だけで作ります。それで見た目がどう変わるかも、作る前に伝えます。キーが無いまま絵や模型を作ろうとすると、コマンドはサービスに何も頼まずに止まり、エージェントが、どのキーをどこに書くかを伝えます。

サービスが断ったとき(残高が足りない、頼みすぎた、絵が断られた、など)は、エージェントが、どのサービスがなぜ断ったかと、何に料金がかかったかを、コマンドが伝える範囲で伝えます。残高とキーのことは、あなたがそのサービスで直します。

模型を頼んだかどうかが分からなくなったときは、エージェントは作り直さず、あなたに Tripo の作業の一覧を見てもらいます。見つかった作業の模型は、料金をかけずに受け取れます。

## 知っておくこと

### 開発用の頁は、コマンドが動いているあいだだけ使える

開発用の頁は、`livlive stage dev` が読んだフォルダを描きます。コマンドが止まると、頁には「手元のフォルダとのつながりが切れました。」と出ます。そのあと開いた頁には、描くものがありません。エージェントが自分で動かしたコマンドは、エージェントの番が終わると一緒に止まることがあります。だから、コマンドはあなたのターミナルで動かしたままにします。

開発用の頁には、livlive にログインしたブラウザと、あなたのキャラクターが要ります。

### 開くまで、少し待つ

ステージは、キャストの全員の体を読み込んでから動き出します。キャラクターが一人増えるごとに、待つ時間が増えます。一度読み込んだ体は、頁を開いているあいだ頁が持っています。キャストを変えたときに読み込むのは、まだ読み込んでいない体だけです。

### ゲームのあるステージでは、頁がキャストを埋める

ゲームのあるステージでは、開発用の頁は、ゲームを遊べる最多の人数ぶんのキャラクターを並べます。「二人目」などで選ばなかった場所は、あなたのほかのキャラクターで埋め、その名前を頁に出します。あなたが一人を動かすあいだ、ほかのキャラクターが動くのは、ゲームがその番を求めたときだけです。そのときは選べる行から引いて動くので、ゲームは進みます。キャラクターが自分の行為で始めるゲームで、番を求めないものでは、ほかのキャラクターはこの頁では立ったままです。

遊ぶのに要る人数よりキャラクターが少ないと、ゲームは開きません。頁は、何人要るかを伝えます。そのときは、キャラクターを迎えます([キャラクター](https://docs.livlive.ai/guide/characters.md))。

### 絵は、あなたが動かすキャラクターについていく

開発用の頁の絵は、あなたが乗り移ったキャラクターを追います。キャストのほかのキャラクターもステージにいて、自分の番に動いていますが、その絵に入ったときだけ映ります。ほかのキャラクターから見たいときは、「キャラクター」でそのキャラクターを選びます(まだ読み込んでいない体があれば、そこで読み込みます)。二人が一緒に映るのを見るのは、リハーサルです。

### 三つの動かし方

| 動かし方 | 誰が選ぶか | クレジット |
| - | - | - |
| 乗り移り | あなたが、並んだ行から選ぶ | 使わない |
| 巡回 | 決まった手順が、席と物をひととおり回る | 使わない |
| キャラに任せる | キャラクター自身の判断(声とせりふは無く、選ぶだけ) | 使う |

**巡回**は、あなたが動かすキャラクターで、すべての席と物を回り、スイッチを一度ずつ使います。ゲームがあれば、ゲームを外して回ったあと、ゲームを遊びます。頁の「巡回」で始めるか、コマンド(`livlive stage dev <フォルダ> --patrol`)で始めます。見つかったことは、頁と、`livlive stage dev` を動かしているターミナルの両方に、一つずつ出ます。ターミナルに出た行をエージェントに渡せば、エージェントが読んで直します。

**キャラに任せる**は、頁に「任せている間、クレジットを使います(キャラの判断と部屋の分)」と出ます。あなたが「キャラに任せて動かす」を押したときだけ始まり、CLI と MCP からは始められません。「止める」を押したとき、保存して頁が描き直したとき、キャラクターを変えたとき、頁を閉じたとき、しばらく画面に見えていなかったとき、始めてから決まった時間がたったときなどに止まります。止まる場合のすべては [stage-package](https://docs.livlive.ai/developers/skills/stage-package.md) にあります。

どの動かし方で確かめても、最後に決めるのはスタジオのリハーサルです。

### 絵のこと

* **盤面の行の数で、絵が変わる。** ゲームの盤面に並ぶ行の数によっては、ゲームのあいだ、上から見た卓が絵のすべてになり、部屋とキャラクターは映りません。それ以外のときは、盤面は部屋の絵に重ねて出て、キャラクターも映ります。エージェントは、これを提案のときに伝えます。
* **物のほうを向くと、顔がカメラから外れることがある。** キャラクターは、物のそばに行くとその物のほうを向きます。壁ぎわの物では、カメラに背を向けることがあります。エージェントは、カメラが立てる範囲と物の置き方で、顔が見えるようにします。巡回は、顔が隠れる場所を見つけて伝えます。
* **照明は、キャラクターのため。** 開発用の頁で、キャストのどのキャラクターも、白く飛ばず、暗く沈まずに、元の色で見えるようにします。色の白いキャラクターから先に白く飛ぶので、「キャラクター」で一人ずつ選んで見てください。暗い雰囲気は、照明を暗くして出すのではなく、部屋の色で出します。暗くした照明を補おうと強めると、キャラクターが白くなるからです。部屋を明るくするときも、部屋の色や、それ自体が光る面で明るくし、人に当てる光は強くしません。

### 巡回で何も見つからなくても、まだできあがりではない

巡回で見つかるものが無くても、それは PC の検査を通ったということです。決めるのはリハーサルです。

誰でもいつでも行為ができるゲームでは、巡回はゲームが始まったと数えられず、「巡回で確かめきれなかった: ゲーム」と出ます。これは確かめきれなかったということで、ステージの誤りではありません。そういうゲームは、`livlive game check` とリハーサルで確かめます。

### 登録が断られても、ステージは変わらない

断られた登録は、何も変えません。ステージは、前に登録した中身のままです。そのステージでリハーサルか本番が動いているあいだは、登録は断られます。終わってから登録し直します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.