> ## 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.

# 仕組み

> 部屋、物の一言、ゲームの一手と盤面、ルールが動く箱について。

ステージを形づくる考え方です。ファイルの形と言葉のすべては、[エンジンのリファレンス](https://docs.livlive.ai/developers/reference/engine.md)にあります。作るのはエージェントですが、ここを知っておくと、提案や直しの話が分かりやすくなります。

## 部屋

部屋は、ステージの土台です。部屋の形(`room.glb`)と、エンジンが読む部屋の言葉(`world.json`)でできています。

* **形:** GLB ファイル一つに、全部を入れます。部屋のランプも、GLB の中のライトです(面の光は、部屋の言葉に書きます)。
* **言葉:** キャラクターが最初に立つ位置と向き、歩ける範囲、物の一覧、席、カメラが立てる範囲、明かりのスイッチ、出来事、天気、見た目の調子を書きます。
* エンジンは、キャラクターが最初に立つ位置を原点にして、部屋を置きます。

エンジンは、部屋の形そのものでキャラクターを歩かせ、座らせ、撮ります。そのとき、形はどれも体の半径ほど太らせて考えます。だから、見た目が正しい部屋でも、体の立つ場所が無いことがあります。席の前の立つ場所と、そこまでの道は空けておきます。

カメラについてステージが決めるのは、カメラが立てる範囲と、立てる場所(名前を付けて置けます)だけです。どう撮るかは番組が決めます。人を撮る絵の上の端は、その人の頭のすぐ上です。それより高く見える物は、その絵に映りません(くわしくはリファレンスの `camera`)。顔は、その顔の側からしか見えません。キャラクターの顔とカメラの範囲のあいだに背の高い物を置かず、背の高い物は、カメラから見てキャラクターの後ろに置きます。

## 物の一言

部屋の物は、物の一覧に一行ずつ書きます。一行に書くのは、id、人が呼ぶ名前、一言の説明(`about`)、種類、できること(`can`)などです。

* **一言:** 何で、どう見えるかを一行で書きます。キャラクターはこれを、指示としてではなく、その物についての事実として読み、話題にします。だから、その物の何がおもしろいか(いわれ、その場所の習わし、説明のつかないこと)を、作り手の言葉で書きます。
* **できること:** リファレンスにある言葉が、キャラクターの動作を開きます(座る、座って作業する、見る、点ける・消す)。ほかの言葉は手がかりとして残りますが、動作は開きません。
* **そばへ行ける:** 一覧のどの物にも、キャラクターは歩いて行けます。ただし、席(座る行が代わりになります)、キャラクターが立つ床、そばに立てる場所の無い物は除きます。だから物の一行ごとに、そばに立てる場所と、そこにいる顔を撮れるカメラの範囲が要ります。それを用意できない物は一行にせず、カメラの場所を用意できる別の物の一言に書くほうがよいです。
* **手に持てる物:** 別のファイルで持ってきた物は、キャラクターが手に持てるようにできます。持ち方は、決まった形から選ぶか、その物の持ち方を書きます。
* **隠れている物:** 始めは無く、出来事で見せる物も置けます。

ステージが差し出すのは、選べるものまでです。どれを選び、何を話すかは、キャラクターが決めます。

## ゲームの一手と盤面

ゲームは、ステージだけのものです。ルールをパッケージに入れ、部屋の言葉で、このステージ自身のゲームを使うと書きます。ゲームは一手ずつ進みます。

### 一手

* ゲームは、キャラクターが選べる行を差し出します。行には言葉があり、キャラクターはその言葉を読んで選びます。
* その行が、いまはできない理由を、言葉で返せます。
* 順番のあるゲームは、その人の番の行に印を付けます。番のあいだ、その場から動かさず、番の行だけを選ばせることもできます。
* 番の行について、キャラクターに問いを出せます(問いは `keeper.json` に書きます)。
* ゲームは各キャラクターに、その人だけの事実を伝えられます。ほかの人の手札は入れません(入れないのはルールを書く側の役目です)。
* ゲームが持つ行為は `keeper.json` に書き、見せる動きを、エンジンの動きの名前から選びます。
* 遊ぶ人数の最少と最多を `keeper.json` に書けます(書かなければ、出演者の全員が遊びます)。最少に足りないと、ゲームは開かず、ステージは部屋として動きます。最多より多いときは、席の順で最多までが遊び、ほかのキャラクターは見て話します。

### 盤面

* ゲームは、盤面に載せる中身を返します。題、遊ぶ人ごとの行(札と短い一言など)、真ん中の表示、勝ちや終わりの瞬間です。描くのはエンジンで、札はどれも同じ幅に描かれます。
* 盤面の行の数で、絵が変わります。行の数によっては、ゲームのあいだ、上から見た卓が絵のすべてになり、部屋とキャラクターは映りません。それ以外のときは、盤面は部屋の絵に帯で重なり、キャラクターも映ります。どの数でどうなるかは、リファレンスの `view` にあります。
* アプリ配信では、盤面は描かれません。
* 誰かが勝つと、カメラがその人へ行って戻り(その人が絵の中にいるとき)、キャストの全員にそれが伝わります。
* 盤面が終わりを伝えると、ゲームは終わります。

## ルールが動く箱

ゲームのルールは、TypeScript で `src/` に書きます。ルールはあなたの PC で `keeper.js` に変換され、livlive の箱の中で動きます。

* **箱の決まり:** 一回の呼び出しの時間、メモリ、コードの大きさ、返す答えの大きさなどに上限があります(リファレンスの「キーパー」)。
* **起こされるときだけ動く:** ルールが起こされるのは、ステージが開いたときと、キャラクターの行為などの出来事があったとき、ルールが決めた時刻だけです。毎フレームは動きません。
* **偶然は番組から:** 偶然はすべて、番組ごとに決まる種(seed)から作ります。`Math.random` は使えません。
* **入口の関数:** ステージが開いたときの `reset` と、出来事ごとの `step` は必ず書きます。行を差し出す `offers`、盤面を返す `view` などは、使うときだけ書きます。
* **外を読み込まない:** ルールが読み込めるのは `src/` の中のファイルだけです。`@livlive/game` からは、型だけを読みます。これはエディタのための型で、`livlive` の変換、確かめ、登録には要りません。
* **登録のときに試す:** 登録では、ゲームを最少の人数と最多の人数で遊んで試し、止まるゲームは断ります。PC では `livlive game check` で、同じように試せます。


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