ScreenPlay Formater for VSCode – 使用ガイド v2.0.0 ゲーム分岐シナリオ、マルチファイル対応版
映画・アニメ・ボイスドラマ・ゲームシナリオ作成支援 VS Code 拡張機能
📚 目次
🚀 基本的な使い方
1. 新規ファイル作成
Ctrl+Shift+P → "ScreenPlay: 新規ファイル作成"
基本的なシナリオテンプレートが作成されます：
title: "新しいシナリオ"
authors:
- "作者名"
sequences:
- id: 1
name: "シーケンス1"
scenes:
- id: 1
name: "シーン1"
location: "場所"
time_of_day: "時間帯"
cuts:
- id: 1
camera: "カメラアングル"
dialogue:
- speaker: "キャラ名"
text: "セリフ"
2. プレビュー表示
Ctrl+Shift+P → "ScreenPlay: シーンをプレビュー"
3つのレイアウトから選択：
- 縦書き – 従来の日本語シナリオ形式
- 横書き – モダンなシナリオ形式
- 絵コンテ – 絵コンテ用紙形式
📖 シナリオの構造
基本階層
Project (プロジェクト)
├── Sequences (シーケンス) - 大きな章・パート
│ ├── Scenes (シーン) - 場面・カット群
│ │ ├── Cuts (カット) - 個別のカメラワーク
│ │ │ ├── Dialogue (セリフ) - 会話
│ │ │ └── Action (アクション) - 動作・演出
必須フィールド
| フィールド | 説明 | 例 |
|---|---|---|
title | 作品タイトル | “風の谷の少年” |
authors | 作者一覧 | [“山田太郎”] |
sequences | シーケンス配列 | – |
sequences[].id | シーケンス番号 | 1 |
sequences[].scenes | シーン配列 | – |
scenes[].id | シーン番号 | 1 |
scenes[].cuts | カット配列 | – |
cuts[].id | カット番号 | 1 |
オプションフィールド
| フィールド | 説明 | 例 |
|---|---|---|
description | 作品説明 | “青春ファンタジー” |
genre | ジャンル | “アニメ” |
scenes[].location | 撮影場所 | “学校の屋上” |
scenes[].time_of_day | 時間帯 | “夕方” |
cuts[].camera | カメラワーク | “主人公のアップ” |
cuts[].duration | 尺（秒） | 5 |
🎬 実際の作成例
基本的なシーン
title: "青春の一ページ"
authors:
- "新人脚本家"
sequences:
- id: 1
name: "出会い"
scenes:
- id: 1
name: "屋上での会話"
location: "学校の屋上"
time_of_day: "放課後"
cuts:
- id: 1
camera: "屋上全景、夕日が差し込む"
duration: 3
- id: 2
camera: "ユウが一人でたたずんでいる"
dialogue:
- speaker: "ユウ"
text: "今日もいい天気だな..."
- id: 3
camera: "階段から現れるアヤ"
dialogue:
- speaker: "アヤ"
text: "あ、ユウくん！こんなところにいたのね"
- speaker: "ユウ"
text: "アヤちゃん...どうしてここに？"
- speaker: "アヤ"
text: "実は、話があるの"
🛠️ コマンド一覧
ファイル操作
| コマンド | ショートカット | 説明 |
|---|---|---|
sp.createNewFile | – | 新規ファイル作成 |
sp.addTemplate | – | テンプレート追加 |
構造追加
| コマンド | 説明 |
|---|---|
sp.addSequences | 新しいシーケンス追加 |
sp.addScene | 新しいシーン追加 |
sp.addCut | 新しいカット追加 |
プレビュー・分析
| コマンド | 説明 |
|---|---|
sp.previewScene | シーンプレビュー表示 |
sp.countTotalDuration | 総尺計算 |
sp.countDialogueCharacters | セリフ文字数カウント |
sp.validateYaml | YAML構文チェック |
エクスポート（単一ファイル）
| コマンド | 説明 |
|---|---|
sp.exportHtml | HTML書き出し |
sp.exportCsvMarkers | Premiere Pro用CSVマーカー |
sp.exportFcpXml | Final Cut Pro用XML |
🆕 マルチファイルプロジェクト（v2.0.0+）
| コマンド | 説明 | 使用例 |
|---|---|---|
🏠 プロジェクトルート設定 | メインファイルの場所を設定 | main.ymlのあるフォルダを指定 |
🌐 プロジェクト全体HTML生成 | 全YAMLファイルを一括HTML変換 | プロジェクト全体をまとめて出力 |
🔗 リンク検証 | デッドリンクや不正リンクをチェック | br_linkの整合性確認 |
📦 プロジェクト統合書き出し | 全ファイルを1つに統合して出力 | 配布用の単一ファイル作成 |
👁️ プレビュー機能
縦書きプレビュー（シナリオ形式）
風の谷の少年
第一章 旅立ち
○屋上での会話（学校の屋上・放課後）
屋上全景、夕日が差し込む
ユウ 「今日もいい天気だな...」
階段から現れるアヤ
アヤ 「あ、ユウくん！こんなところにいたのね」
ユウ 「アヤちゃん...どうしてここに？」
横書きプレビュー（モダン形式）
INT. 学校の屋上 - 放課後
屋上全景、夕日が差し込む
ユウが一人でたたずんでいる
ユウ
今日もいい天気だな...
階段から現れるアヤ
アヤ
あ、ユウくん！こんなところに
いたのね
ユウ
アヤちゃん...どうしてここに？
絵コンテプレビュー
┌─────────────────────────────────────┐
│ Cut 1: 屋上全景、夕日が差し込む │
│ Duration: 3秒 │
│ │
│ [絵コンテエリア] │
│ │
│ ナレーション: - │
│ セリフ: - │
└─────────────────────────────────────┘
📤 エクスポート機能
HTML書き出し
3つのレイアウトでHTML書き出し可能：
出力ファイル: シナリオ名_縦書き.html
出力ファイル: シナリオ名_横書き.html
出力ファイル: シナリオ名_絵コンテ.html
ブラウザで開いて印刷用PDFとして保存できます。
Premiere Pro連携
CSVマーカーファイルを書き出し：
Marker Name,Description,In,Out,Duration,Marker Type
シーン1-カット1,ユウ「今日もいい天気だな...」,00:00:00:00,00:00:03:00,00:00:03:00,Comment
シーン1-カット2,アヤ「あ、ユウくん！」,00:00:03:00,00:00:08:00,00:00:05:00,Comment
Final Cut Pro連携
FCPXML形式で書き出し、タイムライン上にマーカーとして配置されます。
🎮 v2.0.0 分岐型シナリオ機能
新しい分岐記法（推奨）
v2.0.0では人間が読みやすい分岐記法を導入しました。全てオプションなので既存ファイルとの互換性を保持しています。
基本的な分岐シナリオ
title: "恋愛ゲーム"
authors: ["シナリオライター"]
# グローバル変数・フラグ（オプション）
br_variables:
love_points: 0
friendship_points: 0
br_flags:
first_meeting: false
has_gift: false
sequences:
- id: 1
name: "出会い"
scenes:
- id: 1
name: "公園での出会い"
cuts:
- id: 1
camera: "公園のベンチ"
dialogue:
- speaker: "主人公"
text: "今日はいい天気だな"
- id: 2
camera: "主人公のアップ"
dialogue:
- speaker: "ヒロイン"
text: "あの...すみません"
br_effects:
- "first_meeting = true"
# 選択肢を提示
- id: 3
br_choices:
- br_id: "help"
br_text: "どうしました？手伝いましょうか？"
br_link: "route_help"
- br_id: "ignore"
br_text: "急いでいるので..."
br_link: "route_ignore"
# 親切ルート
- id: 2
name: "親切ルート"
br_condition: "choice_selected == 'help'"
cuts:
- id: 1
dialogue:
- speaker: "主人公"
text: "どうしました？手伝いましょうか？"
br_effects:
- "love_points = love_points + 10"
- speaker: "ヒロイン"
text: "ありがとうございます！優しいんですね"
# 無視ルート
- id: 3
name: "無視ルート"
br_condition: "choice_selected == 'ignore'"
cuts:
- id: 1
dialogue:
- speaker: "主人公"
text: "急いでいるので..."
- speaker: "ヒロイン"
text: "そ、そうですか..."
br_effects:
- "love_points = love_points - 5"
条件分岐
cuts:
# 変数による条件分岐
- id: 1
br_condition: "love_points >= 50"
dialogue:
- speaker: "ヒロイン"
text: "あなたのことが好きになりました"
- id: 2
br_condition: "love_points < 50"
dialogue:
- speaker: "ヒロイン"
text: "いい友達でいましょうね"
# フラグによる条件分岐
- id: 3
br_condition: "has_gift == true"
dialogue:
- speaker: "主人公"
text: "これ、君にプレゼント"
br_effects:
- "has_gift = false"
- "love_points = love_points + 20"
シーン・シーケンス間のリンク
sequences:
- id: 1
name: "第1章"
br_link: "chapter2" # 次のシーケンスへ
- id: 2
name: "第2章"
scenes:
- id: 1
name: "分岐点"
br_link: "ending_good" # 特定シーンへジャンプ
- id: 2
name: "グッドエンド"
br_condition: "love_points >= 80"
分岐フィールド一覧
Choice型
| フィールド | 型 | 説明 | 例 |
|---|---|---|---|
br_id | string | 選択肢ID | “choice_a” |
br_text | string | 表示テキスト | “優しく答える” |
br_link | string | ジャンプ先 | “scene_kind” |
共通分岐フィールド（全階層で利用可能）
| フィールド | 型 | 説明 | 例 |
|---|---|---|---|
br_condition | string | 表示条件 | “love >= 50” |
br_effects | string[] | 実行効果 | [“love = love + 10”] |
br_link | string | リンク先 | “next_scene” |
br_choices | Choice[] | 選択肢 | – |
ScenarioData専用フィールド
| フィールド | 型 | 説明 | 例 |
|---|---|---|---|
br_variables | object | ゲーム変数 | {love: 0, money: 100} |
br_flags | object | フラグ管理 | {met_hero: false} |
📁 プロジェクト管理
単一ファイルプロジェクト
基本的な使用方法。1つのYAMLファイルに全シナリオを記述：
# scenario.yml - 全てが1ファイルに
title: "短編シナリオ"
authors: ["作者名"]
sequences:
- id: 1
name: "始まり"
scenes:
- id: 1
name: "オープニング"
cuts:
- id: 1
dialogue:
- speaker: "主人公"
text: "始まりの物語"
特徴:
- ✅ シンプルで分かりやすい
- ✅ 小規模プロジェクト向け
- ❌ 大規模になると管理困難
- ❌ 複数人での編集が困難
マルチファイルプロジェクト（v2.0.0+）
大規模なゲームシナリオや複数人開発に対応。ファイルを分割して管理：
📋 基本構造
adventure-game/
├── main.yml # 🏠 プロジェクトルート
├── prologue.yml # プロローグ
├── chapter1/ # 第1章フォルダ
│ ├── village.yml # 村のシーン
│ ├── investigation.yml # 調査シーン
│ └── inn.yml # 宿屋シーン
├── chapter2/ # 第2章フォルダ
│ └── forest.yml # 森のシーン
├── endings/ # エンディングフォルダ
│ ├── list.yml # エンディング選択
│ ├── good.yml # ハッピーエンド
│ ├── bad.yml # バッドエンド
│ └── credits.yml # スタッフロール
└── assets/ # アセットフォルダ
├── bgm/ # BGMファイル
├── voice/ # 音声ファイル
└── images/ # 画像ファイル
🏠 メインファイル（main.yml）
プロジェクトの入り口となるファイル：
title: "マルチファイル冒険譚"
authors:
- "ScreenPlay Formater開発チーム"
version: "2.0.0"
description: |
大規模マルチファイルプロジェクトの例
# グローバル変数・フラグ
br_variables:
player_level: 1
money: 100
experience: 0
br_flags:
has_weapon: false
visited_town: false
completed_quest: false
sequences:
- id: 1
name: "メインメニュー"
scenes:
- id: 1
name: "タイトル画面"
cuts:
- id: 1
camera: "タイトル画面"
description: "ゲーム開始画面"
br_choices:
- br_id: "start_game"
br_text: "ゲーム開始"
br_link: "prologue.yml#opening" # 他ファイルへのリンク
- br_id: "load_game"
br_text: "途中から開始"
br_link: "chapter1/village.yml#center" # フォルダ内ファイルへ
- br_id: "view_endings"
br_text: "エンディング一覧"
br_link: "endings/list.yml#menu" # エンディングフォルダへ
🔗 ファイル間リンク記法
1. 同じフォルダ内のファイル
br_link: "other_file.yml#anchor_name"
2. 下位フォルダのファイル
br_link: "chapter1/village.yml#arrival" br_link: "endings/good.yml#happy_ending"
3. 上位フォルダのファイル
br_link: "../main.yml#title_screen" # 1つ上 br_link: "../../main.yml#title_screen" # 2つ上
4. 同じファイル内のアンカー
br_link: "#scene_name"
📄 サブファイル例（prologue.yml）
title: "プロローグ - 旅の始まり"
description: "物語の導入部分"
sequences:
- id: 1
name: "導入"
scenes:
- id: 1
name: "オープニング"
cuts:
- id: 1
anchor: "opening" # アンカー設定
camera: "村の全景"
dialogue:
- speaker: "ナレーター"
text: "ここから冒険が始まる..."
- id: 2
br_choices:
- br_id: "to_village"
br_text: "村へ向かう"
br_link: "chapter1/village.yml#arrival" # 次のファイルへ
- br_id: "back_title"
br_text: "タイトルに戻る"
br_link: "main.yml#title_screen" # メインファイルへ戻る
🏗️ マルチファイルプロジェクトの設定方法
Step 1: プロジェクトルート設定
Ctrl+Shift+P → "🏠 プロジェクトルート設定"
- メインファイル（main.yml）を含むフォルダを選択
Step 2: ファイル構造の作成
my-project/
├── main.yml # まずメインファイルを作成
├── chapter1/ # フォルダを作成
└── endings/ # 必要に応じてフォルダ追加
Step 3: HTML一括生成
Ctrl+Shift+P → "🌐 プロジェクト全体HTML生成"
- 全てのYAMLファイルが一度にHTML化
- 自動的にナビゲーションリンクが追加
- 相対パスが正しく調整される
🧭 ナビゲーション機能
v2.0.0では、生成されたHTMLファイルに自動的にナビゲーションバーが追加されます：
<!-- 自動生成されるナビゲーション -->
<nav class="navigation-bar">
<a href="../main.html" class="home-button">
🏠 メインに戻る
</a>
<span class="breadcrumb">
📁 chapter1/village.yml
</span>
</nav>
特徴:
- ✅ すべてのサブページに「メインに戻る」ボタン
- ✅ 現在位置の表示
- ✅ ファイル階層に応じた正確な相対パス
- ✅ メインファイルには表示されない（自己参照回避）
🔄 リンク解決とパス調整
マルチファイルプロジェクトでは、以下が自動的に処理されます：
YAMLファイル間のリンク
# YAML内の記述 br_link: "chapter1/village.yml#arrival" # HTML生成時に自動変換 href="chapter1/village.html#arrival"
CSS/JSファイルのパス調整
<!-- ルートファイル --> <link rel="stylesheet" href="style.css"> <!-- サブフォルダのファイル --> <link rel="stylesheet" href="../style.css">
階層別のパス例
main.html → style.css
prologue.html → style.css
chapter1/village.html → ../style.css
chapter1/scenes/detail.html → ../../style.css
📊 プロジェクト管理のベストプラクティス
1. ファイル命名規則
main.yml # プロジェクトルート
prologue.yml # プロローグ
chapter1/
├── 01_village.yml # 番号付けで順序管理
├── 02_forest.yml
└── 03_castle.yml
endings/
├── list.yml # エンディング一覧
├── route_a.yml # ルートA
└── route_b.yml # ルートB
2. フォルダ構造の設計
# 章単位でフォルダ分割
chapter1/ # 第1章
chapter2/ # 第2章
epilogue/ # エピローグ
# 機能単位でフォルダ分割
scenes/ # 通常シーン
battles/ # 戦闘シーン
endings/ # エンディング
tutorials/ # チュートリアル
3. 共通要素の管理
# main.yml - プロジェクト共通設定 br_variables: # 全ファイルで共有される変数 player_name: "主人公" current_chapter: 1 br_flags: # 全ファイルで共有されるフラグ tutorial_completed: false first_visit: true
🛠️ マルチファイル専用コマンド
| コマンド | 説明 |
|---|---|
🏠 プロジェクトルート設定 | メインファイルの場所を設定 |
🌐 プロジェクト全体HTML生成 | 全YAMLファイルを一括HTML変換 |
🔗 リンク検証 | デッドリンクや不正リンクをチェック |
📦 プロジェクト統合書き出し | 全ファイルを1つに統合して出力 |
⚠️ 注意事項とトラブルシューティング
デッドリンクの回避
# ❌ 存在しないファイル br_link: "non_existent.yml#scene" # ✅ 存在するファイルとアンカー br_link: "chapter1/village.yml#arrival"
相対パスの注意点
# ❌ 絶対パス（環境依存） br_link: "/full/path/to/file.yml" # ✅ 相対パス（ポータブル） br_link: "../chapter1/scene.yml"
循環参照の回避
# ❌ 循環参照 # file_a.yml → file_b.yml → file_a.yml # ✅ 適切な階層構造 # main.yml → chapter1.yml → scene1.yml → main.yml
🎯 単一ファイル vs マルチファイル 選択指針
| 項目 | 単一ファイル | マルチファイル |
|---|---|---|
| プロジェクト規模 | 小〜中規模（〜500行） | 大規模（500行〜） |
| 開発人数 | 1人 | 複数人 |
| 管理の複雑さ | シンプル | やや複雑 |
| 分岐の多さ | 少ない | 多い |
| 保守性 | 低い | 高い |
| 学習コスト | 低い | 中程度 |
レガシープロジェクト構成例
my-scenario/
├── main.yaml # メインシナリオ
├── chapter1.yaml # 第1章
├── chapter2.yaml # 第2章
├── endings/
│ ├── good_end.yaml # グッドエンド
│ └── bad_end.yaml # バッドエンド
├── assets/
│ ├── bgm/ # BGMファイル
│ ├── voice/ # 音声ファイル
│ └── images/ # 画像ファイル
└── .screenplay-config.yaml # プロジェクト設定
❓ よくある質問
Q: シナリオが長くなってプレビューが重い
A: ファイルを分割して外部リンクを使用してください：
# main.yaml
sequences:
- id: 1
name: "第1章"
link: "file:chapter1.yaml"
Q: キャラクター名を一括変更したい
A: VS Codeの置換機能（Ctrl+H）を使用：
- 検索:
speaker: "旧名前" - 置換:
speaker: "新名前"
Q: 尺の計算が合わない
A: durationフィールドを明示的に指定してください：
cuts:
- id: 1
duration: 5.5 # 5.5秒
dialogue:
- speaker: "キャラ"
text: "長いセリフの場合は明示的に指定"
Q: エクスポートしたHTMLで日本語フォントが表示されない
A: ブラウザの印刷設定で「背景のグラフィック」をオンにしてください。
Q: Premiere ProでCSVマーカーが読み込めない
A: Premiere Proのバージョンを確認してください。CC 2018以降推奨です。
Q: v2.0.0の分岐機能をv1.x記法と混在できますか？
A: はい、完全に互換性があります。同一ファイル内でも混在可能です
cuts:
# v1.x記法
- id: 1
type: "choice"
anchor: "old_choice"
# v2.0.0記法
- id: 2
br_choices:
- br_id: "new_choice"
br_text: "新しい選択肢"
Q: 分岐の動作をテストしたい
A: プレビューでリンク先をクリックして遷移を確認できます。v2.0.0では条件評価のシミュレーション機能も追加予定です。
Q: ゲーム分岐をテストしたい
A: プレビューでリンク先をクリックして遷移を確認できます。
Q: マルチファイルプロジェクトで「🏠 メインに戻る」ボタンが表示されない
A: 以下を確認してください：
- 最新バージョン（v2.0.0+）の拡張機能を使用
- 「🏠 プロジェクトルート設定」でメインファイルを正しく設定
- 「🌐 プロジェクト全体HTML生成」で再生成
- メインファイル自体には表示されません（設計仕様）
Q: ファイル間リンクが「404 Not Found」になる
A: リンクパスを確認してください：
# ❌ 間違った例 br_link: "chapter1\village.yml#scene" # バックスラッシュ br_link: "/chapter1/village.yml#scene" # 絶対パス # ✅ 正しい例 br_link: "chapter1/village.yml#scene" # 相対パス・スラッシュ
Q: マルチファイルプロジェクトのファイルが多すぎて管理困難
A: 以下の整理方法を試してください：
- 機能別フォルダ分割:
scenes/,battles/,endings/ - 番号付け命名:
01_opening.yml,02_village.yml - README.md作成: プロジェクト構造を文書化
- 統合書き出し: 最終的に1ファイルにまとめる
Q: 他の人とマルチファイルプロジェクトを共同編集したい
A: Git等のバージョン管理システムの使用を推奨：
# プロジェクトをクローン git clone https://github.com/user/scenario-project.git # 各自のブランチで作業 git checkout -b feature/chapter1 # 変更をコミット・プッシュ git add chapter1/ git commit -m "第1章を追加" git push origin feature/chapter1
Q: マルチファイルプロジェクトを単一ファイルに戻したい
A: 「📦 プロジェクト統合書き出し」コマンドを使用：
Ctrl+Shift+P → "📦 プロジェクト統合書き出し"
全てのファイルが1つのYAMLファイルに統合されます。
Q: CSSスタイルがマルチファイルで正しく適用されない
A: パス調整機能が自動的に処理しますが、手動で確認する場合：
<!-- ルートレベル（main.html, prologue.html） --> <link rel="stylesheet" href="style.css"> <!-- 1階層下（chapter1/village.html） --> <link rel="stylesheet" href="../style.css"> <!-- 2階層下（chapter1/scenes/detail.html） --> <link rel="stylesheet" href="../../style.css">
🎯 効率的な作業フロー
1. プロット段階
# outline.yaml - まずは大枠から
title: "新作ゲーム"
br_variables:
player_level: 1
story_progress: 0
sequences:
- id: 1
name: "出会い"
# 詳細は後で追加
- id: 2
name: "展開"
- id: 3
name: "クライマックス"
2. 詳細化段階（線形→分岐）
# まずは線形シナリオとして作成
scenes:
- id: 1
name: "初対面"
cuts:
- id: 1
dialogue:
- speaker: "主人公"
text: "こんにちは"
# 後から分岐要素を追加
scenes:
- id: 1
name: "初対面"
cuts:
- id: 1
dialogue:
- speaker: "主人公"
text: "こんにちは"
br_effects: ["first_meeting = true"]
br_choices:
- br_id: "polite"
br_text: "丁寧に挨拶"
br_link: "route_polite"
3. 調整段階
- プレビューで全体確認
- 尺の計算・調整
- セリフの推敲
4. 完成・書き出し
- HTML書き出しで最終確認
- 制作ツール用データ書き出し
📧 サポート: GitHub Issues
🌟 評価: VS Code Marketplace
📖 詳細ドキュメント: README.md
🎮 v2.0.0新機能: 分岐型シナリオ対応、人間が読みやすいYAML記法、ゲーム開発対応
