feat: add Natural Head Movement effect

.github/PULL_REQUEST_TEMPLATE.md

@@ -30,6 +30,8 @@
 - [ ] Effect doesn't conflict with existing effects
 - [ ] Effect overrides `NeedsDriverSeat()`, if it only makes sense in the
       driver's seat
+- [ ] Effects that shouldn't run together declared in
+      `conflicts::kPauses` (`src/core/Conflicts.hpp`), if any
 - [ ] Setting declared in `settings::kAll` (`src/core/Settings.hpp`)
 - [ ] New effect listed in `kEffects` (`src/ui/EffectTabs.cpp`)
 - [ ] Keybind declared in `src/core/Keybinds.hpp` (`kAllActions`), if any

CMakeLists.txt

@@ -19,6 +19,7 @@ add_compile_definitions(_AMD64_)
 set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_CXX_SCAN_FOR_MODULES OFF)
 
 # --- Global MSVC Runtime Configuration (/MT) ---
 # This ensures static runtime linking, avoiding "Win32 Error 126" on
@@ -67,6 +68,7 @@ set(PLUGIN_SOURCES
     "src/effects/cabin/EngineStartStopEffect.cpp"
     "src/effects/cabin/EngineVibrationEffect.cpp"
     "src/effects/cabin/IdleBreathingEffect.cpp"
+    "src/effects/cabin/NaturalHeadMovementEffect.cpp"
     "src/effects/driving/BodyDynamicsEffect.cpp"
     "src/effects/driving/HeadMotionEffect.cpp"
     "src/effects/driving/SteeringCameraEffect.cpp"

CONTRIBUTING.md

@@ -48,6 +48,10 @@ game's `plugins/spfPlugins/MotionCab/`.
 - If an effect only makes sense in the driver's seat, override
   `NeedsDriverSeat()` so it fades out while Cabin Walk has the player
   elsewhere in the cabin.
+- If an effect shouldn't run alongside another one (e.g. Natural Head
+  Movement and Idle Breathing), declare the pair in `conflicts::kPauses`
+  (`src/core/Conflicts.hpp`): while the first is enabled, the second fades
+  out, its settings untouched, and the Quick Settings window says so.
 - Declare a new keybind action once in `src/core/Keybinds.hpp` (default
   key and localization key) and add it to `kAllActions`, plus
   `kPolledActions` if the effect polls it.

README.md

@@ -53,6 +53,8 @@ camera control, keybind rebinding, and the in-game settings UI.
   braking
 - **Engine Start/Stop** — mechanical shudder when the engine catches or
   dies
+- **Natural Head Movement** — TrackIR-like head movement, without a
+  tracker
 - **Manual Zoom** — smooth zoom effect
 - **Blindspot Viewer** — leans forward to see traffic lights hidden by the cab
 - **Cabin Walk** — walks around the parked cabin and sits in the passenger
@@ -165,6 +167,12 @@ Values are persisted by the framework to `plugins/spfPlugins/MotionCab/config/se
 | **Engine Start/Stop**        |         |                                                                                                                                      |
 | `intensity`                  | 0.1     | How strong the shudder feels when the engine starts or stops.                                                                        |
 | `duration`                   | 1.0     | How long the start-up shudder lasts. The stop shudder is shorter and gentler than this.                                              |
+| **Natural Head Movement**    |         |                                                                                                                                      |
+| `tremor_intensity`           | 5.0     | How much your head trembles slightly, all the time.                                                                                  |
+| `micro_intensity`            | 2.5     | How far your head moves when it makes a small adjustment.                                                                            |
+| `posture_intensity`          | 1.3     | How far your head shifts when it settles into a new position: tilted, leaning forward or to one side.                                |
+| `posture_interval`           | 15.0    | About how long your head holds a position before settling into a new one.                                                            |
+| `steering_tilt`              | 1.5     | How much your head tilts into the turn as you turn the steering wheel.                                                               |
 | **Manual Zoom**              |         |                                                                                                                                      |
 | `zoom_fov_deg`               | 40.0    | How zoomed in the view gets while holding the zoom key. Lower = more zoomed in.                                                      |
 | `smoothing_time`             | 0.25    | How smooth the zoom in/out feels.                                                                                                    |
@@ -213,6 +221,7 @@ game's `plugins/spfPlugins/MotionCab/`.
 │   │   ├── PluginContext.cpp / .hpp  Shared plugin state
 │   │   ├── Profiles.cpp / .hpp       Create/save/switch named presets
 │   │   ├── Settings.cpp / .hpp       Every setting: key, default, slider range
+│   │   ├── Conflicts.hpp             Which effects pause which while enabled
 │   │   ├── Loc.cpp / .hpp            Translated string lookup (loc::Tr)
 │   │   ├── Keybinds.hpp              Keybind action names and key polling helpers
 │   │   ├── Strings.hpp               Case-insensitive string helpers
@@ -221,7 +230,7 @@ game's `plugins/spfPlugins/MotionCab/`.
 │   │   ├── SpringDamper.hpp          Critically-damped spring, the core smoothing primitive
 │   │   ├── Noise.hpp                 Deterministic gradient noise
 │   │   ├── Oscillator.hpp            Damped spring that can overshoot and ring
-│   │   └── Units.hpp                 Unit conversions, SmoothStep, phase wrapping
+│   │   └── Units.hpp                 Unit conversions, easing, Lerp, phase wrapping
 │   ├── effects/
 │   │   ├── Effect.hpp                Base effect interface + HeadOffset struct
 │   │   ├── ConfigurableEffect.hpp    Base for effects: enabled toggle + settings access
@@ -230,7 +239,8 @@ game's `plugins/spfPlugins/MotionCab/`.
 │   │   ├── driving/                  HeadMotion, BodyDynamics, SteeringCamera
 │   │   ├── road/                     Suspension, RoadIrregularity, SpeedShake,
 │   │   │                             Surface (ground classification)
-│   │   ├── cabin/                    IdleBreathing, EngineVibration, EngineStartStop
+│   │   ├── cabin/                    IdleBreathing, EngineVibration, EngineStartStop,
+│   │   │                             NaturalHeadMovement
 │   │   └── manual/                   MirrorCheck, ManualLook, ManualZoom, BlindspotViewer
 │   │       └── cabin_walk/
 │   │           ├── CabinWalkEffect.*     The effect: standing up, walking, sitting down

localization/cs.json

@@ -81,6 +81,8 @@
   },
   "settings": {
     "enabled_desc": "Zapne nebo vypne tento efekt.",
+    "paused_by": "Pozastaveno efektem: {effects}.",
+    "pauses": "Po zapnutí pozastaví následující efekt(y):",
     "driving": {
       "title": "Jízda",
       "head_motion": {
@@ -235,6 +237,29 @@
           "title": "Doba trvání",
           "desc": "Jak dlouho trvá škubnutí při startu. Škubnutí při vypnutí je kratší a jemnější."
         }
+      },
+      "natural_head_movement": {
+        "title": "Přirozený pohyb hlavy",
+        "tremor_intensity": {
+          "title": "Chvění",
+          "desc": "Jak moc se hlava neustále lehce chvěje."
+        },
+        "micro_intensity": {
+          "title": "Mikropohyby",
+          "desc": "Jak daleko se hlava pohne při drobné korekci."
+        },
+        "posture_intensity": {
+          "title": "Změny držení",
+          "desc": "Jak daleko se hlava posune, když zaujme novou polohu: naklonění, předklon nebo posun do strany."
+        },
+        "posture_interval": {
+          "title": "Interval držení",
+          "desc": "Přibližně jak dlouho hlava drží jednu polohu, než zaujme novou."
+        },
+        "steering_tilt": {
+          "title": "Náklon při zatáčení",
+          "desc": "Jak moc se hlava nakloní do zatáčky, když otáčíte volantem."
+        }
       }
     },
     "manual": {

localization/de.json

@@ -81,6 +81,8 @@
   },
   "settings": {
     "enabled_desc": "Schaltet diesen Effekt ein oder aus.",
+    "paused_by": "Pausiert durch {effects}.",
+    "pauses": "Wenn aktiviert, pausiert dies folgende(n) Effekt(e):",
     "driving": {
       "title": "Fahren",
       "head_motion": {
@@ -235,6 +237,29 @@
           "title": "Dauer",
           "desc": "Wie lange das Rütteln beim Start dauert. Das Rütteln beim Abstellen ist kürzer und sanfter."
         }
+      },
+      "natural_head_movement": {
+        "title": "Natürliche Kopfbewegung",
+        "tremor_intensity": {
+          "title": "Zittern",
+          "desc": "Wie stark dein Kopf ständig leicht zittert."
+        },
+        "micro_intensity": {
+          "title": "Mikrobewegungen",
+          "desc": "Wie weit sich dein Kopf bei einer kleinen Korrektur bewegt."
+        },
+        "posture_intensity": {
+          "title": "Haltungswechsel",
+          "desc": "Wie weit sich dein Kopf verschiebt, wenn er eine neue Haltung einnimmt: geneigt, nach vorn oder zur Seite gelehnt."
+        },
+        "posture_interval": {
+          "title": "Haltungsintervall",
+          "desc": "Wie lange dein Kopf ungefähr eine Haltung hält, bevor er eine neue einnimmt."
+        },
+        "steering_tilt": {
+          "title": "Neigung beim Lenken",
+          "desc": "Wie stark sich dein Kopf beim Lenken in die Kurve neigt."
+        }
       }
     },
     "manual": {

localization/en.json

@@ -81,6 +81,8 @@
   },
   "settings": {
     "enabled_desc": "Turn this effect on or off.",
+    "paused_by": "Paused by {effects}.",
+    "pauses": "When enabled, this pauses the following effect(s):",
     "driving": {
       "title": "Driving",
       "head_motion": {
@@ -235,6 +237,29 @@
           "title": "Duration",
           "desc": "How long the start-up shudder lasts. The stop shudder is shorter and gentler than this."
         }
+      },
+      "natural_head_movement": {
+        "title": "Natural Head Movement",
+        "tremor_intensity": {
+          "title": "Tremor",
+          "desc": "How much your head trembles slightly, all the time."
+        },
+        "micro_intensity": {
+          "title": "Micro-Adjustments",
+          "desc": "How far your head moves when it makes a small adjustment."
+        },
+        "posture_intensity": {
+          "title": "Posture Changes",
+          "desc": "How far your head shifts when it settles into a new position: tilted, leaning forward or to one side."
+        },
+        "posture_interval": {
+          "title": "Posture Interval",
+          "desc": "About how long your head holds a position before settling into a new one."
+        },
+        "steering_tilt": {
+          "title": "Steering Tilt",
+          "desc": "How much your head tilts into the turn as you turn the steering wheel."
+        }
       }
     },
     "manual": {

localization/es.json

@@ -81,6 +81,8 @@
   },
   "settings": {
     "enabled_desc": "Activa o desactiva este efecto.",
+    "paused_by": "En pausa por {effects}.",
+    "pauses": "Al activarlo, pausa el/los siguiente(s) efecto(s):",
     "driving": {
       "title": "Conducción",
       "head_motion": {
@@ -235,6 +237,29 @@
           "title": "Duración",
           "desc": "Cuánto dura la sacudida de arranque. La de parada es más corta y suave."
         }
+      },
+      "natural_head_movement": {
+        "title": "Movimiento natural de cabeza",
+        "tremor_intensity": {
+          "title": "Temblor",
+          "desc": "Cuánto tiembla ligeramente tu cabeza, todo el tiempo."
+        },
+        "micro_intensity": {
+          "title": "Microajustes",
+          "desc": "Cuánto se mueve tu cabeza al hacer un pequeño ajuste."
+        },
+        "posture_intensity": {
+          "title": "Cambios de postura",
+          "desc": "Cuánto se desplaza tu cabeza al adoptar una nueva posición: inclinada, hacia delante o hacia un lado."
+        },
+        "posture_interval": {
+          "title": "Intervalo de postura",
+          "desc": "Cuánto tiempo aproximadamente mantiene tu cabeza una posición antes de adoptar otra."
+        },
+        "steering_tilt": {
+          "title": "Inclinación al girar",
+          "desc": "Cuánto se inclina tu cabeza hacia el interior de la curva al girar el volante."
+        }
       }
     },
     "manual": {

localization/fr.json

@@ -81,6 +81,8 @@
   },
   "settings": {
     "enabled_desc": "Active ou désactive cet effet.",
+    "paused_by": "Mis en pause par {effects}.",
+    "pauses": "Une fois activé, cet effet met en pause le(s) effet(s) suivant(s) :",
     "driving": {
       "title": "Conduite",
       "head_motion": {
@@ -235,6 +237,29 @@
           "title": "Durée",
           "desc": "Durée de la secousse au démarrage. Celle de l'arrêt est plus courte et plus douce."
         }
+      },
+      "natural_head_movement": {
+        "title": "Mouvement de tête naturel",
+        "tremor_intensity": {
+          "title": "Tremblement",
+          "desc": "À quel point votre tête tremble légèrement, en permanence."
+        },
+        "micro_intensity": {
+          "title": "Micro-ajustements",
+          "desc": "À quel point votre tête bouge lors d'un petit ajustement."
+        },
+        "posture_intensity": {
+          "title": "Changements de posture",
+          "desc": "À quel point votre tête se déplace quand elle prend une nouvelle position : penchée, avancée ou décalée sur un côté."
+        },
+        "posture_interval": {
+          "title": "Intervalle de posture",
+          "desc": "Combien de temps environ votre tête garde une position avant d'en prendre une nouvelle."
+        },
+        "steering_tilt": {
+          "title": "Inclinaison au volant",
+          "desc": "À quel point votre tête s'incline vers l'intérieur du virage quand vous tournez le volant."
+        }
       }
     },
     "manual": {

localization/it.json

@@ -81,6 +81,8 @@
   },
   "settings": {
     "enabled_desc": "Attiva o disattiva questo effetto.",
+    "paused_by": "In pausa a causa di {effects}.",
+    "pauses": "Se attivo, mette in pausa i seguenti effetti:",
     "driving": {
       "title": "Guida",
       "head_motion": {
@@ -235,6 +237,29 @@
           "title": "Durata",
           "desc": "Quanto dura lo scossone all'avvio. Quello all'arresto è più breve e più dolce."
         }
+      },
+      "natural_head_movement": {
+        "title": "Movimento naturale della testa",
+        "tremor_intensity": {
+          "title": "Tremore",
+          "desc": "Quanto la tua testa trema leggermente, in ogni momento."
+        },
+        "micro_intensity": {
+          "title": "Microaggiustamenti",
+          "desc": "Quanto si muove la tua testa durante un piccolo aggiustamento."
+        },
+        "posture_intensity": {
+          "title": "Cambi di postura",
+          "desc": "Quanto si sposta la tua testa quando assume una nuova posizione: inclinata, in avanti o di lato."
+        },
+        "posture_interval": {
+          "title": "Intervallo di postura",
+          "desc": "Per quanto tempo circa la tua testa mantiene una posizione prima di assumerne una nuova."
+        },
+        "steering_tilt": {
+          "title": "Inclinazione in sterzata",
+          "desc": "Quanto la tua testa si inclina verso l'interno della curva quando giri il volante."
+        }
       }
     },
     "manual": {

localization/ja.json

@@ -81,6 +81,8 @@
   },
   "settings": {
     "enabled_desc": "このエフェクトのオン/オフを切り替えます。",
+    "paused_by": "{effects}により一時停止中です。",
+    "pauses": "オンにすると、次のエフェクトを一時停止します：",
     "driving": {
       "title": "運転",
       "head_motion": {
@@ -235,6 +237,29 @@
           "title": "長さ",
           "desc": "始動時の揺れが続く時間。停止時の揺れはこれより短く穏やかです。"
         }
+      },
+      "natural_head_movement": {
+        "title": "自然な頭の動き",
+        "tremor_intensity": {
+          "title": "微振動",
+          "desc": "頭が常にわずかに揺れる量です。"
+        },
+        "micro_intensity": {
+          "title": "微調整",
+          "desc": "頭が小さく調整するときの動きの大きさです。"
+        },
+        "posture_intensity": {
+          "title": "姿勢の変化",
+          "desc": "頭が新しい姿勢に移るときの動きの大きさです（傾ける、前に乗り出す、横に寄るなど）。"
+        },
+        "posture_interval": {
+          "title": "姿勢の間隔",
+          "desc": "頭が新しい姿勢に移るまで、ひとつの姿勢を保つおおよその時間です。"
+        },
+        "steering_tilt": {
+          "title": "ハンドル操作時の傾き",
+          "desc": "ハンドルを切ったときに頭がカーブの内側へ傾く量です。"
+        }
       }
     },
     "manual": {

localization/ko.json

@@ -81,6 +81,8 @@
   },
   "settings": {
     "enabled_desc": "이 효과를 켜거나 끕니다.",
+    "paused_by": "{effects}에 의해 일시 정지되었습니다.",
+    "pauses": "켜면 다음 효과를 일시 정지합니다:",
     "driving": {
       "title": "주행",
       "head_motion": {
@@ -235,6 +237,29 @@
           "title": "지속 시간",
           "desc": "시동 떨림이 지속되는 시간입니다. 정지 떨림은 이보다 짧고 부드럽습니다."
         }
+      },
+      "natural_head_movement": {
+        "title": "자연스러운 머리 움직임",
+        "tremor_intensity": {
+          "title": "떨림",
+          "desc": "머리가 항상 살짝 떨리는 정도입니다."
+        },
+        "micro_intensity": {
+          "title": "미세 조정",
+          "desc": "머리가 작게 조정할 때 움직이는 정도입니다."
+        },
+        "posture_intensity": {
+          "title": "자세 변화",
+          "desc": "머리가 새 자세로 바뀔 때 움직이는 정도입니다: 기울이기, 앞으로 숙이기, 한쪽으로 기대기."
+        },
+        "posture_interval": {
+          "title": "자세 간격",
+          "desc": "머리가 새 자세로 바꾸기 전에 한 자세를 유지하는 대략적인 시간입니다."
+        },
+        "steering_tilt": {
+          "title": "핸들 기울기",
+          "desc": "핸들을 돌릴 때 머리가 커브 안쪽으로 기우는 정도입니다."
+        }
       }
     },
     "manual": {