Add documentation for collision detection and mesh classes

Co-authored-by: orange-cpp <59374393+orange-cpp@users.noreply.github.com>

docs/engines/source_engine/mesh_trait.md

@@ -0,0 +1,182 @@
+# `omath::source_engine::MeshTrait` — mesh transformation trait for Source Engine
+
+> Header: `omath/engines/source_engine/traits/mesh_trait.hpp`
+> Namespace: `omath::source_engine`
+> Purpose: provide Source Engine-specific rotation matrix computation for `omath::primitives::Mesh`
+
+---
+
+## Summary
+
+`MeshTrait` is a trait class that provides the `rotation_matrix` function for transforming meshes in Source Engine's coordinate system. It serves as a template parameter to `omath::primitives::Mesh`, enabling engine-specific rotation behavior.
+
+---
+
+## Coordinate System
+
+**Source Engine** uses:
+* **Up axis**: +Z
+* **Forward axis**: +Y
+* **Right axis**: +X
+* **Handedness**: Right-handed
+* **Rotation order**: Pitch (X) → Yaw (Z) → Roll (Y)
+
+---
+
+## API
+
+```cpp
+namespace omath::source_engine {
+
+class MeshTrait final {
+public:
+    [[nodiscard]]
+    static Mat4X4 rotation_matrix(const ViewAngles& rotation);
+};
+
+} // namespace omath::source_engine
+```
+
+---
+
+## Method: `rotation_matrix`
+
+```cpp
+static Mat4X4 rotation_matrix(const ViewAngles& rotation);
+```
+
+Computes a 4×4 rotation matrix from Source Engine-style Euler angles.
+
+**Parameters**:
+* `rotation` — `ViewAngles` containing pitch, yaw, and roll angles
+
+**Returns**: 4×4 rotation matrix suitable for mesh transformation
+
+**Implementation**: Delegates to `source_engine::rotation_matrix(rotation)` defined in `formulas.hpp`.
+
+---
+
+## Usage
+
+### With Mesh
+
+```cpp
+using namespace omath::source_engine;
+
+// Create mesh (MeshTrait is used automatically)
+Mesh my_mesh(vertices, indices);
+
+// Set rotation using ViewAngles
+ViewAngles angles;
+angles.pitch = PitchAngle::from_degrees(30.0f);
+angles.yaw = YawAngle::from_degrees(45.0f);
+angles.roll = RollAngle::from_degrees(0.0f);
+
+my_mesh.set_rotation(angles);
+
+// The rotation matrix is computed using MeshTrait::rotation_matrix
+auto matrix = my_mesh.get_to_world_matrix();
+```
+
+### Direct Usage
+
+```cpp
+using namespace omath::source_engine;
+
+ViewAngles angles;
+angles.pitch = PitchAngle::from_degrees(45.0f);
+angles.yaw = YawAngle::from_degrees(90.0f);
+angles.roll = RollAngle::from_degrees(0.0f);
+
+Mat4X4 rot_matrix = MeshTrait::rotation_matrix(angles);
+
+// Use the matrix directly
+Vector3<float> local_point{1, 0, 0};
+auto rotated = rot_matrix * mat_column_from_vector(local_point);
+```
+
+---
+
+## Rotation Conventions
+
+The rotation matrix is built following Source Engine's conventions:
+
+1. **Pitch** (rotation around X-axis / right axis)
+   * Positive pitch looks upward (+Z direction)
+   * Range: typically [-89°, 89°]
+
+2. **Yaw** (rotation around Z-axis / up axis)
+   * Positive yaw rotates counterclockwise when viewed from above
+   * Range: [-180°, 180°]
+
+3. **Roll** (rotation around Y-axis / forward axis)
+   * Positive roll tilts right
+   * Range: [-180°, 180°]
+
+**Composition**: The matrices are combined in the order Pitch × Yaw × Roll, producing a rotation that:
+* First applies roll around the forward axis
+* Then applies yaw around the up axis
+* Finally applies pitch around the right axis
+
+This matches Source Engine's internal rotation order.
+
+---
+
+## Related Functions
+
+The trait delegates to the formula defined in `formulas.hpp`:
+
+```cpp
+[[nodiscard]]
+Mat4X4 rotation_matrix(const ViewAngles& angles) noexcept;
+```
+
+See [Formulas Documentation](formulas.md) for details on the rotation matrix computation.
+
+---
+
+## Type Alias
+
+The Source Engine mesh type is pre-defined:
+
+```cpp
+namespace omath::source_engine {
+    using Mesh = primitives::Mesh<Mat4X4, ViewAngles, MeshTrait, float>;
+}
+```
+
+Use this alias to ensure correct trait usage:
+
+```cpp
+using namespace omath::source_engine;
+
+// Correct: uses Source Engine trait
+Mesh my_mesh(vbo, vao);
+
+// Avoid: manually specifying template parameters
+primitives::Mesh<Mat4X4, ViewAngles, MeshTrait, float> verbose_mesh(vbo, vao);
+```
+
+---
+
+## Notes
+
+* **Angle ranges**: Ensure angles are within valid ranges (pitch: [-89°, 89°], yaw/roll: [-180°, 180°])
+* **Performance**: Matrix computation is O(1) with ~64 floating-point operations
+* **Caching**: The mesh caches the transformation matrix; recomputed only when rotation changes
+* **Compatibility**: Works with all Source Engine games (CS:GO, TF2, Portal, Half-Life 2, etc.)
+
+---
+
+## See Also
+
+- [Mesh Documentation](../../3d_primitives/mesh.md) - Mesh primitive using this trait
+- [MeshCollider Documentation](../../collision/mesh_collider.md) - Collision wrapper for meshes
+- [Formulas Documentation](formulas.md) - Source Engine rotation formula
+- [CameraTrait Documentation](camera_trait.md) - Camera transformation trait
+- [Constants Documentation](constants.md) - Source Engine constants
+- [API Overview](../../api_overview.md) - High-level API reference
+
+---
+
+*Last updated: 13 Nov 2025*