紙芝居DSL 3.2から4.0への変換ガイド

このガイドの位置づけ

このガイドは、DSL 3.1／3.2の文法を説明し直す資料でも、4.0の全項目を説明する資料でもありません。 既存TXT台本を安全にYAMLへ変換し、4.0作者向けの作業へ引き渡すところまでを扱います。

変換前は本書の「自動変換を停止する入力」まで確認し、変換後は 紙芝居DSL 4.0 台本作成ガイドの最小台本、作品フォルダーの配置、エラー表示の順に読みます。 項目の型や必須条件を調べるときだけ、検索用のSchemaリファレンスを使用します。

基本コマンド

必要なパッケージを導入した作品フォルダーで実行します。

pnpm exec tm-kamishibai convert-dsl4 \
  --input source.txt \
  --output story.k4.yml

TMPoseURLは既定でlazy remote poseModelへ変換されます。内容を固定した自己完結SB3を作る場合だけ、 --pose-modelsでローカルのモデルディレクトリへ置き換えます。

pnpm exec tm-kamishibai convert-dsl4 \
  --input source.txt \
  --output story.k4.yml \
  --pose-models pose-models.json

相対パスは、コマンドを実行したディレクトリを基準に解決されます。新しいDSL 4.0のソースには短い.k4.yml suffixを 推奨しますが、互換の拡張子である.k4.yaml、.kamishibai.yml、.kamishibai.yamlも使用できます。

変換される内容

converterは、次の構造をDSL 4.0に対応する形へ変換します。

• backdrop、costume、sound、actor
• cover、runtime variable、Loading表示、ポーズ認識音
• SVG Text style、branch、scene
• DSL 4.0 coreに対応するglobal actionとactor action

次のように意味を決める必要がある変換は、元ファイルの行・列と、安定した診断コードを含む警告を 標準エラー出力へ表示します。

• DSL 3.1を3.2互換の文法として解釈した場合
• runtime variableのスカラー型を推論した場合
• costumeを論理的なactorへ付け替えた場合
• 旧DSLに秒数指定がないtransitionを0秒として明示した場合

対応表と各診断の分類は、実装リポジトリの DSL 3.1／3.2からDSL 4.0への移行仕様を 参照してください。

自動変換を停止する入力

意味を保てない入力ではエラーを返し、YAMLを部分出力しません。主な例は次のとおりです。

• 旧Text Asset、TMPoseURL以外の検証情報を確定できないremote／cacheの素材
• 秒数なしの永続say／think、style付きsay／think、hideなど同じ意味を保証できないaction
• 4.0で必須のcharge soundがないpose recognition設定
• TMPoseURLがないpose scene、不正または空のTMPoseURL、空のpose名
• 要素数が異なるbranch／key／touch inputのparallel list、最後の無条件遷移がないbranch
• scene内のsetRuntimeVariable、1以外のstartSceneIndex
• 非zeroのposeIdle、独自action、不正なarity、曖昧なcolon区切り

旧Text Assetは、DSL 4.0移行仕様の手動移行例に 従ってSVG Text actorへ移します。独自のScratch blockやSB3のblock graphは入力台本から推測せず、 converterもblockを生成・変更しません。

ポーズモデルの配布方法を選ぶ

変換で一つだけ判断が必要なのが、ポーズモデルをどう配るかです。公開URLのモデルをそのまま参照するか、 モデルを作品へ取り込んで内容を固定するかを選びます。

assets:
  PoseModel1:
    kind: poseModel
    delivery: remote
    source:
      url: https://example.com/models/rescue/
    loading: lazy

{
  "https://example.com/models/rescue/": {
    "id": "RescuePose",
    "file": "rescue-pose",
    "loading": "lazy"
  }
}

エラー表示と終了状態

正常時は生成先を標準出力へ表示します。警告とエラーは標準エラー出力へ source:line:column: severity [code] message形式で表示します。

Converted /project/story.k4.yml

/project/source.txt:2:1: warning [K4-CONVERT-VARIABLE-TYPE] ...

変換後に確認する

生成YAMLを本番と同じフロントエンドで検証します。--max-source-bytesには作品で許容する有限上限を 指定してください。現行実装で指定できる最大値は262144 bytesです。

pnpm exec tm-kamishibai validate-dsl4 \
  --input story.k4.yml \
  --max-source-bytes 262144 \
  --format pretty

次に紙芝居DSL 4.0 台本作成ガイドに従って作品フォルダーを配置し、プレビューで scene遷移、表示、音、ポーズ認識、作品固有blockとの関係を確認します。問題があれば生成YAMLと4.0成果物だけを 破棄し、元台本を3.2のランタイムで継続できます。

プログラムから変換する（JavaScript API）

副作用なしで文字列を変換する場合は、パッケージのexportを使用します。

import {convertDsl32ToDsl4} from '@kubohiroya/tm-kamishibai/converter';

const result = convertDsl32ToDsl4(sourceText, {
  sourceId: 'source.txt',
  poseModels,
});

if (result.ok) {
  console.log(result.yaml);
} else {
  console.error(result.diagnostics);
}

convertDsl32ToDsl4はファイル入出力を行わず、ok、正規化したsource、変換後のdocument／yaml、 diagnosticsを返します。ファイルを一括で変換するAPIが必要な場合は、同じexportの convertDsl32File({inputPath, outputPath, poseModelMapPath})を使用します。

関連資料

• 紙芝居DSL 4.0 台本作成ガイド: 変換後の作品フォルダーの配置、プレビュー、ビルド、実行確認
• 紙芝居DSL 4.0 Schemaリファレンス: field、型、remote assetを含む制約
• DSL 3.1／3.2からDSL 4.0への移行仕様: 対応表、診断分類、rollback境界
• convert-dsl4実装Issue #276: CLIとpure APIの受け入れ条件