Merge pull request #84 from Shenzhen-Robotics-Alliance/dev

updated documents on reefscape simulation

docs/index.md

@@ -35,24 +35,24 @@ For an in-depth description of the simulations, please refer to [Simulation Deta
 ??? "AdvantageKit Users"
     AdvantageKit provides Advanced Swerve Drive templates for teams using Akit and swerve. These templates have been modified to implement maple-sim, you can use them directly:
     <br> 
-    [AKitSparkSwerveTemplate-maple-sim](https://github.com/Shenzhen-Robotics-Alliance/maple-sim/tree/main/templates/AdvantageKit_SparkSwerveTemplate-maple-sim):  The AdvantageKit Swerve Template with REV SparkMax hardware, enhanced with maple-sim integration for improved chassis physics simulation.
+    **[AKitSparkSwerveTemplate-maple-sim](https://github.com/Shenzhen-Robotics-Alliance/maple-sim/tree/main/templates/AdvantageKit_SparkSwerveTemplate-maple-sim)**:  The AdvantageKit Swerve Template with REV SparkMax hardware, enhanced with maple-sim integration for improved chassis physics simulation.
     <br>
-    [AkitTalonSwerveTemplate-maple-sim](https://github.com/Shenzhen-Robotics-Alliance/maple-sim/tree/main/templates/AdvantageKit_TalonSwerveTemplate-maple-sim): The AdvantageKit Swerve Template with CTRE hardware, enhanced with maple-sim integration for improved chassis physics simulation.
+    **[AkitTalonSwerveTemplate-maple-sim](https://github.com/Shenzhen-Robotics-Alliance/maple-sim/tree/main/templates/AdvantageKit_TalonSwerveTemplate-maple-sim)**: The AdvantageKit Swerve Template with CTRE hardware, enhanced with maple-sim integration for improved chassis physics simulation.
     <br>
-    [AkitTalonSwerveTemplate_EnhancedPhoenixSimulation](https://github.com/Shenzhen-Robotics-Alliance/maple-sim/tree/dev/templates/AdvantageKit_TalonSwerveTemplate_EnhancedPhoenixSimulation): A further enhanced version of the TalonSwerveTemplate-maple-sim project, utilizing [Phoenix 6 simulation](https://v6.docs.ctr-electronics.com/en/latest/docs/api-reference/simulation/simulation-intro.html) to simulate CTRE motor controller closed-loops and the CAN bus. *(Note: This project is in the dev branch, and the work is still in progress.)*
+    **[AkitTalonSwerveTemplate_EnhancedPhoenixSimulation](https://github.com/Shenzhen-Robotics-Alliance/maple-sim/tree/dev/templates/AdvantageKit_TalonSwerveTemplate_EnhancedPhoenixSimulation)**: A further enhanced version of the TalonSwerveTemplate-maple-sim project, utilizing [Phoenix 6 simulation](https://v6.docs.ctr-electronics.com/en/latest/docs/api-reference/simulation/simulation-intro.html) to simulate CTRE motor controller closed-loops and the CAN bus. *(Note: This project is in the dev branch, and the work is still in progress.)*
 
 ??? "YAGSL Users"
     maple-sim is officially included in YAGSL for 2025!
     <br>
-    See [YAGSL - 2025 release](https://github.com/BroncBotz3481/YAGSL-Example/releases/tag/2025.1.0): Official 2025-beta release of the amazing [Yet Another Generic Swerve Drive Library](https://www.chiefdelphi.com/t/yet-another-generic-swerve-library-yagsl-v1-release/450844), with maple-sim implemented for enhanced drivetrain simulation.
+    See **[YAGSL - 2025 release](https://github.com/BroncBotz3481/YAGSL-Example/releases/tag/2025.1.0)**: Official 2025-beta release of the amazing [Yet Another Generic Swerve Drive Library](https://www.chiefdelphi.com/t/yet-another-generic-swerve-library-yagsl-v1-release/450844), with maple-sim implemented for enhanced drivetrain simulation.
 
 ??? "Base-Talon-Swerve Users"
-    See [Base-Talon-Swerve with maple-sim](https://github.com/Shenzhen-Robotics-Alliance/maple-sim/tree/main/templates/BaseTalonSwerve-maple-sim): Base-Talon-Swerve, modified with advanced drivetrain simulation. This is an example implementation of the [Simplified Swerve Simulation](https://shenzhen-robotics-alliance.github.io/maple-sim/3.1_SWERVE_SIM_EZ_MODE.html).
+    See **[Base-Talon-Swerve with maple-sim](https://github.com/Shenzhen-Robotics-Alliance/maple-sim/tree/main/templates/BaseTalonSwerve-maple-sim)**: Base-Talon-Swerve, modified with advanced drivetrain simulation. This is an example implementation of the [Simplified Swerve Simulation](https://shenzhen-robotics-alliance.github.io/maple-sim/3.1_SWERVE_SIM_EZ_MODE.html).
 
 ??? "Other Custom Code"
-    [Maple-Swerve-Skeleton](https://github.com/Shenzhen-Robotics-Alliance/Maple-Swerve-Skeleton): Our custom swerve drive project based on the Advanced Swerve Drive Project, featuring drivetrain simulation, vision simulation, and convenient control features.
+    **[Maple-Swerve-Skeleton](https://github.com/Shenzhen-Robotics-Alliance/Maple-Swerve-Skeleton)**: Our custom swerve drive project based on the Advanced Swerve Drive Project, featuring drivetrain simulation, vision simulation, and convenient control features.
     <br>
-    [5516-2024-OffSeason-RobotCode](https://github.com/Shenzhen-Robotics-Alliance/Maple-Swerve-Skeleton/tree/main/example/5516-2024-OffSeason): Our 2024 off-season robot code, which implements a range of advanced simulations. This code can be run on a real robot and even played like a video game. Watch the [Videos](https://www.youtube.com/watch?v=5jr1L8xWpog&list=PLFS6A0KifAK1ycwlzIlvvFJkWNsQHVjSN)
+    **[5516-2024-OffSeason-RobotCode](https://github.com/Shenzhen-Robotics-Alliance/Maple-Swerve-Skeleton/tree/main/example/5516-2024-OffSeason)**: Our 2024 off-season robot code, which implements a range of advanced simulations. This code can be run on a real robot and even played like a video game. Watch the [Videos](https://www.youtube.com/watch?v=5jr1L8xWpog&list=PLFS6A0KifAK1ycwlzIlvvFJkWNsQHVjSN)
 
 ## Online Documentation
 

docs/reefscape.md

@@ -1,8 +1,8 @@
 # 2025 Reefscape Simulation
 ![alt text](media/fd_frc_socialgraphics_fb_post.png)
 
-## CORAL and ALGAE on the Field
-CORAL and ALGAE can be added to the field as game pieces:
+## ***CORAL*** and ***ALGAE*** on the Field
+***CORAL*** and ***ALGAE*** can be added to the field as game pieces:
 
 ```java
 SimulatedArena.getInstance().addGamePiece(new ReefscapeCoral(
@@ -21,37 +21,19 @@ Logger.recordOutput("FieldSimulation/Coral",
     SimulatedArena.getInstance().getGamePiecesArrayByType("Coral"));
 ```
 
-For more details, see:
-- [Adding Game Pieces to the Field](https://shenzhen-robotics-alliance.github.io/maple-sim/using-the-simulated-arena/#3-adding-game-pieces-to-the-field)
-- [Visualizing Game Pieces](https://shenzhen-robotics-alliance.github.io/maple-sim/using-the-simulated-arena/#4-visualizing-game-pieces)
-
-![Reefscape Game Pieces](./media/reefscape%20game%20pieces.gif)
+And display the data in AdvantageScope:
 
-## Launching ALGAE
-ALGAE can be launched into the air, and the simulation will detect if it reaches its target—the NET.
+![](./media/reefscape%20coral%20algae%20ascope.png)
 
-```java
-ReefscapeAlgaeOnFly.setHitNetCallBack(() -> System.out.println("ALGAE hits NET!"));
-SimulatedArena.getInstance()
-    .addGamePieceProjectile(new ReefscapeAlgaeOnFly(
-        driveSimulation.getSimulatedDriveTrainPose().getTranslation(),
-        new Translation2d(),
-        driveSimulation.getDriveTrainSimulatedChassisSpeedsFieldRelative(),
-        driveSimulation.getSimulatedDriveTrainPose().getRotation(),
-        0.4, // initial height of the ball, in meters
-        9, // initial velocity, in m/s
-        Math.toRadians(70)) // shooter angle
-        .withProjectileTrajectoryDisplayCallBack(
-            (poses) -> Logger.recordOutput("successfulShotsTrajectory", poses.toArray(Pose3d[]::new)),
-            (poses) -> Logger.recordOutput("missedShotsTrajectory", poses.toArray(Pose3d[]::new))));
-```
+![Reefscape Game Pieces](./media/reefscape%20game%20pieces.gif)
 
-See [Simulating Projectiles](./simulating-projectiles.md).
+??? "Detailed Documents on Game Pieces Simulation"
+    - **[Adding Game Pieces to the Field](https://shenzhen-robotics-alliance.github.io/maple-sim/using-the-simulated-arena/#3-adding-game-pieces-to-the-field)**
+    - **[Visualizing Game Pieces](https://shenzhen-robotics-alliance.github.io/maple-sim/using-the-simulated-arena/#4-visualizing-game-pieces)**
 
-![](./media/launching%20algae.gif)
 
-## The CORAL-ALGAE Stack
-CORAL are staged on the field with ALGAE on top. You can place these stacks on the field:
+## The ***CORAL-ALGAE*** Stack
+***CORAL*** are staged on the field with ***ALGAE*** on top. You can place these stacks on the field:
 
 ```java
 SimulatedArena.getInstance().addGamePiece(new ReefscapeCoralAlgaeStack(new Translation2d(2,2)));
@@ -63,19 +45,62 @@ Or reset the layout by performing a field reset:
 SimulatedArena.getInstance().resetFieldForAuto();
 ```
 
-To visualize the stacks, use:
+!!! tip
+    When you display ***CORAL*** and ***ALGAE*** using the method specified above, the ***CORAL*** and ***ALGAE*** in the stacks will also be displayed.
+![alt text](./media/reefscape%20stack%20ascope.png)
+
+
+!!! tip
+    Stacks will collapse and become a ***CORAL*** and ***ALGAE*** on the field if you hit them:
+
+![](./media/reefscape%20stack.gif)
+
+## Interacting with ***CORAL*** and ***ALGAE***
+Users can use `IntakeSimulation` to simulate the interaction between robot intakes and the game pieces. 
 
 ```java
-Logger.recordOutput("FieldSimulation/StackedAlgae", 
-    ReefscapeCoralAlgaeStack.getStackedAlgaePoses());
-Logger.recordOutput("FieldSimulation/StackedCoral", 
-    ReefscapeCoralAlgaeStack.getStackedCoralPoses());
+this.intakeSimulation = IntakeSimulation.OverTheBumperIntake(
+        // Specify the type of game pieces that the intake can collect
+        "Coral",
+        // Specify the drivetrain to which this intake is attached
+        driveTrainSimulation,
+        // Width of the intake
+        Meters.of(0.4),
+        // The extension length of the intake beyond the robot's frame (when activated)
+        Meters.of(0.2),
+        // The intake is mounted on the back side of the chassis
+        IntakeSimulation.IntakeSide.BACK,
+        // The intake can hold up to 1 note
+        1);
 ```
 
-And display the data in AdvantageScope:
+??? "Detailed Documents on IntakeSimulation"
+    **[Simulating Intake](https://shenzhen-robotics-alliance.github.io/maple-sim/simulating-intake/)**
 
-![](./media/reefscape%20stack%20ascope.png)
+!!! tip
+    - If your `IntakeSimulation` is targeted to ***CORAL***, it will also be able to grab the ***CORAL*** from the ***CORAL-ALGAE*** stack. And the ***ALGAE*** will fall to the ground as the ***CORAL*** disapear.
+    - Vise versa, if your `IntakeSimulation` is targeted to ***ALGAE***, it will also be able to grab the ***ALGAE*** from the ***CORAL-ALGAE*** stack. And the ***CORAL*** will fall to the ground as the ***ALGAE*** disapear.
 
-Stacks will collapse and become a CORAL and ALGAE on the field if you hit them:
 
-![](./media/reefscape%20stack.gif)
+## Launching ***ALGAE*** into the air
+***ALGAE*** can be launched into the air, and the simulation will detect if it reaches its target—the ***NET***.
+
+```java
+ReefscapeAlgaeOnFly.setHitNetCallBack(() -> System.out.println("ALGAE hits NET!"));
+SimulatedArena.getInstance()
+    .addGamePieceProjectile(new ReefscapeAlgaeOnFly(
+        driveSimulation.getSimulatedDriveTrainPose().getTranslation(),
+        new Translation2d(),
+        driveSimulation.getDriveTrainSimulatedChassisSpeedsFieldRelative(),
+        driveSimulation.getSimulatedDriveTrainPose().getRotation(),
+        0.4, // initial height of the ball, in meters
+        9, // initial velocity, in m/s
+        Math.toRadians(70)) // shooter angle
+        .withProjectileTrajectoryDisplayCallBack(
+            (poses) -> Logger.recordOutput("successfulShotsTrajectory", poses.toArray(Pose3d[]::new)),
+            (poses) -> Logger.recordOutput("missedShotsTrajectory", poses.toArray(Pose3d[]::new))));
+```
+
+See [Simulating Projectiles](./simulating-projectiles.md).
+
+![](./media/launching%20algae.gif)