Initial commit

Assets/_Project/Scripts/Documentation/video_presentation_guide.md

@@ -0,0 +1,100 @@
+# Video Presentation Guide: Unity 3D Meccano Editor
+
+This guide is structured to help you present your Meccano Editor to other developers. It flows from high-level concepts down to implementation details, ensuring the audience understands *why* decisions were made before seeing *how* they are implemented.
+
+---
+
+## 1. Project Overview (0:00 - 2:00)
+**Goal:** Hook the viewer and explain the core functionality.
+* **On Screen:** Start in the Unity Editor in "Play Mode". Build a quick 3- or 4-piece Meccano assembly. Show the grid, snap a few pieces together, and undo an action.
+* **What to Mention:**
+  - This is a 3D Meccano building application where players can snap mechanical parts together.
+  - It supports undo/redo, saving/loading, and complex mechanical joints.
+  - The architecture is highly decoupled, event-driven, and relies heavily on the Command Pattern to manage state.
+
+---
+
+## 2. Core Architecture (2:00 - 4:00)
+**Goal:** Explain the foundational pillars of the codebase.
+* **On Screen:** Open an architectural diagram (or draw one on screen/whiteboard) showing three columns: `Interaction Layer -> Command Layer -> BlocksLayer (Environment)`.
+* **Important Things to Mention:**
+  - The separation of concerns: The Interaction layer ONLY handles input and ghosts. It *never* directly modifies the Environment.
+  - The `Environment` class is the single source of truth for instantiated blocks.
+  - **Code to Open:** `Injector.cs`
+    - Briefly show the custom Dependency Injection system. Explain why you built `[Inject]` and `[Provide]` attributes: to guarantee dependencies are resolved before `Start()` and to handle reactive `RuntimeAnchor` changes cleanly.
+
+---
+
+## 3. Data & Commands (4:00 - 7:00)
+**Goal:** Explain how state mutations are encapsulated.
+* **On Screen:** Split screen or switch between `CommandManager.cs` and `CreateBlockCommand.cs`.
+* **What to Mention:**
+  - Introduce the **Command Pattern**. Explain that every action is an `ICommand`.
+  - Show how `CreateBlockCommand` stores the required data (prefab ID, position, rotation) to execute *and* reverse the action.
+  - Highlight the `CommandManager` class. Show the `commandStack` and `redoStack`.
+* **Common Questions to Address:** 
+  - *Why not just instantiate blocks directly from the UI?* -> "If we instantiate directly, we lose the ability to easily undo actions or serialize the history for saves."
+
+---
+
+## 4. Object Manipulation & The Ghost System (7:00 - 10:00)
+**Goal:** Explain the drag-and-drop workflow and how visual feedback is given before committing an action.
+* **On Screen:** Go back to Unity Play Mode. Pick up a block, drag it around (it should look semi-transparent), and hover it over a valid and invalid spot.
+* **Code to Open:** `GhostManager.cs` and `IGhostMovementStrategy.cs`.
+* **Important Things to Mention:**
+  - `GhostManager` is the most complex UI component. It creates a dummy version of the block that doesn't interact with physics.
+  - Mention the **Strategy Pattern**: `IGhostMovementStrategy` allows the ghost to behave differently (e.g., free movement vs. axis-constrained movement).
+  - Show how, upon release, `GhostManager` doesn't place the block itself, but instead fires off a Command to the `CommandHandler`.
+
+---
+
+## 5. UI & Interaction (10:00 - 12:00)
+**Goal:** Show how user input flows into the system.
+* **Code to Open:** `PCIntputProvider.cs` and `RayInteractor.cs`.
+* **What to Mention:**
+  - Show the use of Unity's new Input System (`InputAction`).
+  - Explain how `BaseInputProvider` abstracts the input device, allowing easy future support for Mobile or VR.
+  - Show `RayInteractor.cs` and explain that it strictly handles firing rays and casting events, delegating the logic of *what* happens to the `InteractionManager`.
+
+---
+
+## 6. Sockets & Joints (12:00 - 15:00)
+**Goal:** Explain the mechanical heart of the Meccano system.
+* **On Screen:** In the Editor (not Play Mode), select a Meccano piece prefab. Show its `SocketContainer` and `SocketPoint` components in the Inspector. Turn on Gizmos to show the socket radii/normals.
+* **Code to Open:** `SocketPoint.cs` and `JointBlock.cs`.
+* **What to Mention:**
+  - `SocketPoint` defines the compatibility (hole vs pin, radius sizes).
+  - Explain that when two compatible sockets snap, `JointBlock.cs` dynamically creates a Unity Physics Joint (like `FixedJoint` or `HingeJoint`) between the Rigidbody components.
+  - **Common Questions to Address:**
+    - *How do you prevent physics explosions?* -> "We validate placements using `IValidator` before creating the joints."
+
+---
+
+## 7. Save/Load System & Event Sourcing (15:00 - 17:00)
+**Goal:** Demonstrate how the Command Pattern makes saving almost trivial.
+* **On Screen:** Build something in Play Mode. Hit save. Clear the scene. Hit load. Watch it rebuild.
+* **Code to Open:** `EnvironmentObserver.cs` and `CommandSaveHandler.cs`.
+* **Important Things to Mention:**
+  - **Event Sourcing:** We don't save a list of objects; we save a list of *instructions*. 
+  - `CommandDTO` structs serialize the command data to JSON.
+  - When loading, we use a Coroutine (`CommandSaveHandler.excuteAllCommands()`) to replay the commands frame-by-frame.
+  - **Honest Critique (Weakness):** Mention that while this is elegant, if a user makes 10,000 moves, the save file might get large and slow to replay. A future optimization could involve taking state snapshots.
+
+---
+
+## 8. Extending the System (17:00 - 19:00)
+**Goal:** Prove the architecture is developer-friendly.
+* **On Screen:** Open `BlockFactory.cs` and your `Resources/BlocksData` folder.
+* **What to Mention:**
+  - **Adding a new block:** "Just create a prefab, add a `Block` and `SocketPoint` component, create a `BlockData` ScriptableObject, and put it in the Resources folder. The system picks it up automatically."
+  - **Adding a new command:** "Implement `ICommand`, add your execute/undo logic, and update `CommandDTO` so it can be saved."
+
+---
+
+## 9. Final Walkthrough & Model Checking System (19:00 - 20:00)
+**Goal:** End on a high note by showing the 'Game' aspect (Puzzles).
+* **On Screen:** Open `ModelCheckManager.cs`.
+* **What to Mention:**
+  - Explain the puzzle mode: The system can compare the current `Environment` against a predefined `BlocksMap` ScriptableObject.
+  - Show the Editor tooling: A developer can build a structure in Play Mode, click a button, and generate a `BlocksMap` asset to serve as a new level objective.
+* **Closing Statement:** Thank the viewers and summarize that the decoupled, command-driven architecture makes the editor robust, testable, and easily extensible.