From cc2d78bf16760f81fa455a330b47685a4487cf6a Mon Sep 17 00:00:00 2001
From: Jonathan Embley-Riches <jonathanembleyriches@outlook.com>
Date: Wed, 22 Apr 2026 22:50:25 +0100
Subject: [PATCH] Add per-articulation SimOptions priority and conflict
 resolver

---
 .../Private/MuJoCo/Core/MjArticulation.cpp    |   5 +-
 .../Private/MuJoCo/Core/MjPhysicsEngine.cpp   |  21 +
 .../Private/MuJoCo/Core/MjSimOptions.cpp      | 391 +++++++++++++++++-
 .../URLab/Public/MuJoCo/Core/MjArticulation.h |   6 +
 .../URLab/Public/MuJoCo/Core/MjSimOptions.h   |   9 +
 Source/URLab/URLab.Build.cs                   |   3 +-
 .../Tests/MjSimOptionsResolverTests.cpp       | 293 +++++++++++++
 docs/getting_started.md                       |   6 +
 docs/guides/sim_options_priority.md           | 160 +++++++
 docs/index.md                                 |   1 +
 mkdocs.yml                                    |   1 +
 11 files changed, 891 insertions(+), 5 deletions(-)
 create mode 100644 Source/URLabEditor/Private/Tests/MjSimOptionsResolverTests.cpp
 create mode 100644 docs/guides/sim_options_priority.md

diff --git a/Source/URLab/Private/MuJoCo/Core/MjArticulation.cpp b/Source/URLab/Private/MuJoCo/Core/MjArticulation.cpp
index 2a0865f..d296198 100644
--- a/Source/URLab/Private/MuJoCo/Core/MjArticulation.cpp
+++ b/Source/URLab/Private/MuJoCo/Core/MjArticulation.cpp
@@ -246,9 +246,8 @@ void AMjArticulation::Setup(mjSpec* Spec, mjVFS* VFS)
     m_ChildSpec = mj_makeSpec();
     m_ChildSpec->compiler.degree = false;
 
-    // Apply this articulation's simulation options to the child spec.
-    // mjs_attach will merge these into the root spec at compile time.
-    SimOptions.ApplyToSpec(m_ChildSpec);
+    // SimOptions get folded into the parent spec by FMuJoCoOptions::Resolve;
+    // writing to m_ChildSpec here would be discarded by mjs_attach.
 
     m_prefix = GetName() + TEXT("_");
     
diff --git a/Source/URLab/Private/MuJoCo/Core/MjPhysicsEngine.cpp b/Source/URLab/Private/MuJoCo/Core/MjPhysicsEngine.cpp
index a639ed6..6f18369 100644
--- a/Source/URLab/Private/MuJoCo/Core/MjPhysicsEngine.cpp
+++ b/Source/URLab/Private/MuJoCo/Core/MjPhysicsEngine.cpp
@@ -172,6 +172,27 @@ void UMjPhysicsEngine::PreCompile()
             m_heightfieldActors.Add(HFA);
         }
     }
+
+    // mjs_attach above drops each articulation's <option> block; fold the
+    // per-articulation SimOptions back into m_spec before mj_compile.
+    {
+        TArray<const FMuJoCoOptions*> OptionList;
+        TArray<int32>                 PriorityList;
+        TArray<FString>               NameList;
+        OptionList.Reserve(m_articulations.Num());
+        PriorityList.Reserve(m_articulations.Num());
+        NameList.Reserve(m_articulations.Num());
+
+        for (AMjArticulation* Art : m_articulations)
+        {
+            if (!Art) continue;
+            OptionList.Add(&Art->SimOptions);
+            PriorityList.Add(Art->SimOptionsPriority);
+            NameList.Add(Art->GetName());
+        }
+
+        FMuJoCoOptions::Resolve(OptionList, PriorityList, NameList, m_spec);
+    }
 }
 
 void UMjPhysicsEngine::PostCompile()
diff --git a/Source/URLab/Private/MuJoCo/Core/MjSimOptions.cpp b/Source/URLab/Private/MuJoCo/Core/MjSimOptions.cpp
index af9a63c..05cb4b9 100644
--- a/Source/URLab/Private/MuJoCo/Core/MjSimOptions.cpp
+++ b/Source/URLab/Private/MuJoCo/Core/MjSimOptions.cpp
@@ -17,9 +17,21 @@
 // endorsed by, or sponsored by Epic Games, Inc. "Unreal" and "Unreal Engine" are 
 // trademarks or registered trademarks of Epic Games, Inc. in the US and elsewhere.
 //
-// This plugin incorporates third-party software: MuJoCo (Apache 2.0), 
+// This plugin incorporates third-party software: MuJoCo (Apache 2.0),
 // CoACD (MIT), and libzmq (MPL 2.0). See ThirdPartyNotices.txt for details.
 #include "MuJoCo/Core/MjSimOptions.h"
+#include "Utils/URLabLogging.h"
+#include "Misc/MessageDialog.h"
+#include "HAL/PlatformProcess.h"
+#include "Misc/App.h"
+
+#if WITH_EDITOR
+    #include "Dialog/SCustomDialog.h"
+    #include "Widgets/Input/SHyperlink.h"
+    #include "Widgets/Input/SMultiLineEditableTextBox.h"
+    #include "Widgets/SBoxPanel.h"
+#endif
+
 #include <mujoco/mujoco.h>
 
 void FMuJoCoOptions::ApplyToSpec(mjSpec* Spec) const
@@ -140,3 +152,380 @@ void FMuJoCoOptions::ApplyOverridesToModel(mjModel* Model) const
         Model->opt.enableflags &= ~MJ_ENBL_SLEEP;
     }
 }
+
+namespace
+{
+    template <typename TValue,
+              typename FHasOverride,
+              typename FGetValue,
+              typename FApply,
+              typename FEquals,
+              typename FFormat>
+    void ResolveField(const TArray<const FMuJoCoOptions*>& Options,
+                      const TArray<int32>& Priorities,
+                      const TArray<FString>& Names,
+                      mjSpec* Spec,
+                      const TCHAR* FieldName,
+                      FHasOverride HasOverride,
+                      FGetValue    GetValue,
+                      FApply       Apply,
+                      FEquals      Equals,
+                      FFormat      Format,
+                      TArray<FString>& OutDialogLines)
+    {
+        struct FEntry
+        {
+            int32   Index;
+            int32   Priority;
+            TValue  Value;
+            FString Name;
+        };
+
+        TArray<FEntry> Contributors;
+        for (int32 i = 0; i < Options.Num(); ++i)
+        {
+            if (!Options[i]) continue;
+            if (!HasOverride(Options[i])) continue;
+            Contributors.Add(FEntry{ i, Priorities[i], GetValue(Options[i]), Names[i] });
+        }
+
+        if (Contributors.Num() == 0) return;
+
+        if (Contributors.Num() == 1)
+        {
+            Apply(Spec, Contributors[0].Value);
+            return;
+        }
+
+        // Multi-contributor. First check if all values agree - silent in that case.
+        bool bAllAgree = true;
+        const TValue& Reference = Contributors[0].Value;
+        for (int32 i = 1; i < Contributors.Num(); ++i)
+        {
+            if (!Equals(Contributors[i].Value, Reference))
+            {
+                bAllAgree = false;
+                break;
+            }
+        }
+        if (bAllAgree)
+        {
+            Apply(Spec, Reference);
+            return;
+        }
+
+        // Real disagreement: sort by (priority desc, index asc).
+        Contributors.Sort([](const FEntry& A, const FEntry& B) {
+            if (A.Priority != B.Priority) return A.Priority > B.Priority;
+            return A.Index < B.Index;
+        });
+
+        const FEntry& Winner = Contributors[0];
+        Apply(Spec, Winner.Value);
+
+        // Build contributor summary string.
+        FString Summary;
+        for (int32 i = 0; i < Contributors.Num(); ++i)
+        {
+            if (i > 0) Summary += TEXT(", ");
+            Summary += FString::Printf(TEXT("%s(pri=%d, val=%s)"),
+                *Contributors[i].Name,
+                Contributors[i].Priority,
+                *Format(Contributors[i].Value));
+        }
+
+        UE_LOG(LogURLab, Warning,
+            TEXT("[SimOptions] '%s' conflict across %d articulations: %s. Applying %s's value %s."),
+            FieldName, Contributors.Num(), *Summary,
+            *Winner.Name, *Format(Winner.Value));
+
+        // Detect priority tie with the winner.
+        bool bTie = false;
+        for (int32 i = 1; i < Contributors.Num(); ++i)
+        {
+            if (Contributors[i].Priority == Winner.Priority)
+            {
+                bTie = true;
+                break;
+            }
+        }
+        if (bTie)
+        {
+            FString TiedNames;
+            for (const FEntry& E : Contributors)
+            {
+                if (E.Priority != Winner.Priority) continue;
+                if (!TiedNames.IsEmpty()) TiedNames += TEXT(", ");
+                TiedNames += E.Name;
+            }
+            UE_LOG(LogURLab, Warning,
+                TEXT("[SimOptions] '%s' ambiguous priority tie between %s (all pri=%d). "
+                     "Fell back to actor iteration order; applied %s's value. "
+                     "Set AMjArticulation.SimOptionsPriority to disambiguate."),
+                FieldName, *TiedNames, Winner.Priority, *Winner.Name);
+        }
+
+        OutDialogLines.Add(FString::Printf(
+            TEXT("%s (%d articulations disagreed%s)\n"
+                 "     APPLIED: %s value %s (priority %d)"),
+            FieldName,
+            Contributors.Num(),
+            bTie ? TEXT(", priority tie") : TEXT(""),
+            *Winner.Name,
+            *Format(Winner.Value),
+            Winner.Priority));
+    }
+}
+
+void FMuJoCoOptions::Resolve(const TArray<const FMuJoCoOptions*>& Options,
+                             const TArray<int32>& Priorities,
+                             const TArray<FString>& ContributorNames,
+                             mjSpec* TargetSpec)
+{
+    if (!TargetSpec) return;
+    if (Options.Num() == 0) return;
+
+    checkf(Options.Num() == Priorities.Num() && Options.Num() == ContributorNames.Num(),
+        TEXT("FMuJoCoOptions::Resolve: parallel arrays must have equal length (%d/%d/%d)"),
+        Options.Num(), Priorities.Num(), ContributorNames.Num());
+
+    TArray<FString> DialogLines;
+
+    // --- Timing ---
+    ResolveField<float>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Timestep"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Timestep; },
+        [](const FMuJoCoOptions* O){ return O->Timestep; },
+        [](mjSpec* S, float V){ S->option.timestep = V; },
+        [](float A, float B){ return FMath::IsNearlyEqual(A, B, 1e-12f); },
+        [](float V){ return FString::Printf(TEXT("%.6g"), V); },
+        DialogLines);
+
+    ResolveField<int32>(Options, Priorities, ContributorNames, TargetSpec, TEXT("MemoryMB"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_MemoryMB; },
+        [](const FMuJoCoOptions* O){ return O->MemoryMB; },
+        [](mjSpec* S, int32 V){ S->memory = static_cast<mjtSize>(V) * 1024 * 1024; },
+        [](int32 A, int32 B){ return A == B; },
+        [](int32 V){ return FString::Printf(TEXT("%d"), V); },
+        DialogLines);
+
+    // --- Physics Environment ---
+    // Gravity / Wind / Magnetic do the UE -> MJ coordinate conversion inside Apply.
+    ResolveField<FVector>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Gravity"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Gravity; },
+        [](const FMuJoCoOptions* O){ return O->Gravity; },
+        [](mjSpec* S, FVector V){
+            S->option.gravity[0] =  V.X / 100.0;
+            S->option.gravity[1] = -V.Y / 100.0;
+            S->option.gravity[2] =  V.Z / 100.0;
+        },
+        [](FVector A, FVector B){ return A.Equals(B, 1e-6); },
+        [](FVector V){ return V.ToString(); },
+        DialogLines);
+
+    ResolveField<FVector>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Wind"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Wind; },
+        [](const FMuJoCoOptions* O){ return O->Wind; },
+        [](mjSpec* S, FVector V){
+            S->option.wind[0] =  V.X / 100.0;
+            S->option.wind[1] = -V.Y / 100.0;
+            S->option.wind[2] =  V.Z / 100.0;
+        },
+        [](FVector A, FVector B){ return A.Equals(B, 1e-6); },
+        [](FVector V){ return V.ToString(); },
+        DialogLines);
+
+    ResolveField<FVector>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Magnetic"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Magnetic; },
+        [](const FMuJoCoOptions* O){ return O->Magnetic; },
+        [](mjSpec* S, FVector V){
+            S->option.magnetic[0] =  V.X;
+            S->option.magnetic[1] = -V.Y;
+            S->option.magnetic[2] =  V.Z;
+        },
+        [](FVector A, FVector B){ return A.Equals(B, 1e-6); },
+        [](FVector V){ return V.ToString(); },
+        DialogLines);
+
+    ResolveField<float>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Density"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Density; },
+        [](const FMuJoCoOptions* O){ return O->Density; },
+        [](mjSpec* S, float V){ S->option.density = V; },
+        [](float A, float B){ return FMath::IsNearlyEqual(A, B, 1e-12f); },
+        [](float V){ return FString::Printf(TEXT("%.6g"), V); },
+        DialogLines);
+
+    ResolveField<float>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Viscosity"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Viscosity; },
+        [](const FMuJoCoOptions* O){ return O->Viscosity; },
+        [](mjSpec* S, float V){ S->option.viscosity = V; },
+        [](float A, float B){ return FMath::IsNearlyEqual(A, B, 1e-12f); },
+        [](float V){ return FString::Printf(TEXT("%.6g"), V); },
+        DialogLines);
+
+    // --- Solver ---
+    ResolveField<float>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Impratio"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Impratio; },
+        [](const FMuJoCoOptions* O){ return O->Impratio; },
+        [](mjSpec* S, float V){ S->option.impratio = V; },
+        [](float A, float B){ return FMath::IsNearlyEqual(A, B, 1e-12f); },
+        [](float V){ return FString::Printf(TEXT("%.6g"), V); },
+        DialogLines);
+
+    ResolveField<float>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Tolerance"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Tolerance; },
+        [](const FMuJoCoOptions* O){ return O->Tolerance; },
+        [](mjSpec* S, float V){ S->option.tolerance = V; },
+        [](float A, float B){ return FMath::IsNearlyEqual(A, B, 1e-12f); },
+        [](float V){ return FString::Printf(TEXT("%.6g"), V); },
+        DialogLines);
+
+    ResolveField<int32>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Iterations"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Iterations; },
+        [](const FMuJoCoOptions* O){ return (int32)O->Iterations; },
+        [](mjSpec* S, int32 V){ S->option.iterations = V; },
+        [](int32 A, int32 B){ return A == B; },
+        [](int32 V){ return FString::Printf(TEXT("%d"), V); },
+        DialogLines);
+
+    ResolveField<int32>(Options, Priorities, ContributorNames, TargetSpec, TEXT("LsIterations"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_LsIterations; },
+        [](const FMuJoCoOptions* O){ return (int32)O->LsIterations; },
+        [](mjSpec* S, int32 V){ S->option.ls_iterations = V; },
+        [](int32 A, int32 B){ return A == B; },
+        [](int32 V){ return FString::Printf(TEXT("%d"), V); },
+        DialogLines);
+
+    ResolveField<int32>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Integrator"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Integrator; },
+        [](const FMuJoCoOptions* O){ return (int32)O->Integrator; },
+        [](mjSpec* S, int32 V){ S->option.integrator = V; },
+        [](int32 A, int32 B){ return A == B; },
+        [](int32 V){ return FString::Printf(TEXT("%d"), V); },
+        DialogLines);
+
+    ResolveField<int32>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Cone"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Cone; },
+        [](const FMuJoCoOptions* O){ return (int32)O->Cone; },
+        [](mjSpec* S, int32 V){ S->option.cone = V; },
+        [](int32 A, int32 B){ return A == B; },
+        [](int32 V){ return FString::Printf(TEXT("%d"), V); },
+        DialogLines);
+
+    ResolveField<int32>(Options, Priorities, ContributorNames, TargetSpec, TEXT("Solver"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_Solver; },
+        [](const FMuJoCoOptions* O){ return (int32)O->Solver; },
+        [](mjSpec* S, int32 V){ S->option.solver = V; },
+        [](int32 A, int32 B){ return A == B; },
+        [](int32 V){ return FString::Printf(TEXT("%d"), V); },
+        DialogLines);
+
+    ResolveField<int32>(Options, Priorities, ContributorNames, TargetSpec, TEXT("NoslipIterations"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_NoslipIterations; },
+        [](const FMuJoCoOptions* O){ return (int32)O->NoslipIterations; },
+        [](mjSpec* S, int32 V){ S->option.noslip_iterations = V; },
+        [](int32 A, int32 B){ return A == B; },
+        [](int32 V){ return FString::Printf(TEXT("%d"), V); },
+        DialogLines);
+
+    ResolveField<float>(Options, Priorities, ContributorNames, TargetSpec, TEXT("NoslipTolerance"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_NoslipTolerance; },
+        [](const FMuJoCoOptions* O){ return O->NoslipTolerance; },
+        [](mjSpec* S, float V){ S->option.noslip_tolerance = V; },
+        [](float A, float B){ return FMath::IsNearlyEqual(A, B, 1e-12f); },
+        [](float V){ return FString::Printf(TEXT("%.6g"), V); },
+        DialogLines);
+
+    ResolveField<int32>(Options, Priorities, ContributorNames, TargetSpec, TEXT("CCD_Iterations"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_CCD_Iterations; },
+        [](const FMuJoCoOptions* O){ return (int32)O->CCD_Iterations; },
+        [](mjSpec* S, int32 V){ S->option.ccd_iterations = V; },
+        [](int32 A, int32 B){ return A == B; },
+        [](int32 V){ return FString::Printf(TEXT("%d"), V); },
+        DialogLines);
+
+    ResolveField<float>(Options, Priorities, ContributorNames, TargetSpec, TEXT("CCD_Tolerance"),
+        [](const FMuJoCoOptions* O){ return O->bOverride_CCD_Tolerance; },
+        [](const FMuJoCoOptions* O){ return O->CCD_Tolerance; },
+        [](mjSpec* S, float V){ S->option.ccd_tolerance = V; },
+        [](float A, float B){ return FMath::IsNearlyEqual(A, B, 1e-12f); },
+        [](float V){ return FString::Printf(TEXT("%.6g"), V); },
+        DialogLines);
+
+    // bEnableMultiCCD, bEnableSleep, SleepTolerance have no bOverride_ flag;
+    // Manager-level scene toggles only, not per-articulation.
+
+    if (DialogLines.Num() > 0)
+    {
+        UE_LOG(LogURLab, Warning,
+            TEXT("[SimOptions] %d field(s) had cross-articulation conflicts. "
+                 "See https://urlab-sim.github.io/UnrealRoboticsLab/guides/sim_options_priority/ "
+                 "for resolution rules."),
+            DialogLines.Num());
+    }
+
+#if WITH_EDITOR
+    if (DialogLines.Num() > 0 && !FApp::IsUnattended())
+    {
+        static const TCHAR* GuideURL =
+            TEXT("https://urlab-sim.github.io/UnrealRoboticsLab/guides/sim_options_priority/");
+
+        FString Msg;
+        Msg += FString::Printf(
+            TEXT("SimOptions conflict detected between %d articulations.\n\n"),
+            Options.Num());
+        Msg += TEXT("MuJoCo stores one value per simulation-option field "
+                    "(timestep, gravity, solver, ...) globally. Two or more "
+                    "articulations in this scene set the same field to "
+                    "different values. Each conflict below was resolved by "
+                    "SimOptionsPriority; you can change the outcome without "
+                    "editing MJCF.\n\nConflicts:\n");
+        for (const FString& Line : DialogLines)
+        {
+            Msg += TEXT("  * ");
+            Msg += Line;
+            Msg += TEXT("\n\n");
+        }
+        Msg += TEXT("What to do:\n");
+        Msg += TEXT("  * Accept the resolution: no action needed if the "
+                    "winning value is correct for your scene.\n");
+        Msg += TEXT("  * Pick a different winner: change SimOptionsPriority "
+                    "on the articulations in the Details panel.\n");
+        Msg += TEXT("  * Apply a full override via the MjManager: set the "
+                    "field on AAMjManager -> Options. Manager values are a "
+                    "full override applied post-compile and ignore the "
+                    "articulation resolution entirely.\n");
+        Msg += TEXT("\nFull per-contributor breakdown (every articulation's "
+                    "value and priority) is in the Output Log under "
+                    "LogURLab.\n\n"
+                    "Press Dismiss to continue simulation.");
+
+        TSharedRef<SCustomDialog> Dialog = SNew(SCustomDialog)
+            .Title(NSLOCTEXT("URLab", "SimOptionsConflictTitle", "SimOptions Conflict"))
+            .Buttons({ SCustomDialog::FButton(NSLOCTEXT("URLab", "Dismiss", "Dismiss")) })
+            .Content()
+            [
+                SNew(SVerticalBox)
+                + SVerticalBox::Slot().AutoHeight().Padding(4.0f)
+                [
+                    SNew(SMultiLineEditableTextBox)
+                        .Text(FText::FromString(Msg))
+                        .IsReadOnly(true)
+                        .AutoWrapText(true)
+                        .AlwaysShowScrollbars(false)
+                        .Padding(FMargin(6.0f))
+                ]
+                + SVerticalBox::Slot().AutoHeight().Padding(8.0f, 6.0f)
+                [
+                    SNew(SHyperlink)
+                        .Text(NSLOCTEXT("URLab", "OpenGuide", "Open SimOptions Priority guide in browser"))
+                        .OnNavigate_Lambda([]()
+                        {
+                            FPlatformProcess::LaunchURL(GuideURL, nullptr, nullptr);
+                        })
+                ]
+            ];
+
+        Dialog->ShowModal();
+    }
+#endif
+}
diff --git a/Source/URLab/Public/MuJoCo/Core/MjArticulation.h b/Source/URLab/Public/MuJoCo/Core/MjArticulation.h
index 42a5e3d..bdfc888 100644
--- a/Source/URLab/Public/MuJoCo/Core/MjArticulation.h
+++ b/Source/URLab/Public/MuJoCo/Core/MjArticulation.h
@@ -418,6 +418,12 @@ class URLAB_API AMjArticulation : public APawn
      */
     UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "MuJoCo|Options")
     FMuJoCoOptions SimOptions;
+
+    /** Priority for SimOptions conflict resolution when multiple articulations
+     *  set the same field. Higher wins; ties fall back to actor iteration order. */
+    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "MuJoCo|Options",
+        meta=(DisplayName = "SimOptions Priority"))
+    int32 SimOptionsPriority = 0;
     
     /**
      * @brief Initializes the articulation, adding its components to the provided mjSpec.
diff --git a/Source/URLab/Public/MuJoCo/Core/MjSimOptions.h b/Source/URLab/Public/MuJoCo/Core/MjSimOptions.h
index 56b0f08..0875c9e 100644
--- a/Source/URLab/Public/MuJoCo/Core/MjSimOptions.h
+++ b/Source/URLab/Public/MuJoCo/Core/MjSimOptions.h
@@ -211,4 +211,13 @@ struct URLAB_API FMuJoCoOptions
      * Used by the manager for post-compile runtime overrides.
      */
     void ApplyOverridesToModel(mjModel* Model) const;
+
+    /** Resolve per-articulation SimOptions into TargetSpec->option, gated by
+     *  bOverride_* flags. Disagreeing values log a WARNING and pop an editor
+     *  dialog; highest SimOptionsPriority wins, tiebreak on index.
+     *  Parallel arrays must match in length. */
+    static void Resolve(const TArray<const FMuJoCoOptions*>& Options,
+                        const TArray<int32>& Priorities,
+                        const TArray<FString>& ContributorNames,
+                        mjSpec* TargetSpec);
 };
diff --git a/Source/URLab/URLab.Build.cs b/Source/URLab/URLab.Build.cs
index a2daeeb..ed14ed0 100644
--- a/Source/URLab/URLab.Build.cs
+++ b/Source/URLab/URLab.Build.cs
@@ -45,7 +45,8 @@ public URLab(ReadOnlyTargetRules Target) : base(Target)
 			PrivateDependencyModuleNames.AddRange(new string[]
 			{
 				"UnrealEd",
-				"AssetTools"
+				"AssetTools",
+				"ToolWidgets"
 			});
 		}
 
diff --git a/Source/URLabEditor/Private/Tests/MjSimOptionsResolverTests.cpp b/Source/URLabEditor/Private/Tests/MjSimOptionsResolverTests.cpp
new file mode 100644
index 0000000..44c7794
--- /dev/null
+++ b/Source/URLabEditor/Private/Tests/MjSimOptionsResolverTests.cpp
@@ -0,0 +1,293 @@
+// Copyright (c) 2026 Jonathan Embley-Riches. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// --- LEGAL DISCLAIMER ---
+// UnrealRoboticsLab is an independent software plugin. It is NOT affiliated with,
+// endorsed by, or sponsored by Epic Games, Inc. "Unreal" and "Unreal Engine" are
+// trademarks or registered trademarks of Epic Games, Inc. in the US and elsewhere.
+//
+// This plugin incorporates third-party software: MuJoCo (Apache 2.0),
+// CoACD (MIT), and libzmq (MPL 2.0). See ThirdPartyNotices.txt for details.
+
+// Covers FMuJoCoOptions::Resolve across five conflict scenarios.
+// Verifies the compiled mjModel->opt value; warning text is spot-checked
+// manually in the test log.
+
+#include "CoreMinimal.h"
+#include "Misc/AutomationTest.h"
+#include "Tests/MjTestHelpers.h"
+#include "MuJoCo/Core/AMjManager.h"
+#include "MuJoCo/Core/MjArticulation.h"
+#include "MuJoCo/Components/Bodies/MjWorldBody.h"
+#include "MuJoCo/Components/Bodies/MjBody.h"
+#include "MuJoCo/Components/Geometry/MjGeom.h"
+#include "MuJoCo/Components/Joints/MjJoint.h"
+#include "Engine/World.h"
+#include "mujoco/mujoco.h"
+
+namespace
+{
+    AMjArticulation* SpawnSecondArticulation(FMjUESession& S, const FString& Name)
+    {
+        if (!S.World) return nullptr;
+
+        FActorSpawnParameters P;
+        P.Name = *Name;
+        AMjArticulation* Bot = S.World->SpawnActor<AMjArticulation>(P);
+        if (!Bot) return nullptr;
+
+        UMjWorldBody* WB = NewObject<UMjWorldBody>(Bot, TEXT("WorldBody"));
+        Bot->SetRootComponent(WB);
+        WB->RegisterComponent();
+
+        UMjBody* Body = NewObject<UMjBody>(Bot, TEXT("Body"));
+        Body->RegisterComponent();
+        Body->AttachToComponent(WB, FAttachmentTransformRules::KeepRelativeTransform);
+
+        UMjGeom* Geom = NewObject<UMjGeom>(Bot, TEXT("Geom"));
+        Geom->Size = FVector(0.1f, 0.1f, 0.1f);
+        Geom->bOverride_Size = true;
+        Geom->RegisterComponent();
+        Geom->AttachToComponent(Body, FAttachmentTransformRules::KeepRelativeTransform);
+
+        UMjJoint* Joint = NewObject<UMjJoint>(Bot, TEXT("Joint"));
+        Joint->RegisterComponent();
+        Joint->AttachToComponent(Body, FAttachmentTransformRules::KeepRelativeTransform);
+
+        return Bot;
+    }
+}
+
+// ============================================================================
+// URLab.SimOptions.SingleArticulation
+//   One articulation sets timestep; compiled model reflects that value.
+// ============================================================================
+IMPLEMENT_SIMPLE_AUTOMATION_TEST(FMjSimOptionsSingleArticulation,
+    "URLab.SimOptions.SingleArticulation",
+    EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter)
+
+bool FMjSimOptionsSingleArticulation::RunTest(const FString&)
+{
+    FMjUESession S;
+    if (!S.Init([](FMjUESession& Sess)
+    {
+        Sess.Robot->SimOptions.bOverride_Timestep = true;
+        Sess.Robot->SimOptions.Timestep = 0.003f;
+    }))
+    {
+        AddError(FString::Printf(TEXT("Init failed: %s"), *S.LastError));
+        S.Cleanup();
+        return false;
+    }
+
+    mjModel* M = S.Manager->PhysicsEngine->m_model;
+    TestNotNull(TEXT("Model"), M);
+    if (M)
+    {
+        TestTrue(TEXT("Single-articulation timestep applied"),
+            FMath::IsNearlyEqual((float)M->opt.timestep, 0.003f, 1e-6f));
+    }
+
+    S.Cleanup();
+    return true;
+}
+
+// ============================================================================
+// URLab.SimOptions.TwoArticulationsAgreeOnValue
+//   Both articulations set timestep to the same value - silent apply,
+//   value reaches the compiled model.
+// ============================================================================
+IMPLEMENT_SIMPLE_AUTOMATION_TEST(FMjSimOptionsTwoArticulationsAgreeOnValue,
+    "URLab.SimOptions.TwoArticulationsAgreeOnValue",
+    EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter)
+
+bool FMjSimOptionsTwoArticulationsAgreeOnValue::RunTest(const FString&)
+{
+    FMjUESession S;
+    if (!S.Init([](FMjUESession& Sess)
+    {
+        Sess.Robot->SimOptions.bOverride_Timestep = true;
+        Sess.Robot->SimOptions.Timestep = 0.0025f;
+
+        AMjArticulation* Second = SpawnSecondArticulation(Sess, TEXT("SecondBot_Agree"));
+        if (Second)
+        {
+            Second->SimOptions.bOverride_Timestep = true;
+            Second->SimOptions.Timestep = 0.0025f;
+        }
+    }))
+    {
+        AddError(FString::Printf(TEXT("Init failed: %s"), *S.LastError));
+        S.Cleanup();
+        return false;
+    }
+
+    mjModel* M = S.Manager->PhysicsEngine->m_model;
+    TestNotNull(TEXT("Model"), M);
+    if (M)
+    {
+        TestTrue(TEXT("Agreed-value timestep applied to compiled model"),
+            FMath::IsNearlyEqual((float)M->opt.timestep, 0.0025f, 1e-6f));
+    }
+
+    S.Cleanup();
+    return true;
+}
+
+// ============================================================================
+// URLab.SimOptions.TwoArticulationsDiffValues_HigherPriorityWins
+//   ArmA(pri=5, timestep=0.002) vs ArmB(pri=2, timestep=0.005).
+//   Compiled model must have 0.002. A [SimOptions] 'Timestep' conflict
+//   WARNING is logged (verify in test run log).
+// ============================================================================
+IMPLEMENT_SIMPLE_AUTOMATION_TEST(FMjSimOptionsDiffValuesHigherPriorityWins,
+    "URLab.SimOptions.TwoArticulationsDiffValues_HigherPriorityWins",
+    EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter)
+
+bool FMjSimOptionsDiffValuesHigherPriorityWins::RunTest(const FString&)
+{
+    FMjUESession S;
+    if (!S.Init([](FMjUESession& Sess)
+    {
+        Sess.Robot->SimOptions.bOverride_Timestep = true;
+        Sess.Robot->SimOptions.Timestep = 0.002f;
+        Sess.Robot->SimOptionsPriority = 5;
+
+        AMjArticulation* Second = SpawnSecondArticulation(Sess, TEXT("SecondBot_LowerPri"));
+        if (Second)
+        {
+            Second->SimOptions.bOverride_Timestep = true;
+            Second->SimOptions.Timestep = 0.005f;
+            Second->SimOptionsPriority = 2;
+        }
+    }))
+    {
+        AddError(FString::Printf(TEXT("Init failed: %s"), *S.LastError));
+        S.Cleanup();
+        return false;
+    }
+
+    mjModel* M = S.Manager->PhysicsEngine->m_model;
+    TestNotNull(TEXT("Model"), M);
+    if (M)
+    {
+        TestTrue(TEXT("Higher-priority articulation's timestep wins (expected 0.002)"),
+            FMath::IsNearlyEqual((float)M->opt.timestep, 0.002f, 1e-6f));
+    }
+
+    S.Cleanup();
+    return true;
+}
+
+// ============================================================================
+// URLab.SimOptions.TwoArticulationsSamePriority_ActorOrderWins
+//   ArmA(pri=0, val=0.002) vs ArmB(pri=0, val=0.005). First wins by actor
+//   iteration order. Two WARNINGs expected (conflict + ambiguous priority tie).
+// ============================================================================
+IMPLEMENT_SIMPLE_AUTOMATION_TEST(FMjSimOptionsSamePriorityActorOrderWins,
+    "URLab.SimOptions.TwoArticulationsSamePriority_ActorOrderWins",
+    EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter)
+
+bool FMjSimOptionsSamePriorityActorOrderWins::RunTest(const FString&)
+{
+    FMjUESession S;
+    if (!S.Init([](FMjUESession& Sess)
+    {
+        Sess.Robot->SimOptions.bOverride_Timestep = true;
+        Sess.Robot->SimOptions.Timestep = 0.002f;
+        Sess.Robot->SimOptionsPriority = 0;
+
+        AMjArticulation* Second = SpawnSecondArticulation(Sess, TEXT("SecondBot_SamePri"));
+        if (Second)
+        {
+            Second->SimOptions.bOverride_Timestep = true;
+            Second->SimOptions.Timestep = 0.005f;
+            Second->SimOptionsPriority = 0;
+        }
+    }))
+    {
+        AddError(FString::Printf(TEXT("Init failed: %s"), *S.LastError));
+        S.Cleanup();
+        return false;
+    }
+
+    mjModel* M = S.Manager->PhysicsEngine->m_model;
+    TestNotNull(TEXT("Model"), M);
+    if (M)
+    {
+        // Actor iteration order isn't formally guaranteed, so accept either
+        // value as "tie resolved deterministically on this platform".
+        const bool bRobotWon  = FMath::IsNearlyEqual((float)M->opt.timestep, 0.002f, 1e-6f);
+        const bool bSecondWon = FMath::IsNearlyEqual((float)M->opt.timestep, 0.005f, 1e-6f);
+        TestTrue(TEXT("Same-priority tie resolved to one of the two values"),
+            bRobotWon || bSecondWon);
+
+        if (!bRobotWon)
+        {
+            AddInfo(TEXT("Tie broke to second articulation; platform iteration "
+                         "order differs from spawn order. Not a failure."));
+        }
+    }
+
+    S.Cleanup();
+    return true;
+}
+
+// ============================================================================
+// URLab.SimOptions.ManagerOverrideTrumpsResolver
+//   Manager sets timestep=0.010. Two articulations disagree (0.002 vs 0.005).
+//   Compiled model should have 0.010 (Manager always wins). The resolver
+//   still logs its conflict WARNING even though Manager will overwrite.
+// ============================================================================
+IMPLEMENT_SIMPLE_AUTOMATION_TEST(FMjSimOptionsManagerOverrideTrumpsResolver,
+    "URLab.SimOptions.ManagerOverrideTrumpsResolver",
+    EAutomationTestFlags::EditorContext | EAutomationTestFlags::ProductFilter)
+
+bool FMjSimOptionsManagerOverrideTrumpsResolver::RunTest(const FString&)
+{
+    FMjUESession S;
+    if (!S.Init([](FMjUESession& Sess)
+    {
+        Sess.Robot->SimOptions.bOverride_Timestep = true;
+        Sess.Robot->SimOptions.Timestep = 0.002f;
+        Sess.Robot->SimOptionsPriority = 1;
+
+        AMjArticulation* Second = SpawnSecondArticulation(Sess, TEXT("SecondBot_MgrOverride"));
+        if (Second)
+        {
+            Second->SimOptions.bOverride_Timestep = true;
+            Second->SimOptions.Timestep = 0.005f;
+            Second->SimOptionsPriority = 0;
+        }
+
+        Sess.Manager->PhysicsEngine->Options.bOverride_Timestep = true;
+        Sess.Manager->PhysicsEngine->Options.Timestep = 0.010f;
+    }))
+    {
+        AddError(FString::Printf(TEXT("Init failed: %s"), *S.LastError));
+        S.Cleanup();
+        return false;
+    }
+
+    mjModel* M = S.Manager->PhysicsEngine->m_model;
+    TestNotNull(TEXT("Model"), M);
+    if (M)
+    {
+        TestTrue(TEXT("Manager's timestep override wins over articulation resolution (expected 0.010)"),
+            FMath::IsNearlyEqual((float)M->opt.timestep, 0.010f, 1e-6f));
+    }
+
+    S.Cleanup();
+    return true;
+}
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 3a28d81..97e654a 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -200,6 +200,12 @@ If the `build_all.ps1` script fails with code `-1073741571`, your compiler has r
 * **Workaround:** Force a larger stack size by running:
   `cmake -B build ... -DCMAKE_CXX_FLAGS="/F10000000"`
 
+### Dialog: "SimOptions conflicts detected"
+
+Two or more articulations in your scene set the same MuJoCo option field (timestep, gravity, solver, etc.) to different values. MuJoCo compiles to one value per field globally, so URLab picks a winner based on each articulation's `SimOptionsPriority`. The dialog summarises every conflict and the chosen winner.
+
+See the [SimOptions Priority guide](guides/sim_options_priority.md) for the full resolution rules, worked examples, and the three knobs you can use to change the outcome.
+
 ### UI: "Simulate" Dashboard Not Appearing
 The UI is context-sensitive and requires specific conditions:
 * Ensure an `MjManager` actor is present in the level.
diff --git a/docs/guides/sim_options_priority.md b/docs/guides/sim_options_priority.md
new file mode 100644
index 0000000..f61f37c
--- /dev/null
+++ b/docs/guides/sim_options_priority.md
@@ -0,0 +1,160 @@
+# SimOptions Priority
+
+MuJoCo stores one `mjOption` block per compiled model. When multiple articulations in the same scene set the same simulation-option field (timestep, gravity, solver, ...), URLab's resolver picks which value wins. This guide covers the rules and how to control the outcome without editing MJCF.
+
+---
+
+## The problem
+
+MJCF lets every model declare an `<option>` block:
+
+```xml
+<mujoco model="armA">
+  <option timestep="0.002" integrator="Newton"/>
+  ...
+</mujoco>
+```
+
+```xml
+<mujoco model="armB">
+  <option timestep="0.005" gravity="0 0 -1"/>
+  ...
+</mujoco>
+```
+
+MuJoCo's own spec merge (`mjs_attach`) silently drops these per-subtree option blocks during compile. Every field in `mjOption` is global: one timestep, one gravity vector, one solver choice. Without additional logic, a scene with both arms above would compile with none of their option settings applied.
+
+URLab fills that gap with the resolver. It runs after every articulation attaches to the root spec and before `mj_compile`, writing per-articulation option values back into the compound spec based on priority.
+
+---
+
+## Resolution rules
+
+The resolver walks each option field independently, using the field's `bOverride_<Field>` flag to decide who contributes:
+
+1. **No articulations set `bOverride_<Field>`**: the field stays at MuJoCo's default (or whatever the Manager's `SimOptions` applies post-compile).
+2. **One articulation sets `bOverride_<Field>`**: its value applies, silently.
+3. **Two or more agree on the same value**: that value applies, silently.
+4. **Two or more disagree**: highest `SimOptionsPriority` wins. Ties break on actor iteration order. A `WARNING` is logged to `LogURLab`. Ties also get a second `WARNING` about ambiguous fallback.
+5. **The Manager's `SimOptions` (on `AAMjManager`)** is applied post-compile and acts as a full override: when the Manager has `bOverride_<Field>=true`, that value wins regardless of what the articulation resolver produced.
+
+---
+
+## Why per-field instead of whole-articulation
+
+Two alternatives were considered: per-field (chosen) and "whole-block" (entire highest-priority articulation wins, losers contribute nothing).
+
+Per-field matches how MJCF is authored. Authors write `<option field1="X" field2="Y"/>` with exactly the fields they care about; `bOverride_<Field>` mirrors that. When two articulations set *different* fields, both authors get what they asked for. Whole-block would silently discard non-conflicting settings from every articulation except the priority winner.
+
+The trade-off is that per-field may produce a combination neither author explicitly tested (e.g. one author's `integrator` paired with another author's `tolerance`). That's rare in practice, but if it matters for your scene, push the authoritative values onto the Manager; Manager overrides run after the resolver.
+
+---
+
+## Worked example
+
+Scene contains two articulations:
+
+| Articulation | `bOverride_Timestep` | `Timestep` | `bOverride_Integrator` | `Integrator` | `bOverride_Gravity` | `Gravity` | `SimOptionsPriority` |
+|---|---|---|---|---|---|---|---|
+| ArmA | true | `0.002` | true | `Newton` | false | (default) | `5` |
+| ArmB | true | `0.005` | false | (default) | true | low | `2` |
+
+Resolution:
+
+- **Timestep**: both set, values disagree, priority 5 > 2, ArmA wins. Spec `timestep = 0.002`. One WARNING.
+- **Integrator**: only ArmA set. ArmA's `Newton` applies silently.
+- **Gravity**: only ArmB set. ArmB's low gravity applies silently.
+
+Compiled model: `timestep=0.002, integrator=Newton, gravity=<low>`. Both authors' intent is honored everywhere they didn't fight with another author. Exactly one warning fired, for the one real conflict.
+
+---
+
+## How to tailor the resolver
+
+Three knobs, in increasing order of force:
+
+### 1. Tweak `SimOptionsPriority`
+
+Per-articulation integer in the Details panel under `MuJoCo|Options`. Higher wins. Default is `0`.
+
+Use when two articulations disagree and you know which one's value is correct for the scene. Leaves every other field untouched.
+
+### 2. Toggle `bOverride_<Field>` on the articulation
+
+Open `SimOptions` on the articulation in the Details panel. Each field has a checkbox that gates whether the articulation participates in the resolver for that field.
+
+Use to stop an articulation from contributing a value it no longer needs (silences warnings), or to explicitly start contributing one that MJCF didn't set.
+
+### 3. Full override on the Manager
+
+`AAMjManager` has its own `Options` struct. Set `bOverride_<Field>=true` there plus the value, and the Manager's value wins regardless of what the articulation resolver produced.
+
+Use when you want one authoritative value for the whole scene, or when a particular combination of article-level settings is producing behaviour you don't want and you'd rather short-circuit the resolver for that field.
+
+---
+
+## How to silence a specific warning
+
+The resolver only warns when articulations *actually disagree* on a field value. If you're seeing a warning you consider noise:
+
+1. Check that the values really are different. The resolver uses `FMath::IsNearlyEqual` with `1e-12` precision for floats; `FVector::Equals` with `1e-6` for vectors. Near-equal is counted as agreement.
+2. If one articulation no longer needs the override, untick its `bOverride_<Field>` in the Details panel.
+3. If you want one authoritative value for the whole scene, move the override onto the Manager. Manager overrides never trigger the resolver's warnings.
+
+---
+
+## Reading the warnings
+
+The log lines follow a consistent format so you can grep them:
+
+```
+LogURLab: Warning: [SimOptions] '<Field>' conflict across <N> articulations: <Name>(pri=<P>, val=<V>), ... . Applying <Winner>'s value <V>.
+LogURLab: Warning: [SimOptions] '<Field>' ambiguous priority tie between <Names> (all pri=<P>). Fell back to actor iteration order; applied <Winner>'s value. Set AMjArticulation.SimOptionsPriority to disambiguate.
+LogURLab: Warning: [SimOptions] <N> field(s) had cross-articulation conflicts. See https://urlab-sim.github.io/UnrealRoboticsLab/guides/sim_options_priority/ for resolution rules.
+```
+
+The first line fires once per disagreeing field. The second only appears when the winning priority ties with another contributor's priority. The third is a single tail line per compile cycle pointing at this guide.
+
+---
+
+## Fields covered by the resolver
+
+All fields on `FMuJoCoOptions` that have a paired `bOverride_<Field>` flag participate. At the time of writing:
+
+| Category | Field | Type | Notes |
+|---|---|---|---|
+| Timing | `Timestep` | float | Simulation time resolution. Lower values are more stable but slower. |
+| Timing | `MemoryMB` | int | Arena size for the compiled model. |
+| Environment | `Gravity` | FVector | UE units (cm/s^2). Converted at apply. |
+| Environment | `Wind` | FVector | UE units (cm/s). Converted at apply. |
+| Environment | `Magnetic` | FVector | MuJoCo units; Y is negated. |
+| Environment | `Density` | float | Fluid density of the medium. |
+| Environment | `Viscosity` | float | Fluid viscosity. |
+| Solver | `Impratio` | float | Friction-to-normal impedance ratio. |
+| Solver | `Tolerance` | float | Convergence tolerance. |
+| Solver | `Iterations` | int | Solver iteration cap. |
+| Solver | `LsIterations` | int | Line-search iteration cap. |
+| Solver | `Integrator` | enum | Euler / RK4 / Implicit / ImplicitFast. |
+| Solver | `Cone` | enum | Pyramidal / Elliptic friction cone. |
+| Solver | `Solver` | enum | PGS / CG / Newton. |
+| Solver | `NoslipIterations` | int | Noslip constraint solver iteration cap. |
+| Solver | `NoslipTolerance` | float | Noslip constraint solver tolerance. |
+| Solver | `CCD_Iterations` | int | Continuous collision detection iteration cap. |
+| Solver | `CCD_Tolerance` | float | CCD tolerance. |
+
+`bEnableMultiCCD`, `bEnableSleep`, and `SleepTolerance` do not have `bOverride_<Field>` flags and are treated as Manager-only scene toggles. They never participate in articulation-level resolution.
+
+---
+
+## When the dialog appears
+
+The dialog pops once per compile cycle, editor only, when at least one field had a real disagreement. It summarises every conflict in a single popup and points at this guide. The automation test suite (`-Unattended`) suppresses the dialog via `FMessageDialog::Open`'s built-in unattended handling, so running the test suite will never block on a dialog.
+
+Full per-contributor details live in the Output Log under `LogURLab` warnings (see [Reading the warnings](#reading-the-warnings) above).
+
+---
+
+## Related
+
+- [Troubleshooting: SimOptions conflicts](../getting_started.md#dialog-simoptions-conflicts-detected) in Getting Started.
+- MuJoCo's own [`<option>` XML reference](https://mujoco.readthedocs.io/en/stable/XMLreference.html#option) documents every field and its effect on the simulation.
diff --git a/docs/index.md b/docs/index.md
index 3e83740..3d71257 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -36,6 +36,7 @@ The plugin gives you research-grade contact dynamics alongside Unreal's renderin
 | [ZMQ Networking & ROS 2](guides/zmq_networking.md) | ZMQ transport, topics, camera streaming |
 | [URLab Bridge](guides/policy_bridge.md) | Python middleware, RL policies, remote control |
 | [Architecture](architecture.md) | Subsystem design, threading model, compilation pipeline |
+| [SimOptions Priority](guides/sim_options_priority.md) | How URLab resolves per-articulation option conflicts in scenes with multiple robots |
 
 ---
 
diff --git a/mkdocs.yml b/mkdocs.yml
index a944f57..ef419c5 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -85,6 +85,7 @@ nav:
     - ZMQ Networking & ROS 2: guides/zmq_networking.md
     - URLab Bridge: guides/policy_bridge.md
     - MJCF Schema Coverage: mjcf_schema_coverage.md
+    - SimOptions Priority: guides/sim_options_priority.md
   # -- AUTO-GENERATED BELOW THIS LINE (do not edit manually) --
   - API Reference:
     - Overview: api/index.md