v0.4.9: Consolidated imports, documentation audit, and bug fixes

Author: ShenyfZero9211

p3deditor/Blueprint.pde

@@ -1,3 +1,14 @@
+/**
+ * Blueprint.pde - Visual Logic Container
+ * 
+ * Version: v0.4.9
+ * Responsibilities:
+ * - Manages a graph of VLB nodes and connections for an entity or level.
+ * - Implements the transpilation engine that converts visual nodes into PDES 
+ *   assembly script.
+ * - Handles event-specific PDES generation (OnStart, OnUpdate, etc.).
+ * - Manages node spatial organization (Offset/Zoom).
+ */
 class Blueprint {
   Object owner; // Can be Entity or SceneManager
   ArrayList<VLBNode> nodes = new ArrayList<VLBNode>();
@@ -47,6 +58,15 @@ class Blueprint {
     dst.connectedTo = src;
   }
 
+  /**
+   * generatePDES() - Transpilation Hub
+   * 
+   * [ALGORITHM] VLB to PDES Conversion
+   * This is the heart of the Visual Logic System. It traverses the node graph 
+   * starting from 'Event: OnStart' and recursively emits PDES commands.
+   * It ensures that data-dependency nodes (Math, GetPos) are emitted BEFORE 
+   * the flow nodes (Log, SetPos) that consume them.
+   */
   String generatePDES() {
     VLBNode startNode = null;
     for (VLBNode n : nodes) if (n.title.equals("Event: OnStart")) { startNode = n; break; }
@@ -108,7 +128,15 @@ class Blueprint {
     }
   }
 
-  // v1.4: Recursively emit commands for data-only nodes that have no flow pins
+  /**
+   * [ALGORITHM] emitDataDeps() - Recursive Dependency Emission
+   * 
+   * For a given flow node, this function finds all connected input data pins, 
+   * traces them back to their source nodes (e.g., an 'Add' node), and recursively 
+   * emits the script commands needed to calculate those values. 
+   * Results are stored in temporary variables ($add_12, $pos_x_5) for the 
+   * consumer to use.
+   */
   void emitDataDeps(VLBNode n, StringBuilder sb, HashSet<Integer> visited) {
     if (n == null || visited.contains(n.id)) return;
     // Only process data-producing nodes (no flow input)
@@ -171,6 +199,16 @@ class Blueprint {
     }
   }
 
+  /**
+   * [ALGORITHM] traverseNode() - Control Flow Generation
+   * 
+   * Performs a linear traversal of the flow-carrying nodes in the graph.
+   * 1. Assigns a PDES label (:node_ID) to the current segment.
+   * 2. Calls emitDataDeps to prepare all necessary input variables.
+   * 3. Maps the visual node type to its corresponding PDES command (tp, spawn, echo, etc.).
+   * 4. Follows the output flow pin to the next node in the chain.
+   * 5. Special Case: Branch nodes emit 'if/else/goto' logic instead of linear fallthrough.
+   */
   void traverseNode(VLBNode n, StringBuilder sb, HashSet<Integer> visited) {
     if (n == null) return;
     visited.add(n.id);
@@ -362,6 +400,15 @@ class Blueprint {
     }
   }
 
+  /**
+   * resolveData() - Pin Value Binding
+   * 
+   * [ALGORITHM] Variable Reference Mapping
+   * Determines what string should represent a pin's value in the final script.
+   * - If disconnected: Returns the pin's literal value (10.0, "Hello").
+   * - If connected: Returns a variable reference ($res_ID, $pos_x_ID) that 
+   *   points to the pre-emitted calculation result of the source node.
+   */
   String resolveData(VLBPin p) {
     if (p == null) return "0";
     // v1.1: Follow connected data pins to their source

p3deditor/BlueprintEditor.pde

@@ -1,3 +1,14 @@
+/**
+ * BlueprintEditor.pde - Visual Logic Workspace
+ * 
+ * Version: v0.4.9
+ * Responsibilities:
+ * - Provides an interactive 'Node Graph' canvas for visual programming.
+ * - Handles infinite panning, zooming, and grid rendering.
+ * - Manages node lifecycle: spawning, dragging, connecting, and deletion.
+ * - Implements the 'Compile' bridge to the PDES Scripting system.
+ * - Supports 'Hot-Reload' of logic during engine play sessions.
+ */
 class BlueprintEditor {
   Blueprint activeBlueprint = null;
   boolean visible = false;
@@ -30,7 +41,7 @@ class BlueprintEditor {
   float menuScrollY = 0;      // v1.2: Menu scroll offset
 
   // v1.0: Categorized Node Menu
-  String[] menuCategories = { "— Action —", "— Logic —", "— Math —", "— Data —", "— Event —", "— Value —" };
+  String[] menuCategories = { "�Action �, "�Logic �, "�Math �, "�Data �, "�Event �, "�Value � };
   String[][] menuItems = {
     { "Action: Wait", "Action: Log", "Action: Print", "Action: Set Position", "Action: Spawn Entity", "Action: Set Visibility", "Action: Light Settings", "Action: Set Background", "Action: Camera Teleport", "Action: Get Visibility" },
     { "Logic: Branch", "Logic: Compare", "Logic: Counter", "Logic: AND", "Logic: OR", "Logic: NOT" },
@@ -74,6 +85,16 @@ class BlueprintEditor {
     return null;
   }
 
+  /**
+   * render() - Blueprint Canvas Pass
+   * 
+   * [ALGORITHM] Layer-based UI Composition
+   * Draws the visual graph in clear depth stages:
+   * 1. Background Grid (infinite parallax).
+   * 2. Bezier Connections (wire layer).
+   * 3. VLB Nodes (interactive blocks).
+   * 4. Overlays (Compiling status, Menu, Headers).
+   */
   void render() {
     if (!visible || activeBlueprint == null) return;
 
@@ -153,7 +174,7 @@ class BlueprintEditor {
       float pulse = sin((millis() - compileFlashTime) * 0.005f) * 0.3f + 0.7f;
       fill(lerpColor(color(45, 140, 45), color(80, 255, 80), pulse));
       rect(runX, 10, 100, 25, 4);
-      fill(255); textSize(11); textAlign(CENTER, CENTER); text("✓ Compiled!", runX + 50, 22);
+      fill(255); textSize(11); textAlign(CENTER, CENTER); text("�Compiled!", runX + 50, 22);
     } else {
       if (mouseX > runX && mouseX < runX + 100 && mouseY > 10 && mouseY < 35) fill(60, 180, 60); else fill(45, 70, 45);
       rect(runX, 10, 100, 25, 4);
@@ -349,7 +370,15 @@ class BlueprintEditor {
     bezier(x1, y1, x1 + ctrlOffset, y1, x2 - ctrlOffset, y2, x2, y2);
   }
 
-  // === MOUSE PRESSED ===
+  /**
+   * handleMousePressed() / Dragged() / Released()
+   * 
+   * [ALGORITHM] Graph Interaction Workflow
+   * - Left-Click: Node selection or Pin drag start (wiring).
+   * - Box Select: Dragging on empty space to group-select nodes.
+   * - Right-Drag: Viewport panning.
+   * - Context Menu: Right-click on empty space to spawn nodes.
+   */
   void handleMousePressed() {
     if (!visible || activeBlueprint == null) return;
 
@@ -450,7 +479,7 @@ class BlueprintEditor {
       if (cwx > n.x && cwx < n.x + n.w && cwy > n.y && cwy < n.y + n.h) {
         // v1.4: If clicking an already-selected node, keep multi-selection for group drag
         if (n.selected) {
-          // Already selected — just set as drag target, don't clear others
+          // Already selected �just set as drag target, don't clear others
           draggingNode = n;
         } else {
           if (!p3deditor.this.keyPressed || (p3deditor.this.key != 17 && p3deditor.this.keyCode != p3deditor.this.CONTROL)) {
@@ -661,17 +690,24 @@ class BlueprintEditor {
     editingPinText = "";
   }
 
-  // v1.7: Sync Expression Pins based on variables in the "Expression" pin
+  /**
+   * [ALGORITHM] syncExpressionPins() - Dynamic Reflection
+   * 
+   * This critical algorithm parses a mathematical expression string (e.g. "sin(val) * 10")
+   * and automatically generates input pins for every undefined variable ("val") 
+   * found in the string. It preserves existing connections during the sync, 
+   * enabling seamless 'Expressive Programming'.
+   */
   void syncExpressionPins(VLBNode n) {
      VLBPin exprPin = n.findPin("Expression", true);
      if (exprPin == null) return;
 
      String expr = exprPin.sVal;
-     java.util.HashSet<String> vars = new java.util.HashSet<String>();
-     java.util.regex.Matcher m = java.util.regex.Pattern.compile("[a-zA-Z_][a-zA-Z0-9_]*").matcher(expr);
+     HashSet<String> vars = new HashSet<String>();
+     Matcher m = Pattern.compile("[a-zA-Z_][a-zA-Z0-9_]*").matcher(expr);
 
      // Reserved words to ignore (functions and constants)
-     java.util.List<String> reserved = java.util.Arrays.asList(
+     List<String> reserved = Arrays.asList(
        "sin", "cos", "tan", "sqrt", "abs", "rand", "min", "max", "PI", "E", "time", "dt"
      );
 

p3deditor/Command.pde

@@ -1,10 +1,27 @@
-import java.util.Stack;
+/**
+ * Command.pde - Undo/Redo System Implementation
+ * 
+ * Version: v0.4.9
+ * Responsibilities:
+ * - Implements the 'Command' design pattern to capture user actions as objects.
+ * - Manages the Undo and Redo stacks via UndoManager.
+ * - Provides specific command implementations for transforms, hierarchy changes, 
+ *   and property edits.
+ */
 
 abstract class Command {
   abstract void execute();
   abstract void undo();
 }
 
+/**
+ * UndoManager - Stack Manager
+ * 
+ * [ALGORITHM] Dual-Stack Undo/Redo
+ * Maintains two stacks: 'undoStack' for past actions and 'redoStack' for 
+ * undone actions. When a new command is pushed, the redoStack is cleared 
+ * to ensure linear history.
+ */
 class UndoManager {
   Stack<Command> undoStack = new Stack<Command>();
   Stack<Command> redoStack = new Stack<Command>();

p3deditor/CommandInterpreter.pde

@@ -1,6 +1,13 @@
-import java.util.Map;
-import java.util.HashMap;
-
+/**
+ * CommandInterpreter.pde - PDES Vocabulary & Dispatcher
+ * 
+ * Version: v0.4.9
+ * Responsibilities:
+ * - Defines the execution logic for all text-based engine commands.
+ * - Handles alias expansion and recursive command resolution.
+ * - Implements argument parsing with support for quoted strings.
+ * - Bridges high-level script intent to low-level engine state changes.
+ */
 class CommandInterpreter {
   SceneManager scene;
   String lastResult = "";
@@ -17,6 +24,15 @@ class CommandInterpreter {
     this.scriptManager = sm;
   }
 
+  /**
+   * execute() - Command Dispatcher
+   * 
+   * [ALGORITHM] Command Resolution Pipe
+   * 1. Splits semicolon-separated commands for batch execution.
+   * 2. Tokenizes the command string into parts.
+   * 3. Resolves aliases recursively (up to MAX_RECURSION).
+   * 4. Dispatches the command to its implementation block (if, move, tp, etc.).
+   */
   String execute(String cmdLine) {
     if (cmdLine == null || cmdLine.trim().isEmpty()) return "";
 
@@ -386,6 +402,14 @@ class CommandInterpreter {
     return "SUCCESS: Executed " + count + " instructions from " + filename;
   }
 
+  /**
+   * parseArgs() - Tokenizer
+   * 
+   * [ALGORITHM] Quote-Aware Splitting
+   * Splits a command line into space-separated tokens while treating text 
+   * within quotes (e.g. "My Entity Name") as a single argument. This is 
+   * critical for handling object names with spaces.
+   */
   ArrayList<String> parseArgs(String line) {
     ArrayList<String> args = new ArrayList<String>();
     boolean inQuotes = false;

p3deditor/DebugConsole.pde

@@ -1,6 +1,13 @@
-import java.io.*;
-import java.util.*;
-
+/**
+ * DebugConsole.pde - Engine Diagnostic Terminal
+ * 
+ * Version: v0.4.9
+ * Responsibilities:
+ * - Provides a 'Quake-style' dropdown terminal for direct command entry.
+ * - Manages session-based logging with persistence to disk (.log files).
+ * - Implements input history (Up/Down) and multi-line message rendering.
+ * - Serves as the primary feedback loop for PDES script execution.
+ */
 class LogEntry {
   String message;
   int type; // 0:Info, 1:Success, 2:Warn, 3:Error
@@ -51,6 +58,15 @@ class DebugConsole {
     }
   }
 
+  /**
+   * addLog() - Message Dispatcher
+   * 
+   * [ALGORITHM] Multi-line Log Ingestion
+   * High-level messages (like help text or batch results) containing newlines 
+   * are automatically decomposed into individual `LogEntry` objects to 
+   * maintain consistent line spacing in the terminal UI. 
+   * Also mirrors all logs to the persistent session file.
+   */
   void addLog(String msg, int type) {
     if (msg == null) return;
 
@@ -74,6 +90,14 @@ class DebugConsole {
     }
   }
 
+  /**
+   * render() - Terminal HUD Pass
+   * 
+   * [ALGORITHM] Clipped Text Rendering
+   * Draws a semi-transparent 'Glass' overlay over the viewport. 
+   * Uses `clip()` to ensure text overflow doesn't bleed into the main 3D 
+   * viewport while allowing for vertical scroll offsets.
+   */
   void render() {
     if (!active) return;
 
@@ -121,6 +145,14 @@ class DebugConsole {
     p3deditor.this.popStyle();
   }
 
+  /**
+   * handleKey() - Command Ingestion
+   * 
+   * [ALGORITHM] Buffered Input & History
+   * Accumulates keystrokes into `currentInput`. On ENTER, it pushes the 
+   * buffer to the `CommandInterpreter`, clears the buffer, and records 
+   * the command in the persistent session history for Up/Down retrieval.
+   */
   void handleKey(char key, int keyCode) {
     if (key == '`') {
       active = !active;

p3deditor/EditorCamera.pde

@@ -1,3 +1,13 @@
+/**
+ * EditorCamera.pde - Dual-Mode Viewport Controller
+ * 
+ * Version: v0.4.9
+ * Responsibilities:
+ * - Manages 3D viewport navigation (Fly Mode and Orbit Mode).
+ * - Derives World-Space basis vectors (Forward/Right/Up) from Euler angles.
+ * - Handles 'Fly Mode' using Robot-based cursor locking and WASD movement.
+ * - Handles 'Orbit Mode' using pivot-based rotation, panning, and zooming.
+ */
 class EditorCamera {
   PVector pos = new PVector(0, -100, 400); 
   PVector target = new PVector(0, 0, 0);
@@ -24,7 +34,15 @@ class EditorCamera {
     updatePosFromTarget();
   }
 
-  // Mathematical derivation of View space basis vectors mapped to World space
+  /**
+   * getForward() / getRight() / getUp()
+   * 
+   * [ALGORITHM] View Space Basis Derivation
+   * Uses spherical coordinates (Pitch/Yaw) to derive the Forward vector.
+   * The Right vector is the cross product of Up(0,1,0) and Forward.
+   * The local Up vector is the cross product of Right and Forward, 
+   * ensuring an orthonormal basis for the camera's view matrix.
+   */
   PVector getForward() { 
     return new PVector(cos(rotX)*sin(rotY), -sin(rotX), -cos(rotX)*cos(rotY)); 
   }
@@ -51,7 +69,15 @@ class EditorCamera {
     target = PVector.add(pos, PVector.mult(getForward(), orbitDistance));
   }
 
-  // Called every frame
+  /**
+   * update() - Every Frame Logic
+   * 
+   * [ALGORITHM] Fly Mode & Cursor Lock
+   * If Right-Click is held (and Alt is NOT held), the system:
+   * 1. Hides the system cursor and locks it to the center of the screen using Java Robot.
+   * 2. Accumulates mouse delta into rotation (Pitch/Yaw).
+   * 3. Processes WASDQE keys for translation relative to the camera's orientation.
+   */
   void update(boolean[] keyStates) {
     if (isRightDragging && !isAltDown) { // Fly mode WASD movement and Cursor Lock
 
@@ -112,6 +138,15 @@ class EditorCamera {
     if (mouseButton == RIGHT) isRightDragging = true;
   }
 
+  /**
+   * handleMouseDragged() - Interaction Routing
+   * 
+   * [ALGORITHM] Orbit Mode logic
+   * If Alt is held:
+   * - Left Mouse: Orbit (rotate camera around 'target' point).
+   * - Center Mouse: Pan (move both 'pos' and 'target' on the camera plane).
+   * - Right Mouse: Zoom (adjust 'orbitDistance').
+   */
   void handleMouseDragged(boolean isAltDown) {
     float dx = mouseX - lastMouseX;
     float dy = mouseY - lastMouseY;