Document async physics settings

Add an option to the launcher
Update changelog

CHANGELOG.md

@@ -67,6 +67,7 @@
     Feature #5524: Resume failed script execution after reload
     Feature #5525: Search fields tweaks (utf-8)
     Feature #5545: Option to allow stealing from an unconscious NPC during combat
+    Feature #5563: Run physics update in background thread
     Feature #5579: MCP SetAngle enhancement
     Feature #5610: Actors movement should be smoother
     Task #5480: Drop Qt4 support

apps/launcher/advancedpage.cpp

@@ -94,6 +94,9 @@ bool Launcher::AdvancedPage::loadSettings()
             unarmedFactorsStrengthComboBox->setCurrentIndex(unarmedFactorsStrengthIndex);
         loadSettingBool(stealingFromKnockedOutCheckBox, "always allow stealing from knocked out actors", "Game");
         loadSettingBool(enableNavigatorCheckBox, "enable", "Navigator");
+        int numPhysicsThreads = mEngineSettings.getInt("async num threads", "Physics");
+        if (numPhysicsThreads >= 0)
+            physicsThreadsSpinBox->setValue(numPhysicsThreads);
     }
 
     // Visuals
@@ -208,6 +211,9 @@ void Launcher::AdvancedPage::saveSettings()
             mEngineSettings.setInt("strength influences hand to hand", "Game", unarmedFactorsStrengthIndex);
         saveSettingBool(stealingFromKnockedOutCheckBox, "always allow stealing from knocked out actors", "Game");
         saveSettingBool(enableNavigatorCheckBox, "enable", "Navigator");
+        int numPhysicsThreads = physicsThreadsSpinBox->value();
+        if (numPhysicsThreads != mEngineSettings.getInt("async num threads", "Physics"))
+            mEngineSettings.setInt("async num threads", "Physics", numPhysicsThreads);
     }
 
     // Visuals

docs/source/reference/modding/settings/index.rst

@@ -57,3 +57,4 @@ The ranges included with each setting are the physically possible ranges, not re
 	water
 	windows
 	navigator
+	physics

docs/source/reference/modding/settings/physics.rst

@@ -0,0 +1,37 @@
+Physics Settings
+################
+
+async num threads
+-----------------
+
+:Type:		integer
+:Range:		>= 0
+:Default:	0
+
+Determines how many threads will be spawned to compute physics update in the background (that is, process actors movement). A value of 0 means that the update will be performed in the main thread.
+A value greater than 1 requires the Bullet library be compiled with multithreading support. If that's not the case, a warning will be written in ``openmw.log`` and a value of 1 will be used.
+
+lineofsight keep inactive cache
+-------------------------------
+
+:Type:		integer
+:Range:		>= -1
+:Default:	0
+
+The line of sight determines if 2 actors can see each other (without taking into account game mechanics such as invisibility or sneaking). It is used by some scripts (the getLOS function), by the AI (to determine if an actor should start combat or chase an opponent) and for functionnalities such as greetings or turning NPC head toward an object.
+This parameters determine for how long a cache of request should be kept warm. It depends on :ref:`async num threads` being > 0, otherwise a value of -1 will be used. If a request is not found in the cache, it is always fulfilled immediately. In case Bullet is compiled without multithreading support, non-cached requests involve blocking the async thread(s), which might hurt performance.
+A value of -1 means no caching.
+A value of 0 means that for as long as a request is made (after the first one), it will be preemptively "refreshed" in the async thread, without blocking neither the main thread nor the async thread.
+Any value > 0 is the number of frames for which the values are kept in cache even if the results was not requested again.
+If Bullet is compiled with multithreading support, requests are non blocking, it is better to set this parameter to -1.
+
+defer aabb update
+-----------------
+
+:Type:		boolean
+:Range:		True/False
+:Default:	True
+
+Axis-aligned bounding box (aabb for short) are used by Bullet for collision detection. They should be updated anytime a physical object is modified (for instance moved) for collision detection to be correct.
+This parameter control wether the update should be done as soon as the object is modified (the default), which involves blocking the async thread(s), or queue the modifications to update them as a batch before the collision detections. It depends on :ref:`async num threads` being > 0, otherwise it will be disabled.
+Disabling this parameter is intended as an aid for debugging collisions detection issues.

files/ui/advancedpage.ui

@@ -211,6 +211,36 @@
          </item>
         </layout>
        </item>
+       <item>
+        <layout class="QHBoxLayout" name="horizontalPhysicsThreadsLayout">
+         <item>
+          <widget class="QLabel" name="physicsThreadsLabel">
+           <property name="toolTip">
+            <string>&lt;html&gt;&lt;head/&gt;&lt;body&gt;&lt;p&gt;How many threads will be spawned to compute physics update in the background. A value of 0 means that the update will be performed in the main thread.&lt;/p&gt;&lt;p&gt;A value greater than 1 requires the Bullet library be compiled with multithreading support.&lt;/p&gt;&lt;/body&gt;&lt;/html&gt;</string>
+           </property>
+           <property name="text">
+            <string>Background physics threads</string>
+           </property>
+          </widget>
+         </item>
+         <item>
+          <widget class="QSpinBox" name="physicsThreadsSpinBox"/>
+         </item>
+         <item>
+          <spacer name="horizontalSpacer_4">
+           <property name="orientation">
+            <enum>Qt::Horizontal</enum>
+           </property>
+           <property name="sizeHint" stdset="0">
+            <size>
+             <width>40</width>
+             <height>20</height>
+            </size>
+           </property>
+          </spacer>
+         </item>
+        </layout>
+       </item>
        <item>
         <spacer name="verticalSpacer_3">
          <property name="orientation">