# nordstream3/godot-4-ros2-integration architecture

> Architecture diagram of the GitHub repository nordstream3/godot-4-ros2-integration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nordstream3/godot-4-ros2-integration
- Repository: https://github.com/nordstream3/godot-4-ros2-integration

## Overview

##### Project type and purpose
- This is a robotics-simulation integration project that fuses:
- Blender (for 3D asset and scene creation)
- Godot 4.x engine (for real-time simulation and physics)
- ROS2 middleware (for robot control and sensor data exchange)
- It provides a full pipeline: author assets in Blender → run a Godot-based simulation of a 4WS4WD mobile robot → expose sensor data and control interfaces via ROS2 nodes.

##### File structure
- Top-level:
- LICENSE, README.md
- src/
- Under src/:
- Godot_4WS4WD_simulation_game/
– Godot project files (.tscn, .tres, .blend.zip)
– GDScript control and sensor scripts (ros_steering.gd, depth_camera_3d.gd, etc.)
- godot_custom_modules/godot_ros/
– C++ module sources, headers, SCsub build script, plus GDScript demos (cmd_listener.gd, talker.gd, viewport_publisher.gd)
- ros_control/
– inputter.py (a ROS2 publisher for keyboard controls)
- Key patterns:
- Modular extension of Godot via a custom C++ “godot_ros” module
- A separate Godot project containing assets, scenes, and GDScript logic
- ROS2 pub/sub integration embedded in both C++ and GDScript layers
- A helper Python node in ros_control for user input

##### README for additional insights
- Confirms use of Jolt Physics Engine as a Godot addon for accurate physics
- Describes the ROS2 topics in play: robot control subscription and sensor publications (depth camera, downward camera)
- Details build and run steps for:
- Building Godot with the custom module
- Packaging Jolt into the Godot project
- Running the simulation and auxiliary ROS2 tools (inputter.py, rqt_image_view)

- Blender Asset Pipeline
- Godot Engine Core
- Jolt Physics Extension (addon inside Godot)
- Godot-ROS2 Custom Module (C++ + GDScript)
- Godot Simulation Project (4WS4WD game scene + scripts)
- ROS2 Middleware (DDS network, topics/services)
- ROS2 Control Node (inputter.py)
- ROS2 Visualization (rqt_image_view)
1. Blender → Godot Simulation Project (“.blend/.tscn assets imported”)
2. Godot Engine Core + Jolt Physics → Godot Simulation Project (“physics simulation of robot”)
3. Godot Simulation Project → Godot-ROS2 Module (“calls into C++ module for ROS2”)
4. Godot-ROS2 Module ↔ ROS2 Middleware (“publishes / subscribes to topics”)
5. ROS2 Control Node → ROS2 Middleware (“keyboard → /cmd_vel”)
6. ROS2 Middleware → Godot-ROS2 Module → Godot Simulation (“control commands drive robot”)
7. Godot Simulation (Depth Camera) → Godot-ROS2 Module → ROS2 Middleware (“publishes /depth_image”)
c. Architectural patterns & principles:
- Modular plugin architecture (Godot custom module)
- Publisher/subscriber messaging pattern (ROS2 topics)
- Separation of concerns: asset creation, simulation engine, middleware, control & visualization
- Extensibility: additional sensors or control schemes can be added as GDScript or C++ modules
d. Relevant technologies:
- Godot 4.4 engine
- Jolt physics for high-precision simulation
- ROS2 (Humble or later) for middleware
- Blender for asset authoring
- Python ROS2 node for input (inputter.py)
- rqt_image_view for sensor visualization

##### Elements
- Middleware (ROS2, rqt_image_view) in another

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Asset & Scene Preparation Layer
    subgraph "Asset & Scene Preparation"
        direction TB
        BlenderAssets["Blender Asset Pipeline"]:::assettools
        MobileBlend["mobile_robot.blend.zip"]:::assettools
        WarehouseBlend["warehouse.blend.zip"]:::assettools
    end

    %% Simulation Engine Layer
    subgraph "Simulation Engine Layer"
        direction TB
        GodotEngine["Godot Engine Core"]:::engine
        JoltPhysics["Jolt Physics Extension"]:::physics
        GodotROSModule["Godot-ROS2 Custom Module"]:::module
        SimulationProject["Godot Simulation Project (4WS4WD)"]:::simproject
    end

    %% ROS2 Layer
    subgraph "ROS2 Layer"
        direction TB
        ROS2Control["ROS2 Control Node\n(inputter.py)"]:::control
        ROS2Middleware["ROS2 Middleware\n(DDS, Topics)"]:::middleware
        RQT["rqt_image_view"]:::visualization
    end

    %% Relationships
    MobileBlend -->|import .blend| SimulationProject
    WarehouseBlend -->|import .blend| SimulationProject
    BlenderAssets --> MobileBlend
    BlenderAssets --> WarehouseBlend

    GodotEngine -->|runtime physics| SimulationProject
    JoltPhysics -->|runtime physics| SimulationProject

    SimulationProject -->|calls into C++ module| GodotROSModule
    GodotROSModule -->|build-time dependency| GodotEngine
    GodotROSModule -.->|build-time dependency| JoltPhysics

    ROS2Control -->|/cmd_vel| ROS2Middleware
    ROS2Middleware -->|control topics| GodotROSModule
    GodotROSModule -->|drives robot| SimulationProject

    SimulationProject -->|sensor data| GodotROSModule
    GodotROSModule -->|/depth_image| ROS2Middleware

    ROS2Middleware -->|visualize feed| RQT

    %% Click Events
    click MobileBlend "https://github.com/nordstream3/godot-4-ros2-integration/blob/main/src/Godot_4WS4WD_simulation_game/mobile_robot.blend.zip"
    click WarehouseBlend "https://github.com/nordstream3/godot-4-ros2-integration/blob/main/src/Godot_4WS4WD_simulation_game/warehouse.blend.zip"
    click GodotEngine "https://github.com/nordstream3/godot-4-ros2-integration/blob/main/src/Godot_4WS4WD_simulation_game/project.godot"
    click JoltPhysics "https://github.com/nordstream3/godot-4-ros2-integration/blob/main/src/Godot_4WS4WD_simulation_game/depth_filter.gdshader"
    click SimulationProject "https://github.com/nordstream3/godot-4-ros2-integration/tree/main/src/Godot_4WS4WD_simulation_game/"
    click GodotROSModule "https://github.com/nordstream3/godot-4-ros2-integration/tree/main/src/godot_custom_modules/godot_ros/"
    click ROS2Control "https://github.com/nordstream3/godot-4-ros2-integration/blob/main/src/ros_control/inputter.py"

    %% Styles
    classDef assettools fill:#FFE599,stroke:#D6B656,stroke-width:2px
    classDef engine fill:#8FAADC,stroke:#3D5A80,stroke-width:2px
    classDef physics fill:#A2D5AB,stroke:#2F855A,stroke-width:2px
    classDef module fill:#F4A261,stroke:#9C6644,stroke-width:2px
    classDef simproject fill:#B4B4B4,stroke:#555555,stroke-width:2px
    classDef middleware fill:#E07A5F,stroke:#8E4A33,stroke-width:2px
    classDef control fill:#81B29A,stroke:#2F6250,stroke-width:2px
    classDef visualization fill:#F2CC8F,stroke:#B08900,stroke-width:2px
```
