From ec16339f5561f8e7f0f978ce1a0e5f1087c7e1cf Mon Sep 17 00:00:00 2001 From: Cedric Date: Sat, 28 Dec 2024 22:25:52 +0000 Subject: [PATCH] docs: update vehiclesplus-v3/api/gettingstarted --- vehiclesplus-v3/api/gettingstarted.md | 169 ++++++-------------------- 1 file changed, 39 insertions(+), 130 deletions(-) diff --git a/vehiclesplus-v3/api/gettingstarted.md b/vehiclesplus-v3/api/gettingstarted.md index 0343008..0a58e1c 100644 --- a/vehiclesplus-v3/api/gettingstarted.md +++ b/vehiclesplus-v3/api/gettingstarted.md @@ -2,151 +2,60 @@ title: Getting Started description: Api usage published: false -date: 2024-12-28T22:24:06.183Z +date: 2024-12-28T22:25:49.881Z tags: developers editor: markdown dateCreated: 2024-12-28T20:10:42.650Z --- -# VehiclesPlus API Examples +# API Usage -In this section, you'll find additional examples of how to use the VehiclesPlus API (v3) for various tasks. +This guide explains how to integrate the new and improved VehiclesPlus API (v3) into your project. -## Example 1: Adding a Car to Someone's Garage +## Adding VehiclesPlus to Your Project -```java -// Give car to garage -public void giveCar(Garage garage, String vehicleType) { - // Attempt to create a vehicle - StorageVehicle vehicle = VehiclesPlusAPI.createVehicle(vehicleType); +To use the VehiclesPlus API in your plugin, follow these steps: - if (vehicle == null) { - System.err.println("Failed to create vehicle of type: " + vehicleType); - return; // Exit if the vehicle could not be created +### 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 + + sbdevelopment-repo + https://repo.sbdevelopment.tech/releases + + + + tech.sbdevelopment + vehiclesplus + latest + +``` + +Gradle (`build.gradle`): + +```gradle +repositories { + maven { + url 'https://repo.sbdevelopment.tech/releases' } +} - // Add the vehicle's UUID to the garage - garage.addVehicle(vehicle.getUuid()); - System.out.println("Vehicle created and added to the garage successfully."); +dependencies { + implementation 'tech.sbdevelopment:vehiclesplus:latest' } ``` -## Example 2: Adding a Vehicle to the Player's Default Garage +> **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`). +{.is-info} -```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); +## Examples - // Retrieve the player's default garage - Optional optionalGarage = VehiclesPlusAPI.getGarage(player.getName()); +For usage examples, please visit the [VehiclesPlus Examples Page](https://docs.sbdevelopment.tech/en/vehiclesplus-v3/api/gettingstarted). - if (vehicle == null) { - System.err.println("Failed to create vehicle of type: " + vehicleType); - return; // Exit if the vehicle could not be created - } +## API Documentation - 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. - } -} -``` - -## Example 3: Despawning the First Vehicle of a Player - -```java -public void despawnFirstVehicle(Player player) { - // Retrieve the first spawned vehicle of the player - Optional firstSpawnedVehicleOptional = VehiclesPlusAPI.getVehicle(player); - - // Check if a vehicle is present to despawn - if (firstSpawnedVehicleOptional.isPresent()) { - // Despawn the vehicle using the API's despawn reason - firstSpawnedVehicleOptional.get().despawn(VehicleDespawnEvent.DespawnReason.API); - System.out.println("Vehicle despawned successfully."); - } else { - // Handle the case where the player doesn't have a spawned vehicle - System.err.println("Player does not have a spawned vehicle."); - } -} -``` - -## Example 4: Despawning the Closest Vehicle to a Player - -```java -public void despawnClosestVehicle(Player executor, Player targetPlayer) { - // Retrieve a list of all spawned vehicles belonging to the target player - @NotNull List vehiclesOfTargetPlayer = VehiclesPlusAPI.getVehicles(targetPlayer); - - // Find the closest spawned vehicle to the executor player - Optional closestVehicleOptional = vehiclesOfTargetPlayer.stream() - .filter(vehicle -> vehicle instanceof SpawnedVehicle) // Only consider spawned vehicles - .map(vehicle -> (SpawnedVehicle) vehicle) - .min(Comparator.comparingDouble(vehicle -> vehicle.getHolder().getLocation().distance(executor.getLocation()))); - - // Check if the closest vehicle was found - if (closestVehicleOptional.isPresent()) { - // Despawn the closest vehicle using the API's despawn reason - closestVehicleOptional.get().despawn(VehicleDespawnEvent.DespawnReason.API); - System.out.println("Closest vehicle despawned successfully."); - } else { - // Handle the case where no spawned vehicles are found for the target player - System.err.println("Target player does not have any spawned vehicles."); - } -} -``` - -## Example 5: Removing a Vehicle from the Police Garage - -```java -public void removeVehicleFromPoliceGarage(String vehicleModelName) { - // Retrieve the "police" garage using its name - Optional policeGarageOptional = VehiclesPlusAPI.getGarage("police"); - - // Check if the police garage exists, and if not, print an error message and exit - if (policeGarageOptional.isEmpty()) { - System.err.println("Error: The 'police' garage does not exist."); - return; - } - - // Get the actual garage object - Garage policeGarage = policeGarageOptional.get(); - - // Search for the vehicle with the given model name within the "police" garage - Optional vehicleToRemoveOptional = policeGarage.getVehicles().stream() - // Convert the vehicle UUID to an actual StorageVehicle object - .map(vehicleUuid -> VehiclesPlusAPI.getVehicle(vehicleUuid)) - // Filter vehicles to match the given model name - .filter(vehicle -> vehicle != null && vehicle.getVehicleModel().getId().equals(vehicleModelName)) - // Select the first match - .findFirst(); - - // If a matching vehicle is found, attempt to remove it - if (vehicleToRemoveOptional.isPresent()) { - Vehicle vehicleToRemove = vehicleToRemoveOptional.get(); - - try { - // Remove the vehicle from the garage - vehicleToRemove.remove(); - System.out.println("Vehicle with model '" + vehicleModelName + "' has been successfully removed from the police garage."); - } catch (DataStorageException e) { - // Handle any errors that occur during the removal process - System.err.println("Error: Failed to remove vehicle with model '" + vehicleModelName + "' from the garage."); - throw new RuntimeException("Error while removing vehicle", e); - } - } else { - // If no matching vehicle was found, print an error message - System.err.println("Error: No vehicle with model '" + vehicleModelName + "' found in the police garage."); - } -} -``` - -## More Examples - -For additional usage examples, please visit the [VehiclesPlus API Examples on GitHub](https://git.sbdevelopment.tech/SBDevelopment/VehiclesPlus-v3-API-example). \ No newline at end of file +For additional details and advanced usage refer to the official [VehiclesPlus Javadoc](https://sbdevelopment.tech/javadoc/vehiclesplus-v3/index.html). \ No newline at end of file