claudes_game/docs/planning/matrix-implementation-plan.md

Matrix Implementation Plan - 3D Orbital Rotations

Objective

Implement 3x3 rotation matrices in the physics module to support 3D orbital element orientation (inclination, RAAN, argument of periapsis).

Background

Currently orbital_elements_to_cartesian() only produces 2D orbits (z=0). To support inclined orbits like Molniya, we need to apply rotation matrices to transform 2D orbital plane coordinates into 3D space.

Rotation Sequence (z-x-z Euler angles)

r_final = R_z(Ω) · R_x(i) · R_z(ω) · r_orbital_plane
v_final = R_z(Ω) · R_x(i) · R_z(ω) · v_orbital_plane

Where:

• ω (omega) = argument of periapsis
• i = inclination
• Ω (Omega) = longitude of ascending node

Implementation

1. Data Structure (physics.h)

struct Mat3 {
    double m00, m01, m02;  // Row 0
    double m10, m11, m12;  // Row 1
    double m20, m21, m22;  // Row 2
};

Format: Row-major 3x3 matrix (different from raylib's column-major 4x4)

2. Functions to Implement (physics.h/cpp)

Core Matrix Operations

• mat3_identity() - Returns identity matrix
• mat3_multiply(Mat3 a, Mat3 b) - Matrix-matrix multiplication
• mat3_multiply_vec3(Mat3 m, Vec3 v) - Matrix-vector multiplication

Rotation Matrices

• mat3_rotation_x(double angle) - Rotation about X axis (for inclination)
• mat3_rotation_z(double angle) - Rotation about Z axis (for ω and Ω)

Convenience Function

• mat3_rotation_orbital(double omega, double i, double Omega) - Combined rotation

3. Test Plan (test_integration.cpp)

Basic Operations

• Identity matrix multiplication
• Matrix-vector multiplication
• Matrix-matrix multiplication

Edge Cases for Rotations

• Identity (0° rotation)
• 180° rotation (π radians) - coordinate flip
• 360° rotation (2π radians) - should equal identity
• Negative angles (-90° = 270°)
• Very small angles (numerical stability)
• Combined rotations that cancel (+90° then -90°)

Validation Tests

• Orthogonality: R^T · R = I
• Determinant = 1 (proper rotation)

4. Integration (Future Session)

After matrix implementation, modify orbital_elements_to_cartesian() to:

1. Generate 2D position/velocity in orbital plane
2. Apply combined rotation matrix
3. Return 3D coordinates

References

• docs/planning/molniya-orbit-test-plan.md
• src/orbital_mechanics.cpp (orbital_elements_to_cartesian)
• Standard orbital mechanics: Keplerian to Cartesian conversion

Date

Created: 2026-01-28