diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index b23fd98..264ebe6 100644 --- a/.github/workflows/build.yaml +++ b/.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 }}/Tools/ + sudo cp -r Tools/ build/${{ matrix.targetPlatform }}/ - if: matrix.targetPlatform == 'StandaloneWindows64' run: cd build/${{ matrix.targetPlatform }} && sudo zip -r ../build-${{ matrix.targetPlatform }}.zip * && cd - - if: matrix.targetPlatform == 'StandaloneWindows64' diff --git a/README.md b/README.md index 8215c6c..e023f47 100644 --- a/README.md +++ b/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) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index dde0467..0d2356f 100644 --- a/docs/.vitepress/config.mts +++ b/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' } ] } ], diff --git a/docs/Development_Guide.md b/docs/Development_Guide.md new file mode 100644 index 0000000..d902c97 --- /dev/null +++ b/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) diff --git a/docs/Simulation_Logging.md b/docs/Simulation_Logging.md index ed07254..d81ce7a 100644 --- a/docs/Simulation_Logging.md +++ b/docs/Simulation_Logging.md @@ -1,12 +1,259 @@ -# Simulation Logging +# 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 -`C:\Users\\AppData\LocalLow\BAMLAB\micromissiles\Telemetry`. +For example, on Windows, the logs are exported to: -On MacOS, the logs will be exported to -`~/Library/Application Support/BAMLAB/micromissiles/Telemetry`. +``` +C:\Users\\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/) diff --git a/docs/index.md b/docs/index.md index 5a18210..70b189a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,9 +10,9 @@ hero: - theme: brand text: Documentation link: /Keybinds_and_Controls - #- theme: alt - # text: Simulation Configuration Guide - # link: /Simulation_Config_Guide + - theme: alt + text: Development Guide + link: /Development_Guide --- diff --git a/docs/public/images/sim_visualizer.png b/docs/public/images/sim_visualizer.png new file mode 100644 index 0000000..ad2cd7f Binary files /dev/null and b/docs/public/images/sim_visualizer.png differ