Add Simulation_Logging guide, reorg docs for dev guide

.github/workflows/build.yaml

@@ -45,8 +45,7 @@ jobs:
           targetPlatform: ${{ matrix.targetPlatform }}
       - name: Copy Tools Directory
         run: |
-          sudo mkdir -p build/${{ matrix.targetPlatform }}/Tools
+          sudo cp -r Tools/ build/${{ matrix.targetPlatform }}/
-          sudo cp -r Tools/ build/${{ matrix.targetPlatform }}/Tools/
       - if: matrix.targetPlatform == 'StandaloneWindows64'
         run: cd build/${{ matrix.targetPlatform }} && sudo zip -r ../build-${{ matrix.targetPlatform }}.zip * && cd -
       - if: matrix.targetPlatform == 'StandaloneWindows64'

README.md

@@ -5,9 +5,11 @@
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/PisterLab/micromissiles-unity/build.yaml?link=https%3A%2F%2Fgithub.com%2FPisterLab%2Fmicromissiles-unity%2Factions%2Fworkflows%2Fbuild.yaml)](https://github.com/PisterLab/micromissiles-unity/actions/workflows/build.yaml)
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/PisterLab/micromissiles-unity/test.yaml?label=tests&link=https%3A%2F%2Fgithub.com%2FPisterLab%2Fmicromissiles-unity%2Factions%2Fworkflows%2Ftest.yaml)](https://github.com/PisterLab/micromissiles-unity/actions/workflows/test.yaml)
 [![GitHub Release](https://img.shields.io/github/v/release/PisterLab/micromissiles-unity?link=https%3A%2F%2Fgithub.com%2FPisterLab%2Fmicromissiles-unity%2Freleases%2Flatest)](https://github.com/PisterLab/micromissiles-unity/releases/latest)
+[![Static Badge](https://img.shields.io/badge/documentation-page?label=Docs)](https://pisterlab.github.io/micromissiles-unity/)
 
+# Documentation 
 
-
+Documentation is hosted on the [micromissiles-unity GitHub Pages site](https://pisterlab.github.io/micromissiles-unity/).
 
 # Quick Start
 
@@ -31,91 +33,3 @@ You can find the latest release [here](https://github.com/PisterLab/micromissile
      * Navigate to `Privacy & Security`.
      * Click on `Open Anyway` to bypass Apple's developer check.
 
-# Development
-
-This guide will help you set up and run the project in development mode. You'll learn how to install Unity Hub, open the project, and navigate the main scene.
-
-## Table of Contents
-
-- [Prerequisites](#prerequisites)
-- [Installation Steps](#installation-steps)
-  - [1. Install Unity Hub](#1-install-unity-hub)
-  - [2. Clone the Project Repository](#2-clone-the-project-repository)
-  - [3. Launch the Project via Unity Hub](#3-launch-the-project-via-unity-hub)
-  - [4. Open the Main Scene](#4-open-the-main-scene)
-- [Next Steps](#next-steps)
-- [Additional Resources](#additional-resources)
-
-## Prerequisites
-
-- A computer with internet access.
-- Administrative privileges to install software.
-- [Git](https://git-scm.com/downloads) installed on your system (optional, for cloning the repository).
-
-## Installation Steps
-
-### 1. Install Unity Hub
-
-Unity Hub is a desktop application that manages your Unity projects and installations. It simplifies the process of installing different Unity versions and launching projects.
-
-**Steps to Install Unity Hub:**
-
-1. Visit the [Unity Download Page](https://unity3d.com/get-unity/download).
-2. Click on **"Download Unity Hub"**.
-3. Run the downloaded installer and follow the on-screen instructions to complete the installation.
-
-### 2. Clone the Project Repository
-
-Obtain the project source code by cloning the repository from GitHub.
-
-```bash
-git clone https://github.com/PisterLab/micromissiles-unity.git
-```
-Alternatively, you can download the repository as a ZIP file and extract it to a preferred location.
-
-### 3. Launch the Project via Unity Hub
-
-![Unity Hub](docs/public/images/unity_hub.png)
-
-1. **Open Unity Hub**.
-
-2. **Add the Project to Unity Hub**:
-   - Navigate to the **"Projects"** tab.
-   - Click on the **"ADD"** button.
-   - Browse to the folder where you cloned or extracted the project.
-   - Select the folder containing the `Assets` folder and click on **"Select Folder"**.
-
-3. **Install the Required Unity Version**:
-   - Unity Hub will detect if the project requires a Unity version that is not currently installed.
-   - A notification or warning icon may appear next to the project name.
-   - Click on the notification and select **"Install Unity **[version]**"**.
-   - Unity Hub will download and install the required Unity version automatically.
-
-4. **Open the Project**:
-   - Once the required Unity version is installed, click on the project name in Unity Hub to open it.
-
-### 4. Open the Main Scene
-
-After the project opens in Unity:
-
-1. In the **Project** window (usually located at the bottom), navigate to:
-
-   ```
-   Assets/Scenes/
-   ```
-
-2. Find the main scene file, usually named `MainScene.unity`.
-
-3. Double-click on `MainScene.unity` to open it.
-
-4. The scene will load in the **Scene** view. You can now run the simulation by clicking the **Play** button at the top of the Unity Editor.
-
-## Next Steps
-
-- Familiarize yourself with the [**Keybinds and Controls**](docs/Keybinds_and_Controls.md) to navigate and interact with the simulation.
-- Learn how to configure the simulation settings by reading the [**Simulation Configuration Guide**](docs/Simulation_Config_Guide.md).
-
-## Additional Resources
-
-- [Keybinds and Controls](docs/Keybinds_and_Controls.md)
-- [Simulation Configuration Guide](docs/Simulation_Config_Guide.md)

docs/.vitepress/config.mts

@@ -9,7 +9,8 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Documentation', link: '/Keybinds_and_Controls' }
+      { text: 'Documentation', link: '/Keybinds_and_Controls' },
+      { text: 'Development Guide', link: '/Development_Guide' }
     ],
 
     sidebar: [
@@ -19,7 +20,8 @@ export default defineConfig({
           { text: 'Keybinds and Controls', link: '/Keybinds_and_Controls' },
           { text: 'Simulation Configuration Guide', link: '/Simulation_Config_Guide' },
           { text: 'Simulation Logging', link: '/Simulation_Logging' },
-          { text: 'Coverage Reports', link: '/coverage/editmode/Report/' }
+          { text: 'Coverage Reports', link: '/coverage/editmode/Report/' },
+          { text: 'Development Guide', link: '/Development_Guide' }
         ]
       }
     ],

docs/Development_Guide.md

@@ -0,0 +1,88 @@
+# Development Guide
+
+This guide will help you set up and run the project in development mode. You'll learn how to install Unity Hub, open the project, and navigate the main scene.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Installation Steps](#installation-steps)
+  - [1. Install Unity Hub](#1-install-unity-hub)
+  - [2. Clone the Project Repository](#2-clone-the-project-repository)
+  - [3. Launch the Project via Unity Hub](#3-launch-the-project-via-unity-hub)
+  - [4. Open the Main Scene](#4-open-the-main-scene)
+- [Next Steps](#next-steps)
+- [Additional Resources](#additional-resources)
+
+## Prerequisites
+
+- A computer with internet access.
+- Administrative privileges to install software.
+- [Git](https://git-scm.com/downloads) installed on your system (optional, for cloning the repository).
+
+## Installation Steps
+
+### 1. Install Unity Hub
+
+Unity Hub is a desktop application that manages your Unity projects and installations. It simplifies the process of installing different Unity versions and launching projects.
+
+**Steps to Install Unity Hub:**
+
+1. Visit the [Unity Download Page](https://unity3d.com/get-unity/download).
+2. Click on **"Download Unity Hub"**.
+3. Run the downloaded installer and follow the on-screen instructions to complete the installation.
+
+### 2. Clone the Project Repository
+
+Obtain the project source code by cloning the repository from GitHub.
+
+```bash
+git clone https://github.com/PisterLab/micromissiles-unity.git
+```
+Alternatively, you can download the repository as a ZIP file and extract it to a preferred location.
+
+### 3. Launch the Project via Unity Hub
+
+![Unity Hub](docs/public/images/unity_hub.png)
+
+1. **Open Unity Hub**.
+
+2. **Add the Project to Unity Hub**:
+   - Navigate to the **"Projects"** tab.
+   - Click on the **"ADD"** button.
+   - Browse to the folder where you cloned or extracted the project.
+   - Select the folder containing the `Assets` folder and click on **"Select Folder"**.
+
+3. **Install the Required Unity Version**:
+   - Unity Hub will detect if the project requires a Unity version that is not currently installed.
+   - A notification or warning icon may appear next to the project name.
+   - Click on the notification and select **"Install Unity **[version]**"**.
+   - Unity Hub will download and install the required Unity version automatically.
+
+4. **Open the Project**:
+   - Once the required Unity version is installed, click on the project name in Unity Hub to open it.
+
+### 4. Open the Main Scene
+
+After the project opens in Unity:
+
+1. In the **Project** window (usually located at the bottom), navigate to:
+
+   ```
+   Assets/Scenes/
+   ```
+
+2. Find the main scene file, usually named `MainScene.unity`.
+
+3. Double-click on `MainScene.unity` to open it.
+
+4. The scene will load in the **Scene** view. You can now run the simulation by clicking the **Play** button at the top of the Unity Editor.
+
+## Next Steps
+
+- Familiarize yourself with the [**Keybinds and Controls**](docs/Keybinds_and_Controls.md) to navigate and interact with the simulation.
+- Learn how to configure the simulation settings by reading the [**Simulation Configuration Guide**](docs/Simulation_Config_Guide.md).
+
+## Additional Resources
+
+- [Keybinds and Controls](docs/Keybinds_and_Controls.md)
+- [Simulation Configuration Guide](docs/Simulation_Config_Guide.md)

docs/Simulation_Logging.md

@@ -1,12 +1,259 @@
 # Simulation Logging 
 
+This guide provides instructions on how to access and interpret the simulation logs, how they are structured by the `SimMonitor` class, and how to utilize the provided `visualize_log.py` script to analyze simulation data. Additionally, it offers guidance on creating your own scripts for custom analysis.
+
+## Overview
+
+![Python simulation log visualizer](images/sim_visualizer.png)
+
+Simulation logs capture detailed telemetry and event data from each simulation run. These logs are essential for debugging, performance analysis, and understanding the behavior of agents within the simulation.
+
 Logs are exported to the `Telemetry/Logs` folder in your operating system's [persistent data path](https://docs.unity3d.com/ScriptReference/Application-persistentDataPath.html).
 
-For example, on Windows, the logs will be exported to 
+For example, on Windows, the logs are exported to:
-`C:\Users\<user>\AppData\LocalLow\BAMLAB\micromissiles\Telemetry`.
 
-On MacOS, the logs will be exported to 
+```
-`~/Library/Application Support/BAMLAB/micromissiles/Telemetry`.
+C:\Users\<user>\AppData\LocalLow\BAMLAB\micromissiles\Telemetry\Logs
+```
+
+On macOS, the logs are exported to:
+
+```
+~/Library/Application Support/BAMLAB/micromissiles/Telemetry/Logs
+```
+
+`visualize_log.py` is an example script provided to help visualize and interpret the simulation logs. It is included in the `Tools` directory of the release download.
 
 
+## Understanding Log Files and Directory Structure
 
+### Log Directory Structure
+
+Simulation logs are organized into timestamped directories within the `Logs` folder. Each simulation run generates a new directory named with the timestamp of the run.
+
+For example:
+
+```
+Telemetry/
+└── Logs/
+    ├── 20241002_101305/
+    │   ├── sim_telemetry_20241002_101311.csv
+    │   ├── sim_events_20241002_101311.csv
+    │   │
+    │   ├── sim_telemetry_20241002_101306.csv
+    │   └── sim_events_20241002_101306.csv
+    ├── 20241002_012122/
+    │   ├── sim_telemetry_20241002_012122.csv
+    │   └── sim_events_20241002_012122.csv
+    └── ...
+```
+
+Each simulation run produces two main CSV files:
+
+- **Telemetry Log (`sim_telemetry_*.csv`)**: Contains detailed state information for each agent at each time step.
+- **Event Log (`sim_events_*.csv`)**: Records significant events such as hits, misses, agent creation, and destruction.
+
+### Log Files Generated by `SimMonitor`
+
+The logging system is managed by the `SimMonitor` class in the simulation codebase.
+
+```csharp
+public class SimMonitor : MonoBehaviour
+{
+    // Responsible for logging simulation data
+    // ...
+}
+```
+
+**Key Responsibilities of `SimMonitor`:**
+
+- Collecting agent state data at each simulation step.
+- Writing telemetry data to `sim_telemetry_*.csv`.
+- Recording significant events to `sim_events_*.csv`.
+- Organizing logs into timestamped directories for each simulation run.
+
+### Telemetry Log Structure
+
+The telemetry log provides a snapshot of the simulation at each time step for every agent. Key columns include:
+
+- **`Time`**: Simulation time at the log entry.
+- **`AgentID`**: Unique identifier for each agent.
+- **`AgentType`**: Type of the agent (e.g., interceptor, threat).
+- **`AgentX`**, **`AgentY`**, **`AgentZ`**: Position coordinates of the agent.
+- **`AgentVelocityX`**, **`AgentVelocityY`**, **`AgentVelocityZ`**: Velocity components.
+- **`AgentStatus`**: Current status of the agent (e.g., active, destroyed).
+
+### Event Log Structure
+
+The event log records significant occurrences within the simulation. Key columns include:
+
+- **`Time`**: Time when the event occurred.
+- **`PositionX`**, **`PositionY`**, **`PositionZ`**: Position where the event occurred.
+- **`EventType`**: Type of event (e.g., `HIT`, `MISS`, `NEW_THREAT`, `NEW_INTERCEPTOR`).
+- **`Details`**: Additional details about the event.
+
+
+## Running the `visualize_log.py` Script
+
+The `visualize_log.py` script helps visualize agent trajectories and significant events in a 3D plot.
+
+### Locating the Script
+
+After downloading and extracting the release package, you can find the script at:
+
+```
+Tools/visualize_log.py
+```
+
+Make sure you have Python 3 installed on your system, along with the required libraries to run the script.
+
+### Required Python Libraries
+
+The script depends on the following Python libraries:
+
+- **`pandas`**
+- **`matplotlib`**
+- **`numpy`**
+
+You can install them using `pip`:
+
+```bash
+pip install pandas matplotlib numpy
+```
+
+### Usage
+
+#### Navigate to the Tools Directory
+
+Open a terminal or command prompt and navigate to the `Tools` directory:
+
+```bash
+cd path/to/Tools/
+```
+
+#### Run the Script
+
+To visualize the most recent simulation logs:
+
+```bash
+python visualize_log.py
+```
+
+**What the Script Does:**
+
+- **Automatically Finds the Latest Logs**: If no arguments are provided, it locates the most recent `sim_telemetry_*.csv` and `sim_events_*.csv` files.
+- **Prints a Summary**: Outputs a summary of events, including total counts and timing of hits and misses.
+- **Generates a 3D Plot**: Displays agent trajectories and marks events such as hits and misses.
+
+#### Specifying Log Files Manually
+
+You can also provide specific file paths as arguments:
+
+```bash
+python visualize_log.py path/to/sim_telemetry_file.csv path/to/sim_events_file.csv
+```
+
+### Example Output
+
+```
+Total number of events: 150
+
+Event Counts:
+  HIT: 120
+  MISS: 30
+
+First hit at 5.00 seconds, last hit at 15.00 seconds
+
+[3D plot window opens showing trajectories and events]
+```
+
+### Interpreting the Plot
+
+The 3D plot displays:
+
+- **Agent Trajectories**: Lines representing the paths of interceptors and threats.
+  - **Colors** indicate agent types (e.g., blue for interceptors, red for threats).
+- **Event Markers**: Symbols marking where events occurred.
+  - **Hits**: Marked with green circles.
+  - **Misses**: Marked with red crosses.
+
+### Adjusting the Visualization
+
+- **View Angle**: You can rotate the 3D plot by clicking and dragging to view the simulation from different perspectives.
+- **Zoom**: Use the scroll wheel to zoom in and out.
+
+## Writing Your Own Scripts
+
+The simulation logs are in CSV format, making them accessible for custom analysis and visualization.
+
+### Getting Started
+
+- **Choose a Programming Language**: Python or MATLAB are recommended for ease-of-use and data analysis capabilities.
+
+For example, using Python and the `pandas` library, you can load the telemetry and event data like this:
+
+```python
+import pandas as pd
+
+telemetry_df = pd.read_csv('path/to/sim_telemetry_*.csv')
+event_df = pd.read_csv('path/to/sim_events_*.csv')
+```
+
+### Visualization
+
+- **2D Plots**: Use `matplotlib` to create time-series plots:
+
+```python
+import matplotlib.pyplot as plt
+
+plt.plot(telemetry_df['Time'], telemetry_df['AgentY'])
+plt.xlabel('Time (s)')
+plt.ylabel('Altitude (m)')
+plt.title('Agent Altitude Over Time')
+plt.show()
+```
+
+- **3D Plots**: Use `mpl_toolkits.mplot3d` for 3D trajectory plots.
+
+### Sample Script: Calculating Miss Distances
+
+```python
+import pandas as pd
+import numpy as np
+
+# Load telemetry and event data
+telemetry_df = pd.read_csv('path/to/sim_telemetry_*.csv')
+event_df = pd.read_csv('path/to/sim_events_*.csv')
+
+# Filter miss events
+miss_events = event_df[event_df['Event'] == 'MISS']
+
+# Calculate miss distances
+miss_distances = []
+for idx, miss in miss_events.iterrows():
+    agent_id = miss['AgentID']
+    time = miss['Time']
+    # Get agent position at the time of miss
+    agent_state = telemetry_df[(telemetry_df['AgentID'] == agent_id) & (telemetry_df['Time'] == time)]
+    if not agent_state.empty:
+        x = agent_state['AgentX'].values[0]
+        y = agent_state['AgentY'].values[0]
+        z = agent_state['AgentZ'].values[0]
+        # Calculate distance to target or predefined point
+        distance = np.sqrt(x**2 + y**2 + z**2)
+        miss_distances.append(distance)
+
+# Output average miss distance
+average_miss_distance = np.mean(miss_distances)
+print(f'Average Miss Distance: {average_miss_distance:.2f} meters')
+```
+
+### Suggestions for Analysis
+
+- **Performance Metrics**: Determine interception success rates, average time to intercept, or hit accuracy.
+- **Behavioral Analysis**: Examine how changes in simulation configurations affect agent behavior.
+- **Batch Processing**: Automate analysis over multiple simulation runs to compare different scenarios.
+
+## Additional Resources
+
+- **Python Documentation**: [pandas](https://pandas.pydata.org/), [matplotlib](https://matplotlib.org/), [NumPy](https://numpy.org/)

docs/index.md

@@ -10,9 +10,9 @@ hero:
     - theme: brand
       text: Documentation
       link: /Keybinds_and_Controls
-    #- theme: alt
+    - theme: alt
-    #  text: Simulation Configuration Guide
+      text: Development Guide
-    #  link: /Simulation_Config_Guide
+      link: /Development_Guide
 
 ---