proejct commit

docs/PHYSICS.md

@@ -0,0 +1,475 @@
+# Physik der Sandbox
+
+Dieses Dokument erklärt, *was* die Physik-Engine berechnet und *warum* sie es so tut. Alle
+Formeln finden sich im Code wieder, meist mit derselben Bezeichnung. Die Zahlenwerte stehen
+in [`src/sandbox/config.py`](../src/sandbox/config.py) (`PhysicsConfig`).
+
+Die Physik-Schicht (`src/sandbox/physics/`) verwendet ausschließlich das Standardmodul
+`math` sowie `typing`/`dataclasses` für Typangaben. Ein Architektur-Test stellt sicher,
+dass dort nie pygame importiert wird.
+
+## Inhalt
+
+1. [Einheiten und Koordinaten](#1-einheiten-und-koordinaten)
+2. [Körper: Masse und Trägheit](#2-körper-masse-und-trägheit)
+3. [Integration mit festem Zeitschritt](#3-integration-mit-festem-zeitschritt)
+4. [Ablauf eines Simulationsschritts](#4-ablauf-eines-simulationsschritts)
+5. [Kollisionserkennung](#5-kollisionserkennung)
+6. [Impulsbasierte Kollisionsauflösung](#6-impulsbasierte-kollisionsauflösung)
+7. [Restitution (Elastizität)](#7-restitution-elastizität)
+8. [Reibung und Rollen](#8-reibung-und-rollen)
+9. [Rollwiderstand](#9-rollwiderstand)
+10. [Positionskorrektur](#10-positionskorrektur)
+11. [Ruhe ohne Zittern: Schlafmodus](#11-ruhe-ohne-zittern-schlafmodus)
+12. [Tunneln verhindern](#12-tunneln-verhindern)
+13. [Ziehen und Werfen](#13-ziehen-und-werfen)
+14. [Parameterübersicht](#14-parameterübersicht)
+
+---
+
+## 1. Einheiten und Koordinaten
+
+| Größe | Einheit |
+|---|---|
+| Länge | Pixel (px) |
+| Zeit | Sekunde (s) |
+| Geschwindigkeit | px/s |
+| Masse | Fläche × Dichte (px² · Dichte; nur Verhältnisse zählen) |
+
+Der Ursprung liegt oben links in der Welt, **x zeigt nach rechts, y nach unten** – wie auf
+dem Bildschirm. Die Schwerkraft ist deshalb `g = (0, +980) px/s²`; bei einem Maßstab von
+100 px pro Meter entspricht das 9,8 m/s².
+
+Weil y nach unten zeigt, bedeutet ein positiver Drehwinkel eine Drehung **im
+Uhrzeigersinn** auf dem Bildschirm. Die Formeln sind davon unabhängig, solange man
+konsequent `a × b = a.x·b.y − a.y·b.x` verwendet.
+
+## 2. Körper: Masse und Trägheit
+
+Jeder Körper (`Body`) hat eine Form, eine Position (Schwerpunkt), eine Geschwindigkeit und
+bei Kreisen zusätzlich Winkel und Winkelgeschwindigkeit.
+
+**Masse = Fläche × Dichte.** Damit sind größere Körper bei gleicher Dichte schwerer:
+
+| Form | Fläche | Trägheitsmoment |
+|---|---|---|
+| Kreis (Radius r) | `π·r²` | `I = ½·m·r²` (homogene Scheibe) |
+| Rechteck (halbe Kanten hw, hh) | `4·hw·hh` | unendlich (dreht nie) |
+
+Herleitung des Scheiben-Trägheitsmoments: Die Scheibe zerfällt in dünne Ringe mit Radius s
+und Masse `dm = m/(π·r²) · 2π·s·ds`. Jeder Ring trägt `s²·dm` bei:
+
+```text
+I = (2m / r²) · ∫₀ʳ s³ ds = (2m / r²) · r⁴/4 = ½·m·r²
+```
+
+Rechtecke sind laut Aufgabenstellung **achsenparallel**. Ein unendliches Trägheitsmoment
+(also `1/I = 0`) garantiert, dass kein Drehimpuls sie jemals drehen kann.
+
+**Inverse Massen.** Gespeichert werden zusätzlich `1/m` und `1/I`. Wände haben `1/m = 0`
+(unendliche Masse). So passen bewegliche und unbewegliche Körper ohne Sonderfälle in
+dieselben Formeln: Ein Impuls P ändert die Geschwindigkeit um `P/m` – bei einer Wand um 0.
+
+## 3. Integration mit festem Zeitschritt
+
+### Semi-impliziter Euler
+
+Pro Schritt `dt = 1/120 s`:
+
+```text
+v ← v + g·dt          (zuerst die Geschwindigkeit …)
+x ← x + v·dt          (… dann die Position mit der NEUEN Geschwindigkeit)
+θ ← θ + ω·dt
+```
+
+Der explizite Euler (Position mit der *alten* Geschwindigkeit) gewinnt bei Schwingungen und
+Umlaufbahnen systematisch Energie und wird instabil. Der semi-implizite (symplektische)
+Euler kostet genauso wenig, bleibt aber energetisch stabil.
+
+Für den freien Fall ergibt sich nach n Schritten exakt `v = n·g·dt` und
+`s = g·dt²·n(n+1)/2`. Das weicht nur um den Faktor `(1 + 1/n)` vom analytischen
+`s = ½·g·t²` ab; nach 0,5 s sind das 1,7 %. Genau diese Beziehung prüft ein Test.
+
+### Fester Zeitschritt, entkoppelt von der Bildrate
+
+Die Stabilität hängt von `dt` ab. Mit der schwankenden Frame-Dauer als `dt` würde sich die
+Simulation auf jedem Rechner anders verhalten. Ein Ruckler von 200 ms ließe Körper außerdem
+durch andere hindurchspringen. Deshalb sammelt ein Akkumulator (`FixedTimestep`) die real
+vergangene Zeit und gibt sie in festen Portionen weiter:
+
+```text
+akkumulator += frame_zeit
+while akkumulator ≥ dt:  world.step(dt);  akkumulator −= dt
+alpha = akkumulator / dt                  (Rest für die Interpolation)
+```
+
+- **Obergrenze** `max_steps_per_frame`: Schafft der Rechner die Physik nicht in Echtzeit,
+  wird der Rückstand verworfen, statt ihn endlos mitzuschleppen ("Spiral of Death").
+- **Interpolation:** Gezeichnet wird `lerp(vorige_position, position, alpha)`. Die Physik
+  läuft mit 120 Hz, der Bildschirm z. B. mit 60 Hz – ohne Interpolation ruckelt die
+  Bewegung sichtbar.
+
+## 4. Ablauf eines Simulationsschritts
+
+`World.step(dt)` führt nacheinander aus:
+
+```mermaid
+flowchart TD
+    A[Zustand merken<br/>für Interpolation] --> B[Geschwindigkeiten integrieren<br/>v += g·dt]
+    B --> C[Broadphase<br/>Sweep-and-Prune]
+    C --> D[Narrowphase<br/>Kontakte Körper–Körper]
+    D --> E[Berührte Schläfer wecken]
+    E --> F[Wandkontakte]
+    F --> G[Impulse lösen<br/>Normale · Reibung · Rollwiderstand]
+    G --> H[Geschwindigkeit begrenzen]
+    H --> I[Positionen integrieren<br/>x += v·dt]
+    I --> J[Positionskorrektur]
+    J --> K[Notbremse an den Wänden]
+    K --> L[Schlafmodus aktualisieren]
+```
+
+Vor jedem Schritt setzt die Anwendung die Geschwindigkeit eines gezogenen Körpers
+(siehe [Abschnitt 13](#13-ziehen-und-werfen)).
+
+## 5. Kollisionserkennung
+
+Jede Prüfung liefert einen **Kontakt** mit
+
+- **Normale n** – Einheitsvektor von Körper A zu Körper B,
+- **Eindringtiefe** – Überlappung entlang n (≥ 0),
+- **Kontaktpunkt** – Angriffspunkt der Kräfte.
+
+### Broadphase: Sweep-and-Prune
+
+Alle Paare genau zu prüfen kostet n·(n−1)/2 Tests – bei 150 Körpern über 11 000 pro
+Schritt. Deshalb werden die umschließenden Boxen nach ihrer linken Kante sortiert. Für jede
+Box müssen nur die Nachfolger geprüft werden, die links von ihrer rechten Kante beginnen.
+Der Aufwand sinkt auf etwa O(n·log n + k) für k benachbarte Paare. Paare aus zwei
+schlafenden Körpern werden übersprungen.
+
+### Kreis–Kreis
+
+```text
+d = |p_B − p_A|,   Kontakt, wenn d ≤ r_A + r_B
+n = (p_B − p_A) / d,   Tiefe = r_A + r_B − d
+```
+
+Der Kontaktpunkt liegt in der Mitte des Überlappungsbereichs. Liegen die Mittelpunkte exakt
+aufeinander, ist die Richtung unbestimmt. Dann wird die feste Ersatznormale (0, −1)
+verwendet, statt durch 0 zu teilen.
+
+### Kreis–Rechteck
+
+Den Kreismittelpunkt (relativ zum Rechteck) komponentenweise auf das Rechteck klemmen. Das
+liefert den nächstgelegenen Punkt q des Rechtecks:
+
+```text
+q = (clamp(dx, −hw, hw), clamp(dy, −hh, hh))
+Kontakt, wenn |Mittelpunkt − q| ≤ r
+```
+
+Sonderfall: Liegt der Kreismittelpunkt *im* Rechteck, ist q der Mittelpunkt selbst und
+liefert keine Richtung. Dann wird der Kreis über die nächstgelegene Kante hinausgeschoben;
+die Tiefe ist Radius + Abstand zu dieser Kante.
+
+### Rechteck–Rechteck
+
+Zwei achsenparallele Rechtecke überlappen genau dann, wenn sich ihre Projektionen auf
+**beide** Achsen überlappen (Trennachsensatz):
+
+```text
+overlap_x = hw_A + hw_B − |dx|,   overlap_y = hh_A + hh_B − |dy|
+```
+
+Getrennt wird entlang der Achse mit der kleineren Überlappung – das ist der kürzeste Weg
+aus der Durchdringung. Bei Gleichstand gewinnt die y-Achse, weil aufeinanderliegende Körper
+der häufigste Fall sind.
+
+### Wände als Halbebenen
+
+Boden, Decke und Seiten sind Halbebenen `n·p ≥ offset` (die Normale zeigt in die Welt).
+Die Reichweite eines Rechtecks entlang n ist `|n.x|·hw + |n.y|·hh`, die eines Kreises r.
+Weil eine Halbebene unendlich dick ist, wird ein Körper **auch dann erkannt, wenn er in
+einem Schritt komplett hinter die Wandlinie springt** – er kann nicht hindurchtunneln.
+
+## 6. Impulsbasierte Kollisionsauflösung
+
+### Herleitung des Kollisionsimpulses
+
+Relativgeschwindigkeit des Kontaktpunkts (B relativ zu A), mit den Hebelarmen r vom
+Schwerpunkt zum Kontaktpunkt und `ω × r = ω·(−r.y, r.x)`:
+
+```text
+v_rel = (v_B + ω_B × r_B) − (v_A + ω_A × r_A),        v_n = v_rel · n
+```
+
+`v_n < 0` bedeutet: Die Körper nähern sich an. Ein Impuls `P = λ·n` wirkt auf B positiv und
+auf A negativ (actio = reactio):
+
+```text
+v_A' = v_A − λ·n/m_A        ω_A' = ω_A − (r_A × λn)/I_A
+v_B' = v_B + λ·n/m_B        ω_B' = ω_B + (r_B × λn)/I_B
+```
+
+Eingesetzt ändert sich die Normalgeschwindigkeit linear in λ:
+
+```text
+v_n' = v_n + λ·K,     K = 1/m_A + 1/m_B + (r_A × n)²/I_A + (r_B × n)²/I_B
+```
+
+Aus Newtons Stoßgesetz `v_n' = −e·v_n` folgt:
+
+```text
+λ = −(1 + e) · v_n / K
+```
+
+`1/K` ist die **effektive Masse** des Kontakts – die träge Masse, die der Stoß entlang n
+"spürt". Für einen einzelnen zentralen Stoß erhält diese Formel den Gesamtimpuls exakt und
+liefert die Lehrbuchergebnisse. Beim elastischen Stoß zweier Kreise mit Massenverhältnis
+1 : 3 und Geschwindigkeiten 200 bzw. −100 px/s kommen zum Beispiel exakt −250 und 50 px/s
+heraus. Ein Test prüft das.
+
+**Besonderheit dieser Engine:** Bei Kreisen geht die Normale durch den Mittelpunkt
+(r ∥ n, also r × n = 0), und Rechtecke drehen sich nie (1/I = 0). Die Drehterme von K
+verschwinden daher für die Normale – **Normalimpulse erzeugen kein Drehmoment**. Nur die
+Reibung bringt Kreise ins Rollen.
+
+### Viele Kontakte: Sequential Impulses
+
+Liegt ein Körper auf mehreren anderen, beeinflussen sich die Kontakte gegenseitig. Statt
+ein Gleichungssystem zu lösen, werden die Kontakte reihum mehrfach aufgelöst
+(Gauß-Seidel, `velocity_iterations = 8`). Zwei Details machen das Verfahren korrekt und
+stabil:
+
+1. **Akkumulierte Impulse klemmen.** Geklemmt wird der über alle Durchläufe *summierte*
+   Impuls (`P_n ≥ 0`), nicht der Teilimpuls eines Durchlaufs. Ein späterer Durchlauf darf
+   einen zu großen früheren Impuls also wieder zurücknehmen. Das Verfahren konvergiert so
+   gegen die physikalische Lösung, in der Kontakte nur drücken und nie ziehen.
+2. **Warm-Starting.** Die akkumulierten Impulse des vorigen Schritts werden zu Beginn erneut
+   angewendet. Ruhende Kontakte ändern sich kaum, der Startwert ist also schon fast richtig –
+   Stapel stehen dadurch nach wenigen Durchläufen stabil. Hat sich die Normale stark
+   gedreht (Skalarprodukt < 0,95), wird der alte Impuls verworfen.
+
+Reihenfolge je Kontakt und Durchlauf: **Normale → Reibung → Rollwiderstand.** Reibung und
+Rollwiderstand sind durch den Normalimpuls begrenzt. Werden sie danach gelöst, gelten ihre
+Grenzen nach jedem Durchlauf exakt für den aktuellen Normalimpuls.
+
+## 7. Restitution (Elastizität)
+
+Die Stoßzahl `e ∈ [0, 1]` ist das Verhältnis von Trenn- zu Aufprallgeschwindigkeit:
+`e = 0` völlig unelastisch, `e = 1` vollkommen elastisch.
+
+- **Energieverlust:** Beim zentralen Stoß geht `ΔE = ½·μ·(1 − e²)·v_rel²` verloren
+  (μ = m_A·m_B/(m_A + m_B), die reduzierte Masse). Ein Test prüft genau diesen Wert.
+- **Sprunghöhe:** Ein fallender Ball erreicht nach dem Aufprall `e²` seiner Fallhöhe
+  (Energie ∝ v²).
+- **Mischregel:** `e = max(e_A, e_B)` – ein Gummiball springt auch von einem Holzklotz
+  ab. Wände haben `e = 0`, sodass allein das Material des Körpers zählt.
+- **Schwellwert (`restitution_threshold` = 50 px/s):** Unterhalb dieser
+  Aufprallgeschwindigkeit wird nicht abgeprallt. Sonst würden aufliegende Körper durch
+  winzige Dauer-Hüpfer zittern.
+- **Aufprallgeschwindigkeit vom Schrittbeginn:** `v_n` wird aus den Geschwindigkeiten *vor*
+  Schwerkraft und Warm-Starting bestimmt (`Body.previous_velocity`). Nähme man die
+  Geschwindigkeit nach der Schwerkraft, prallte ein Ball mit `e·(v + g·dt)` statt `e·v` ab.
+  Ein vollkommen elastischer Ball (e = 1) gewönne dann mit jedem Aufprall Höhe – Energie
+  aus dem Nichts. So springt er dagegen immer wieder genau auf seine Fallhöhe; ein Test
+  prüft das über mehrere Sprünge.
+- **Gehaltene Körper prallen nicht ab:** Die Hand fängt den Stoß ab. Andernfalls würde ein
+  gegen ein Hindernis gedrückter Körper in jedem Schritt zurückprallen, sofort wieder
+  herangezogen werden und dabei sichtbar zittern.
+
+## 8. Reibung und Rollen
+
+**Coulomb-Reibung:** Entlang der Tangente `t = (−n.y, n.x)` soll die Gleitgeschwindigkeit
+verschwinden. Der Reibungsimpuls ist aber begrenzt:
+
+```text
+|P_t| ≤ μ · P_n
+```
+
+Reicht die Grenze, haften die Körper (Haftreibung). Sonst rutschen sie mit konstanter
+Verzögerung `μ·g` (Gleitreibung): Eine Box mit 300 px/s kommt nach `v²/(2μg)` zum Stehen.
+Gemischt wird mit dem geometrischen Mittel `μ = √(μ_A·μ_B)` – ein glatter Partner macht
+den Kontakt glatt.
+
+**Rollen:** Der Reibungsimpuls greift am Kontaktpunkt an, nicht im Schwerpunkt. Bei Kreisen
+erzeugt er daher ein Drehmoment `r × P_t`, die effektive Masse enthält den Term
+`(r × t)²/I`. Eine rutschende Scheibe wird gebremst und zugleich in Drehung versetzt, bis
+die Rollbedingung `v = ω·r` gilt. Drehimpulserhaltung um den Kontaktpunkt liefert die
+Endgeschwindigkeit – unabhängig vom Reibwert:
+
+```text
+v_end = v₀ / (1 + I/(m·r²)) = v₀ / 1,5 = ⅔ · v₀
+```
+
+Auch das prüft ein Test. Damit man die Drehung sieht, zeichnet der Renderer in jeden Kreis
+einen Radius-Strich.
+
+## 9. Rollwiderstand
+
+Reines Rollen verbraucht keine Reibungsenergie – ein rollender Kreis würde ewig rollen. Ein
+Rechteck auf einem kleinen Kreis führe darauf wie auf einer Rolle davon. Real verformen sich
+Kreis und Unterlage ein wenig, was ein bremsendes Moment erzeugt:
+
+```text
+M ≤ μ_r · N · r        (μ_r = rolling_resistance = 0,1)
+```
+
+Pro Schritt entspricht das einem Drehimpuls `≤ μ_r · P_n · r`. Umgesetzt ist das wie die
+Reibung: als begrenzter Impuls, hier aber auf die relative Winkelgeschwindigkeit
+`ω_B − ω_A`, mit der effektiven Masse `1/(1/I_A + 1/I_B)`. Weil die Grenze mit der
+Normalkraft wächst, kommen schwer belastete "Rollen" schnell zur Ruhe, während ein frei
+rollender Ball weit rollt.
+
+Für einen rollenden Ball ergibt sich eine konstante Verzögerung:
+
+```text
+a = μ_r·g / (1 + I/(m·r²)) = μ_r·g / 1,5 ≈ 65 px/s²
+```
+
+Ein Ball mit 200 px/s rollt so etwa 300 px weit. Der Test misst genau diese Verzögerung.
+
+## 10. Positionskorrektur
+
+Impulse korrigieren nur Geschwindigkeiten. Durch den diskreten Zeitschritt überlappen
+Körper trotzdem ein wenig: Ein fallender Körper "landet" meist schon etwas in der
+Unterlage. Ohne Korrektur würden Stapel langsam ineinander einsinken.
+
+Die Korrektur verschiebt die **Positionen** direkt ("Projektion"), im Verhältnis der
+inversen Massen:
+
+```text
+C = factor · max(Tiefe − slop, 0)        (höchstens max_position_correction)
+p_A −= n · C · (1/m_A) / (1/m_A + 1/m_B)
+p_B += n · C · (1/m_B) / (1/m_A + 1/m_B)
+```
+
+- **Warum Positionen statt Zusatzgeschwindigkeit (Baumgarte)?** Eine Geschwindigkeit, die
+  Körper auseinandertreibt, bleibt nach der Trennung erhalten und schleudert sie davon –
+  besonders bei großen Überlappungen, etwa wenn ein Objekt mitten in einen Haufen gesetzt
+  wird. Die Projektion erzeugt keine Bewegungsenergie.
+- **Slop (0,5 px):** Eine kleine Resttiefe bleibt stehen. So wird der Kontakt im nächsten
+  Schritt sicher wieder erkannt, statt ständig zwischen "Kontakt" und "kein Kontakt" zu
+  wechseln – auch das wäre sichtbares Zittern.
+- **Aktuelle Tiefe ohne erneute Kollisionsprüfung:** Tiefe bei der Erkennung minus die
+  seither erfolgte Relativverschiebung entlang n. Das ist exakt für Wände und Rechtecke und
+  eine sehr gute Näherung für Kreise.
+- **Notbremse:** Kein Körper darf mehr als `max_wall_penetration` (12 px) in eine Wand
+  ragen. Der Wert liegt bewusst über der größten Eindringtiefe, die ein frei fliegender
+  Körper in einem Schritt erreichen kann (`MAX_SPEED · dt ≈ 10,8 px`). Normale Aufpralle
+  löst deshalb immer der Solver; die Bremse greift nur in Extremfällen, etwa wenn ein
+  gezogenes Objekt einen Körper gegen die Wand quetscht. Würde sie schon bei normalen
+  Aufprallen greifen, verschöbe sie Positionen und fügte dabei Lageenergie hinzu.
+
+## 11. Ruhe ohne Zittern: Schlafmodus
+
+Ein Solver mit endlich vielen Iterationen hinterlässt immer winzige Restbewegungen. Ein
+Stapel "atmet" dadurch sichtbar oder kriecht. Deshalb werden ruhende Körper eingefroren:
+
+1. Jeder Körper zählt, wie lange er ununterbrochen fast stillsteht
+   (`|v| ≤ 4 px/s` und `|ω| ≤ 0,1 rad/s`).
+2. Körper, die sich direkt oder über andere berühren, bilden eine **Insel** (Union-Find über
+   die Kontakte). Wände verbinden keine Inseln, sonst wäre alles am Boden eine einzige Insel.
+3. Eine Insel schläft ein, wenn **alle** ihre Körper seit `time_to_sleep` (0,5 s) ruhen.
+   Jeder Körper merkt sich dabei seine Insel (`Body.sleep_island`).
+4. Schlafende Körper werden weder integriert noch aufgelöst – das spart auch Rechenzeit.
+5. **Aufwecken – immer die ganze Insel:** bei Berührung durch einen wachen, beweglichen
+   Körper, beim Greifen, beim Umschalten der Schwerkraft und wenn ein Körper der Insel
+   gelöscht wird.
+
+Warum Inseln statt einzelner Körper? Sonst könnte ein schlafender Körper unter einem wachen
+liegen. Der wache weckt ihn, beide ruhen, einer schläft früher ein, der andere weckt ihn
+wieder – ein endloses Hin und Her.
+
+Warum wacht die ganze Insel auf? Zwei schlafende Körper werden nicht auf Kontakte
+untereinander geprüft. Wird die unterste Kiste eines schlafenden Stapels geweckt und im
+selben Schritt weggestoßen – oder im Pausenmodus weggezogen –, bemerkte sonst niemand, dass
+die Kisten darüber ihre Stütze verloren haben. Sie schliefen in der Luft weiter. Weil alle
+Körper, die einander berühren, gemeinsam eingeschlafen sind, genügt es, ihre Insel
+gemeinsam zu wecken.
+
+Zusammen mit Schwellwert (Abschnitt 7), Slop (Abschnitt 10), Warm-Starting (Abschnitt 6)
+und Rollwiderstand (Abschnitt 9) kommen Stapel und Haufen vollständig zur Ruhe. Ein Test
+lässt 60 zufällige Körper fallen und verlangt, dass nach 8 s alle schlafen.
+
+**Grenze des Verfahrens:** Wie jeder Schlafmodus mit Geschwindigkeitsschwellen kann er
+eine Lage einfrieren, die kein echtes Gleichgewicht ist. Ein Beispiel: Ein Kreis liegt
+wenige Pixel außermittig auf einem anderen Kreis. Ist die Kontaktnormale steiler geneigt,
+als der Rollwiderstand hält (tan α > μ_r), rollt er ab. Anfangs so langsam, dass er
+0,5 s lang unter 4 px/s bleibt und einschläft. Er bleibt dann liegen, bis ihn etwas
+berührt, und rollt erst danach weiter. Die Auswirkung beschränkt sich auf wenige Pixel.
+Strengere Schwellen würden solche Fälle seltener machen, ließen dafür aber auch ruhende
+Haufen später einschlafen.
+
+## 12. Tunneln verhindern
+
+Die Kollisionserkennung ist diskret: Sie sieht nur die Positionen am Ende jedes Schritts.
+
+- **Wände** sind Halbebenen und damit ohnehin tunnelsicher (Abschnitt 5).
+- **Körper untereinander:** Fliegen zwei der kleinsten Körper (Radius `MIN_BODY_SIZE` =
+  12 px) frontal aufeinander zu, darf ihre Relativbewegung pro Schritt die Summe ihrer
+  Radien nicht übersteigen. Sonst springen die Mittelpunkte aneinander vorbei:
+
+  ```text
+  2·v·dt < 2·MIN_BODY_SIZE   ⇒   v < MIN_BODY_SIZE / dt = 1440 px/s
+  ```
+
+  Mit Sicherheitsfaktor 0,9 ergibt das `MAX_SPEED ≈ 1296 px/s`. Jede Geschwindigkeit wird
+  nach dem Lösen der Impulse darauf begrenzt, ebenso die Wurfgeschwindigkeit. Aus demselben
+  Grund ist bei Rechtecken keine *halbe* Kantenlänge kleiner als `MIN_BODY_SIZE`, jede
+  Seite ist also mindestens 24 px lang.
+- Auch die Winkelgeschwindigkeit ist begrenzt (`MAX_SPEED / MIN_BODY_SIZE`).
+
+## 13. Ziehen und Werfen
+
+Ein gezogener Körper wird **nicht** an die Mausposition teleportiert. Dann könnte er durch
+andere Körper und Wände hindurchgeschoben werden. Stattdessen setzt `DragController` vor
+jedem Physikschritt die Geschwindigkeit in Richtung Ziel:
+
+```text
+v = (Ziel − Position) · rate        (rate = 60/s; rate·dt ≤ 1 verhindert Überschwingen)
+```
+
+Danach löst der Solver die Kontakte ganz normal. Das gezogene Objekt **kollidiert also
+weiterhin**: Leichtere Körper werden weggeschoben, Wände und schwere Stapel bremsen es. Das
+Ziel wird so geklemmt, dass der Körper ganz in die Welt passt. Gehaltene Körper unterliegen
+keiner Schwerkraft ("die Hand trägt sie"), prallen nicht ab ("die Hand fängt den Stoß ab",
+siehe [Abschnitt 7](#7-restitution-elastizität)) und schlafen nie ein. Beim Greifen wird
+die Schlaf-Insel des Körpers geweckt.
+
+Folge der fehlenden Restitution: Schlägt man mit einem gehaltenen Objekt einen Ball, stößt
+es ihn wie ein unelastischer Schläger. Der Ball fliegt deshalb etwas langsamer davon als
+bei einem freien, elastischen Stoß (in einer Messung des Reviews um etwa 13 %). Dafür
+steht ein gegen ein Hindernis gedrücktes Objekt ruhig.
+
+**Werfen:** Beim Loslassen erhält der Körper die Mausgeschwindigkeit der letzten Frames.
+`VelocityTracker` glättet sie in zwei Stufen:
+
+1. **Zeitfenster:** mittlere Geschwindigkeit über die letzten 0,1 s (Weg / Zeit zwischen
+   ältester und neuester Probe) – unabhängig von der Bildrate.
+2. **Exponentielle Glättung:** `v ← v + (v_roh − v)·(1 − e^(−Δt/τ))` mit τ = 0,05 s. Der
+   Exponentialterm macht die Glättung ebenfalls bildratenunabhängig.
+
+Hält man die Maus vor dem Loslassen still, klingt die Geschwindigkeit schnell ab, und das
+Objekt fällt einfach herunter. Im Pausenmodus wird direkt verschoben und nicht geworfen.
+
+## 14. Parameterübersicht
+
+Alle Werte stehen in [`config.py`](../src/sandbox/config.py) und lassen sich dort anpassen.
+
+| Parameter | Wert | Bedeutung |
+|---|---|---|
+| `gravity` | (0, 980) px/s² | Schwerkraft |
+| `time_step` | 1/120 s | fester Zeitschritt |
+| `velocity_iterations` | 8 | Solver-Durchläufe pro Schritt |
+| `position_iterations` | 2 | Durchläufe der Positionskorrektur |
+| `restitution_threshold` | 50 px/s | darunter kein Abprallen |
+| `penetration_slop` | 0,5 px | geduldete Resttiefe |
+| `position_correction_factor` | 0,4 | Anteil der Korrektur pro Durchlauf |
+| `max_position_correction` | 6 px | Obergrenze der Korrektur pro Durchlauf |
+| `max_speed` | ≈ 1296 px/s | Tunnel-Schutz |
+| `rolling_resistance` | 0,1 | Rollwiderstandsbeiwert μ_r |
+| `sleep_linear_speed` / `sleep_angular_speed` | 4 px/s / 0,1 rad/s | Ruheschwellen |
+| `time_to_sleep` | 0,5 s | Ruhezeit bis zum Einschlafen |
+| `wall_friction` / `wall_restitution` | 0,6 / 0 | Wandmaterial |
+| `max_wall_penetration` | 12 px | Notbremse an den Wänden (> `MAX_SPEED · dt`) |