Box2d 3.1.1 migration

.devcontainer/Dockerfile

@@ -2,14 +2,17 @@ ARG ROS_DISTRO=humble
 FROM ros:${ROS_DISTRO}
 
 ARG DEBIAN_FRONTEND=noninteractive
+ARG USERNAME=flatland
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     bash-completion \
     ccache \
     gdb \
     git \
+    openssh-client \
     python3-colcon-common-extensions \
     python3-rosdep \
+    sudo \
     && rm -rf /var/lib/apt/lists/*
 
 COPY . /tmp/flatland
@@ -19,4 +22,20 @@ RUN rosdep update && \
     rm -rf /tmp/flatland /var/lib/apt/lists/*
 
 ENV CCACHE_DIR=/tmp/.ccache
-WORKDIR /opt/overlay_ws
+ENV QT_QPA_PLATFORM=xcb
+WORKDIR /opt/overlay_ws
+RUN if id -u ubuntu >/dev/null 2>&1; then \
+        if [ "$USERNAME" != ubuntu ]; then \
+            usermod -l "$USERNAME" -d "/home/$USERNAME" -m ubuntu && \
+            groupmod -n "$USERNAME" ubuntu; \
+        fi; \
+    else \
+        groupadd -g 1000 "$USERNAME" && \
+        useradd -m -u 1000 -g "$USERNAME" -s /bin/bash "$USERNAME"; \
+    fi && \
+    usermod -aG sudo "$USERNAME" && \
+    printf '%s ALL=(ALL) NOPASSWD:ALL\n' "$USERNAME" > /etc/sudoers.d/flatland && \
+    chmod 0440 /etc/sudoers.d/flatland && \
+    mkdir -p /opt/overlay_ws/src /tmp/.ccache && \
+    chown -R "$USERNAME:$USERNAME" /opt/overlay_ws /tmp/.ccache
+USER ${USERNAME}

.devcontainer/humble/devcontainer.json

@@ -3,9 +3,18 @@
     "build": {
         "dockerfile": "../Dockerfile",
         "context": "../..",
-        "args": { "ROS_DISTRO": "humble" }
+        "args": { "ROS_DISTRO": "humble", "USERNAME": "${localEnv:USER:flatland}" }
     },
-    "runArgs": ["--init"],
+    "remoteUser": "${localEnv:USER:flatland}",
+    "updateRemoteUserUID": true,
+    "runArgs": [
+        "--init",
+        "--privileged",
+        "--volume=/dev:/dev",
+        "--volume=/tmp/.X11-unix:/tmp/.X11-unix",
+        "--env=DISPLAY=${localEnv:DISPLAY}",
+        "--env=QT_X11_NO_MITSHM=1"
+    ],
     "workspaceFolder": "/opt/overlay_ws/src/flatland",
     "workspaceMount": "source=${localWorkspaceFolder},target=${containerWorkspaceFolder},type=bind",
     "mounts": [
@@ -14,7 +23,6 @@
     ],
     "remoteEnv": { "CCACHE_DIR": "/tmp/.ccache" },
     "onCreateCommand": "bash .devcontainer/on-create-command.sh",
-    "updateContentCommand": "bash .devcontainer/update-content-command.sh",
     "postCreateCommand": "bash .devcontainer/post-create-command.sh",
     "customizations": {
         "vscode": {

.devcontainer/jazzy/devcontainer.json

@@ -3,9 +3,18 @@
     "build": {
         "dockerfile": "../Dockerfile",
         "context": "../..",
-        "args": { "ROS_DISTRO": "jazzy" }
+        "args": { "ROS_DISTRO": "jazzy", "USERNAME": "${localEnv:USER:flatland}" }
     },
-    "runArgs": ["--init"],
+    "remoteUser": "${localEnv:USER:flatland}",
+    "updateRemoteUserUID": true,
+    "runArgs": [
+        "--init",
+        "--privileged",
+        "--volume=/dev:/dev",
+        "--volume=/tmp/.X11-unix:/tmp/.X11-unix",
+        "--env=DISPLAY=${localEnv:DISPLAY}",
+        "--env=QT_X11_NO_MITSHM=1"
+    ],
     "workspaceFolder": "/opt/overlay_ws/src/flatland",
     "workspaceMount": "source=${localWorkspaceFolder},target=${containerWorkspaceFolder},type=bind",
     "mounts": [
@@ -14,7 +23,6 @@
     ],
     "remoteEnv": { "CCACHE_DIR": "/tmp/.ccache" },
     "onCreateCommand": "bash .devcontainer/on-create-command.sh",
-    "updateContentCommand": "bash .devcontainer/update-content-command.sh",
     "postCreateCommand": "bash .devcontainer/post-create-command.sh",
     "customizations": {
         "vscode": {

.devcontainer/kilted/devcontainer.json

@@ -3,9 +3,18 @@
     "build": {
         "dockerfile": "../Dockerfile",
         "context": "../..",
-        "args": { "ROS_DISTRO": "kilted" }
+        "args": { "ROS_DISTRO": "kilted", "USERNAME": "${localEnv:USER:flatland}" }
     },
-    "runArgs": ["--init"],
+    "remoteUser": "${localEnv:USER:flatland}",
+    "updateRemoteUserUID": true,
+    "runArgs": [
+        "--init",
+        "--privileged",
+        "--volume=/dev:/dev",
+        "--volume=/tmp/.X11-unix:/tmp/.X11-unix",
+        "--env=DISPLAY=${localEnv:DISPLAY}",
+        "--env=QT_X11_NO_MITSHM=1"
+    ],
     "workspaceFolder": "/opt/overlay_ws/src/flatland",
     "workspaceMount": "source=${localWorkspaceFolder},target=${containerWorkspaceFolder},type=bind",
     "mounts": [
@@ -14,7 +23,6 @@
     ],
     "remoteEnv": { "CCACHE_DIR": "/tmp/.ccache" },
     "onCreateCommand": "bash .devcontainer/on-create-command.sh",
-    "updateContentCommand": "bash .devcontainer/update-content-command.sh",
     "postCreateCommand": "bash .devcontainer/post-create-command.sh",
     "customizations": {
         "vscode": {

.devcontainer/lyrical/devcontainer.json

@@ -3,9 +3,18 @@
     "build": {
         "dockerfile": "../Dockerfile",
         "context": "../..",
-        "args": { "ROS_DISTRO": "lyrical" }
+        "args": { "ROS_DISTRO": "lyrical", "USERNAME": "${localEnv:USER:flatland}" }
     },
-    "runArgs": ["--init"],
+    "remoteUser": "${localEnv:USER:flatland}",
+    "updateRemoteUserUID": true,
+    "runArgs": [
+        "--init",
+        "--privileged",
+        "--volume=/dev:/dev",
+        "--volume=/tmp/.X11-unix:/tmp/.X11-unix",
+        "--env=DISPLAY=${localEnv:DISPLAY}",
+        "--env=QT_X11_NO_MITSHM=1"
+    ],
     "workspaceFolder": "/opt/overlay_ws/src/flatland",
     "workspaceMount": "source=${localWorkspaceFolder},target=${containerWorkspaceFolder},type=bind",
     "mounts": [
@@ -14,7 +23,6 @@
     ],
     "remoteEnv": { "CCACHE_DIR": "/tmp/.ccache" },
     "onCreateCommand": "bash .devcontainer/on-create-command.sh",
-    "updateContentCommand": "bash .devcontainer/update-content-command.sh",
     "postCreateCommand": "bash .devcontainer/post-create-command.sh",
     "customizations": {
         "vscode": {

.devcontainer/on-create-command.sh

@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-mkdir -p /opt/overlay_ws/src /tmp/.ccache
+sudo mkdir -p /opt/overlay_ws/{src,build,install,log} /tmp/.ccache
+sudo chown "$(id -u):$(id -g)" /opt/overlay_ws /opt/overlay_ws/src
+sudo chown -R "$(id -u):$(id -g)" /opt/overlay_ws/{build,install,log} /tmp/.ccache
 git config --global --add safe.directory /opt/overlay_ws/src/flatland

.devcontainer/post-create-command.sh

@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-setup_line='source /opt/overlay_ws/install/setup.bash'
+setup_line='if [ -f /opt/overlay_ws/install/setup.bash ]; then source /opt/overlay_ws/install/setup.bash; else for setup_file in /opt/ros/*/setup.bash; do if [ -f "$setup_file" ]; then source "$setup_file"; break; fi; done; fi'
+if grep -Fxq 'source /opt/overlay_ws/install/setup.bash' "$HOME/.bashrc"; then
+    sed -i '\|^source /opt/overlay_ws/install/setup.bash$|d' "$HOME/.bashrc"
+fi
 if ! grep -Fxq "$setup_line" "$HOME/.bashrc"; then
     printf '\n%s\n' "$setup_line" >> "$HOME/.bashrc"
 fi

.devcontainer/rolling/devcontainer.json

@@ -3,9 +3,18 @@
     "build": {
         "dockerfile": "../Dockerfile",
         "context": "../..",
-        "args": { "ROS_DISTRO": "rolling" }
+        "args": { "ROS_DISTRO": "rolling", "USERNAME": "${localEnv:USER:flatland}" }
     },
-    "runArgs": ["--init"],
+    "remoteUser": "${localEnv:USER:flatland}",
+    "updateRemoteUserUID": true,
+    "runArgs": [
+        "--init",
+        "--privileged",
+        "--volume=/dev:/dev",
+        "--volume=/tmp/.X11-unix:/tmp/.X11-unix",
+        "--env=DISPLAY=${localEnv:DISPLAY}",
+        "--env=QT_X11_NO_MITSHM=1"
+    ],
     "workspaceFolder": "/opt/overlay_ws/src/flatland",
     "workspaceMount": "source=${localWorkspaceFolder},target=${containerWorkspaceFolder},type=bind",
     "mounts": [
@@ -14,7 +23,6 @@
     ],
     "remoteEnv": { "CCACHE_DIR": "/tmp/.ccache" },
     "onCreateCommand": "bash .devcontainer/on-create-command.sh",
-    "updateContentCommand": "bash .devcontainer/update-content-command.sh",
     "postCreateCommand": "bash .devcontainer/post-create-command.sh",
     "customizations": {
         "vscode": {

.github/workflows/industrial_ci_action.yml

@@ -6,16 +6,21 @@ on:
       - main
   pull_request:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   industrial_ci:
+    name: ROS ${{ matrix.env.ROS_DISTRO }}
     strategy:
       matrix:
         env:
-          - {ROS_DISTRO: humble, ROS_REPO: main, AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS: true}
+          - {ROS_DISTRO: humble, ROS_REPO: main, DOCKER_IMAGE: 'osrf/ros:humble-desktop-full', AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS: true}
           # - {ROS_DISTRO: jazzy, ROS_REPO: main, AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS: true}
           # - {ROS_DISTRO: kilted, ROS_REPO: main, AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS: true, TARGET_CMAKE_ARGS: '-DCMAKE_COMPILE_WARNING_AS_ERROR=ON'}
-          - {ROS_DISTRO: lyrical, ROS_REPO: main, AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS: true, TARGET_CMAKE_ARGS: '-DCMAKE_COMPILE_WARNING_AS_ERROR=ON'}
-          - {ROS_DISTRO: rolling, ROS_REPO: main, OS_CODE_NAME: noble, AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS: true, TARGET_CMAKE_ARGS: '-DCMAKE_COMPILE_WARNING_AS_ERROR=ON'}
+          - {ROS_DISTRO: lyrical, ROS_REPO: main, DOCKER_IMAGE: 'osrf/ros:lyrical-desktop-full', AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS: true, TARGET_CMAKE_ARGS: '-DCMAKE_COMPILE_WARNING_AS_ERROR=ON'}
+          - {ROS_DISTRO: rolling, ROS_REPO: main, OS_CODE_NAME: noble, DOCKER_IMAGE: 'osrf/ros:rolling-desktop-full-noble', AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS: true, TARGET_CMAKE_ARGS: '-DCMAKE_COMPILE_WARNING_AS_ERROR=ON'}
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4

.gitignore

@@ -1,4 +1,7 @@
 lcov.info
+/build/
+/install/
+/log/
 docs/doxygen/*
 !docs/doxygen/conf.py
 !docs/doxygen/index.rst
@@ -10,3 +13,6 @@ docs/_templates/*
 */.history
 **/.idea/
 **/cmake-build-debug/
+core
+core.*
+__pycache__/

docs/core_functions/model_plugins.rst

@@ -51,11 +51,11 @@ However, we recommend throwing exceptions from flatland_server/exceptions.h.
     // in the contact, or false otherwise. If true, entity returns the pointer
     // to the entity that collided with the model, this_fixture returns the
     // fixture in the model, other_fixture returns the fixture in the entity
-    bool FilterContact(b2Contact *contact, Entity *&entity,
-                       b2Fixture *&this_fixture, b2Fixture *&other_fixture);
+    bool FilterContact(flatland::b2Contact *contact, Entity *&entity,
+                       flatland::b2Fixture *&this_fixture, flatland::b2Fixture *&other_fixture);
 
     // simplified version that just return true / false
-    bool FilterContact(b2Contact *contact);
+    bool FilterContact(flatland::b2Contact *contact);
 
 
     // Box2D collision callbacks use the FilterContact method to check if the this 
@@ -65,18 +65,35 @@ However, we recommend throwing exceptions from flatland_server/exceptions.h.
     // time is always equal to the time at BeforePhysicsStep().
 
     // Called when two fixtures starts to contact
-    virtual void BeginContact(b2Contact *contact) {}  // time t
+    virtual void BeginContact(flatland::b2Contact *contact) {}  // time t
 
     // called when two fixtures stops contact
-    virtual void EndContact(b2Contact *contact) {}  // time t
+    virtual void EndContact(flatland::b2Contact *contact) {}  // time t
 
-    // called before solving collision, may be called multiple times in a time step
-    virtual void PreSolve(b2Contact *contact, const b2Manifold *oldManifold) {}  // time t
-
-    // called after solving collision, may be called multiple times in a time step
-    virtual void PostSolve(b2Contact *contact, const b2ContactImpulse *impulse) {}  // time t
+    // called once per touching solid contact after the physics step
+    virtual void PostSolve(flatland::b2Contact *contact,
+                 const flatland::b2ContactImpulse *impulse) {}  // time t
   }
 
+Box2D 3.1 Version Compatibility Notes
+------------------------------------
+
+The ``PreSolve`` plugin hook has been removed. Flatland's Box2D 3.1 adapter
+receives contact data after the solver completes, so a callback at that point
+cannot modify the current step's collision response and would misleadingly be
+named pre-solve. Use ``PostSolve`` to observe touching solid contacts instead.
+Plugins that used ``PreSolve`` to change collision behavior need a different
+approach; Flatland does not expose Box2D 3.1's native pre-solve callback.
+
+In Box2D 3.1, begin/end contact and sensor events are collected during a step
+and dispatched between ``BeforePhysicsStep`` and ``AfterPhysicsStep``. The
+simulation clock still reads ``t`` until the callbacks finish. Contact impulse
+values can also differ because the new solver uses substeps instead of separate
+velocity and position iterations. Legacy fixture and contact pointers are
+provided by Flatland's compatibility API, not by the Box2D 3.1 C API.
+Compatibility types live in the ``flatland`` namespace; native Box2D C types
+remain global and can be included alongside them.
+
 Box2D contact object is generated when two Box2D fixtures collide, it contains
 all the information about the collision. Box2D fixtures are the underlying physics 
 implementation of footprints in the simulation. From b2Contacts, you can obtain
@@ -173,7 +190,7 @@ constant x, y and yaw rates. This will reside in a package called my_plugins.
     }
 
     void ConstVelocity::BeforePhysicsStep(const flatland_server::Timekeeper &timekeeper) {
-      body->GetPhysicsBody()->SetLinearVelocity(b2Vec2(vel_x, vel_y));
+      body->GetPhysicsBody()->SetLinearVelocity(flatland::b2Vec2(vel_x, vel_y));
       body->GetPhysicsBody()->SetAngularVelocity(omega);
     }
 

docs/core_functions/models.rst

@@ -135,6 +135,10 @@ shown here. Examples can be found in flatland_server/tests.
       # rotate 360 degrees otherwise, applies only to revolute joints
       limits: [0, 0]
 
+      # Box2D 3.1 enforces limits only within about +/-3.11 radians. Wider
+      # configured values are clamped to the supported range. Joint limit
+      # getters report the effective limits, not the original YAML values.
+
       # required, specifies the anchor point on each body, applies to all joint
       # types
       bodies:

docs/core_functions/world.rst

@@ -9,19 +9,21 @@ Configuring World
 The simulation world is defined by a YAML file as shown below. Examples can
 be found in flatland_server/tests.
 
+``substeps`` controls the solver's internal divisions of each physics step.
+``step_size`` remains a separate ROS launch parameter controlling simulated
+seconds per update; see :doc:`ros_launch`. Existing worlds may still specify
+``velocity_iterations`` and ``position_iterations``. Those deprecated keys
+produce a warning, and if ``substeps`` is absent the larger legacy value is
+used as the substep count (default 10). This fallback does not reproduce the
+old solver's behavior exactly.
+
 .. code-block:: yaml
 
   # required, world properties
   properties:
 
-    # optional, defaults to 10, number of velocity iterations for the Box2D 
-    # physics solver
-    velocity_iterations: 10
-
-    # optional, defaults to 10, number of position iterations for the Box2D 
-    # physics solver
-    position_iterations: 10
-
+    # optional, Box2D 3.1 solver substeps (defaults to 10)
+    substeps: 4
 
 
   # required, specifies a list of layers, maximum number of layers is 16,