Merge pull request #5 from GoetzDeBouville/dev

update docs

Author: GoetzDeBouville

README.MD

@@ -17,9 +17,15 @@ Inspired by [PhysicsLayout](https://github.com/Jawnnypoo/PhysicsLayout/).
 
 ## Demo Screencast
 
-[![Android demo](demoVideo/android_demo.gif)](demoVideo/android_demo.mp4)
-[![Desktop demo 1](demoVideo/desktop_demo0.gif)](demoVideo/desktop_demo0.mp4)
-[![Desktop demo 2](demoVideo/desktop_demo2.gif)](demoVideo/desktop_demo2.mp4)
+<a href="demoVideo/android_demo.mp4">
+  <img src="demoVideo/android_demo.gif" alt="PhysicsBox Demo Android" width="15%" />
+</a>
+<a href="demoVideo/desktop_demo0.mp4">
+  <img src="demoVideo/desktop_demo0.gif" alt="PhysicsBox Demo Desktop" width="47%" />
+</a>
+<a href="demoVideo/desktop_demo2.mp4">
+  <img src="demoVideo/desktop_demo2.gif" alt="PhysicsBox Demo2 Desktop" width="47%" />
+</a>
 
 ## Quick Start
 

docs/concepts.md

@@ -39,6 +39,21 @@ Update it using `PhysicsBoxState.updateGravity(...)`.
 ## Boundaries
 `BoundariesConfig` creates static walls around the container. This keeps bodies inside the visible area and lets you control restitution/friction at the edges.
 
+!!! note "Boundary tunneling"
+    - Bodies can tunnel through boundaries when they cross a wall between simulation steps or when
+      the solver cannot resolve a deep overlap with a wall in time.
+    - Tunneling is more likely with thin walls, high velocity/impulse, strong drag or fling, large
+      gravity, low step frequency, low solver iterations, or bodies marked as non-bullet.
+    - Tunneling can also happen when large bodies are spawned at `(0, 0)` or near/outside the
+      container edge, because they can start intersecting the wall or already be partially beyond it.
+    - Spawning many bodies in the same point can create large overlap-correction impulses that push
+      bodies through boundaries.
+    - Increase `BoundariesConfig.thicknessPx` for larger or faster bodies, and use
+      `PhysicsBodyConfig.isBullet` for bodies that can move quickly.
+    - Use `PhysicsTransform` to spawn bodies away from walls and avoid initial intersections with
+      boundaries or other bodies. For multiple bodies, distribute their initial transforms instead of
+      placing all of them at the same position.
+
 ## Units and coordinate system
 - Screen‑oriented axes: **+X right**, **+Y down**