Julian_Duran:_PongRL_Week_1

Assets/Source/Scripts/Pong/Ball/PongBallController.cs

@@ -34,6 +34,11 @@ public partial class PongBallController : MonoBehaviour
         // initialization check
         private bool isInitialized = false;
 
+        /// <summary>
+        /// Initializes the events that will be interpreted as a point score and a rebound.
+        /// Onscore() and OnRebound() are called as functions during runtime.
+        /// </summary>
+        /// <returns>None</returns>
         public void Initialize(Action scoreProcedure, Action reboundProcedure) {
             OnScore = scoreProcedure;
             OnRebound = reboundProcedure;
@@ -54,6 +59,11 @@ void Start()
         }
 
         // Update is called once per frame
+        /// <summary>
+        /// Updates the balls position every frame by calculating the current ball velocity,
+        /// then passing this velocity into the MoveLocal function that will move the ball.
+        /// </summary>
+        /// <returns>None</returns>
         void Update()
         {
             if (!isInitialized) {
@@ -71,7 +81,12 @@ void Update()
             }
         }
 
-        //* Deals with Movement, and Collision + Interactions as a Result of that movement
+        /// <summary>
+        /// Moves the ball in the direction of the passed Vector3, and then calculates any
+        /// collisions or scoring positions that this movement may have placed the ball in.
+        /// Calls functions for scoring or rebounding depending on collision detection.
+        /// </summary>
+        /// <returns>None</returns>
         public void MoveLocal(Vector3 localDelta_dt) {
             // origin is in the center
             Vector3 MAX_POS = BG_TRANSFORM.localScale / 2f;

Assets/Source/Scripts/Pong/Ball/_Pong-Ball.cs

@@ -11,13 +11,21 @@ namespace Pong.Ball {
      * Player lastTouchedBy
      * Destroys the ball and increments points
     */
+    /// <summary>
+    /// Represents the physical ball that is visible on game screen, and handles
+    /// ball logic such as scoring and serving
+    /// </summary>
     public partial class PongBall {}
 
     /*
      * Handle collisions -> adjust trajectory
        speedX = GameCache.BALL_SPEED_VP
        velocityY = ForceAdjustment => Equation (due to possible derivatives) 
     */
+    /// <summary>
+    /// Controls the physical ball that is visible on game screen, calculating
+    /// trajectory, movement, and collisions
+    /// </summary>
     public partial class PongBallController : MonoBehaviour {}
 
     /*public static class BallStatus {
@@ -37,6 +45,10 @@ public static bool IsGoal(int ballStatus) {
         }
     }*/
 
+    /// <summary>
+    /// Defines constants for keeping track of which player scored last which is used
+    /// to determine which player's turn it is to serve
+    /// </summary>
     public static class BallGoal {
         public const bool LEFT = true;
         public const bool RIGHT = false;

Assets/Source/Scripts/Pong/GamePlayer/Player.cs

@@ -54,6 +54,11 @@ public Player(PlayerData playerData, GameObject sprite, PlayerControls controls,
             playerSprite = new ControlledGameObject<PlayerController>(sprite, controller);
         }
 
+        /// <summary>
+        /// Initializes a player object including setting the players name, passing them a paddle
+        /// object, setting their viewport view, and setting their controls.
+        /// </summary>
+        /// <returns>Player object</returns>
         public static Player CreateNew(string name, GameObject prefab, Vector2 viewportPos, PlayerControls controls, TMP_Text scoreText) {
             // create paddle
             GameObject paddle = GameObject.Instantiate(prefab, ToLocal(viewportPos), Quaternion.identity);
@@ -92,6 +97,10 @@ public void Update() {
             //TODO: playerData.feed(...);
         }
 
+        /// <summary>
+        /// Updates the scoreboard when Player scores a point.
+        /// </summary>
+        /// <returns>None</returns>
         public void ScorePoint() {
             // Game: score point
             scoreboard.ScorePoint();
@@ -105,6 +114,12 @@ public Rebounder AsRebounder() {
             return new Rebounder(forceMap, playerSprite.gameObj.GetComponent<RectangularBodyFrame>());
         }
 
+        /// <summary>
+        /// Sets the dimensions of a players paddle depending on the viewport dimensions which 
+        /// are passed in as two floats. Calculates correct dimensions regardless of viewport
+        /// size, allowing for scalability of game window.
+        /// </summary>
+        /// <returns>void</returns>
         public void SetLocalPaddleDimensionsFromVP(float vpXThickness, float vpYLength) {
             Vector3 bgScale = GameCache.BG_TRANSFORM.localScale;
 

Assets/Source/Scripts/Pong/GamePlayer/_Pong-GamePlayer.cs

@@ -5,13 +5,28 @@
 using UnityEngine;
 
 namespace Pong.GamePlayer {
+    /// <summary>
+    /// Player object handles player actions such as initialization of  
+    /// paddle size and collision ‘walls’, paddle movement and sprite initialization,
+    /// and scoring 
+    /// </summary>
     public partial class Player {}
 
+    /// <summary>
+    /// Stores player data and gameplay history for use in RL training
+    /// </summary>
     public partial class PlayerData : ScriptableObject {}
     //public partial class AIPlayerData : PlayerData {}
 
+    /// <summary>
+    /// Controls the physical player paddle that appears on the game screen, as well
+    /// as interpreting user input from keyboard controls.
+    /// </summary>
     public partial class PlayerController : MonoBehaviour {}
 
+    /// <summary>
+    /// Stores player control scheme
+    /// </summary>
     public class PlayerControls {
         public readonly KeyCode Up, Down;
         public PlayerControls(KeyCode up, KeyCode down) {

Assets/Source/Scripts/Pong/Physics/Motion2D.cs

@@ -12,6 +12,11 @@ public partial class Motion2D {
         public Vector2 velocity = new Vector2(0f, 0f);
         public readonly float[] yAccelerationAndBeyond = new float[GameConstants.BALL_Y_MAX_DERIVATIVE - 1];
 
+        /// <summary>
+        /// Creates a new Motion2D object with a pre-set velocity that is specified
+        /// by the input Vector2
+        /// </summary>
+        /// <returns>Motion2D object</returns>
         public Motion2D(Vector2 velocity2f) {
             velocity.Set(velocity2f.x, velocity2f.y);
             ResetYAccelerationAndBeyond();
@@ -39,6 +44,12 @@ public void ZeroOut() {
             ResetYAccelerationAndBeyond();
         }
 
+        /// <summary>
+        /// Calculates the velocity vector for an object given an input t which represents
+        /// the elapsed trajectory time. This function is called every frame as part of the
+        /// PongBall's update() function.
+        /// </summary>
+        /// <returns>2 dimensional velocity vector</returns>
         public Vector2 CalculateTotalVelocity(float t) {
             Vector2 totalVelocity = new Vector2(velocity.x, velocity.y);
 
@@ -56,6 +67,13 @@ public Vector2 CalculateTotalVelocity(float t) {
         }
 
         // [(x, y), (x', y'), (x'', y''), ...]
+        /// <summary>
+        /// Takes in a single 2 dimensional vector representing position and returns an array of
+        /// pairs of vectors representing higher derivatives of position and velocity.
+        /// NOTE: higher derivatives of position are always 0, whereas higher derivatives of
+        /// velocity represent acceleration, jerk, etc..
+        /// </summary>
+        /// <returns>An series of 2-dimensional vectors</returns>
         public Vector2[] RetrieveTrajectory(Vector2 position) {
             Vector2[] trajectory = new Vector2[2 + yAccelerationAndBeyond.Length]; // position and velocity are included too!
 

Assets/Source/Scripts/Pong/_Pong.cs

@@ -7,6 +7,12 @@
 using Pong.GamePlayer;
 
 namespace Pong {
+
+    /// <summary>
+    /// Contains many global game constants that are crucial for game initialization
+    /// and runtime game logic including physics constants, viewport scaling constants,
+    /// and viewport position constants
+    /// </summary>
     public static class GameConstants {
         // must be >= 1 because velocity is required
         public const uint BALL_Y_MAX_DERIVATIVE = 3; // velocity + (acceleration, acceleration')
@@ -40,6 +46,11 @@ public static class GameConstants {
         public static readonly char[] WINDOWS_BANNED_CHARS = {'\\', '/', ':', '*', '?', '\"', '<', '>', '|'};
     }
 
+    /// <summary>
+    /// Contains variables that are passed into the GameManager and set by the GameManager
+    /// during runtime. Variables effect player speed, ball speed, serve and bounce angle
+    /// maximums, and the win condition.
+    /// </summary>
     public static class GameCache {
         // cached at the beginning of GameManager
         public static Transform BG_TRANSFORM;
@@ -55,6 +66,10 @@ public static class GameCache {
         public static bool MUTE_SOUNDS = false; // when turned on, audio won't be played
     }
 
+    /// <summary>
+    /// Helper functions for computing vectors during runtime, such as casting a 3d vector
+    /// to a 2d vector or vice versa.
+    /// </summary>
     public static class GameHelpers {
         public static Vector2 ToVector2(Vector3 vector) {
             return new Vector2(vector.x, vector.y);