feat: xquartz forwarding

.devcontainer/devcontainer.json

@@ -1,49 +1,44 @@
 {
-    "dockerComposeFile": ["../docker/docker-compose.yml", "../docker/docker-compose-dev.yml"],
+    "name": "simulations",
+    "dockerComposeFile": "../docker/docker-compose.yml",
     "service": "sim",
     "runServices": ["sim"],
 
     "workspaceFolder": "/home/trickfire/simulations",
     "remoteEnv": {
         "HOST_WORKSPACE": "${localWorkspaceFolder}"
     },
+    "initializeCommand": "bash .devcontainer/host-env.sh || true",
     "postCreateCommand": "pip3 install --break-system-packages -e .", // install the sim cli
     "postStartCommand": "bash ./.devcontainer/x_server.sh || true",
 
     "customizations": {
         "vscode": {
             "settings": {
+                "workbench.activityBar.location": "default",
                 "shfmt.executablePath": "/usr/local/bin/shfmt"
             },
             "extensions": [
-                // --- Python ---
                 "ms-python.python",
                 "ms-python.vscode-pylance",
                 "charliermarsh.ruff",
                 "ms-python.mypy-type-checker",
-
-                // --- C and C++ ---
                 "ms-vscode.cmake-tools",
                 "josetr.cmake-language-support-vscode",
                 "llvm-vs-code-extensions.vscode-clangd",
                 "ms-vscode.makefile-tools",
-
-                // --- Robotics / ROS / URDF / meshes ---
                 "Ranch-Hand-Robotics.rde-ros-2",
                 "smilerobotics.urdf",
                 "morningfrog.urdf-visualizer",
                 "misiekhardcore.stl-previewer",
-
-                // --- Container ---
                 "ms-azuretools.vscode-docker",
-
-                // --- Formatters ---
                 "esbenp.prettier-vscode",
                 "yzhang.markdown-all-in-one",
                 "DotJoshJohnson.xml",
                 "tamasfe.even-better-toml",
                 "github.vscode-github-actions",
-                "mkhl.shfmt"
+                "mkhl.shfmt",
+                "unifiedjs.vscode-mdx"
             ]
         }
     }

.devcontainer/host-env.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -eu
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+docker_dir="$(cd "$script_dir/../docker" && pwd)"
+
+defaults="$docker_dir/.env.defaults"
+overrides="$docker_dir/.env.local"
+env_out="$docker_dir/.env"
+
+uname_s="$(uname -s 2>/dev/null || echo unknown)"
+
+log() { printf "\033[1;36m%s\033[0m\n" "$1"; }
+
+gpu_available() {
+    [ "$uname_s" = "Linux" ] || return 1
+    command -v nvidia-smi >/dev/null 2>&1 || return 1
+    nvidia-smi -L >/dev/null 2>&1 || return 1
+    docker info --format '{{json .Runtimes}}' 2>/dev/null | grep -q '"nvidia"' || return 1
+}
+
+gpu_runtime=""
+gpu_available && gpu_runtime="nvidia"
+
+write_display_env() {
+    case "$uname_s" in
+    Darwin)
+        echo "# host: macOS (XQuartz over TCP + VirtualGL)"
+        echo "DISPLAY=host.docker.internal:0"
+        echo "VGL_DISPLAY=:88"
+        echo "VGL_COMPRESS=proxy"
+        ;;
+    MINGW* | MSYS* | CYGWIN*)
+        echo "# host: Windows (VcXsrv/X410 over TCP + VirtualGL)"
+        echo "DISPLAY=host.docker.internal:0"
+        echo "VGL_DISPLAY=:88"
+        echo "VGL_COMPRESS=proxy"
+        ;;
+    Linux)
+        echo "# host: Linux/WSLg (direct socket passthrough)"
+        echo "DISPLAY=${DISPLAY:-:0}"
+        ;;
+    *)
+        echo "# host: unknown ($uname_s) - falling back to local display :0"
+        echo "DISPLAY=${DISPLAY:-:0}"
+        ;;
+    esac
+}
+
+write_env() {
+    echo "# generated by .devcontainer/host-env.sh - do not edit or commit"
+    echo "# to change ports/flags, edit docker/.env.defaults (shared) or docker/.env.local (yours)"
+    echo ""
+
+    cat "$defaults"
+
+    if [ -f "$overrides" ]; then
+        echo ""
+        echo "# --- user overrides (docker/.env.local) ---"
+        cat "$overrides"
+    fi
+
+    echo ""
+    echo "# --- host-detected (generated, do not edit) ---"
+    write_display_env
+    echo "SIM_GPU_RUNTIME=$gpu_runtime"
+
+    if [ -n "$gpu_runtime" ]; then
+        echo "NVIDIA_VISIBLE_DEVICES=all"
+        echo "NVIDIA_DRIVER_CAPABILITIES=graphics,display,compute,utility"
+        echo "__EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/10_nvidia.json"
+    fi
+}
+
+write_env >"$env_out"
+
+echo "[INFO] host=$uname_s gpu=${gpu_runtime:-none}"

.devcontainer/x_server.sh

@@ -1,10 +1,6 @@
 #!/usr/bin/env bash
-
-# --------------------------------------------------------------------------------------------
-# Starts a headless X11 desktop (Xorg/Xvfb + Openbox + x11vnc + noVNC) inside the container.
-# Intended for running GUI apps (Gazebo) in Docker.
-# Supports --verbose flag for debugging (prints all output to console instead of log file).
-# --------------------------------------------------------------------------------------------
+# Sets up the container's display: Wayland/X11 passthrough when available, otherwise a
+# headless Xorg/Xvfb + Openbox + x11vnc + noVNC stack. See docs/setup/docker.mdx.
 
 set -eo pipefail
 trap '' HUP
@@ -57,19 +53,62 @@ parse_args() {
     done
 }
 
-try_wayland_passthrough() {
+start_vgl_3d_server() {
+    if [[ $DISPLAY == :* ]]; then
+        return 0
+    fi
+
+    if ! command -v vglrun >/dev/null 2>&1; then
+        log "[VGL] vglrun not found - skipping (Gazebo/RViz will not be able to render)"
+        return 0
+    fi
+
+    local vgl_display="${VGL_DISPLAY:-:88}"
+    if xdpyinfo -display "$vgl_display" &>/dev/null; then
+        log "[VGL] 3D X server already running on $vgl_display"
+        return 0
+    fi
+
+    log "[VGL] Starting VirtualGL 3D X server (Xvfb) on $vgl_display"
+    Xvfb "$vgl_display" -screen 0 2560x1440x24 >>"$LOG_FILE" 2>&1 &
+    local vgl_pid=$!
+    disown "$vgl_pid" 2>/dev/null || true
+
+    # Xvfb takes a moment to start listening; without this the first `sim gazebo` after a
+    # container start could race it and silently fall back to unaccelerated rendering.
+    local i
+    for i in $(seq 1 20); do
+        if xdpyinfo -display "$vgl_display" &>/dev/null; then
+            log "[VGL] 3D X server ready on $vgl_display"
+            return 0
+        fi
+        sleep 0.25
+    done
+
+    log "[VGL] WARNING: 3D X server on $vgl_display did not come up - see $LOG_FILE"
+}
+
+try_display_passthrough() {
     if [ -n "$FORCE_VNC" ]; then
         DISPLAY="${FORCE_VNC_DISPLAY:-:77}"
         unset WAYLAND_DISPLAY
         log "[X11] FORCE_VNC set. Forcing virtual display $DISPLAY + VNC/noVNC"
         return
     fi
 
+    # Case 1: Linux host with a Wayland compositor, or WSL2 with WSLg. The host socket is
+    # bind-mounted into /run/host-runtime by docker-compose.yml.
     local wayland_sock="/run/host-runtime/${WAYLAND_DISPLAY:-wayland-0}"
     if [ -S "$wayland_sock" ]; then
         log "[X11] Using Wayland socket at $wayland_sock"
         exit 0
     fi
+
+    if [ -n "$DISPLAY" ] && xdpyinfo -display "$DISPLAY" &>/dev/null; then
+        log "[X11] Using host X11 display at $DISPLAY"
+        start_vgl_3d_server
+        exit 0
+    fi
 }
 
 detect_backend() {
@@ -158,7 +197,12 @@ start_services() {
 
 main() {
     parse_args "$@"
-    try_wayland_passthrough
+    try_display_passthrough
+
+    if [[ $DISPLAY != :* ]]; then
+        log "[X11] $DISPLAY unreachable; falling back to internal Xvfb/Xorg on :0"
+        DISPLAY=":0"
+    fi
 
     detect_backend
     parse_screen_resolution
@@ -167,11 +211,6 @@ main() {
     : "${VNC_PORT:?VNC_PORT is not set}"
     : "${NOVNC_PORT:?NOVNC_PORT is not set}"
 
-    if xdpyinfo -display "$DISPLAY" &>/dev/null; then
-        log "[ERROR] Display $DISPLAY is already in use!"
-        exit 1
-    fi
-
     start_services
 }
 

.gitignore

@@ -7,22 +7,19 @@
 !.vscode/launch.json
 !.vscode/extensions.json
 
-# pixi
-.pixi/
-
-# Python
+# python
 .mypy_cache
 __pycache__
 *.egg-info/
 build/
 **/.venv
 
-# ROS2
+# ros
 gazebo/install
 gazebo/build
 gazebo/log
 
-# sim create tests
+# sim tests
 cli/gazebo/create/tests
 
 # chrono outputs
@@ -31,9 +28,8 @@ chrono/results/*
 
 # env
 **/*.env
-!docker/.env
+docker/.env
+docker/.env.local
 
 # trickfire-docs
-.trickfire-docs/
 dist/
-.cache/

.vscode/settings.json

@@ -29,6 +29,10 @@
         "editor.formatOnSave": true,
         "editor.formatOnPaste": true
     },
+    "[mdx]": {
+        "editor.wordWrap": "on",
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
     "[json]": {
         "editor.defaultFormatter": "esbenp.prettier-vscode",
         "editor.formatOnSave": true,
@@ -74,6 +78,5 @@
         "${workspaceFolder}/gazebo/sim_common"
     ],
     "ROS2.distro": "jazzy",
-    "cmake.ignoreCMakeListsMissing": true,
-    "autoDevcontainer.enabled": true
+    "cmake.ignoreCMakeListsMissing": true
 }

README.md

@@ -6,8 +6,8 @@ Robot simulations for TrickFire Robotics - Gazebo Harmonic (ROS 2 Jazzy) for rob
 
 **Full documentation is at [docs.trickfirerobotics.com/simulations](https://docs.trickfirerobotics.com/simulations)**
 
-- [Getting Started](https://docs.trickfirerobotics.com/simulations/getting-started) - native setup, Dev Container alternative, first launch
+- [Getting Started](https://docs.trickfirerobotics.com/simulations) - native setup, Dev Container alternative, first launch
 - [Running Gazebo](https://docs.trickfirerobotics.com/simulations/gazebo/gazebo) - `sim gazebo` CLI usage and flags
 - [Running Chrono](https://docs.trickfirerobotics.com/simulations/chrono/chrono) - `sim chrono` CLI usage
 - [Adding a New Robot](https://docs.trickfirerobotics.com/simulations/gazebo/adding-robots) - OnShape to Gazebo with `sim gazebo create`
-- [Environment](https://docs.trickfirerobotics.com/simulations/reference/docker-environment) - Docker environment in depth
+- [Dev Notes](https://docs.trickfirerobotics.com/simulations/dev-notes) - architecture decisions, Docker environment internals, CLI tips

chrono/data/vsg/imgui.ini

@@ -9,4 +9,5 @@ Size=531,121
 [Window][Simulation]
 Pos=5,5
 Size=238,362
+Collapsed=1