Initial commit

Assets/_Project/Scripts/Documentation/detailed_class_documentation.md

@@ -0,0 +1,350 @@
+# Unity 3D Meccano Editor - Detailed Class Documentation
+
+This document provides a deep dive into the most important classes in the Meccano Editor system. It explains their roles, how they fit into the broader architecture, and includes relevant code snippets to illustrate their inner workings.
+
+---
+
+## 1. The Command Layer
+
+The Command Layer is the backbone of the application's state management. It encapsulates all user actions (like creating, moving, or deleting a block) so that they can be tracked, reversed, and serialized.
+
+### `ICommand` Interface
+Every action that modifies the world must implement this interface. 
+
+```csharp
+public interface ICommand
+{
+    void execute();
+    void undo();
+    CommandDTO toDTO();
+}
+```
+
+### `CreateBlockCommand`
+This class implements `ICommand` to handle the instantiation of a new block. Notice how it stores all necessary parameters (prefab ID, position, rotation) so that it can be reversed (`undo`) or serialized (`toDTO`).
+
+```csharp
+public class CreateBlockCommand : ICommand
+{
+    private string prefabId;
+    private Vector3 position;
+    private Quaternion rotation;
+    private string blockId; // Captured after creation
+    
+    // Dependencies
+    private BlockFactory factory;
+    private Environment environment;
+
+    public void execute()
+    {
+        // Creates the physical object in the scene
+        GameObject objectCreated = factory.createblock(prefabId, position, rotation, blockId, layerDiff);
+        
+        // We capture the generated UUID so we can target it during Undo
+        if (objectCreated != null)
+        {
+            Block blockComponent = objectCreated.GetComponent<Block>();
+            blockId = blockComponent.getBlockId();
+        }
+    }
+
+    public void undo()
+    {
+        // Completely removes the block from the environment registry and destroys it
+        environment.removeBlock(blockId);
+    }
+
+    public CommandDTO toDTO()
+    {
+        return new CommandDTO.CommandDTOBuilder()
+            .SetCommandName("CreateCommand")
+            .AddParameter("prefabId", prefabId)
+            .AddParameter("position", position)
+            .AddParameter("rotation", rotation)
+            .Build();
+    }
+}
+```
+
+### `CommandManager`
+This Singleton maintains the history of executed commands. It uses two `LinkedList`s to handle the `undo` and `redo` operations efficiently.
+
+```csharp
+public class CommandManager
+{
+    private LinkedList<ICommand> commandStack = new LinkedList<ICommand>();
+    private LinkedList<ICommand> redoStack = new LinkedList<ICommand>();
+    private int maxCapacity = 100; // Prevents memory leaks on long sessions
+
+    public void executeCommand(ICommand command)
+    {
+        command.execute();
+
+        commandStack.AddFirst(command);
+        redoStack.Clear(); // Any new action invalidates the redo stack
+        
+        if (commandStack.Count > maxCapacity)
+        {
+            commandStack.RemoveLast();
+        }
+    }
+
+    public void undo()
+    {
+        if (commandStack.Count > 0)
+        {
+            ICommand command = commandStack.First.Value;
+            commandStack.RemoveFirst();
+            command.undo();
+            redoStack.AddFirst(command);
+        }
+    }
+}
+```
+
+---
+
+## 2. Dependency Injection
+
+The project uses a custom reflection-based DI container to avoid tightly coupling classes together and relying too heavily on Singletons for internal systems.
+
+### `Injector`
+This class runs very early in the Unity lifecycle (`[DefaultExecutionOrder(-1000)]`). It searches for all `MonoBehaviour` instances, collects those implementing `IDependencyProvider`, and injects their provided values into any fields marked with `[Inject]`.
+
+```csharp
+[DefaultExecutionOrder(-1000)] 
+public class Injector : MonoBehaviour
+{
+    void Awake()
+    {
+        var monoBehaviours = FindMonoBehaviours();
+
+        // 1. Collect IDependencyProvider components and register what they provide via [Provide]
+        var providers = monoBehaviours.OfType<IDependencyProvider>();
+        foreach (var provider in providers)
+        {
+            RegisterProvider(provider);
+        }
+
+        // 2. Inject all injectable MonoBehaviours (fields with [Inject])
+        var injectables = monoBehaviours.Where(IsInjectable);
+        foreach (var injectable in injectables)
+        {
+            Inject(injectable);
+        }
+        
+        // 3. Setup watchers for RuntimeAnchors
+        SetupAnchorWatchers(injectables);
+    }
+    
+    // ...
+}
+```
+
+---
+
+## 3. The Environment and Save System
+
+The `Environment` is the source of truth for the physical world. The Save system works by "listening" to the Environment.
+
+### `Environment`
+It maintains a `Dictionary` of all active blocks mapped by a UUID.
+
+```csharp
+public class Environment : MonoBehaviour
+{
+    private Dictionary<string, Block> blockRegistry = new Dictionary<string, Block>();
+    
+    // Observers listen to these to react to the world state changing
+    public UnityEvent<Block> onBlockAddedEvent;
+    public UnityEvent<Block> onBlockRemovedEvent;
+    public UnityEvent onChangeEvent;
+
+    public void addBlock(Block block, string existingUUID = null)
+    {
+        // 1. Assign ID: Use existing (Undo/Redo) or generate a new one (Fresh placement)
+        string uuid = string.IsNullOrEmpty(existingUUID) ? Guid.NewGuid().ToString() : existingUUID;
+        block.setBlockId(uuid);
+
+        // 2. Register in the dictionary
+        blockRegistry[uuid] = block;
+        
+        applyChanges(); // Invokes onChangeEvent
+        onBlockAddedEvent.Invoke(block);
+    }
+}
+```
+
+### `EnvironmentObserver`
+This class demonstrates the "Event Sourcing" approach to saving. When `autoSaving` is enabled, it listens to the `onChangeEvent`. Instead of saving GameObjects, it loops through the current registry and builds a fresh stack of `CreateBlockCommand`s, then serializes them.
+
+```csharp
+public class EnvironmentObserver : MonoBehaviour
+{
+    private void Start()
+    {
+        environment.onChangeEvent.AddListener(onChange);
+    }
+
+    public void save()
+    {
+        commandSaveHandler.clearCommandList();
+        
+        // Loop through everything in the Environment
+        Dictionary<string, Block> blockRegistry = environment.getBlockRegistry();
+        foreach (var blockEntry in blockRegistry)
+        {
+            if (blockEntry.Value != null)
+            {
+                // Create a command representing the current state of the block
+                string prefabId = blockEntry.Value.getBlockData()?.blockName;
+                Vector3 position = blockEntry.Value.transform.position;
+                Quaternion rotation = blockEntry.Value.transform.rotation;
+                
+                ICommand createCommand = new CreateBlockCommand(prefabId, position, rotation);
+                
+                // Convert to a Data Transfer Object and add to the save queue
+                commandSaveHandler.addLastCommand(createCommand.toDTO());
+            }
+        }
+        
+        // Write the queue to JSON
+        commandSaveHandler.saveCommands();
+    }
+}
+```
+
+---
+
+## 4. Object Interaction: GhostManager
+
+The `GhostManager` handles the visual drag-and-drop feedback. It creates a semi-transparent "Ghost" of the object being manipulated.
+
+```csharp
+public class GhostManager : MonoBehaviour
+{
+    // ... State tracking variables
+    private IGhostMovementStrategy currentStrategy = new FreeMoveStrategy();
+
+    public void SetupBlock(BlockData blockData = null)
+    {
+        // Instantiate a fake "ghost" object for the user to drag around
+        GameObject prefab = selectedBlockData.blockPrefab;
+        ghostObject = Instantiate(prefab, rayInteractor.GetHitPosition(), prefab.transform.rotation);
+
+        // Make the ghost semi-transparent and ignore physics raycasts
+        SetLayerRecursively(ghostObject, LayerMask.NameToLayer("Ignore Raycast"));
+        InitialiseGhostFromObject(ghostObject); // Turns materials translucent
+
+        canPlace = true;
+    }
+
+    private void Update()
+    {
+        if (!HasActiveGhost()) return;
+
+        UpdateSurfaceTracking();
+        
+        // Trigger Snapping logic to find nearby sockets
+        snappingSystem.UpdateSockets(currentSurfacePoint, ghostObject.transform);
+
+        // Create a context object to pass into the movement strategy
+        var ctx = new GhostMovementContext(...);
+
+        // Strategy pattern: Allows swapping between free-move, axis-locked, etc.
+        currentStrategy.UpdateMovement(ref ctx);
+
+        // Validate the placement (e.g. are we colliding with something?)
+        isValidPlacement = validator != null ? validator.IsValidPlacement(ghostObject) : true;
+        UpdateVisualFeedback(isValidPlacement); // Turns green or red
+    }
+    
+    private void PlaceBlock()
+    {
+        if (!isValidPlacement) return;
+        
+        // We do NOT instantiate the real block here! We delegate to the CommandHandler.
+        if (block != null)
+            commandHandler.createBlock(
+                block.getBlockData()?.blockName,
+                ghostObject.transform.position,
+                ghostObject.transform.rotation);
+    }
+}
+```
+
+---
+
+## 5. Sockets & Mechanical Connections
+
+The mechanical logic relies on `SocketPoint`s representing holes and pins, and `JointBlock`s which create physical constraints between them.
+
+### `SocketPoint`
+Defines compatibility via radii and a `SocketType` enum.
+
+```csharp
+public class SocketPoint : MonoBehaviour, ISocket
+{
+    [SerializeField] private SocketType socketType = SocketType.Regular;
+    [SerializeField] private float socketRadius = 0.1f;
+    [SerializeField] private List<SocketType> acceptableTypes = new List<SocketType>();
+    [SerializeField] private float radiusTolerance = 0.05f;
+
+    public bool CanAccept(ISocket otherSocket)
+    {
+        // Must be empty
+        if (isOccupied) return false;
+
+        // Must match type
+        if (acceptableTypes.Count > 0 && !acceptableTypes.Contains(otherSocket.GetSocketType()))
+            return false;
+
+        // The hole must be larger than or equal to the pin, within a tolerance
+        float radiusDiff = socketRadius - otherSocket.GetSocketRadius();
+        return radiusDiff >= -radiusTolerance && radiusDiff <= radiusTolerance;
+    }
+}
+```
+
+### `JointBlock`
+When two pieces are successfully snapped together, `JointBlock` takes over to simulate the mechanical connection by creating Unity Physics joints.
+
+```csharp
+public class JointBlock : MonoBehaviour
+{
+    [SerializeField] private JointBlockType jointType = JointBlockType.FixedPivot;
+
+    public void CreatePhysicsJoint(GameObject targetObj, SocketPoint socket)
+    {
+        Rigidbody jointRb = GetComponent<Rigidbody>();
+        if (jointRb == null) jointRb = gameObject.AddComponent<Rigidbody>();
+
+        Rigidbody targetRb = targetObj.GetComponent<Rigidbody>();
+        if (targetRb == null) targetRb = targetObj.AddComponent<Rigidbody>();
+
+        // Create appropriate joint type
+        Joint joint = CreateJointByType(targetRb, socket);
+        if (joint != null)
+        {
+            createdJoints.Add(joint);
+        }
+    }
+
+    private Joint CreateJointByType(Rigidbody connectedBody, SocketPoint socket)
+    {
+        switch (jointType)
+        {
+            case JointBlockType.HingePivot:
+                HingeJoint joint = gameObject.AddComponent<HingeJoint>();
+                joint.connectedBody = connectedBody;
+                joint.axis = transform.InverseTransformDirection(transform.forward); 
+                joint.anchor = transform.InverseTransformPoint(socket.GetTransform().position);
+                return joint;
+
+            case JointBlockType.FixedPivot:
+            default:
+                return gameObject.AddComponent<FixedJoint>();
+        }
+    }
+}
+```