docs: create vehiclesplus-v3/API

vehiclesplus-v3/API.md

@@ -0,0 +1,100 @@
+---
+title: API
+description: Api usage examples
+published: true
+date: 2024-12-28T20:10:42.650Z
+tags: developers
+editor: markdown
+dateCreated: 2024-12-28T20:10:42.650Z
+---
+
+# API Usage
+
+This guide explains how to integrate the new and improved VehiclesPlus API (v3) into your project.
+
+## Adding VehiclesPlus to Your Project
+
+To use the VehiclesPlus API in your plugin, follow these steps:
+
+### Step 1: Add VehiclesPlus to Your Dependencies
+Ensure VehiclesPlus is added as a dependency in your project. To always use the latest version, update your dependency configuration as shown below:
+
+Maven (`pom.xml`):
+```xml
+<repository>
+    <id>sbdevelopment-repo</id>
+    <url>https://repo.sbdevelopment.tech/releases</url>
+</repository>
+
+<dependency>
+    <groupId>tech.sbdevelopment</groupId>
+    <artifactId>vehiclesplus</artifactId>
+    <version>LATEST</version>
+</dependency>
+```
+
+Gradle (`build.gradle`):
+```gradle
+repositories {
+    maven {
+        url 'https://repo.sbdevelopment.tech/releases'
+    }
+}
+
+dependencies {
+    implementation 'tech.sbdevelopment:vehiclesplus:LATEST'
+}
+```
+> **Note**: Using `LATEST` ensures that your project always fetches the most recent release, but it might cause issues if breaking changes are introduced. For more stability, consider specifying a specific version (e.g., `3.0.2`).
+
+
+## Example: Adding a Car to Someone's Garage
+
+This example demonstrates how to add a vehicle to any garage:
+
+
+```java
+// Give car to garage
+public void giveCar(Garage garage, String vehicleType) {
+    // Attempt to create a vehicle
+    StorageVehicle vehicle = VehiclesPlusAPI.createVehicle(vehicleType);
+
+    if (vehicle == null) {
+        System.err.println("Failed to create vehicle of type: " + vehicleType);
+        return; // Exit if the vehicle could not be created
+    }
+
+    // Add the vehicle's UUID to the garage
+    garage.addVehicle(vehicle.getUuid());
+    System.out.println("Vehicle created and added to the garage successfully.");
+}
+```
+
+## Example: Adding a Vehicle to the Player's Default Garage
+
+This example demonstrates how to add a vehicle to the player's default garage:
+
+```java
+// Give car to player's default garage
+public void giveCar(Player player, String vehicleType) {
+    // Attempt to create a vehicle
+    StorageVehicle vehicle = VehiclesPlusAPI.createVehicle(vehicleType);
+
+    // Retrieve the player's default garage
+    Optional<Garage> optionalGarage = VehiclesPlusAPI.getGarage(player.getName());
+
+    if (vehicle == null) {
+        System.err.println("Failed to create vehicle of type: " + vehicleType);
+        return; // Exit if the vehicle could not be created
+    }
+
+    if (optionalGarage.isPresent()) {
+        Garage garage = optionalGarage.get();
+        garage.addVehicle(vehicle.getUuid());
+        System.out.println("Vehicle created and added to the garage successfully.");
+    } else {
+        System.err.println("Garage not found for player: " + player.getName());
+        // Optionally, you could create a new garage for the player here if the API allows it.
+    }
+}
+```