stage-package

How an agent builds a livlive stage on the person’s own PC and hands it in — any tools, a package folder checked against the engine reference, livlive stage push, the gate’s coded answer, then a rehearsal on the real road. Read before making or changing a stage package outside the backstage.

このページは、エージェントが読む skill「stage-package」の本文です。

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

This skill is the build: how a stage is made, checked and handed in. The conversation with the person — what they want, what to propose, when to show it, where the work stands — is stage-lead; read it first when a person has asked for a stage or a game.

​

What a stage is for

A stage is the place a character enters. It holds what can be done there — the things, where a body may walk and sit, what can be switched or opened, the events, a game of its own — and the characters choose among those as they go. The stage leads; the motions and the words follow from what it offers. So a stage is good when a character has something real to do in it, and when it reads as one place. Build for that first, and for the picture second.

​

The package

A stage is handed in as one folder: the package. Its layers are named in the engine reference (reference/engine.json in livlive-kit, the MCP resource livlive://reference/engine):

• layers — each layer’s files, its version, the layers it needs, and what it adds. The room is always there; the others come only when the stage uses them. Read the folder’s shape from here, never from memory: a layer added later is one more entry.
• schemas — each JSON file’s definition, by layer and file, with what every field means.
• limits and package — sizes, counts and the GLB features the platform draws.
• frames — the units and directions the engine reads positions and headings in.
• kinds, looks, can, acts — the words the engine knows for things and what they let a character do.
• keeper — the protocol and the entry points of a game of the stage’s own.
• hold — the shared ways to hold a thing, by name (a thing’s hold.pose). A thing none of them fits brings its own row as hold.arm in place of pose (the hand, its arm’s bones, the grip point — the shape schemas describes); the gate lays it on a test body and refuses one whose hand enters the torso, whose elbow rises over the shoulder, or that lands differently on a VRM 0.x body (problems). What a character can still do with her hands full, and what can change how a thing she holds looks, is hold.whileHeld: read it before a wish or a game puts something in a hand.
• problems — every code the gate can answer, with its words and the scope it is checked in.

The reference is generated from the engine. When it and anything else disagree, the reference is right. livlive reference prints the one livlive serves now; the copy a kit carries can be older, and the CLI says so when it is.

A stage can also be kept as a source folder, which the CLI packs whenever it checks or hands the stage in:

• stage.mjs — the world, the package’s manifest, and the room’s GLB by its path in the folder;
• src/ — the rules, in TypeScript, typed by @livlive/game (import type only);
• keeper.json — what the rules declare. An act the game owns (acts) names the motion it shows from the reference’s keeper.motions, and only a name listed there.

keeper.json also says how many play: players { min, max }, whole numbers, 1 ≤ min ≤ max ≤ 4 (the reference’s schemas has the words). Below min no game opens — the stage dev page and the studio say why, and the stage runs as a room alone; above max the first max in seat order play and the others watch and talk. Registration tries the game with min performers and with max; a game that says nothing is tried with two, and every performer plays it.

livlive stage new <folder> makes these empty shapes. livlive room-kit gives the room kit’s folder, for a room built in Blender.

livlive stage new <folder> --name <name>, run at the proposal’s yes (stage-lead), also makes the stage itself on livlive by that name when the CLI is logged in, and writes livlive.json at the folder’s top: { "stage": "<id>" }, the stage the folder is for. Every push and check of the folder goes to that stage with no flag, so keep the file with the folder and never write it by hand. Logged out, stage new makes the folder only and says so, and the first push with --name makes the stage. No layer names livlive.json: it is never handed in.

​

The stage’s face

What the stage’s page and the person’s list of stages show of it, and what its performers read, are its face. It is kept beside the package and handed in with it:

• face/picture.png (or .jpg, .webp) — its 一枚絵, one picture of the whole stage;
• face/face.json — { "note": "<ひとこと>", "tone": "<色>" }: its one line, and its colour, one word of the stage page’s list;
• world/*.md — its 世界観 documents, which the performers read: one Markdown file each, named in letters, digits, ., _ and -.

world/world.md is the stage’s own document, and its place is the chapter ## 舞台: what is seen there, its air and its colour. When the stage is a place in a world, that chapter is all its performers read of these documents; when it is not, they read every document whole. So keep each chapter to a few lines, and use only the names the person gave. The ひとこと says where, who and what, in one line.

Their bounds and the 色’s words are in stage.face’s entry of the ops reference (livlive ops); livlive stage check checks the files that are there, on the PC, and says each problem as livlive would. It also warns when no document in world/ has a ## 舞台 chapter. The face is not required: a folder without face/ and world/ hands in the space alone, and the stage’s page says what is missing. stage new writes none of it. Each part is shown to the person and goes in only on their yes (stage-lead).

​

The stage’s own skill (SKILL.md)

A stage may carry one skill: how to make a show on it. It is the skill layer — a SKILL.md at the top of the package folder. Whenever a content is set on the stage, the writer (ツヅリ) is given it whole beside the other skills, so a show made here follows it.

• Its frontmatter is flat key: value lines, as every livlive skill; a list is its key alone on a line and then one - item line for each item, indented under it (an item line that starts at the margin is refused as a key out of shape). The keys: name (40 characters at most), description (when to read it), title (16), summary (60), guide (a list of 1–3 lines, 50 each). No other key is taken.
• Write what only this stage knows: what is played for, how one round runs, which rules a viewer needs and when, where the moments are. Say only what the stage does — its rules, its acts and its settings as the package makes them; nothing it cannot do.
• The guide lines are checked against every draft of a sheet made on the stage: write each as something a finished sheet visibly does.
• No concrete examples, no sample lines: they are copied.
• stage check refuses a SKILL.md out of these bounds, with its words, before anything is kept.

​

Build with any tool

Blender, a script, another model’s output, a hand-written glTF — the tools are free. The gate checks only the package. Keep the sources of the build beside the package if the person wants to change it later; they are not handed in.

Make the room’s shape the shape the characters meet: what they walk on, what stands in the way, where they sit. Name what a character can use, and describe it in the person’s language. A thing brought as its own file is placed by the world’s rows, as the things layer says.

​

What the bodies and the cameras need

The engine walks, seats and frames the characters by the room’s shape itself — every shape grown by about a body’s radius. A room that looks right can still leave a body nowhere to stand. Check these on what you built, and again on the real road:

• A seat is reached and sat in. The place a body stands to sit — in front of the seat, toward where it faces — and the way to it from the floor stay clear once every shape is grown by a body’s radius. A piece larger than the seat it serves can close that way: size it or set it back until the way is clear, and judge by the way, not by the picture alone. Its seat’s top is the height the seat declares (states, seat_height).
• What is reached across stays reachable. What a seated hand reaches over keeps its edge and rail below the hand’s path; a reach whose hand or forearm meets the room’s shape is not made.
• The cameras see the faces. Nothing tall stands between the camera’s room (camera.volume) and the face of a body in a seat or at a place it acts from. Anything tall belongs behind the bodies as the cameras see them. A face is also seen only from its own side: a body at a thing stands facing it, so at a thing against a wall she turns her back on a camera room that lies behind her. The camera’s room has to reach beside her there — level with her or ahead of her. Every row of objects is a place a character may walk up to unless the reference means otherwise for it (the can list’s go_to row: a seat and a floor she stands on are never offered a walk), so each other row needs such a place for a camera. A row with nowhere to stand beside it is no exception: it is a fault, and the patrol reports it. What cannot have a place for a camera is better told in the about of a thing that can than given a row of its own.
• What is high is out of the picture. The programme’s shots are framed on the people through a narrow view, so anything meant to be seen in a picture stands within it: the world schema’s camera says how high that reaches. Read it before placing anything far above the people.
• A thing invites a word. A thing a character can look at and talk about carries its about in the person’s language. That is what a character takes up in talk, and its words come back as the characters’ lines. In a place to live in, it keeps what is curious about the thing: its story, a habit of the place, something left unexplained. On a stage made for a programme that wants dense talk, it keeps to what the thing is and what it is for, with no atmosphere and no little story.
• A drawn look is declared, not baked in. Outlines and light in steps (look.ink) and a glow around what is bright (look.glow) are the space’s own words, within the ranges limits names; what glows is what the room’s materials light from themselves.

​

Check before handing in

Before a push, check what you can on the PC:

1. Every JSON file against its schema in schemas (any JSON Schema validator).
2. Every GLB with a glTF validator (the Khronos glTF-Validator): no errors, and only the features package lists.
3. The counts and sizes against limits.
4. Positions and headings in frames’ units and directions, and the rules each schema states for its own file (a thing’s origin is in thing.json’s).
5. livlive game check <folder> — the rules translated on this PC, checked on livlive’s side and played on the stage’s world, as registration plays them.
6. livlive stage dev <folder> — the stage drawn by livlive’s engine on its dev page, read from the folder on this PC; each saved file shows again in seconds. A saved rule file is translated again on this PC; a problem of the translation prints at once as <code> — <words> (the game.* codes of scope translate in the reference’s problems). The dev page tells this terminal, in registration’s codes, when a game does not open, and the terminal prints each as <code> — <words> in every mode. Silence means only that no refusal was heard — a page that is not open tells nothing — and is no OK. A game without reset or step is shown on the page, but this terminal does not name it; livlive game check says it as keeper.js_functions. The dev page has three ways to move the characters: 乗り移り, 巡回 (the one --patrol asks for) and キャラに任せる. The first two stay free. 乗り移り lets the person take a character’s place: the rows offered are what that character may do now, in the words the character reads; on a stage with a game the page casts the game’s players as the patrol does (below). A character the person does not play moves only on a turn the game asks of her — rows its offers mark due, which leave no 「いまのまま」 on her menu — and then by a seeded draw, so the game moves while the person plays the lead; a game a character starts by her own act, with no turn asked, leaves the others standing on this page. Every body in the cast is loaded before the stage plays, so each character more is time the person waits. The picture follows the character the person plays: another character of the cast is in the stage and takes her turns, but she is seen only when she comes into that picture. To look at the stage as her, the person makes her the lead; a body once read stays with the open page, so only a body not yet read is downloaded then. Two characters are seen together in the rehearsal. The dev page has no button for a stage’s event (rules.happenings): an event is raised only in the studio, on the 出来事 tab, during 本編 of a rehearsal or a 本番, so the rehearsal is where an event is first seen — do not ask the person to look for its button on this page. --patrol walks the person’s lead character through every seat and every thing and uses each switch once; on a stage with a game it does this first with the game left out, then plays the game with up to as many characters as players.max says (two when it says none) — the person’s chosen 二人目, 三人目 and 四人目, the places left empty filled from their other characters, which the page names — and judges the seats the game gives. It prints each finding as <code> — <words> (the patrol.* codes are in the reference’s problems, scope patrol) and exits 1 for trouble, 3 when it found none but could not check every place, 0 when nothing was found. The page must be open and signed in to livlive: the command opens it (with --no-open, open the address it prints). A page that cannot patrol (no character, a stage it cannot draw) says why and exits 2, as does no report within --wait seconds (900). patrol.not_covered names what the patrol could not check (no answer in time, a face never counted, 「ゲーム」 when the game never got going — often too few characters: a person with fewer than min (two when it says none) must welcome more, since the page fills the places only from the characters they have, and says how many; or a game that never asks a turn: the patrol counts a game as going by the first turn it asks (rows its offers mark due, not only seats to sit in), so a game whose acts stay open to anyone at any time is reported this way however well it plays — say so to the person; livlive game check and the rehearsal speak for such a game): a gap in the check, not a fault of the stage. Exit 3 is an incomplete check, not a wrong stage: read why before changing anything, and never change a game only to let the patrol through. A clean patrol is still no OK: the rehearsal decides. キャラに任せる hands the characters to their own judgment, run by livlive’s runtime with no voice and no lines — only their picks — so a game moves by what they pick. A rehearsal in the studio is still the last word. It uses the person’s credits, for the characters’ judgment and for the minutes of the live room it runs in. The page says so (「任せている間、クレジットを使います(キャラの判断と部屋の分)」). Only the person’s press on 「キャラに任せて動かす」 starts it. With no credits the press is refused (「クレジットを使い切りました。」). The CLI and the MCP never start it and stay unpaid. Ask the person to press. A run ends when:
   • the person presses 「止める」 or chooses another way;
   • the page draws the stage again, which it does on every save (a save that fails to read keeps the run), so finish the edits before asking the person to press, or tell the person that a save ends the run;
   • the characters chosen on the page change;
   • the page is closed or left;
   • the page has been out of sight for five minutes (「しばらく見えていなかったので止めました。」), so keep it in view;
   • 30 minutes have passed since the start (「30分たったので止めました。」), so a run left open does not keep using credits;
   • the stage cannot be drawn (「ステージを描けませんでした。」);
   • the characters’ judgment stops or leaves the room (「キャラの判断が止まりました。」) or does not arrive within a minute of the press (「始められませんでした。もう一度押してください。」): that is livlive’s runtime not answering, not a fault of the stage;
   • a newer start comes: there is one run per person, so a start from another tab ends the older one.
7. livlive stage check <folder> (with --name <name> or --stage <id> only when the folder has no livlive.json) — before replacing a stage’s space: every check a push runs, on a stage you have, which it leaves as it is, and the face’s files against their bounds. A new stage is simply pushed, since a refused push changes nothing. The GLBs a check uploads stay for the push. A live rehearsal or 本番 on that stage refuses the upload, so check between runs.

A check answers for the folder as it stood when the check ran. After a change made because of a finding, run that check again before the push: a push after an unchecked change hands in a guess. The hand-in waits for a patrol that ends without trouble — 0, or 3 with what it could not check said to the person. A finding you would rather leave is the person’s to accept: say which, why it stays and what they will see because of it, and push only on their yes.

These catch most refusals early. The gate still decides; a clean local check is not an OK.

​

Hand it in

livlive stage push <folder>                  # the stage the folder's livlive.json names
livlive stage push <folder> --stage <id>     # a stage you have (livlive stage list), when the folder names none
livlive stage push <folder> --name <name>    # your stage of that name, made when there is none, when the folder names none

These are the CLI’s commands for the stage.* ops (livlive ops lists them). The CLI reads the folder by the reference’s layers, sends each GLB once, and registers the package as the stage’s space. A push replaces the stage’s space at once, and prints the address of the stage’s page. A push is refused while a rehearsal or a 本番 runs on that stage; push again when it ends. livlive stage read <id> shows the registered space as the engine reads it: its things; its seats (where, and the height a body sits at) and placements in the room’s frame, as world.json writes them; its switches and how each starts; the walk in the engine’s frame (placed by the spawn). Compare them with what you wrote.

With face/ or world/ in the folder, the push then sends the stage’s face. It fills only what is empty on the stage: a field the person set on the stage’s page, or an earlier push set, is kept as it is, and the push says what it set and what it kept. To replace a kept field, and only when the person asks for it, push with --replace naming those fields (picture, note, tone, world, joined by commas); never add it on your own. A push cut part way says what it set first: push the same again, and what was set is kept while the rest is filled.

A folder the CLI cannot read (a missing required file, a JSON that does not parse) stops before anything is sent.

​

Read the gate’s answer

A refusal changes nothing: the stage keeps the space it had. Each problem comes as <code> — <words>:

• The code says which rule failed: its first part names the layer or the door it belongs to. Look it up in the reference’s problems: each code is listed with its words, the parts that vary shown as 「…」. Then find that rule in the layer’s schema or in limits.
• The words are what a person reads on the stage page; they say what and where.
• Fix every problem the answer lists, then push again. Fix the cause in the build, not in the exported file, so the next export stays fixed.

​

The real road decides

A registered space is not yet a working stage. The person (or the backstage’s road check) runs a rehearsal on it from the studio, with a character on it: walking, sitting, using what the stage offers, its game if it has one. What goes wrong there is fixed in the package and pushed again. A stage is done when it worked in a rehearsal — never because the gate took it.

A game a character starts by her own act begins whenever she happens to take it — from the first moments of 本編, not at the stretch the programme means for it — and can be over before that stretch comes. A game that must begin at a chosen point of the programme starts from something that happens there: today that is an operator’s press of one of the stage’s events (how a game hears it: the reference’s keeper.contract, its step row).