diff --git a/CHANGELOG.md b/CHANGELOG.md index 53f42b0..d66e14d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,16 +7,16 @@ _No unreleased changes yet._ ## [v0.5.0] - 2025-11-25 ### Added -- Scratch「イベント/このスプライトが押されたとき」Unit を追加しました。 -- ブロックモードと unityroom モードの違いを説明するドキュメントを追加しました。 +- 背景を切り替えるブロックを追加し、StageData の背景リストからインデックス指定で変更できるようにしました。 +- 迷路サンプルのゲームクリア演出を拡充し、StopAll → UI 表示 → Finish までの流れを整理しました。 ### Changed -- Actor の向きと見た目の回転の扱いを整理し、初期状態で右方向に移動するようにしました。 -- ブロックモードの角度仕様（0=上, 90=右, 180=下, 270=左）をドキュメントに反映しました。 +- 色に触れた判定のサンプリングを見直し、境界の色も検出しやすくなるよう改善しました。 +- Speech bubble の反転処理を調整し、左右向きでの表示崩れを防止しました。 ### Fixed -- SetDirection() 呼び出し時に RotationStyle.AllAround の Actor が正しく見た目も回転するように修正しました。 -- Actor の初期向きが上方向になっていた問題を修正しました。 +- StopAll が coroutines を正しく停止するよう `flow.StopCoroutine(false)` を用いる実装へ修正しました。 +- Actor のリセット時にエフェクトが残らないよう、初期化タイミングの処理を修正しました。 ## [v0.4.0] - 2025-11-23 diff --git a/Docs/BlockList.md b/Docs/BlockList.md new file mode 100644 index 0000000..3f8ee53 --- /dev/null +++ b/Docs/BlockList.md @@ -0,0 +1,20 @@ +# Block List + +カテゴリ別に代表的なブロックと補足をまとめます。Scratch 互換の文言を基準にしています。 + +| カテゴリ | ブロック名 | 機能 | 備考 | +| --- | --- | --- | --- | +| 動き | MoveSteps | Actor を n 歩動かす | 1 歩 = 1px。ステージ境界でクランプと反射を実施。 | +| 動き | TurnRight / TurnLeft | 指定角度だけ回転する | ブロックモードの角度系（上=0°/右=90°）を維持。 | +| 動き | GoTo | 位置を指定して移動 | マウス座標や他 Actor へのジャンプに対応。 | +| 見た目 | Say / SayTimed | 吹き出しを表示 | ActorPresenter 経由で吹き出し UI を更新。 | +| 見た目 | SwitchCostume | コスチュームを切り替える | `CostumeIndex` を ActorState に設定し Presenter が反映。 | +| 見た目 | SetBackgroundByIndex | 背景をインデックスで変更 | **New**。StageData の背景リストから切り替え。 | +| 音 | PlaySound | サウンドを再生 | 音量や再生位置はサービスを介して管理。 | +| 調べる | TouchingColor | 指定色に触れたか判定 | 色判定精度を改善。境界の色も検出。 | +| 制御 | StopAll | 全スクリプトを停止 | `flow.StopCoroutine(false)` を利用し ScriptThreadManager と連動。 | +| 制御 | WaitSeconds | 指定時間待つ | ScriptThreadManager 上で待機スレッドを管理。 | +| 変数 | SetVariable / ChangeVariable | 変数を設定・加算 | `FUnityVariableService` を介して管理。 | +| 変数 | ShowVariable / HideVariable | 変数表示を切り替え | UI 上の変数表示パネルを制御。 | + +> 表にないユニットの詳細は [Docs/VS_Scratch_Mapping.md](VS_Scratch_Mapping.md) を参照してください。 diff --git a/Docs/InstallGuide.md b/Docs/InstallGuide.md new file mode 100644 index 0000000..29cdb85 --- /dev/null +++ b/Docs/InstallGuide.md @@ -0,0 +1,42 @@ +# Install Guide + +FUnity をプロジェクトへ組み込む手順と、セットアップを自動化するツールの使い方をまとめます。 + +## 1. パッケージ導入 +1. Unity の Package Manager で **Add package from git URL...** を選択します。 +2. `https://github.com/oco777/FUnity.git#v0.5.0` を入力してインポートします。 +3. 依存パッケージ（Visual Scripting など）が自動で追加されます。 + +## 2. プロジェクト生成ウィザード +`FUnityProjectCreatorWindow` を使うと、新規プロジェクトに必要なアセットをまとめて生成できます。 + +1. メニュー **FUnity/Create/Project Creator...** を開きます。 +2. 保存先を選び、**Create** を実行すると以下が自動生成されます。 + - `FUnityProjectData`（プロジェクト設定） + - `FUnityStageData`（ステージ背景と論理サイズ） + - `PanelSettings` や UI テーマ（不足していれば同梱テンプレートから生成） + - `FUnityActorData_Fooni` とサンプル Macro +3. シーンに `FUnityManager` を配置し、生成された `FUnityProjectData` を参照に設定します。 + +## 3. ActorData / ProjectData の構成 +- **FUnityProjectData** + - モード設定（Block Mode / unityroom モード） + - 既定の StageData / PanelSettings / UI テーマ参照 + - サンプル背景リストとターゲット FPS +- **FUnityActorData** + - Sprites リスト（コスチューム）と初期インデックス + - Visual Scripting Macro 参照と吹き出し設定 + - 移動速度や当たり判定設定 +- **FUnityStageData** + - 背景スプライトのリスト + - ステージ論理サイズ（例: 480x360） + +## 4. シーンへの適用 +1. `FUnityManager` をシーンへ 1 体追加します。 +2. `FUnityProjectData` を `FUnityManager` の参照に割り当てます。 +3. 再生すると `FUnityManager` が StageView / ActorView を生成し、`ActorPresenterAdapter` と `VSPresenterBridge` を通じて Macro を実行します。 + +## 5. トラブルシュートのヒント +- UI が表示されない場合は、`FUnityProjectCreatorWindow` を再実行して PanelSettings とテーマが生成されているか確認してください。 +- Macro を差し替えた後は、`FUnityActorData` の ScriptGraph 参照が切れていないかを確認します。 +- Block Mode の角度がずれる場合は、`ScratchUnitUtil.GetDirectionDegreesForCurrentMode` を利用するユニットが最新か確認してください。 diff --git a/Docs/Overview.md b/Docs/Overview.md new file mode 100644 index 0000000..b6c0379 --- /dev/null +++ b/Docs/Overview.md @@ -0,0 +1,40 @@ +# Overview + +FUnity は「Scratch の楽しさを Unity の表現力で広げる」ことを目的に設計された教育向けツールキットです。Scratch 互換のブロックモードを備え、既存の Unity プロジェクトへ追加するだけで、Actor（キャラクター）とステージを用いた学習体験を提供します。 + +## コンセプト +- **Scratch ライクな操作感**：カテゴリやブロック名を合わせ、子どもが違和感なく移行できる UI を目指します。 +- **MVP アーキテクチャ**：Model（ScriptableObject とランタイム状態）、View（UI Toolkit）、Presenter（状態更新）の三層で責務を分離し、テストしやすい構造を維持します。 +- **Unity との親和性**：UI Toolkit / Visual Scripting / UPM と連携し、既存資産やエディタ拡張と共存できる形で提供します。 + +## Scratch との互換性 +- ブロックカテゴリは「動き／見た目／音／調べる／制御／変数」を用意し、Scratch の代表的なブロックを Visual Scripting Unit として提供します。 +- 停止ブロックやクローン、背景切り替えなど、Scratch の学習パターンを維持したまま Unity の描画と入力に接続します。 +- ActorState の `CostumeIndex` を Presenter が適用し、`ActorPresenter.ApplyCostumeFromState()` → `ActorView.SetSprite(Sprite)` の順で UI へ反映することで、Scratch の「コスチューム」切り替えと同等の体験を実現します。 + +## アーキテクチャ概要 +``` ++-----------------------+ +---------------------+ +| ScriptThreadManager | <----> | VSPresenterBridge | ++-----------+-----------+ +----------+----------+ + ^ | + | registers/stop | calls presenter methods + | v ++-----------+-----------+ +---------------------+ +| FUnityManager | -----> | ActorPresenter | ++-----------+-----------+ +----------+----------+ + | | + v v ++-----------------------+ +---------------------+ +| StageView | | ActorView | ++-----------------------+ +---------------------+ +``` +- **Manager**：`FUnityManager` が Stage と Actor を初期化し、Presenter と View を結線します。 +- **ActorView**：UI Toolkit 上のスプライトや吹き出しを描画する View 層。Presenter からの命令のみで更新します。 +- **Stage**：背景やステージサイズを管理し、背景リストからの切り替えも担当します。 +- **ScriptThreadManager**：Scratch のイベント開始時にスレッドを登録し、「すべてを止める」などの停止ブロックを管理します。 + +## Block Mode +- Visual Scripting の Unit を Scratch 表記で提供し、`FUnity/Scratch/<カテゴリ>` に分類しています。 +- 角度はブロックモードに合わせて「上=0° / 右=90° / 下=180° / 左=270°」を維持します。 +- ScriptMachine に Macro を割り当てるだけでブロックモードを利用でき、C# とのハイブリッドも可能です。 diff --git a/README.md b/README.md index 467ed6c..d0e3b8d 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,59 @@ -# FUnity — Fun × Unity +# FUnity — Scratch スタイルで学べる Unity 教育ツール ![FUnity overview](Docs/images/readme-hero.png) -## FUnity とは？ +## 概要 +FUnity は、Scratch 風のブロックでゲームづくりを学べる Unity 用パッケージです。Actor（スプライト）、背景、サウンドを視覚的に組み合わせ、子どもや初心者でも Unity 6 環境で直感的に作品を作成できます。 -FUnity は、Unity 上で動作する **ブロックプログラミング & ゲーム制作環境** です。 +- 最新バージョン: **v0.5.0** +- Visual Scripting 互換の **ブロックモード (Block Mode)** を同梱 +- Actor / Costume / Speech Balloon / Background を Scratch ライクに操作 +- UPM Git URL からそのまま導入可能 -- 子どもや初心者でも扱いやすい **ブロックモード (Block Mode)** でロジックを組み立て -- そのまま Unity の世界でゲームとして動かせる -- 既存の Unity 資産やエディタ拡張とも連携できる +## 主な機能 +- **Visual Scripting 互換 Scratch ブロック**：ブロックモードのカテゴリと文言を揃え、学習用のサンプル Macro 付き。 +- **Actor / Costume / Speech Balloon**：Actor のスプライト切り替え、吹き出し表示、コスチュームの状態遷移を Presenter 経由で適用。 +- **Background 制御**：背景リストからの切り替えやインデックス指定をブロックで実行可能。 +- **Sound / Effects**：サウンド再生や効果切り替えを Scratch 互換のブロックで管理。 +- **Clone System**：クローン生成・停止を ScriptThreadManager が管理し、Scratch の停止ブロックとも連携。 +- **Script Thread Manager**：`FUnityScriptThreadManager` が Scratch スレッドを一元管理し、「すべてを止める」「スプライトの他のスクリプトを止める」を再現。 -ブロックモードは Scratch 風の操作感を意識しつつ、 -FUnity 独自の Actor / ステージ / プロジェクト構造に最適化されています。 +## 動作環境 +- Unity 6 (6000.x) 以降 +- .NET Standard 2.1 互換ランタイム +- UI Toolkit / UI Builder +- Unity Visual Scripting 1.9.7 以降（依存として自動追加） -## 📦 パッケージ構成と配置ルール -- `Runtime/` — ランタイム C#。**すべての実装はここに置き、`Assets/FUnity/Runtime/` へは置かない。** -- `Editor/` — エディタ拡張。ガードやメニュー、ウィザードなどを配置。 -- `Art/`・`Docs/`・`Samples~` — アセット、ドキュメント、サンプルを格納。 -- `Assets/FUnity/**` — プロジェクト同梱の検証用アセット。ランタイムコードは配置禁止で、混入すると Editor/CI ガードがエラーを報告します。 - -## ⚙ Modes -- `FUnityProjectData` アセットの Inspector で **ブロックモード (Block Mode)** と unityroom モードを切り替えられます。 -- 選択したモードに応じて `FUnityProjectData` 内の ModeConfig 参照がランタイム起動時に自動適用されます。 -- 各モードの仕様やブロック互換ポリシーは [`Assets/FUnity/Docs/Modes/README.md`](Assets/FUnity/Docs/Modes/README.md) を参照してください。 - -## 現状機能サマリ -- UPM の Git URL（`https://github.com/oco777/FUnity.git`）で導入可能。タグ指定（例：`#v0.5.0`）によるバージョン固定にも対応。 -- Samples~/BasicScene 内の **FUnitySample.unity** を開いて、ワンコマンド（**FUnity/Create/FUnityProjectData**）で初期データを生成。 -- `Runtime/Resources/Backgrounds/Background_01.png` と `FUnityActorData_Fooni` を自動設定し、背景とフーニーが 5 分で表示される。 -- `FUnityManager` がシーン起動時に “FUnity UI” GameObject と `UIDocument` を構築し、UI ブリッジや Runner 参照をセットアップ。 -- Unity Visual Scripting を **必須依存**とし、Macro が無い場合でも `Fooni_FloatSetup.asset` を自動生成して割り当てる。 -- ブロックモードの見た目操作として「大きさを ◯ % にする」「大きさを ◯ % ずつ変える」ユニットを提供し、Presenter 経由で UI Toolkit `style.scale` を中心ピボットで適用。 - -## What's new in 0.5.0 - -- Scratch「イベント/このスプライトが押されたとき」ユニットを追加し、イベント開始パターンを拡充しました。 -- Actor の向きと見た目の回転処理を整理し、初期状態で右方向へ移動する挙動に統一しました。 -- ブロックモードと unityroom モードの違いを整理したドキュメントを追加し、ブロックモードの角度仕様（0=上, 90=右, 180=下, 270=左）を明記しました。 - -## 目次 -- [システム要件](#システム要件) -- [インストール（UPM/Git）](#インストールupmgit) -- [クイックスタート](#クイックスタート) -- [FUnityProjectData が行うこと](#funityprojectdata-が行うこと) -- [ランタイム構築フロー](#ランタイム構築フロー) -- [⚙ Modes](#-modes) -- [Visual Scripting での移動例](#visual-scripting-での移動例) -- [トラブルシューティング早見表](#トラブルシューティング早見表) -- [Roadmap / 今後追加したい機能（案）](#roadmap--今後追加したい機能案) -- [ドキュメント](#ドキュメント) -- [ライセンス](#ライセンス) -- [貢献方法](#貢献方法) - -## システム要件 -- Unity 6 (6000.x) 以降。 -- .NET Standard 2.1 互換ランタイム。 -- UI Toolkit / UI Builder。 -- Unity Visual Scripting 1.9.7 以降（FUnity の依存として自動追加される）。 - -## インストール（UPM/Git） -### Git URL を直接指定する場合 -`Packages/manifest.json` の `dependencies` に次のエントリを追加します。 - -```json -"com.papacoder.funity": "https://github.com/oco777/FUnity.git" -``` - -### バージョンを固定したい場合 -特定のタグに固定したい場合は、`#タグ名` を付けます。 +## インストール +`Packages/manifest.json` に Git URL を追加します。 ```json "com.papacoder.funity": "https://github.com/oco777/FUnity.git#v0.5.0" ``` -> ℹ️ Visual Scripting は必須依存のため、`#if UNITY_VISUAL_SCRIPTING` などのガードは不要です。パッケージ導入時に `com.unity.visualscripting` が自動インストールされます。 - -## クイックスタート -1. Package Manager を開き、**Samples → BasicScene** の **Import** を押して `Samples~/BasicScene/FUnitySample.unity` を開きます。 -2. メニュー **FUnity/Create/FUnityProjectData** を実行し、プロジェクト既定データを生成します。 -3. シーンを再生すると背景画像（`Background_01.png`）とフーニーの俳優 UI が表示され、サンプル Macro による移動が動作します。 - -## Scratch本で最初に試すレシピ（5分） -- **FUnity/Create/FUnityActorData** を実行すると、ActorData と関連テンプレートが規定のフォルダに生成され、Stage や Runner を既存プロジェクトへ手早く追加できます。 - - 生成した `FUnityActorData` には `ActorElement.uxml/uss` と吹き出し用ラベルが割り当て済みで、`StageBackgroundService` と組み合わせて背景を適用できます。 - - Runner は必要に応じて既存のテンプレートを複製し、`ScriptMachine` に Macro を割り当てて Visual Scripting グラフを編集してください。 -- Visual Scripting のグラフは Runner の `ScriptMachine` から新規 Macro を作成し、`VSPresenterBridge` の Custom Event を結線するとブロックモードのブロック相当の操作が行えます。 - -## FUnityProjectData が行うこと -メニュー **FUnity/Create/FUnityProjectData**（`Assets/FUnity/Editor/CreateProjectData.cs` 内）を実行すると、既存リソースを尊重しつつ以下が保証されます。 -- `Resources/FUnityProjectData.asset` と `Resources/FUnityStageData.asset` を生成し、ステージ背景に `Runtime/Resources/Backgrounds/Background_01.png` を設定。 -- `Assets/UI Toolkit/UnityThemes/UnityDefaultRuntimeTheme.uss` が存在する場合はそれを `FUnityPanelSettings.asset`（`Assets/FUnity/UI/`）の ThemeStyleSheet に割り当て。存在しなければ `Assets/FUnity/UI/USS/UnityDefaultRuntimeTheme.uss` を生成し、同アセットに設定。 -- `Assets/FUnity/Data/Actors/FUnityActorData_Fooni.asset` を作成し、既存の重複リソース（`Assets/Resources/FUnityActorData_Fooni.asset` など）を検出して削除。Portrait/UXML/USS を既定テンプレートに割り当てます。 -- `Assets/FUnity/VisualScripting/Macros/Fooni_FloatSetup.asset` を探索し、無ければ新規作成。生成した Macro を `FUnityActorData_Fooni` の ScriptGraph に登録します。 +UPM の **Add package from git URL...** に貼り付けても導入できます。 -## ランタイム構築フロー -- シーンに `FUnityManager` を 1 体置くだけで、再生開始時に “FUnity UI” GameObject と `UIDocument` を生成。 -- `FUnityManager` は `FUnityProjectData` を参照して各 Actor Runner を生成し、Runner 側の `ScriptMachine` と `ActorPresenterAdapter` を構成しつつ、`FooniUIBridge` や `VSPresenterBridge` など必要なコンポーネントを結線します。 -- Actor ごとに `FUnityActorData` に設定された Macro が `ScriptMachine` に割り当てられ、`ActorPresenter` が `ActorState` と `ActorView` を橋渡しします。 -- Visual Scripting を用いず C# だけで動作させたい場合も、Presenter 層でロジックを完結させることで UI 更新と分離できます。 +## 使い方の流れ +1. Unity を起動し、メニュー **FUnity/Create/FUnityProjectData** を実行してプロジェクト既定データを生成します。 +2. 必要に応じて **FUnity/Create/FUnityActorData** で俳優テンプレートを追加し、スプライトや吹き出しを設定します。 +3. シーンに `FUnityManager` を 1 体配置すると、起動時に Stage / Actor / UI Document が自動構築されます。 +4. Visual Scripting の Macro で Scratch 互換ブロックを配置し、`VSPresenterBridge` を経由して Actor を操作します。 -## Visual Scripting での移動例 -- サンプル Macro（`Fooni_FloatSetup`）では、`On Update` → `Get Axis (Horizontal/Vertical)` → `Vector2`（Y を `*-1` で反転）→ `FooniUIBridge.NudgeByDefaultSpeed(dir, deltaTime)` の流れで移動量を計算します。 -- 入力 API は `FUnity.Runtime.Input` と `UnityEngine.Input` の名前空間が衝突しやすいため、`UnityEngine.Input.GetAxisRaw` のように完全修飾呼び出しを推奨します。 +## Samples~/ から始める +- **BasicScene**：`Samples~/BasicScene/FUnitySample.unity` を開き、サンプル Macro で移動と吹き出しを体験できます。 +- **Maze**：`Samples~/Maze` の説明に従い、StopAll → GameClearUI → Finish の流れでゲームクリア演出を学べます。 -## トラブルシューティング早見表 -- `CS0234`（`Input.GetAxisRaw` が見つからない）: `UnityEngine.Input.GetAxisRaw` と完全修飾するか、`using UInput = UnityEngine.Input;` を追加します。 -- テーマが null のまま: `Assets/UI Toolkit/UnityThemes/` を確認し、存在しない場合は **FUnity/Create/FUnityProjectData** を再実行して `Assets/FUnity/UI/USS/UnityDefaultRuntimeTheme.uss` が生成されることを確認します。 -- 俳優 UI が表示されない: `FooniElement.uxml` で `name="root"` と `name="actor-root"` が設定されているか確認し、`FooniUIBridge` が要素を取得できるようにします。 - -## Roadmap / 今後追加したい機能（案） - -- YouTube モード（構想中） - - Visual Scripting で作成したアニメーションを - Unity Recorder から動画ファイルとして書き出し、 - YouTube 向けに発表できる作品にするモード。 - - タイトル → 本編 → エンディング の定型テンプレートを用意し、 - キャラクター差し替えだけで作品が作れる構成を目指す。 +## ブロックモードの特徴 +- Scratch に近い見た目とカテゴリ構成（動き／見た目／音／調べる／制御／変数）。 +- ActorState の `CostumeIndex` を Presenter が受け取り、`ActorPresenter.ApplyCostumeFromState()` → `ActorView.SetSprite(Sprite)` の順に UI へ反映。 +- ScriptThreadManager がイベント開始時にスレッドを登録し、停止ブロックが正しく効きます。 ## ドキュメント -- [導入手順](Docs/setup.md) -- [既定データの構成](Docs/data-defaults.md) -- [UI テーマ適用戦略](Docs/ui-theme.md) -- [トラブルシュート集](Docs/troubleshooting.md) -- [MVP アーキテクチャ概要](Docs/mvp-overview.md) - -## ライセンス -- 本プロジェクトは [MIT License](LICENSE.md) に従います。 - -## 貢献方法 -- Issue と Pull Request を歓迎します。まずは課題を記載し、再現手順・スクリーンショットを添付してください。 -- コーディング規約とコメント方針は [Docs/conventions.md](Docs/conventions.md) を参照してください。 +- [Docs/Overview.md](Docs/Overview.md)：FUnity のコンセプトとアーキテクチャ概要 +- [Docs/InstallGuide.md](Docs/InstallGuide.md)：セットアップとプロジェクト生成手順 +- [Docs/BlockList.md](Docs/BlockList.md)：ブロック一覧と備考 +- [Docs/VS_Scratch_Mapping.md](Docs/VS_Scratch_Mapping.md)：Visual Scripting と Scratch の対応表 + +## ライセンスと貢献 +- ライセンス: [MIT License](LICENSE.md) +- Issue / Pull Request を歓迎します。貢献時は [Docs/conventions.md](Docs/conventions.md) を参照してください。 diff --git a/Samples~/Maze/README.md b/Samples~/Maze/README.md new file mode 100644 index 0000000..2e1c5ef --- /dev/null +++ b/Samples~/Maze/README.md @@ -0,0 +1,13 @@ +# Maze Sample + +迷路を進んでゴールするとゲームクリア演出が再生されるサンプルです。Macro で StopAll → GameClearUI → Finish の流れを確認できます。 + +## 動作フロー +1. ゴール判定に到達すると **StopAll** ブロックで全スクリプトを停止します。 +2. `GameClearUI` を表示し、演出用の UI をフェードインします。 +3. 完了演出後に **Finish** 処理を呼び、スコア表示やリトライ操作へ遷移します。 + +## 学べるポイント +- StopAll が `flow.StopCoroutine(false)` を用いて確実にスレッドを停止する実装。 +- 背景変更ブロックを使ったステージ演出の切り替え。 +- Actor のコスチュームと吹き出しを Presenter 経由で更新する一連の流れ。