From 2c43dee22591834cc7f505a7e8ccc0548df7ddd8 Mon Sep 17 00:00:00 2001 From: HumanoidSandvichDispenser Date: Mon, 16 Mar 2026 14:01:33 -0700 Subject: [PATCH] Improve documentation coverage --- as6/Entities.cpp | 12 ++++++++++++ as6/components/CollectibleComponent.cpp | 1 + as6/components/ColliderComponent.cpp | 1 + as6/components/GravityReceiverComponent.cpp | 1 + as6/components/GravityWellComponent.cpp | 3 ++- as6/components/HazardComponent.cpp | 1 + as6/components/LifetimeComponent.cpp | 1 + as6/components/PhysicsComponent.cpp | 4 ++++ as6/components/ProbeStateComponent.cpp | 1 + as6/components/ProjectionComponent.cpp | 4 ++++ as6/components/ScrollComponent.cpp | 1 + as6/components/ScrollableComponent.cpp | 1 + as6/components/SpawnComponent.cpp | 1 + as6/components/StatsComponent.cpp | 1 + as6/scene/GameplayScene.cpp | 4 +--- 15 files changed, 33 insertions(+), 4 deletions(-) diff --git a/as6/Entities.cpp b/as6/Entities.cpp index b23f199..915c78c 100644 --- a/as6/Entities.cpp +++ b/as6/Entities.cpp @@ -6,6 +6,7 @@ #include "raylib-cpp.hpp" #include +// main controllable probe with meter, trail, and projection helpers std::shared_ptr CreateProbe() { auto e = std::make_shared(); auto &transform = e->AddComponent(); @@ -48,6 +49,7 @@ std::shared_ptr CreateProbe() { return e; } +// helper controller entity for free cursor-based well placement std::shared_ptr CreateGravityWell() { auto e = std::make_shared(); auto &transform = e->AddComponent(); @@ -60,6 +62,7 @@ std::shared_ptr CreateGravityWell() { return e; } +// permanent hazard black hole that serves as a heavy obstacle std::shared_ptr CreateBlackHole(float x, float y) { auto e = std::make_shared(); auto &transform = e->AddComponent(); @@ -70,6 +73,7 @@ std::shared_ptr CreateBlackHole(float x, float y) { scrollable.worldX = x; auto &well = e->AddComponent(); + // oversized static hazard that always pulls with high mass so the probe has to dodge it well.mass = static_cast(1 << 21); well.minDist = 24.0f; well.controlledByMouse = false; @@ -100,6 +104,7 @@ std::shared_ptr CreateBlackHole(float x, float y) { return e; } +// player-placed well that expires after ttl and can be cleared via right click std::shared_ptr CreatePlayerBlackHole(float worldX, float y, float scrollX, float ttl) { auto e = std::make_shared(); auto &transform = e->AddComponent(); @@ -110,6 +115,7 @@ std::shared_ptr CreatePlayerBlackHole(float worldX, float y, float scrol scrollable.worldX = worldX; auto &well = e->AddComponent(); + // temporary player-placed well that drains meter and lasts exactly ttl seconds well.mass = static_cast(1 << 22); well.minDist = 28.0f; well.controlledByMouse = false; @@ -147,6 +153,7 @@ std::shared_ptr CreatePlayerBlackHole(float worldX, float y, float scrol return e; } +// collectible star that restores meter and counts toward score std::shared_ptr CreateStar(float x, float y) { auto e = std::make_shared(); auto &t = e->AddComponent(); @@ -174,6 +181,7 @@ std::shared_ptr CreateStar(float x, float y) { return e; } +// small hazard that nudges the player when hit std::shared_ptr CreateAsteroid(float x, float y) { auto e = std::make_shared(); auto &t = e->AddComponent(); @@ -198,6 +206,7 @@ std::shared_ptr CreateAsteroid(float x, float y) { return e; } +// visual debris after collecting stars to reinforce feedback std::shared_ptr CreateDebris(float x, float y, float vx, float vy, float ttl) { auto e = std::make_shared(); auto &t = e->AddComponent(); @@ -225,6 +234,7 @@ std::shared_ptr CreateDebris(float x, float y, float vx, float vy, float return e; } +// null zone that strips gravity and forces the player to avoid it std::shared_ptr CreateNullZone(float x, float width) { auto e = std::make_shared(); auto &t = e->AddComponent(); @@ -251,6 +261,7 @@ std::shared_ptr CreateNullZone(float x, float width) { return e; } +// world entity that owns scrolling and spawn logic std::shared_ptr CreateWorld() { auto e = std::make_shared(); e->AddComponent(); @@ -258,6 +269,7 @@ std::shared_ptr CreateWorld() { return e; } +// hud/stat tracker that shows meter and plays sounds std::shared_ptr CreateStats() { auto e = std::make_shared(); e->AddComponent(); diff --git a/as6/components/CollectibleComponent.cpp b/as6/components/CollectibleComponent.cpp index 3cf61d5..7acc2cd 100644 --- a/as6/components/CollectibleComponent.cpp +++ b/as6/components/CollectibleComponent.cpp @@ -19,6 +19,7 @@ void CollectibleComponent::Setup() { return; } + // probe knock collecting stars is how meter value climbs and provides audiovisual feedback context->EmitCollectiblePicked(*entity); entity->QueueFree(); diff --git a/as6/components/ColliderComponent.cpp b/as6/components/ColliderComponent.cpp index 223be14..80ce36b 100644 --- a/as6/components/ColliderComponent.cpp +++ b/as6/components/ColliderComponent.cpp @@ -40,6 +40,7 @@ void ColliderComponent::Update(float) { const float dy = selfTransform->get().y - otherTransform->get().y; const float r = radius + otherCollider->get().radius; if ((dx * dx + dy * dy) <= (r * r)) { + // collision emitted per frame keeps gameplay reactive without physics bodies EmitCollision(*other); } } diff --git a/as6/components/GravityReceiverComponent.cpp b/as6/components/GravityReceiverComponent.cpp index 935179c..b56bd51 100644 --- a/as6/components/GravityReceiverComponent.cpp +++ b/as6/components/GravityReceiverComponent.cpp @@ -44,6 +44,7 @@ void GravityReceiverComponent::Update(float dt) { } } if (inVoid) { + // inside a null zone, the probe floats freely until it exits return; } diff --git a/as6/components/GravityWellComponent.cpp b/as6/components/GravityWellComponent.cpp index 443a1c5..57c688e 100644 --- a/as6/components/GravityWellComponent.cpp +++ b/as6/components/GravityWellComponent.cpp @@ -21,7 +21,7 @@ void GravityWellComponent::Update(float) { return; } - // Right click removes all player-created black holes + // right click removes all player-created black holes so the player can clear the screen quickly if (IsMouseButtonPressed(MOUSE_BUTTON_RIGHT)) { for (auto &ent : *context->entities) { if (!ent || ent->queuedForFree) { @@ -36,6 +36,7 @@ void GravityWellComponent::Update(float) { // Do not early return; allow left-click placement to still happen in the same frame } + // only spawn a new black hole when the player has enough meter and pressed left if (!IsMouseButtonPressed(MOUSE_BUTTON_LEFT) || !context->statsEntity) { return; } diff --git a/as6/components/HazardComponent.cpp b/as6/components/HazardComponent.cpp index 7fa0314..7a58baa 100644 --- a/as6/components/HazardComponent.cpp +++ b/as6/components/HazardComponent.cpp @@ -16,6 +16,7 @@ void HazardComponent::Setup() { return; } + // hazards instantly end the run by calling the death callback if (context->onPlayerDeath) { context->onPlayerDeath(); } diff --git a/as6/components/LifetimeComponent.cpp b/as6/components/LifetimeComponent.cpp index cfd1a59..08c4b9f 100644 --- a/as6/components/LifetimeComponent.cpp +++ b/as6/components/LifetimeComponent.cpp @@ -7,6 +7,7 @@ void LifetimeComponent::Setup() {} void LifetimeComponent::Update(float dt) { remaining -= dt; if (remaining <= 0.0f) { + // helper component that simply removes itself when the ttl expires entity->QueueFree(); } } diff --git a/as6/components/PhysicsComponent.cpp b/as6/components/PhysicsComponent.cpp index 26be919..823ccbe 100644 --- a/as6/components/PhysicsComponent.cpp +++ b/as6/components/PhysicsComponent.cpp @@ -67,6 +67,7 @@ bool PhysicsComponent::IsInsideNullZone(double xPos) const { return false; } +// looks weird because of formatter bool PhysicsComponent::ComputeGravityDeltaVelocity(double px, double py, double dt, double &dvx, double &dvy, bool ignoreWellActive) const { dvx = 0.0; @@ -80,11 +81,13 @@ bool PhysicsComponent::ComputeGravityDeltaVelocity(double px, double py, double if (context && entity == context->probeEntity && context->statsEntity) { auto stats = context->statsEntity->GetComponent(); if (stats && stats->get().value <= 0.0f) { + // meter drained, block gravity from anything that isn't always active probeMeterDepleted = true; } } if (IsInsideNullZone(px)) { + // null zone overrides gravity, so the probe/globally simulated object stops feeling wells return false; } @@ -115,6 +118,7 @@ bool PhysicsComponent::ComputeGravityDeltaVelocity(double px, double py, double continue; } + // guard against infinite force by respecting the well's minimum distance const double clampedDist = std::max(dist, static_cast(wellGravity->get().minDist)); const double force = static_cast(wellGravity->get().mass) / (clampedDist * clampedDist); diff --git a/as6/components/ProbeStateComponent.cpp b/as6/components/ProbeStateComponent.cpp index b9b9639..3124792 100644 --- a/as6/components/ProbeStateComponent.cpp +++ b/as6/components/ProbeStateComponent.cpp @@ -22,6 +22,7 @@ void ProbeStateComponent::Update(float) { transform->get().x < -20.0f || transform->get().x > static_cast(GetScreenWidth() + 20)) { if (context->onPlayerDeath) { + // leaving the viewport is treated as death to keep the probe bounded context->onPlayerDeath(); } } diff --git a/as6/components/ProjectionComponent.cpp b/as6/components/ProjectionComponent.cpp index 3dd3732..8f1eec3 100644 --- a/as6/components/ProjectionComponent.cpp +++ b/as6/components/ProjectionComponent.cpp @@ -56,6 +56,8 @@ void ProjectionComponent::Update(float) { auto wellGravity = other->GetComponent(); if (wellGravity && wellGravity->get().active) { + // highlight arc when another well is active so the player knows the projection is + // influenced highlightActive = true; break; } @@ -84,6 +86,8 @@ void ProjectionComponent::Update(float) { } } + // storing each simulated position gives the hud the full trajectory so the player can line + // up placements points.push_back({static_cast(px), static_cast(py)}); } diff --git a/as6/components/ScrollComponent.cpp b/as6/components/ScrollComponent.cpp index d51c027..ba74fae 100644 --- a/as6/components/ScrollComponent.cpp +++ b/as6/components/ScrollComponent.cpp @@ -6,6 +6,7 @@ void ScrollComponent::Update(float dt) { speed += accel * dt; scrollX += speed * dt * 60.0f; if (context) { + // stores our current scroll speed for components that rely on the camera position context->scrollX = scrollX; } } diff --git a/as6/components/ScrollableComponent.cpp b/as6/components/ScrollableComponent.cpp index 6009513..60a6359 100644 --- a/as6/components/ScrollableComponent.cpp +++ b/as6/components/ScrollableComponent.cpp @@ -15,6 +15,7 @@ void ScrollableComponent::Update(float) { return; } + // keeps the drawable aligned with the camera by subtracting the global scroll offset transform->get().x = worldX - context->scrollX; } diff --git a/as6/components/SpawnComponent.cpp b/as6/components/SpawnComponent.cpp index 9e3f1eb..4b27678 100644 --- a/as6/components/SpawnComponent.cpp +++ b/as6/components/SpawnComponent.cpp @@ -31,6 +31,7 @@ void SpawnComponent::Update(float) { const float cameraX = scroll->get().scrollX; const float spawnLimit = cameraX + spawnAheadDistance; + // 70% stars, 20% asteroids, 5% null zones, 5% hazards -> keeps early play mostly collectible while (cursorWX < spawnLimit) { const float r = static_cast(GetRandomValue(0, 99)); if (r < 70.0f) { diff --git a/as6/components/StatsComponent.cpp b/as6/components/StatsComponent.cpp index 4f51b73..30fd10a 100644 --- a/as6/components/StatsComponent.cpp +++ b/as6/components/StatsComponent.cpp @@ -6,6 +6,7 @@ void StatsComponent::SetValue(float newValue) { const float oldValue = value; value = newValue; if (context && oldValue != value) { + // notify listeners so the hud and gravity meter stay in sync with the updated value context->EmitMeterChanged(oldValue, value); } } diff --git a/as6/scene/GameplayScene.cpp b/as6/scene/GameplayScene.cpp index 69f2b78..7324927 100644 --- a/as6/scene/GameplayScene.cpp +++ b/as6/scene/GameplayScene.cpp @@ -14,9 +14,7 @@ void GameplayScene::Enter() { meterValue = 60.0f; context.onPlayerDeath = [this]() { - // Inject the collected star count into the queued DeathScene by passing it - // as a constructor argument. SceneManager::QueueSceneChange supports - // forwarding constructor args. + // queue the death scene with the current star count so the recap is accurate manager.QueueSceneChange(collectedCount, this->isMuted); }; context.AddCollectiblePickedListener([this](Entity &collectible) {