Working through some of the PR comments. Concentrating on the text of the tutorial section first as only 90 total comments there, 200+ in the attachments and there's still bugs in the game engine itself. Holding back game code changes until it's bug free.

Author: gpx1000

en/Building_a_Simple_Engine/Camera_Transformations/02_math_foundations.adoc

@@ -29,7 +29,7 @@ In our camera system, vectors serve several critical purposes:
 * *Scalar Multiplication*: Used for scaling movements and directions
   - Example: Slowing down camera movement by multiplying velocity by a factor < 1
 
-* *Dot Product*: Calculates the cosine of the angle between vectors (when normalized)
+* *Dot Product*: Calculates the cosine of the angle between normalized vectors.
   - Applications: Determining if objects are facing the camera, calculating lighting intensity
 
 ==== The Right-Hand Rule
@@ -524,7 +524,7 @@ struct Sphere {
 
 bool rayIntersectsSphere(const Ray& ray, const Sphere& sphere, float& t) {
     // Vector from ray origin to sphere center
-    glm::vec3 oc = ray.origin - sphere.center;
+    glm::vec3 oc = sphere.center - ray.origin;
 
     // Quadratic equation coefficients
     float a = glm::dot(ray.direction, ray.direction);  // Always 1 if direction is normalized
@@ -710,7 +710,7 @@ For complex scenes with many objects, raycasting can become computationally expe
 
 * *Ray Batching*: Process multiple rays together to take advantage of SIMD instructions
 
-* *Early Termination*: Stop testing once you've found the closest intersection (if that's all you need)
+* *Early Termination*: Stop testing once you've found any intersection (if that's all you need)
 
 === Projection in 3D Graphics
 

en/Building_a_Simple_Engine/Camera_Transformations/03_camera_implementation.adoc

@@ -11,7 +11,7 @@ Now that we understand the mathematical foundations, let's implement a flexible
 There are several types of cameras commonly used in 3D applications:
 
 * *First-Person Camera*: Simulates viewing the world through the eyes of a character.
-* *Third-Person Camera*: Follows a character from behind or another fixed position.
+* *Third-Person Camera*: Follows a character from behind or another fixed relative position.
 * *Orbit Camera*: Rotates around a fixed point, useful for object inspection.
 * *Free Camera*: Allows unrestricted movement in all directions.
 
@@ -27,7 +27,7 @@ class Camera {
 private:
     // Camera position and orientation
     glm::vec3 position;
-    glm::vec3 front;
+    glm::vec3 forward;
     glm::vec3 up;
     glm::vec3 right;
     glm::vec3 worldUp;
@@ -40,6 +40,9 @@ private:
     float movementSpeed;
     float mouseSensitivity;
     float zoom;
+    float aspectRatio;
+    float nearPlane;
+    float farPlane;
 
     // Update camera vectors based on Euler angles
     void updateCameraVectors();
@@ -57,16 +60,16 @@ public:
     glm::mat4 getViewMatrix() const;
 
     // Get projection matrix
-    glm::mat4 getProjectionMatrix(float aspectRatio, float nearPlane = 0.1f, float farPlane = 100.0f) const;
+    glm::mat4 getProjectionMatrix() const;
 
-    // Process keyboard input for camera movement
-    void processKeyboard(CameraMovement direction, float deltaTime);
+    // Process camera movement (translation)
+    void move(CameraMovement direction, float deltaTime);
 
-    // Process mouse movement for camera rotation
-    void processMouseMovement(float xOffset, float yOffset, bool constrainPitch = true);
+    // Process camera rotation
+    void rotate(float xOffset, float yOffset, bool constrainPitch = true);
 
-    // Process mouse scroll for zoom
-    void processMouseScroll(float yOffset);
+    // Process zoom
+    void zoom(float delta);
 
     // Getters for camera properties
     glm::vec3 getPosition() const { return position; }
@@ -98,18 +101,26 @@ And implement the movement logic:
 void Camera::processKeyboard(CameraMovement direction, float deltaTime) {
     float velocity = movementSpeed * deltaTime;
 
-    if (direction == CameraMovement::FORWARD)
-        position += front * velocity;
-    if (direction == CameraMovement::BACKWARD)
-        position -= front * velocity;
-    if (direction == CameraMovement::LEFT)
-        position -= right * velocity;
-    if (direction == CameraMovement::RIGHT)
-        position += right * velocity;
-    if (direction == CameraMovement::UP)
-        position += up * velocity;
-    if (direction == CameraMovement::DOWN)
-        position -= up * velocity;
+    switch (direction) {
+        case CameraMovement::FORWARD:
+            position += front * velocity;
+            break;
+        case CameraMovement::BACKWARD:
+            position -= front * velocity;
+            break;
+        case CameraMovement::LEFT:
+            position -= right * velocity;
+            break;
+        case CameraMovement::RIGHT:
+            position += right * velocity;
+            break;
+        case CameraMovement::UP:
+            position += up * velocity;
+            break;
+        case CameraMovement::DOWN:
+            position -= up * velocity;
+            break;
+    }
 }
 ----
 

en/Building_a_Simple_Engine/Camera_Transformations/05_vulkan_integration.adoc

@@ -69,15 +69,13 @@ std::array<UboBuffer, maxConcurrentFrames> uniformBuffers;
 
 void createUniformBuffers() {
     vk::DeviceSize bufferSize = sizeof(UniformBufferObject);
-
+    // Create the buffer
+    vk::BufferCreateInfo bufferInfo{
+        .size = bufferSize,
+        .usage = vk::BufferUsageFlagBits::eUniformBuffer,
+        .sharingMode = vk::SharingMode::eExclusive
+    };
     for (size_t i = 0; i < maxConcurrentFrames; i++) {
-        // Create the buffer
-        vk::BufferCreateInfo bufferInfo{
-            .size = bufferSize,
-            .usage = vk::BufferUsageFlagBits::eUniformBuffer,
-            .sharingMode = vk::SharingMode::eExclusive
-        };
-
         uniformBuffers[i].buffer = vk::raii::Buffer(device, bufferInfo);
 
         // Allocate and bind memory

en/Building_a_Simple_Engine/Engine_Architecture/01_introduction.adoc

@@ -35,7 +35,7 @@ This chapter builds directly on the foundation established in the main Vulkan tu
 
 Beyond Vulkan knowledge, you'll benefit from familiarity with object-oriented programming principles, as modern engine architecture relies heavily on encapsulation, inheritance, and polymorphism to manage complexity. Experience with common design patterns like Observer, Factory, and Singleton will help you recognize when and why we apply these patterns in our engine design.
 
-Modern C++ features play a crucial role in our implementation approach. Smart pointers help us manage resource lifetimes safely, templates enable flexible, reusable components, and other C++11/14/17 features allow us to write more expressive and maintainable code. If you're not comfortable with these concepts, consider reviewing them before proceeding.
+Modern C:pp: features play a crucial role in our implementation approach. Smart pointers help us manage resource lifetimes safely, templates enable flexible, reusable components, and other C:pp:11/14/17 features allow us to write more expressive and maintainable code. If you're not comfortable with these concepts, consider reviewing them before proceeding.
 
 You should also be familiar with the following chapters from the main tutorial:
 

en/Building_a_Simple_Engine/Engine_Architecture/03_component_systems.adoc

@@ -102,13 +102,6 @@ public:
     T* AddComponent(Args&&... args) {
         static_assert(std::is_base_of<Component, T>::value, "T must derive from Component");
 
-        // Check if component of this type already exists
-        for (auto& component : components) {
-            if (dynamic_cast<T*>(component.get())) {
-                return dynamic_cast<T*>(component.get());
-            }
-        }
-
         // Create new component
         auto component = std::make_unique<T>(std::forward<Args>(args)...);
         T* componentPtr = component.get();

en/Building_a_Simple_Engine/Engine_Architecture/04_resource_management.adoc

@@ -95,14 +95,19 @@ public:
     bool IsLoaded() const { return loaded; }
 
     // Virtual interface for resource-specific loading and unloading behavior
-    virtual bool Load() {
-        loaded = true;
-        return true;
+    bool Load() {
+        loaded = doLoad();
+        return loaded;
     }
 
-    virtual void Unload() {
+    void Unload() {
+        doUnload();
         loaded = false;
     }
+
+    protected:
+        virtual bool doLoad() = 0;
+        virtual bool doUnload() = 0;
 };
 ----
 
@@ -124,9 +129,14 @@ private:
     std::unordered_map<std::type_index,
                        std::unordered_map<std::string, std::shared_ptr<Resource>>> resources;
 
-    // Reference counting system for automatic resource lifecycle management
-    // Maps resource IDs to their current usage count for garbage collection
-    std::unordered_map<std::string, int> refCounts;
+    // Two-level reference counting system for automatic resource lifecycle management
+    // First level maps resource type, second level maps resource IDs to their data
+    struct ResourceData {
+        std::shared_ptr<Resource> resource;  // The actual resource
+        int refCount;                        // Reference count for this resource
+    };
+    std::unordered_map<std::type_index,
+                       std::unordered_map<std::string, ResourceData>> refCounts;
 ----
 
 The storage architecture uses a sophisticated two-level mapping system that solves several critical problems in resource management. The outer map keyed by `std::type_index` ensures complete type separation, preventing name collisions between different resource types. For example, you could have both a texture named "stone" and a sound effect named "stone" without conflicts, as they're stored in separate type-specific containers.
@@ -201,8 +211,8 @@ After that, we provide the interface for safely accessing cached resources with
     template<typename T>
     bool HasResource(const std::string& resourceId) {
         // Efficient existence check without resource access overhead
-        auto& typeResources = resources[std::type_index(typeid(T))];
-        return typeResources.find(resourceId) != typeResources.end();
+        auto resourceIt = resources.find(std::type_index(typeid(T)));
+        return resourceIt != resources.end();
     }
 ----