Refactor gamepiece naming conventions and deprecate legacy APIs for i…

core/driver/include/driverheader.h

@@ -75,13 +75,6 @@ void c_rsDestroyWorld(uint64_t world_handle);
  */
 int c_rsCreateBody(uint64_t world_handle, double mass_kg);
 
-/**
- * @brief Creates a new ball simulator in a world.
- * @param world_handle Target world handle.
- * @return Non-negative ball index on success; negative value on failure.
- */
-int c_rsCreateBall(uint64_t world_handle);
-
 /**
  * @brief Creates a new generic gamepiece using sphere hitbox parameters.
  * @param world_handle Target world handle.

core/driver/include/frcsim/api.h

@@ -7,9 +7,6 @@ extern "C" {
 
 using PhysicsWorld_t = frcsim::PhysicsWorld;
 using RigidBody_t = frcsim::RigidBody;
-// Backwards-compatible alias for older APIs.
-using Ball_t = frcsim::BallPhysicsSim3D;
-// New long-term alias: Gamepiece (generic wrapper over ball physics for now).
 using Gamepiece_t = frcsim::Gamepiece;
 
 PhysicsWorld_t* frcsim_create_world();

core/driver/include/frcsim/gamepiece/ball_wrapper.hpp

@@ -0,0 +1,35 @@
+// Copyright (c) JSim contributors.
+// Open Source Software; you can modify and/or share it under the terms of
+// the LGPLv3 license file in the root directory of this project.
+
+#pragma once
+
+#include "frcsim/gamepiece/gamepiece.hpp"
+
+namespace frcsim {
+
+/**
+ * @brief Thin, backwards-friendly ball wrapper around the generic `Gamepiece`.
+ *
+ * This type exists to make call sites that previously relied on `BallPhysicsSim3D`
+ * or `Ball` compile with minimal changes while encouraging new code to use
+ * the generic `Gamepiece` abstraction.
+ */
+class Ball : public Gamepiece {
+ public:
+  using Gamepiece::Gamepiece;
+
+  Ball() = default;
+
+  Ball(const Gamepiece::Config& cfg, const Gamepiece::Properties& props)
+      : Gamepiece(cfg, props) {}
+
+  /** Convenience factory returning an evergreen default ball. */
+  static Ball defaultEvergreen() {
+    Gamepiece::Properties p = Gamepiece::Properties();
+    Gamepiece::Config c = Gamepiece::Config();
+    return Ball(c, p);
+  }
+};
+
+}  // namespace frcsim

core/driver/include/frcsim/gamepiece/gamepiece_presets.hpp

@@ -0,0 +1,58 @@
+// Copyright (c) JSim contributors.
+// Open Source Software; you can modify and/or share it under the terms of
+// the LGPLv3 license file in the root directory of this project.
+
+#pragma once
+
+#include "frcsim/gamepiece/gamepiece_sim.hpp"
+
+namespace frcsim::BallGamepiecePresets {
+
+inline BallPhysicsSim3D::BallProperties fuelProperties() {
+  BallPhysicsSim3D::BallProperties properties{};
+  properties.mass_kg = 0.216;
+  properties.radius_m = 0.075;
+  properties.drag_coefficient = 0.35;
+  properties.reference_area_m2 = 3.14159265358979323846 * properties.radius_m * properties.radius_m;
+  properties.restitution = 0.30;
+  return properties;
+}
+
+inline BallPhysicsSim3D::Config fuelConfig() {
+  BallPhysicsSim3D::Config config = evergreenBallConfig();
+  config.rolling_friction_per_s = 2.0;
+  config.min_bounce_speed_mps = 0.03;
+  return config;
+}
+
+inline BallPhysicsSim3D::BallProperties evergreenBallProperties() {
+  BallPhysicsSim3D::BallProperties properties{};
+  properties.mass_kg = 0.24;
+  properties.radius_m = 0.09;
+  properties.drag_coefficient = 0.50;
+  properties.reference_area_m2 = 3.14159265358979323846 * properties.radius_m * properties.radius_m;
+  properties.restitution = 0.48;
+  return properties;
+}
+
+inline BallPhysicsSim3D::Config evergreenBallConfig() {
+  BallPhysicsSim3D::Config config{};
+  config.gravity_mps2 = Vector3(0.0, 0.0, -9.81);
+  config.air_density_kgpm3 = 1.225;
+  config.magnus_coefficient = 1.0e-4;
+  config.ground_height_m = 0.0;
+  config.rolling_friction_per_s = 1.5;
+  config.min_bounce_speed_mps = 0.06;
+  return config;
+}
+
+inline BallGamepieceSim::FieldConfig evergreenFieldConfig() {
+  BallGamepieceSim::FieldConfig config{};
+  config.min_corner_m = Vector3(0.0, 0.0, 0.0);
+  config.max_corner_m = Vector3(16.54, 8.21, 3.0);
+  config.wall_restitution = 0.25;
+  config.wall_friction = 0.2;
+  return config;
+}
+
+}  // namespace frcsim::BallGamepiecePresets

core/driver/include/frcsim/gamepiece/gamepiece_sim.hpp

@@ -0,0 +1,13 @@
+// Copyright (c) JSim contributors.
+// Open Source Software; you can modify and/or share it under the terms of
+// the LGPLv3 license file in the root directory of this project.
+
+#pragma once
+
+#include "frcsim/gamepiece/ball_gamepiece_sim.hpp"
+
+namespace frcsim {
+
+using GamepieceSim = BallGamepieceSim;
+
+}  // namespace frcsim

core/driver/include/frcsim/gamepiece/intake_simulation.hpp

@@ -9,7 +9,7 @@
 #include <functional>
 #include <string>
 
-#include "frcsim/gamepiece/ball_gamepiece_sim.hpp"
+#include "frcsim/gamepiece/gamepiece_sim.hpp"
 
 namespace frcsim {
 

core/driver/include/frcsim/gamepiece/season_2025_gamepiece.hpp

@@ -0,0 +1,40 @@
+// Copyright (c) JSim contributors.
+// Open Source Software; you can modify and/or share it under the terms of
+// the LGPLv3 license file in the root directory of this project.
+
+#pragma once
+
+#include "frcsim/gamepiece/gamepiece.hpp"
+#include "frcsim/gamepiece/season_2025_gamepiece_presets.hpp"
+
+namespace frcsim {
+
+/**
+ * @brief Season-2025 convenience gamepiece wrapper.
+ *
+ * Creates `Gamepiece` instances pre-configured with the 2025 presets.
+ */
+class Season2025Gamepiece : public Gamepiece {
+ public:
+  Season2025Gamepiece()
+      : Gamepiece(BallGamepiecePresets::season2025BallConfig(),
+                  BallGamepiecePresets::season2025BallProperties()) {
+    setTypeName("Ball2025");
+  }
+
+  Season2025Gamepiece(const Gamepiece::Config& cfg,
+                      const Gamepiece::Properties& props)
+      : Gamepiece(cfg, props) {
+    setTypeName("Ball2025");
+  }
+
+  static Gamepiece::Properties defaultProperties() {
+    return BallGamepiecePresets::season2025BallProperties();
+  }
+
+  static Gamepiece::Config defaultConfig() {
+    return BallGamepiecePresets::season2025BallConfig();
+  }
+};
+
+}  // namespace frcsim

core/driver/include/frcsim/gamepiece/season_2025_gamepiece_presets.hpp

@@ -0,0 +1,43 @@
+// Copyright (c) JSim contributors.
+// Open Source Software; you can modify and/or share it under the terms of
+// the LGPLv3 license file in the root directory of this project.
+
+#pragma once
+
+#include "frcsim/gamepiece/gamepiece_presets.hpp"
+
+namespace frcsim::BallGamepiecePresets {
+
+// Placeholder 2025 season presets. Tune values as appropriate for 2025 game.
+inline BallGamepieceSim::FieldConfig season2025FieldConfig() {
+  BallGamepieceSim::FieldConfig config = evergreenFieldConfig();
+  config.net_boundary_user_id = 2025;
+  config.wall_restitution = 0.24;
+  config.wall_friction = 0.22;
+  return config;
+}
+
+inline BallPhysicsSim3D::BallProperties season2025BallProperties() {
+  BallPhysicsSim3D::BallProperties properties{};
+  properties.mass_kg = 0.20;
+  properties.radius_m = 0.075;
+  properties.drag_coefficient = 0.45;
+  properties.reference_area_m2 = 3.14159265358979323846 * properties.radius_m * properties.radius_m;
+  properties.restitution = 0.46;
+  return properties;
+}
+
+inline BallPhysicsSim3D::Config season2025BallConfig() {
+  BallPhysicsSim3D::Config config = evergreenBallConfig();
+  config.magnus_coefficient = 1.1e-4;
+  config.rolling_friction_per_s = 1.6;
+  return config;
+}
+
+inline void configureSeason2025Field(BallGamepieceSim& sim) {
+  sim.setFieldConfig(season2025FieldConfig());
+  sim.fieldElements().clear();
+  sim.goals().clear();
+}
+
+}  // namespace frcsim::BallGamepiecePresets