紙芝居DSL 4.0 台本作成ガイド

公開プレリリースと文書基準

文書状態: 公開プレリリースrc.8の固定実装基準を説明する台本作成ガイド
調査基準: TM Kamishibai 29c0dea（v4.0.0-rc.8）、2026年8月20日

配布状態との区別: 2026年8月20日時点でv4.0.0-rc.8はprereleaseとして公開されていますが、 正式なv4.0.0ではありません。ポーズoverlayはrc.8と、同版がexact pinするTurboWarp TM 1.12.0で利用できます。

このガイドと紙芝居DSL 4.0 Schemaリファレンスは、同じ完成版の実装を 調査基準にしています。Schemaはruntime実装から生成するものではありません。どの実装がどこまで入っているか、 根拠となる資料はどれかを確認したい方は、巻末の「付録: 実装基準と実装根拠」を参照してください。

チュートリアルと本書の使い分け

入門チュートリアル「紙芝居を作る」は、配布されたひな形を一つ変更して、最初の作品を 完成させるための短い実習です。本書のすべての書き方や命令を順に読む前提ではありません。

チュートリアルがまだ公開されていない間は、最短経路を「大人向け概要 → 本書の記法 → 最小台本 → 作品フォルダーへファイルを置く → ブラウザーで確認する → エラーを直す → 作成時のチェックリスト」とします。チュートリアル 公開後は、最初の作品を完成させる目的ならチュートリアルを先に使い、機能を追加するときだけ本書の該当節へ 移ります。どちらの場合も、本書を最初から最後まで通読する必要はありません。

このガイドの読み進め方

初めて台本を書く場合は、次の順序で進めてください。Schemaリファレンスは最初から通読せず、手順の途中で 項目や命令の詳細が必要になったときに参照します。

すでに3系作品がある方は、先に 3系作品の変換ガイドで別ファイルへ変換し、 生成されたYAMLを本書の「最小台本」「作品フォルダーへファイルを配置する」「診断と安全停止」と照合してください。 実装状況や公開状況を調べる必要がある場合は、巻末の「付録: 実装基準と実装根拠」を参照してください。台本を書くだけなら、そのまま「最小台本」へ進めます。

DSL 4.0の記法

DSL 4.0は制限付きYAML 1.2で記述します。引数には名前が付き、背景、位置、時間などの意味を 台本から読み取れます。一つの項目には命令を一つだけ書きます。

- Hero.show:
    skin: HeroHappy
    x: 0
    y: -60
    scale: 30

標準のファイル名の末尾は.k4.yml、版の宣言はkamishibai: '4.0'です。場面はscenesの下へ、 命令は一つのキーを持つ項目として書きます。複数の指定値はx、y、secondsのような名前で表します。

最小台本

ファイルをUTF-8で保存します。新規projectでは短い.k4.ymlを推奨します。

kamishibai: '4.0'

assets:
  Beach: backdrop
  HeroIdle: costume:Hero

actors:
  Hero: HeroIdle

scenes:
  opening:
    - stage: Beach
    - Hero.say:
        text: こんにちは！
        seconds: 2
    - wait: 1

この台本は、次の内容を表します。

1. Beachをプロジェクト内の背景として登録する
2. HeroIdleをHero用のコスチュームとして登録する
3. Heroアクターの初期コスチュームをHeroIdleにする
4. 最初のopeningシーンで背景を変更する
5. Heroが2秒間話し、1秒待つ

kamishibaiとscenesだけがトップレベルの必須項目です。scenesには一つ以上のシーンが必要です。 通常実行は、scenesへ最初に書いたシーンから始まり、明示的な遷移がなければ記述順に次のシーンへ 進みます。これはYAMLのmapping一般の保証ではなくDSL 4.0固有の規則です。sceneの並べ替えに関する注意は 「sceneの記述順を保つ」を参照してください。

作品フォルダーへファイルを配置する

一般作者向けの最小構成では、YAML、画像、音声をプロジェクトルート直下へ置けます。ポーズモデルだけは複数のファイルを 一つの束として扱うため、モデル単位のディレクトリにまとめます。

tutorial-story/
├── project.source.json
├── story.k4.yml
├── ocean.svg
├── hero-happy.svg
├── opening.mp3
├── rescue-pose/
│   ├── model.json
│   ├── metadata.json
│   └── weights.bin
└── chapters/
    ├── rescue.k4.yml
    └── rescue-background.svg

assets/、images/、sounds/、pose-models/等の分類用ディレクトリは必須ではありません。作品が大きく なった場合に任意で使用できます。単一ソースまたはプロジェクトルートのstory.k4.ymlで宣言したfile: ocean.svgは プロジェクトルートのocean.svgを示します。読み込み先ソースで宣言したアセットは、そのソースのディレクトリを基準に 解決します。

Web Previewで選択するのはYAML fileではなくtutorial-story/に当たるプロジェクトルートのディレクトリです。 Web Previewはプロジェクトルート直下のproject.source.jsonを読み、次の規則でYAMLを一つに決定します。

• 新規の作品フォルダーではプロジェクトルート直下のstory.k4.ymlをpathへ明示する
• path省略時は後方互換の既定値story.kamishibai.yamlを使用する
• 別名を指定する場合も、プロジェクトルート直下にある、正式な拡張子を持つファイル名だけを使用する
• stories/main.k4.ymlのようにディレクトリを含むエントリーパスは使用しない
• ディレクトリ内のDSLソースを走査して推測しない
• manifestが不正な場合は既定値へfallbackせず、診断を表示する

新規の作品フォルダーでは、project.source.jsonへ次のようにエントリーソースを明示します。

{
  "formatVersion": 1,
  "mode": "external",
  "sourceId": "main",
  "path": "story.k4.yml"
}

正式に受理する拡張子は.k4.yml、.k4.yaml、.kamishibai.yml、.kamishibai.yamlです。短い .k4.ymlを新規ソースの推奨表記とし、長い表記は既存の作品フォルダーとの互換性のため維持します。 build-dsl4は--source-manifestでこのmanifestを指定し、validate-dsl4 --inputは検証するYAMLを 直接指定します。

台本を複数ファイルへ分ける（include）

dsl4SourceIncludesを起動時に明示ONにすると、エントリーソースのinclude文から複数ソースを読み込み、 一つの台本として合成できます。includeは一件の文字列またはlistで指定します。

# story.k4.yml
include:
  - chapters/rescue.k4.yml

kamishibai: '4.0'
assets:
  Ocean:
    kind: backdrop
    file: ocean.svg
scenes:
  opening:
    - goto: rescue

# chapters/rescue.k4.yml
assets:
  RescueBackground:
    kind: backdrop
    file: rescue-background.svg
scenes:
  rescue:
    - stage: RescueBackground

chapters/rescue.k4.ymlのfile: rescue-background.svgは、宣言元を基準に chapters/rescue-background.svgへ解決されます。絶対パス、URL、backslash、プロジェクトルート外へのescapeと プロジェクトルート外のsymlinkは、ソースまたはアセットのバイト列を読む前に拒否されます。

include文には次の規則があります。

• kamishibaiはエントリーソースだけに書き、読み込み先ソースへ重ねて宣言しない
• 同じnamespaceの同じIDは、内容が同じでも複数ソースへ宣言しない
• cover、loading、poseRecognition、controlsなどの単一設定は読み込んだ全ファイルで一度だけ宣言する
• プロジェクトルート優先、include順による後勝ち、shadowingはなく、全宣言を確定してから参照を解決する
• include cycleは経路付きK4-INCLUDE-CYCLEで停止する
• 一つのソース、ソース件数、全ファイルの合計バイト数、合成後バイト数、include depthに有限上限を設ける

includeはSchema検証の前に処理するinclude文で、合成後の台本から取り除かれます。 全ソースと参照するローカルアセットを二回安定取得し、同じ世代の同一性になった場合だけプレビューへ反映します。 途中保存、ソースだけ新しい状態、アセットだけ新しい状態は実行中の世代を置き換えません。build成果物は 合成後ソース、宣言元の論理ソースID／range、ローカルアセットを保持する自己完結SB3で、端末の絶対パスや ブラウザーのファイルハンドルを保存しません。

CLIプレビューでinclude文を使う場合は--enable-source-includesを指定し、--max-source-bytes、 --max-source-files、--max-total-source-bytes、--max-include-depthとasset上限を有限値で指定します。 機能フラグがOFFの場合は単一ソース経路を維持します。

ファイル全体の構造

合成後の台本で使用できるトップレベルキーは次のものだけです。表にないキーは警告ではなくエラーに なります。includeは前節のinclude文の前処理だけが受理し、JSON Schemaのトップレベルfieldではありません。

推奨する並び順は表の順番です。YAMLのmappingの字下げには空白を使用し、タブは使いません。

YAMLを書くときの規則

DSL 4.0はYAMLをそのまま受け入れるのではなく、安全に、そして常に同じ結果へ解析できる範囲へ絞って使います。ここでは、その制限のうち台本を書くときに必ず出会うものをまとめます。

kamishibai: '4.0'

scenes:
  opening:
    - stage: Beach
    - wait: 1

# エラー
- stage: Beach
  wait: 1

- stage: Beach
- bgm: OpeningSound
- wait: 1
- goto: ending
- Hero.setSkin: HeroHappy

- Hero.moveTo:
    x: 40
    y: -57
    seconds: 1.5

- Caption.setText:
    text: |-
      海へ出発！
      1か2を押してください
    style: title

名前の規則

アクター、テキストスタイル、変数、分岐、stableIdなどの構文識別子には、Unicodeの文字、数字、 _、-を使用できます。先頭は文字または_にします。

assets:
  Beach_1: backdrop
  主人公-通常: costume:主人公

次の名前は使用できません。

# 先頭が数字
actors:
  1stActor: HeroIdle

# 空白を含む
variables:
  player score: 0

# actor actionの区切りとして予約された`.`を含む
actors:
  main.hero: HeroIdle

日本語名はUnicode NFCで保存します。大文字と小文字は別の識別子として扱われます。

アセットIDとシーンIDはScratch上の名前をそのまま保持する空でない文字列で、空白や記号も使用できます。 値をtrim、alias化、Unicode正規化しません。YAMLとして解釈が曖昧になる名前は引用符で囲みます。

assets:
  'Beach / evening': backdrop
scenes:
  'Scene 1: opening': []

bubbleStylesとbubbleClosePoliciesの名前も内部の空白や日本語を使用できます。ただし、先頭・末尾の 空白、改行、tab、制御文字は使用できません。

素材（asset）を登録する

assets:
  Beach: backdrop
  HeroIdle: costume:Hero
  OpeningSound: sound

assets:
  Ocean:
    kind: backdrop
    file: ocean.svg
    loading: lazy

  HeroHappy:
    kind: costume
    target: Hero
    name: happy

  OpeningSound:
    kind: sound
    name: Opening Theme
    loading: eager

  救助Pose:
    kind: poseModel
    file: rescue-pose
    loading: lazy

  CameraMenuButton:
    kind: image
    file: select-camera.svg
    loading: eager

登場人物（Actor）を登録する

actorsでは、アクターIDと初期コスチュームを対応付けます。

assets:
  HeroIdle: costume:Hero
  HeroHappy: costume:Hero
  TurtleIdle: costume:Turtle

actors:
  Hero: HeroIdle
  Turtle: TurtleIdle

初期コスチュームはcostumeアセットであり、そのtargetがアクターIDと一致している必要があります。 アクションではHero.show、Turtle.sayのように、アクターIDと命令を.でつなぎます。

表紙、読み込み表示、ポーズ認識、カメラ映像を設定する

ここまでで素材と登場人物がそろいました。次は、物語が始まる前と、物語の外側に出る画面の設定です。いずれもトップレベルのキーとして一度だけ書き、シーンごとに書き分けるものではありません。

cover:
  backdrop: Beach
  bgm: OpeningSound

assets:
  LoadingBackground: backdrop
  Loading1: costume:Loading
  Loading2: costume:Loading

loading:
  backdrop: LoadingBackground
  costumes: [Loading1, Loading2]

poseRecognition:
  idleSound: ClockTicking
  chargeSound: Success

poseRecognition:
  modelInitialization:
    policy: latest-needed
    parallel: true

assets:
  ShowMirroredButton:
    kind: image
    file: ui/show-mirrored.svg
    loading: eager
  ShowUnmirroredButton:
    kind: image
    file: ui/show-unmirrored.svg
    loading: eager
  CameraMenuButton:
    kind: image
    file: ui/select-camera.svg
    loading: eager

poseRecognition:
  idleSound: ClockTicking
  chargeSound: Success
  preview:
    mirroring: mirrored
    controls:
      mirroring:
        position: top-center
        opacity: 0.8
        assets:
          showMirrored: ShowMirroredButton
          showUnmirrored: ShowUnmirroredButton
      cameraMenu:
        position: bottom-center
        opacity: 0.8
        buttonAsset: CameraMenuButton

poseRecognition:
  preview:
    mirroring: mirrored
    overlay:
      visible: true
      jointStyles:
        leftWrist:
          color: '#ff00aa'
          opacity: 0.8
          radius: 6
        rightWrist:
          color: '#ff00aa'
          radius: 6
      boneStyle:
        color: '#00e5ff'
        opacity: 0.9
        width: 3
      minimumConfidence: 0.5
      confidenceScaling:
        jointOpacity: true
        jointRadius: false
        boneOpacity: true
        boneWidth: false

SVG Textを設定する

DSL 4.0の標準テキスト表現はSVG Textです。最初にtextStylesで名前付きスタイルを定義します。

textStyles:
  title:
    background: '#112233'
    color: '#ffffff'
    font: Noto Sans JP
    size: 150
    align: center

アクター自身へテキストを表示するときはsetTextを使います。

- Caption.setText:
    text: おしまい
    style: title

行形式のText Asset commandは4.0 core schemaにありません。textStylesとActor.setTextを使用してください。

セリフの見た目（bubble style）を設定する

Actor.sayとActor.thinkで同じ吹き出し表現を再利用するときは、トップレベルのbubbleStylesへ 名前付きの部分styleを定義します。style名には内部の空白や日本語も使用できます。

bubbleStyles:
  Typing:
    characterIntervalSeconds: 0.05
    characterSound: Typewriter
    noSoundCharacters: '「」'
    restCharacters: '、。…'
    restCharacterIntervalSeconds: 0.5
  Hero style:
    styles:
      - Typing
    textStyle: title
    placement: FOOTER_LIKE
    visualStyle: NARRATION

style定義のstyles配列で既存styleを記載順に合成し、その定義自身の値で上書きできます。循環参照、 未定義style、同じstyleの重複指定はエラーです。各styleは部分設定にでき、文字送りの相互依存は合成後の effective styleに対して検査します。

characterIntervalSecondsはUnicode grapheme cluster一つを表示してから次を表示するまでの秒数です。 characterSoundは各文字のsound、noSoundCharactersは文字音を鳴らさない文字、restCharactersは 表示後の間隔をrestCharacterIntervalSecondsへ置き換える文字です。

textStyle、placement、visualStyle、portrait、continueIndicatorで吹き出しを構成できます。 さらにreveal、audio、showAnimation、hideAnimation、visibleAnimationsで段階表示、音、animationを 指定できます。各fieldの列挙値と必須条件はSchemaリファレンスの「吹き出しstyle」を参照してください。

styleには本文、終了条件、吹き出し開始時の音声を含めません。text、closePolicy、seconds、 waitFor、startSoundはセリフ側の設定です。見た目のbubbleStylesと終了条件の bubbleClosePoliciesは別のregistryとして扱います。

吹き出しを閉じる条件（bubble close policy）を設定する

同じ終了条件を複数のActor.say／Actor.thinkで使う場合は、トップレベルのbubbleClosePoliciesへ 名前を付けて定義し、actionのclosePolicyで1件だけ参照します。

bubbleClosePolicies:
  after-3-seconds:
    seconds: 3
  user-advance:
    waitFor: advance
  advance-or-timeout:
    seconds: 10
    waitFor: advance

scenes:
  opening:
    - Hero.say:
        text: 次へ進みます
        closePolicy: user-advance

• secondsだけなら、吹き出しの表示開始から指定秒数後に閉じます。
• waitFor: advanceだけなら、Stageのprimary pointer／tapまたは修飾キーなしの任意キー入力で閉じます。
• 両方なら、入力とtimeoutのうち先に成立した方で閉じます。

policyの継承や合成はありません。closePolicyと、同じaction内のseconds／waitForは併用できません。 未定義のpolicy名はK4-REF-001です。従来のinline指定は引き続き使えるので、一度しか使わない条件まで 無理に名前へ切り出す必要はありません。

runtimeはaction開始前にpolicyを既存のseconds／waitForへ展開します。live reloadの途中ですでに表示中の セリフは開始時に解決した値を使い続け、更新したpolicyは次に開始する物語の世代から適用されます。

変数と条件分岐を設定する

物語の途中で選択の結果を覚えておき、あとの場面で道を分けたい場合は、変数と分岐を組み合わせます。変数はトップレベルのvariablesで初期値を宣言し、分岐はbranchesで条件と移動先の組を登録してから、シーンの中で名前で呼び出します。

variables:
  score: 1
  takeSeaRoute: false
  playerName: ななし

branches:
  rescueResult:
    - if: 'score == 1'
      goto: seaRoute
    - if: takeSeaRoute
      goto: seaRoute
    - else: ending

- branch: rescueResult

操作キーを設定する

controlsでは、development用とproduction用など、実行環境ごとに完全なkeymapを定義できます。

controls:
  keymaps:
    development:
      Space: navigation.nextAction
      Enter: navigation.nextScene
      ArrowLeft: history.previousAction
      ArrowUp: history.previousScene
      ArrowDown: history.nextScene
    production:
      Space: rehearsal.skipPose

ビルダーはcontrolProfileを明示的に一つ選び、選択されたprofileのkeymapだけを有効にする設計です。 profile間の継承、merge、fallbackはありません。

使用できるnavigation commandは次の8個です。

キー名にはKeyboardEvent.codeを使用します。Space、Enter、方向キー、Digit0〜Digit9、 KeyA〜KeyZ、Numpad0〜Numpad9、F1〜F12などがschemaで列挙されています。 Shift+Spaceのようなmodifierとの組み合わせは使用できません。

選択profileにhistory.*が一つでもある場合だけ、時系列historyを有効にします。history移動で実行位置は 変わりますが、物語の変数や表示状態を完全に巻き戻す機能ではありません。同じ物理キーをcontrolsと 作品内のkeyInputToChangeSceneへ重ねて割り当てないでください。

rehearsal.skipPoseはpose action内の次stepへ進み、rehearsal.skipActionは現在のaction全体、 rehearsal.skipSceneは現在のsceneを完了します。これらは実行履歴を移動しません。keymapへ明示したprofileで だけ有効になります。

シーンを書く

scenesの下には、シーンIDをキーとしてシーンを並べます。シーンの書き方には、アクション列だけを書く短形式と、シーン固有の設定を添える長形式の二つがあります。どちらで書いても、検証後には同じ内部表現へ正規化されます。

scenes:
  opening:
    - stage: Beach
    - wait: 1

scenes:
  rescue:
    poseModel: 救助Pose
    posePreview:
      mirroring: unmirrored
    actions:
      - stage: Ocean
      - Hero.pose:
          steps:
            - pose: help
              skin: HeroHelp
              sound: Success

舞台への命令（Global action）

Global actionはアクター名を付けずに記述します。

- stage: Beach
- bgm: OpeningSound
- sound: Success
- wait: 1.5

- debugger:
- broadcastMessageAndWait: playMiniGame
- broadcastMessageAndWait:
    stableId: endingEffects
    message: showEndingEffects

- transition:
    effect: fadeOut
    seconds: 0.5

- goto: ending
- branch: rescueResult

- keyInputToChangeScene:
    Digit1: rescue
    Digit2: ending

- keyInputToChangeScene:
    stableId: routeSelection
    routes:
      Digit1: rescue
      Digit2: ending

- touchInputToChangeScene:
    Hero: rescue
    Caption: ending

登場人物への命令（Actor action）

Actor actionはActorID.commandをキーにします。

- Hero.show:
    skin: HeroHappy
    x: 0
    y: -60
    scale: 30

- Hero.hide: {}

- Hero.setTransparency: 50

- Hero.setTransparency:
    stableId: heroHalfTransparent
    transparency: 50

- Hero.setTransparency:
    from: 0
    to: 50
    seconds: 1
    background: true

- Hero.moveTo:
    x: 40
    y: -57
    seconds: 1.5
    easing: easeInOut

- Hero.say:
    text: 助けに行こう
    closePolicy: advance-or-timeout
    styles:
      - Typing
      - Hero style
    startSound: HeroGreetingVoice
- Hero.think:
    text: どうしよう……
    closePolicy: user-advance
    characterIntervalSeconds: 0.1
    characterSound: Typewriter

- Hero.say:
    text: 3秒だけ表示します
    seconds: 3

- Hero.setSkin: HeroHelp

- Hero.setSkin:
    stableId: heroRescueSkin
    skin: HeroHelp
    scale: 100

- Hero.setLayer: front
- Guide.setLayer: -1

- Hero.loop:
    steps:
      - skin: HeroWalk1
        seconds: 0.2
      - skin: HeroWalk2
        seconds: 0.2

- Caption.setText:
    text: おしまい
    style: title

- Hero.pose:
    steps:
      - pose: help
        skin: HeroHelp
        sound: Success
      - pose: jump
        skin: HeroHappy
        sound: Success

再読み込みに備えてstableIdを付ける

stableIdは、台本のlive reloadで変更前後の同じアクションを特定するための任意IDです。通常の台本で すべてのアクションへ付ける必要はありません。付ける場合は文書全体で一意にします。

- wait:
    stableId: waitBeforeEnding
    seconds: 1

stableIdは名前付きmappingにだけ指定できます。wait: 1のようなscalar短形式へ追加することは できません。

保存した変更をブラウザーの確認画面へ反映する

Issue #390のWeb Previewでは、対応ブラウザーで「プロジェクトを開く」を押し、プロジェクトルートをread-onlyで 選択します。Web Previewに組込みeditorはなく、YAMLとassetは任意の外部editorで変更します。選択した ディレクトリハンドルはsession中だけ保持し、YAML、manifest、SB3、user設定へ保存しません。

最初の正常なYAMLはreload選択を挟まず先頭から開始します。その後にstory.k4.ymlを保存すると、 Web Previewは一定間隔で変更を検出し、書込み途中ではない安定した状態を解析・検証します。正常な 候補だけが次の再開位置の選択へ進みます。

1. 先頭から
2. 現在のsceneから
3. 現在のactionから

現在のactionから再開できるかは、actionが一意でreplay-safeかなどの条件で決まります。stableIdは 変更前後の同じactionを特定しやすくしますが、すべてのactionへ付ける必要はありません。YAMLが不正、 missing、unstableの場合は現在実行中のimmutable snapshotを置き換えず、診断を表示して次の保存を待ちます。 pageがbackgroundの場合はブラウザーのタイマー制限により検出が遅れることがあります。

総合サンプル

次の例は、アセット、表紙、SVG Text、bubble style、変数、keymap、分岐、入力、ポーズ認識を一つの台本へ まとめたものです。利用するreleaseでDSL 4.0と必要な機能フラグを有効にして実行します。

kamishibai: '4.0'

assets:
  Beach: backdrop
  Ocean:
    kind: backdrop
    file: ocean.svg
    loading: lazy
  HeroIdle: costume:Hero
  HeroHappy: costume:Hero
  HeroHelp: costume:Hero
  CaptionIdle: costume:Caption
  OpeningSound: sound
  ClockTicking: sound
  Success: sound
  Typewriter: sound
  HeroGreetingVoice: sound
  HeroThinkingVoice: sound
  ShowMirroredButton:
    kind: image
    file: show-mirrored.svg
    loading: eager
  ShowUnmirroredButton:
    kind: image
    file: show-unmirrored.svg
    loading: eager
  CameraMenuButton:
    kind: image
    file: select-camera.svg
    loading: eager
  救助Pose:
    kind: poseModel
    file: rescue-pose
    loading: lazy

actors:
  Hero: HeroIdle
  Caption: CaptionIdle

cover:
  backdrop: Beach
  bgm: OpeningSound

textStyles:
  title:
    background: '#112233'
    color: '#ffffff'
    font: Noto Sans JP
    size: 150
    align: center

bubbleStyles:
  Typing:
    characterIntervalSeconds: 0.05
    characterSound: Typewriter
    noSoundCharacters: '「」'
    restCharacters: '、。…'
    restCharacterIntervalSeconds: 0.5
  Hero style:
    styles:
      - Typing
    textStyle: title
    placement: FOOTER_LIKE

bubbleClosePolicies:
  user-advance:
    waitFor: advance
  advance-or-timeout:
    seconds: 8
    waitFor: advance

variables:
  score: 1
  takeSeaRoute: false

poseRecognition:
  idleSound: ClockTicking
  chargeSound: Success
  preview:
    mirroring: mirrored
    overlay:
      visible: true
      boneStyle:
        color: '#00e5ff'
        opacity: 0.9
        width: 3
      minimumConfidence: 0.5
    controls:
      mirroring:
        position: top-center
        opacity: 0.8
        assets:
          showMirrored: ShowMirroredButton
          showUnmirrored: ShowUnmirroredButton
      cameraMenu:
        position: bottom-center
        opacity: 0.8
        buttonAsset: CameraMenuButton

controls:
  keymaps:
    development:
      Space: navigation.nextAction
      ArrowLeft: history.previousAction
      ArrowUp: history.previousScene
      ArrowDown: history.nextScene
    production:
      Space: rehearsal.skipPose

branches:
  rescueResult:
    - if: 'score == 1'
      goto: seaRoute
    - if: takeSeaRoute
      goto: seaRoute
    - else: ending

scenes:
  opening:
    - stage: Beach
    - bgm: OpeningSound
    - Caption.setText:
        stableId: openingTitle
        text: |-
          海へ出発！
          1か2を押してください
        style: title
    - Hero.show:
        skin: HeroHappy
        x: 0
        y: -60
        scale: 30
    - Hero.setTransparency:
        from: 100
        to: 0
        seconds: 0.5
    - Hero.say:
        text: 助けに行こう
        closePolicy: advance-or-timeout
        styles:
          - Hero style
        startSound: HeroGreetingVoice
    - keyInputToChangeScene:
        Digit1: rescue
        Digit2: ending

  rescue:
    poseModel: 救助Pose
    posePreview:
      mirroring: unmirrored
    actions:
      - stage: Ocean
      - Hero.setSkin: HeroHelp
      - Hero.pose:
          steps:
            - pose: help
              skin: HeroHelp
              sound: Success
            - pose: jump
              skin: HeroHappy
              sound: Success
      - branch: rescueResult

  seaRoute:
    - Hero.moveTo:
        x: 40
        y: -57
        seconds: 1.5
        easing: easeInOut
    - Hero.think:
        text: 海路で帰ろう……
        closePolicy: user-advance
        startSound: HeroThinkingVoice
    - transition:
        effect: fadeOut
        seconds: 0.5
    - goto: ending

  ending:
    - stage: Beach
    - Caption.setText:
        text: おしまい
        style: title

診断と安全停止

DSL 4.0のソースフロントエンドは、YAMLを読み込んだあと、構造と参照関係の検証が成功するまでアセット準備や アクション実行を始めません。診断にはcode、severity、ソースID、行・列、Story Pathが含まれます。

runtime接続後は、action、scene、branch、port、戻り値などの実行時エラーにもK4-RUNTIME-*診断を 使用します。入力バイト数、YAML node数、nesting深度、scalar長、シーン数、アクション数、アセット数、 診断数には安全上の有限上限があります。include文の各上限はpreview／buildのCLI引数とhost設定で明示し、 一件のソースと全ファイルの合計／合成後ソースを別の責務として検証します。

作成時のチェックリスト

• ファイルをUTF-8で保存し、新規ソースでは.k4.ymlを使用した
• 先頭がkamishibai: '4.0'になっている
• トップレベルとactionに未知のキーがない
• インデントに空白を使い、一つのaction itemへ命令を一つだけ書いた
• IDが文字または_で始まり、Unicode NFCになっている
• 背景、音、コスチューム、ポーズモデルのkindが参照箇所と一致している
• ポーズoverlayを使う場合、関節名、opacity、radius、width、minimumConfidenceが範囲内である
• コスチュームのtargetが使用するアクターと一致している
• fileが宣言元sourceからproject内へ解決できる安全な相対パスになっている
• includeにcycle、プロジェクトルート外のパス、同じnamespaceの重複宣言がない
• すべてのシーン、分岐、スタイル、アセット参照が定義済みである
• 各分岐の最後に一つだけelseがある
• stableIdが文書全体で重複していない
• navigation用キーと作品内の遷移キーが衝突していない
• YAML以外の行形式commandを混在させていない
• 利用するreleaseでDSL 4.0と必要な機能フラグが有効であることを確認した

付録: 実装基準と実装根拠

ここから先は、公開状況や実装の追跡が必要な方のための付録です。台本を書くうえでは読み飛ばせます。

2026年8月20日のrc.8固定基準では、次の実装がTM Kamishibaiへ入っています。

• 制限付きYAMLの解析、JSON Schema検証、参照関係の意味検証
• 行・列とStory Pathを保持するSource Map、K4-*診断
• 検証後の台本をimmutableなStoryDocumentへ正規化するソースフロントエンド
• action実行、分岐、シーン遷移、停止を扱うpure runtime controller
• control profileの解決、キー入力adapter、時系列history reducer、runtime navigation control
• カメラプレビューのstory既定、scene固有の非stickyな左右反転指定、任意の操作UI
• TurboWarp TM 1.12.0を使う、関節とボーンのSVG overlay設定
• Actor.say／Actor.thinkの入力待ち、文字送り、音、portrait、animation、名前付きbubbleStyles
• bubbleClosePoliciesとclosePolicyによる、秒数・入力待ち・両者のraceの名前付き再利用
• Actor.moveToのlinear、easeIn、easeOut、easeInOut
• Actor.setTransparencyの即時指定、foreground／backgroundの線形変化
• broadcastMessageAndWait、debugger、Actor.hide／setLayer／loop
• rehearsal skip、bitmap論理解像度、asset／sceneのliteral ID
• include文で複数ソースを決定的に合成する処理、宣言元相対asset解決、自己完結SB3 packaging
• Web／CLIプレビューのtransactional reload、Source Map、packaging後のsource origin復元
• navigation入力と作品内input actionを一つのsemantic consumerへ限定する入力arbitration

builder、TurboWarp runtime surface、ブラウザー／CLIプレビューを含むend-to-end実装は完成しています。 ただし、完成した機能の一部は起動時固定・既定OFFの機能フラグで段階導入されます。実装完成は、 すべての公開releaseで自動的に有効になることを意味しません。

関連資料

• 紙芝居DSL 4.0 Schemaリファレンス: 固定Schemaに基づくfield、型、制約、action一覧
• DSL 4.0ランタイム変数ガイド: 実行中に参照できる変数と、その扱い方
• 3系作品の変換ガイド: 3系の台本を4.0のYAMLへ変換する手順
• 紙芝居DSL 4.0 リリース履歴: 版ごとの追加機能と変更点
• DSL 4.0表層仕様: 4.0の規範的な作者向け構文
• DSL 4.0 JSON Schema: 機械可読な構造仕様
• DSL 4.0 include文の複数ファイル対応: include、transaction、有限上限、rollback
• DSL 4.0 ポーズoverlay実装 Issue #624: Schema、TurboWarp TM 1.12.0 composition API mapping、YAML opt-in、rollback
• DSL 4.0総合fixture: schemaと意味検証を通る総合例