deploy: 54c7e5fbc7
This commit is contained in:
turtlebasket
5
coverage/playmode/docs/.gitignore
vendored
Normal file
5
coverage/playmode/docs/.gitignore
vendored
Normal file
@@ -0,0 +1,5 @@
|
||||
node_modules/
|
||||
package-lock.json
|
||||
.vuepress/dist/
|
||||
.vitepress/cache/
|
||||
.vitepress/dist/
|
||||
40
coverage/playmode/docs/.vitepress/config.mts
Normal file
40
coverage/playmode/docs/.vitepress/config.mts
Normal file
@@ -0,0 +1,40 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
|
||||
// https://vitepress.dev/reference/site-config
|
||||
export default defineConfig({
|
||||
title: "micromissiles-unity",
|
||||
description: "Swarm-on-swarm simulator using micromissiles for point defense",
|
||||
base: '/micromissiles-unity/',
|
||||
themeConfig: {
|
||||
// https://vitepress.dev/reference/default-theme-config
|
||||
nav: [
|
||||
{ text: 'Home', link: '/' },
|
||||
{ text: 'Documentation', link: '/Keybinds_and_Controls' },
|
||||
{ text: 'Development Guide', link: '/Development_Guide' }
|
||||
],
|
||||
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Documentation',
|
||||
items: [
|
||||
{ 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: 'Development Guide', link: '/Development_Guide' }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/PisterLab/micromissiles-unity' }
|
||||
],
|
||||
search: {
|
||||
provider: 'local'
|
||||
},
|
||||
footer: {
|
||||
message: 'Released under the <a href="https://github.com/PisterLab/micromissiles-unity/blob/main/LICENSE">BSD-3-Clause License</a>.',
|
||||
copyright: 'Copyright © 2024-present, The Regents of the University of California (Regents). All Rights Reserved.'
|
||||
}
|
||||
}
|
||||
})
|
||||
84
coverage/playmode/docs/Development_Guide.md
Normal file
84
coverage/playmode/docs/Development_Guide.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# 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
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Keybinds and Controls](Keybinds_and_Controls.md)
|
||||
- [Simulation Configuration Guide](Simulation_Config_Guide.md)
|
||||
88
coverage/playmode/docs/Keybinds_and_Controls.md
Normal file
88
coverage/playmode/docs/Keybinds_and_Controls.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Keybinds and Controls
|
||||
|
||||
This guide will help you navigate and interact with the environment using your mouse and keyboard. Below are the keybindings organized into easy-to-read tables, along with detailed descriptions to enhance your experience.
|
||||
|
||||
## Table of Contents
|
||||
- [Mouse Controls](#mouse-controls)
|
||||
- [Keyboard Controls](#keyboard-controls)
|
||||
- [Camera Movement](#camera-movement)
|
||||
- [Camera Speed](#camera-speed)
|
||||
- [Simulation Controls](#simulation-controls)
|
||||
- [Additional Controls](#additional-controls)
|
||||
- [Preset Views](#preset-views)
|
||||
|
||||
## Mouse Controls
|
||||
|
||||
Use your mouse to control the camera's orientation and zoom level.
|
||||
|
||||
| **Action** | **Keybind** | **Description** |
|
||||
|---------------------------|-----------------------------|-----------------------------------------------------------|
|
||||
| **Orbit Camera** | Left Mouse Button (Hold) | Rotate the camera around a focal point by holding the left mouse button and moving the mouse. |
|
||||
| **Rotate Camera** | Right Mouse Button (Hold) | Adjust the camera's rotation by holding the right mouse button and moving the mouse. |
|
||||
| **Zoom In/Out** | Mouse Scroll Wheel | Scroll the wheel up to zoom in and scroll down to zoom out. |
|
||||
|
||||
## Keyboard Controls
|
||||
|
||||
### Camera Movement
|
||||
|
||||
Navigate the camera through the simulation using the following keys:
|
||||
|
||||
| **Action** | **Keys** | **Description** |
|
||||
|----------------------|------------------------------------|-----------------------------------------------------------|
|
||||
| **Move Forward** | **W** or **Up Arrow** | Moves the camera forward in the simulation space. |
|
||||
| **Move Left** | **A** or **Left Arrow** | Moves the camera to the left side. |
|
||||
| **Move Backward** | **S** or **Down Arrow** | Moves the camera backward. |
|
||||
| **Move Right** | **D** or **Right Arrow** | Moves the camera to the right side. |
|
||||
| **Move Upward** | **Q** | Raises the camera upward. |
|
||||
| **Move Downward** | **E** | Lowers the camera downward. |
|
||||
|
||||
### Camera Speed
|
||||
|
||||
Adjust the speed of the camera movement to suit your preference:
|
||||
|
||||
| **Action** | **Keybind** | **Description** |
|
||||
|----------------------|-------------------|-----------------------------------------------------------|
|
||||
| **Increase Speed** | **Left Shift (Hold)** | Hold down the Left Shift key to move the camera faster. |
|
||||
| **Normal Speed** | *Release Left Shift* | Releases the Left Shift key to return to normal movement speed. |
|
||||
|
||||
### Simulation Controls
|
||||
|
||||
Manage the simulation state with these keybinds:
|
||||
|
||||
| **Action** | **Keybind** | **Description** |
|
||||
|----------------------|-------------------|-----------------------------------------------------------|
|
||||
| **Pause/Resume** | **Spacebar** | Toggles between pausing and resuming the simulation. |
|
||||
| **Restart Simulation** | **R** | Restarts the simulation from the beginning. |
|
||||
| **Toggle Configuration Panel** | **L** | Opens or closes the configuration selector panel for adjusting simulation settings. |
|
||||
|
||||
### Additional Controls
|
||||
|
||||
Enhance your interaction with the simulation using these additional keybinds:
|
||||
|
||||
| **Action** | **Keybind** | **Description** |
|
||||
|----------------------|-------------------|-----------------------------------------------------------|
|
||||
| **Toggle Auto-Rotate** | **P** | Enables or disables the camera's auto-rotate feature. |
|
||||
| **Quit Application** | **Esc** | Exits the simulation application. |
|
||||
|
||||
### Preset Views
|
||||
|
||||
Quickly switch to predefined camera angles for different perspectives:
|
||||
|
||||
| **Action** | **Keybind** | **Description** |
|
||||
|----------------------|-------------------|-----------------------------------------------------------|
|
||||
| **Preset View 1** | **1** | Switches to the first predefined camera view. |
|
||||
| **Preset View 2** | **2** | Switches to the second predefined camera view. |
|
||||
| **Preset View 3** | **3** | Switches to the third predefined camera view. |
|
||||
| **Preset View 4** | **4** | Switches to the fourth predefined camera view. |
|
||||
| **Preset View 5** | **5** | Switches to the fifth predefined camera view. |
|
||||
| **Preset View 6** | **6** | Switches to the sixth predefined camera view. |
|
||||
|
||||
*Note: The implementation for preset views may be added in future updates.*
|
||||
|
||||
## Tips for Effective Navigation
|
||||
|
||||
- **Combining Controls**: Feel free to combine mouse and keyboard controls for a more dynamic navigation experience. For example, hold the **Left Shift** key while moving the camera forward with the **W** key for faster traversal.
|
||||
- **Pausing for Adjustments**: Use the **Spacebar** to pause the simulation, allowing you to adjust camera angles or settings without interruption.
|
||||
- **Exploring Views**: Utilize the preset views to quickly jump to different perspectives, making it easier to explore various aspects of the simulation.
|
||||
|
||||
Happy simming!
|
||||
85
coverage/playmode/docs/Markdown_Examples.md
Normal file
85
coverage/playmode/docs/Markdown_Examples.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# Markdown Extension Examples
|
||||
|
||||
This page demonstrates some of the built-in markdown extensions provided by VitePress.
|
||||
|
||||
## Syntax Highlighting
|
||||
|
||||
VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
|
||||
|
||||
**Input**
|
||||
|
||||
````md
|
||||
```js{4}
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Highlighted!'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Output**
|
||||
|
||||
```js{4}
|
||||
export default {
|
||||
data () {
|
||||
return {
|
||||
msg: 'Highlighted!'
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Custom Containers
|
||||
|
||||
**Input**
|
||||
|
||||
```md
|
||||
::: info
|
||||
This is an info box.
|
||||
:::
|
||||
|
||||
::: tip
|
||||
This is a tip.
|
||||
:::
|
||||
|
||||
::: warning
|
||||
This is a warning.
|
||||
:::
|
||||
|
||||
::: danger
|
||||
This is a dangerous warning.
|
||||
:::
|
||||
|
||||
::: details
|
||||
This is a details block.
|
||||
:::
|
||||
```
|
||||
|
||||
**Output**
|
||||
|
||||
::: info
|
||||
This is an info box.
|
||||
:::
|
||||
|
||||
::: tip
|
||||
This is a tip.
|
||||
:::
|
||||
|
||||
::: warning
|
||||
This is a warning.
|
||||
:::
|
||||
|
||||
::: danger
|
||||
This is a dangerous warning.
|
||||
:::
|
||||
|
||||
::: details
|
||||
This is a details block.
|
||||
:::
|
||||
|
||||
## More
|
||||
|
||||
Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).
|
||||
344
coverage/playmode/docs/Simulation_Config_Guide.md
Normal file
344
coverage/playmode/docs/Simulation_Config_Guide.md
Normal file
@@ -0,0 +1,344 @@
|
||||
# Simulation Configuration Guide
|
||||
|
||||
This guide provides instructions on how to configure the simulation by editing the configuration files. You can customize interceptor and threat behaviors, simulation parameters, and more to suit your needs.
|
||||
|
||||
## Configuration Files
|
||||
|
||||
The main configuration files you will work with are located in the `Assets/StreamingAssets/Configs/` directory. In a deployment context, these files are located in the `micromissiles_Data/StreamingAssets/Configs/` directory.
|
||||
|
||||
- **Simulation Configurations**:
|
||||
- **`1_salvo_1_hydra_7_drones.json`**: A simple, barebones example of a simulation configuration featuring a single salvo in a 7-on-7 scenario.
|
||||
- **`3_salvo_10_hydra_200_drones.json`**: A more complex example with three salvos, illustrating a 210-on-200 scenario. This demonstrates how to set up multiple salvos within the simulation.
|
||||
- **C# Script**: [`SimulationConfig.cs`](https://github.com/PisterLab/micromissiles-unity/blob/master/Assets/Scripts/Config/StaticConfig.cs)
|
||||
|
||||
- **Model Configurations** (found in `Assets/StreamingAssets/Configs/Models/`):
|
||||
- **`micromissile.json`**
|
||||
- **`hydra70.json`**
|
||||
- **`drone.json`**
|
||||
- **C# Script**: [`StaticConfig.cs`](https://github.com/PisterLab/micromissiles-unity/blob/master/Assets/Scripts/Config/StaticConfig.cs)
|
||||
|
||||
### File Locations
|
||||
|
||||
Development context:
|
||||
- **Simulation Configurations**: `Assets/StreamingAssets/Configs/`
|
||||
- **Model Configurations**: `Assets/StreamingAssets/Configs/Models/`
|
||||
|
||||
Deployment context:
|
||||
- **Simulation Configurations**: `micromissiles_Data/StreamingAssets/Configs/`
|
||||
- **Model Configurations**: `micromissiles_Data/StreamingAssets/Configs/Models/`
|
||||
|
||||
## Overview of Simulation Configurations
|
||||
|
||||
### Simulation Configuration Examples
|
||||
|
||||
The simulation configurations are defined in JSON files that specify the initial setup for missiles and targets.
|
||||
|
||||
#### `1_salvo_1_hydra_7_drones.json`
|
||||
|
||||
This is a basic configuration featuring a single salvo with one interceptor type (`HYDRA_70`) and seven threat drones.
|
||||
|
||||
```json
|
||||
{
|
||||
"timeScale": 1,
|
||||
"interceptor_swarm_configs": [
|
||||
{
|
||||
"num_agents": 1,
|
||||
"agent_config": {
|
||||
"interceptor_type": "HYDRA_70",
|
||||
"initial_state": {
|
||||
"position": { "x": 0, "y": 20, "z": 0 },
|
||||
"rotation": { "x": -45, "y": 0, "z": 0 },
|
||||
"velocity": { "x": 0, "y": 10, "z": 10 }
|
||||
},
|
||||
"dynamic_config": {
|
||||
"launch_config": { "launch_time": 0 },
|
||||
"sensor_config": {
|
||||
"type": "IDEAL",
|
||||
"frequency": 100
|
||||
}
|
||||
},
|
||||
"submunitions_config": {
|
||||
"num_submunitions": 7,
|
||||
"launch_config": { "launch_time": 4 },
|
||||
"agent_config": {
|
||||
"interceptor_type": "MICROMISSILE",
|
||||
// Submunition configuration...
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"threat_swarm_configs": [
|
||||
{
|
||||
"num_agents": 7,
|
||||
"agent_config": {
|
||||
"threat_type": "DRONE",
|
||||
"initial_state": {
|
||||
"position": { "x": 0, "y": 600, "z": 6000 },
|
||||
"rotation": { "x": 90, "y": 0, "z": 0 },
|
||||
"velocity": { "x": 0, "y": 0, "z": -50 }
|
||||
},
|
||||
// Other threat configurations...
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### `3_salvo_10_hydra_200_drones.json`
|
||||
|
||||
This configuration demonstrates a more complex scenario with three salvos, each launching ten `HYDRA_70` missiles at different times against 200 threat drones. This results in a total of 210 missiles (including submunitions) engaging 200 targets.
|
||||
|
||||
```json
|
||||
{
|
||||
"timeScale": 1,
|
||||
"interceptor_swarm_configs": [
|
||||
{
|
||||
"num_agents": 10,
|
||||
"agent_config": {
|
||||
"interceptor_type": "HYDRA_70",
|
||||
"initial_state": {
|
||||
"position": { "x": 0, "y": 20, "z": 0 },
|
||||
"rotation": { "x": -45, "y": 0, "z": 0 },
|
||||
"velocity": { "x": 0, "y": 10, "z": 10 }
|
||||
},
|
||||
"dynamic_config": {
|
||||
"launch_config": { "launch_time": 0 },
|
||||
"sensor_config": {
|
||||
"type": "IDEAL",
|
||||
"frequency": 100
|
||||
}
|
||||
},
|
||||
"submunitions_config": {
|
||||
"num_submunitions": 7,
|
||||
"launch_config": { "launch_time": 4 },
|
||||
"agent_config": {
|
||||
"interceptor_type": "MICROMISSILE",
|
||||
// Submunition configuration...
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
// Two more similar interceptor_swarm_configs with different launch times...
|
||||
],
|
||||
"threat_swarm_configs": [
|
||||
{
|
||||
"num_agents": 200,
|
||||
"agent_config": {
|
||||
"threat_type": "DRONE",
|
||||
"initial_state": {
|
||||
"position": { "x": 0, "y": 600, "z": 6000 },
|
||||
"rotation": { "x": 90, "y": 0, "z": 0 },
|
||||
"velocity": { "x": 0, "y": 0, "z": -50 }
|
||||
},
|
||||
// Other threat configurations...
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Key Differences Between the Examples**:
|
||||
|
||||
The key difference between the examples is that the **Number of Salvos** in `3_salvo_10_hydra_200_drones.json` file includes multiple salvos by adding multiple entries in the `interceptor_swarm_configs` array, each with its own `launch_time`.
|
||||
|
||||
**Achieving Multiple Salvos**:
|
||||
|
||||
Multiple salvos are achieved by:
|
||||
|
||||
- Adding multiple configurations in the `interceptor_swarm_configs` array.
|
||||
- Specifying different `launch_time` values in the `dynamic_config` for each salvo to control when they launch.
|
||||
|
||||
### Key Configuration Parameters
|
||||
|
||||
- **`timeScale`**: Adjusts the speed of the simulation.
|
||||
- **`interceptor_swarm_configs`**: Contains settings for interceptor swarms. Each entry represents a salvo.
|
||||
- **`threat_swarm_configs`**: Contains settings for threat swarms.
|
||||
|
||||
#### Within Each Swarm Configuration
|
||||
|
||||
- **`num_agents`**: Number of agents (missiles or targets) in the swarm.
|
||||
- **`agent_config`**: Settings for each agent, including:
|
||||
|
||||
- **`interceptor_type`** / **`threat_type`**: Defines the type of interceptor or threat.
|
||||
- **`initial_state`**: Sets the starting position, rotation, and velocity.
|
||||
- **`standard_deviation`**: Adds random noise to initial states for variability.
|
||||
- **`dynamic_config`**: Time-dependent settings like `launch_time` and sensor configurations.
|
||||
- **`submunitions_config`**: Details for any submunitions (e.g., micromissiles deployed by a larger interceptor).
|
||||
|
||||
### Adding or Modifying Agents
|
||||
|
||||
1. **Add a New Swarm Configuration**:
|
||||
|
||||
To introduce a new interceptor or threat swarm (or an additional salvo), create a new entry in `interceptor_swarm_configs` or `threat_swarm_configs`.
|
||||
|
||||
```json
|
||||
{
|
||||
"num_agents": 5,
|
||||
"agent_config": {
|
||||
"interceptor_type": "MICROMISSILE",
|
||||
// Additional configurations...
|
||||
"dynamic_config": {
|
||||
"launch_config": { "launch_time": 15 },
|
||||
// Other dynamic settings...
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **`launch_time`** in `dynamic_config` controls when this swarm (or salvo) is deployed.
|
||||
|
||||
2. **Modify Existing Configurations**:
|
||||
|
||||
Adjust parameters like `num_agents`, `initial_state`, or `dynamic_config` to change the behavior of existing agents or salvos.
|
||||
|
||||
## Model Configurations
|
||||
|
||||
The model configurations define the physical and performance characteristics of interceptor and threat models. The default models provided can be customized to suit your research needs.
|
||||
|
||||
### Available Models
|
||||
|
||||
The `Models` directory contains the following default model configurations:
|
||||
|
||||
- **`micromissile.json`**
|
||||
- **`hydra70.json`**
|
||||
- **`drone.json`**
|
||||
|
||||
These JSON files serve as templates and can be tweaked to modify the behavior of the corresponding models.
|
||||
|
||||
### Editing Model Configurations
|
||||
|
||||
#### Example: `micromissile.json`
|
||||
|
||||
This file defines parameters for the micromissile model.
|
||||
|
||||
```json:Assets/StreamingAssets/Configs/Models/micromissile.json
|
||||
{
|
||||
"accelerationConfig": {
|
||||
"maxReferenceAcceleration": 300,
|
||||
"referenceSpeed": 1000
|
||||
},
|
||||
"boostConfig": {
|
||||
"boostTime": 0.3,
|
||||
"boostAcceleration": 350
|
||||
},
|
||||
"liftDragConfig": {
|
||||
"liftCoefficient": 0.2,
|
||||
"dragCoefficient": 0.7,
|
||||
"liftDragRatio": 5
|
||||
},
|
||||
// Other configurations...
|
||||
}
|
||||
```
|
||||
|
||||
**Configurable Parameters**:
|
||||
|
||||
- **`accelerationConfig`**: Controls acceleration characteristics.
|
||||
- **`boostConfig`**: Settings for the boost phase of the craft.
|
||||
- **`liftDragConfig`**: Aerodynamic properties.
|
||||
- **`bodyConfig`**: Physical attributes like mass and area.
|
||||
- **`hitConfig`**: Collision detection and damage properties.
|
||||
|
||||
### Modifying Parameters
|
||||
|
||||
You can tweak the parameters in these model files to adjust performance. For example:
|
||||
|
||||
- **Increase Acceleration**: Modify `maxReferenceAcceleration` in `accelerationConfig`.
|
||||
- **Change Mass**: Adjust the `mass` value in `bodyConfig`.
|
||||
- **Alter Aerodynamics**: Tweak `liftCoefficient` and `dragCoefficient` in `liftDragConfig`.
|
||||
|
||||
### Adding New Models
|
||||
|
||||
To define a new inte or threat model:
|
||||
|
||||
1. **Create a New JSON File** in `Assets/StreamingAssets/Configs/Models/`.
|
||||
|
||||
2. **Define Model Parameters** similar to the existing model files.
|
||||
|
||||
3. **Update the Code** to recognize and load the new model if necessary.
|
||||
|
||||
**Note**: Ensure that any new parameters added to the model configuration are reflected in the corresponding C# classes.
|
||||
|
||||
## Relevant C# Scripts
|
||||
|
||||
### `SimulationConfig.cs`
|
||||
|
||||
This script defines the data structures used to interpret the JSON simulation configuration files.
|
||||
|
||||
[Assets/Scripts/Config/SimulationConfig.cs](https://github.com/PisterLab/micromissiles-unity/blob/master/Assets/Scripts/Config/SimulationConfig.cs)
|
||||
|
||||
**Classes**:
|
||||
|
||||
- `SimulationConfig`: Contains all simulation settings.
|
||||
- `SwarmConfig`: Represents a group of agents (missiles or targets).
|
||||
- `AgentConfig`: Configuration for individual agents.
|
||||
|
||||
**Enums**:
|
||||
|
||||
- `InterceptorType`, `ThreatType`, and `SensorType` define available types.
|
||||
|
||||
### `StaticConfig.cs`
|
||||
|
||||
This script defines the classes corresponding to the model configuration JSON structure.
|
||||
|
||||
[Assets/Scripts/Config/StaticConfig.cs](https://github.com/PisterLab/micromissiles-unity/blob/master/Assets/Scripts/Config/StaticConfig.cs)
|
||||
|
||||
For example:
|
||||
```csharp
|
||||
[Serializable]
|
||||
public class StaticConfig {
|
||||
[Serializable]
|
||||
public class AccelerationConfig {
|
||||
public float maxReferenceAcceleration = 300f;
|
||||
public float referenceSpeed = 1000f;
|
||||
}
|
||||
|
||||
[Serializable]
|
||||
public class BoostConfig {
|
||||
public float boostTime = 0.3f;
|
||||
public float boostAcceleration = 350f;
|
||||
}
|
||||
|
||||
[Serializable]
|
||||
public class LiftDragConfig {
|
||||
public float liftCoefficient = 0.2f;
|
||||
public float dragCoefficient = 0.7f;
|
||||
public float liftDragRatio = 5f;
|
||||
}
|
||||
|
||||
// Other configuration classes...
|
||||
|
||||
public AccelerationConfig accelerationConfig;
|
||||
public BoostConfig boostConfig;
|
||||
public LiftDragConfig liftDragConfig;
|
||||
public BodyConfig bodyConfig;
|
||||
public HitConfig hitConfig;
|
||||
}
|
||||
```
|
||||
|
||||
**Updating Classes**:
|
||||
|
||||
If you add new parameters to the JSON model files, ensure the corresponding classes in `StaticConfig.cs` are updated to include these new fields.
|
||||
|
||||
## Using the Deployment Build
|
||||
|
||||
When using the deployment build:
|
||||
|
||||
- **Include Required Configuration Files**: Ensure all necessary JSON configuration files are present in the `StreamingAssets/Configs/` directory.
|
||||
- **Adjust Simulations Without Rebuilding**: Modify the JSON files to change simulation parameters without needing to rebuild the application.
|
||||
|
||||
While the simulation is running, you can load a new Simulation Configuration JSON file at runtime by opening the panel with 'L'.
|
||||
|
||||
---
|
||||
|
||||
**Note**: Always back up configuration files before making significant changes. Incorrect configurations can lead to simulation errors.
|
||||
|
||||
For further assistance, refer to the comments and documentation within the code files:
|
||||
|
||||
- [`SimManager.cs`](https://github.com/PisterLab/micromissiles-unity/blob/master/Assets/Scripts/SimManager.cs): Manages simulation state and agent creation.
|
||||
- [`InputManager.cs`](https://github.com/PisterLab/micromissiles-unity/blob/master/Assets/Scripts/Managers/InputManager.cs): Handles user input and interactions.
|
||||
|
||||
---
|
||||
|
||||
*This guide aims to help you set up and customize the simulation project effectively. If you encounter any issues or have questions, please reach out to the project maintainers.*
|
||||
```
|
||||
259
coverage/playmode/docs/Simulation_Logging.md
Normal file
259
coverage/playmode/docs/Simulation_Logging.md
Normal file
@@ -0,0 +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
|
||||
|
||||
|
||||
|
||||
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 are exported to:
|
||||
|
||||
```
|
||||
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/)
|
||||
BIN
coverage/playmode/docs/images/sim_salvo_animation.gif
Normal file
BIN
coverage/playmode/docs/images/sim_salvo_animation.gif
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 8.1 MiB |
BIN
coverage/playmode/docs/images/sim_visualizer.png
Normal file
BIN
coverage/playmode/docs/images/sim_visualizer.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 254 KiB |
BIN
coverage/playmode/docs/images/unity_hub.png
Normal file
BIN
coverage/playmode/docs/images/unity_hub.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
41
coverage/playmode/docs/index.md
Normal file
41
coverage/playmode/docs/index.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
# https://vitepress.dev/reference/default-theme-home-page
|
||||
layout: home
|
||||
|
||||
hero:
|
||||
name: "micromissiles-unity"
|
||||
|
||||
tagline: "Swarm-on-swarm simulator using micromissiles for point defense"
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Documentation
|
||||
link: /Keybinds_and_Controls
|
||||
- theme: alt
|
||||
text: Development Guide
|
||||
link: /Development_Guide
|
||||
|
||||
---
|
||||
|
||||
# Quick Start
|
||||
|
||||
We generate pre-built standalone binaries for Windows and Mac users from the `release` branch. These binaries are intended for non-development users who just want to run the application and modify a few configurations along the way.
|
||||
|
||||
You can find the latest release [here](https://github.com/PisterLab/micromissiles-unity/releases/latest).
|
||||
|
||||
## Windows
|
||||
|
||||
1. Download the zip file for Windows: `micromissiles-<version>-windows_x86_64.zip`.
|
||||
2. Unzip the zip file. The zip file should contain a single directory called `micromissiles-<version>-windows_x86_64`.
|
||||
3. In the `micromissiles-<version>-windows_x86_64` directory, run `micromissiles-<version>-StandaloneWindows64.exe`.
|
||||
|
||||
## Mac
|
||||
|
||||
1. Download the tarball file for Darwin: `micromissiles-<version>-darwin.tar.gz`.
|
||||
2. Untar the tarball. The tarball should contain a single directory called `micromissiles-<version>-darwin`.
|
||||
3. In the `micromissiles-<version>-darwin` directory, run the app file.
|
||||
|
||||
|
||||
# Next Steps
|
||||
|
||||
- Familiarize yourself with the [**Keybinds and Controls**](Keybinds_and_Controls.md) to navigate and interact with the simulation.
|
||||
- Learn how to configure the simulation settings by reading the [**Simulation Configuration Guide**](Simulation_Config_Guide.md).
|
||||
Reference in New Issue
Block a user