# tier4/awsim architecture

> Architecture diagram of the GitHub repository tier4/awsim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tier4/awsim
- Repository: https://github.com/tier4/awsim

## Overview

This project is a Unity-based simulation environment named AWSIM – a scene simulator built for autonomous driving research and specifically for Autoware. The simulator is designed to emulate realistic scenes by modeling vehicles, sensors (such as LiDAR, cameras, radar, GNSS, and IMUs), environmental aspects, and traffic behavior while maintaining ROS2-native communication with Autoware.

##### Project Type and Purpose
- AWSIM is fundamentally a simulation platform built with Unity. It provides simulation components such as vehicle dynamics, sensor emulation, scenario simulation, and ROS2 integration. The purpose is to create realistic simulated driving environments to test and debug Autoware systems.

##### Main Components Derived from the File Structure & README
- Simulation Engine – Unity: Acts as the core runtime for the entire simulation. The “Assets” folder holds all the simulation prefabs, scenes, models, and scripts.
- Scene Manager and Environments – Under folders like Assets/AWSIM/Scenes, Assets/AWSIM/Prefabs/Environments, and related Editor scripts. These modules manage scene construction and environmental simulation (including random traffic, smoke simulation, and occlusion data).
- Vehicle Modules – Models, Prefabs, and Scripts for vehicles appear under Assets/AWSIM/Models/Vehicles and Assets/AWSIM/Prefabs/NPCs/Vehicles, along with driver input and control modules.
- Sensor Modules – A large portion of the project is dedicated to sensors. There are folders for “Sensors” (both models and prefabs) and extensive scripts under Assets/AWSIM/Scripts/Sensors. These simulate cameras (with distortion and post‐processing effects), LiDARs (with point cloud data output), GNSS, radar, and others. Each sensor is designed to publish data to ROS2 topics.
- ROS2 & Communication Integration – Located in Assets/AWSIM/Scripts/ROS, Assets/Ros2ForUnity, and in the RGLUnityPlugin directories. These components encapsulate the ROS2 nodes, publishers, and utility scripts, providing a bridge between Unity’s simulation environment and Autoware (over ROS2, using native DDS if needed).
- Editor and Utility Tools – Editor scripts for lanelet creation, random traffic configuration, sensor configuration, and scene management for improving workflow in the Unity environment.

##### Relationships & Interactions
- The Unity Engine hosts the simulation scenes where the Environment, Vehicles, and Sensor components are integrated as prefabs and controlled by their respective scripts.
- Sensor modules capture simulation data and then pass it to ROS2 publisher scripts (e.g., in the “ROS” folders), which then communicate with the external Autoware system.
- The Scene Manager orchestrates dynamic aspects such as traffic simulation, environmental effects (smoke, lighting, random traffic patterns), and vehicle control.
- Editor and UI components facilitate configuration and visualization during development (e.g., FollowCamera, UI prefabs, and Editor scripts) and provide tools for scene setup.

##### Architectural Patterns & Design Principles
- Modular and Component-Based Architecture: Each simulation component (Vehicle, Sensor, Environment) is developed as an independent module. Unity’s GameObject and prefab system enforces a clear separation.
- ROS2 Integration Layer: The design implements a publisher/subscriber pattern for ROS2 communication. ROS2 nodes written as Unity scripts publish sensor data and subscribe to control commands.
- Editor Extensions: Custom Unity editor tools for scene and traffic setup indicate an emphasis on ease-of-use and dynamic simulation configuration.
- Utilization of third-party frameworks and plugins (e.g., ZeroMQ, yamldotnet, RGLUnityPlugin) for lower-level functionalities and extended simulation capabilities.

##### Additional Details
- Don’t hesitate to reference some of the existing .drawio files found in the “docs/Introduction” or “docs/Components” directories to maintain consistency with AWSIM’s documented architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    S1["Unity Simulation Engine"]:::simulation

    subgraph "Simulation Core"
        S2["Scene Manager & Environments"]:::simulation
        S3["Vehicle Modules"]:::simulation
        S4["Sensor Modules"]:::simulation
        S5["Editor & Utility Tools"]:::editor
    end

    R1["ROS2 Integration"]:::communication
    E1["Autoware/ROS2 Ecosystem"]:::external

    S1 -->|"hosts"| S2
    S1 -->|"hosts"| S3
    S1 -->|"hosts"| S4
    S1 -->|"hosts"| S5

    S2 -->|"orchestrates"| S3
    S2 -->|"configures"| S4

    S4 -->|"publishesData"| R1

    R1 <-->|"ROS2Comm"| E1
    E1 -->|"controlCommands"| S3

    classDef simulation fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef communication fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef editor fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef external fill:#FFCCCB,stroke:#000,stroke-width:2px;

    click S1 "https://github.com/tier4/awsim/tree/main/Assets/AWSIM"
    click S2 "https://github.com/tier4/awsim/tree/main/Assets/AWSIM/Scenes"
    click S3 "https://github.com/tier4/awsim/tree/main/Assets/AWSIM/Models/Vehicles"
    click S4 "https://github.com/tier4/awsim/tree/main/Assets/AWSIM/Models/Sensors"
    click R1 "https://github.com/tier4/awsim/tree/main/Assets/AWSIM/Scripts/ROS"
    click S5 "https://github.com/tier4/awsim/tree/main/Assets/AWSIM/Scripts/Editor"
```
