From b715db1c1cd47d3ad8c43bf92bb71181b9ff998d Mon Sep 17 00:00:00 2001 From: Cedric Date: Sat, 28 Dec 2024 22:24:08 +0000 Subject: [PATCH] docs: update vehiclesplus-v3/api/gettingstarted --- vehiclesplus-v3/api/gettingstarted.md | 159 ++++++++++++++++++++------ 1 file changed, 125 insertions(+), 34 deletions(-) diff --git a/vehiclesplus-v3/api/gettingstarted.md b/vehiclesplus-v3/api/gettingstarted.md index 67d7514..0343008 100644 --- a/vehiclesplus-v3/api/gettingstarted.md +++ b/vehiclesplus-v3/api/gettingstarted.md @@ -2,60 +2,151 @@ title: Getting Started description: Api usage published: false -date: 2024-12-28T21:31:42.426Z +date: 2024-12-28T22:24:06.183Z tags: developers editor: markdown dateCreated: 2024-12-28T20:10:42.650Z --- -# API Usage +# VehiclesPlus API Examples -This guide explains how to integrate the new and improved VehiclesPlus API (v3) into your project. +In this section, you'll find additional examples of how to use the VehiclesPlus API (v3) for various tasks. -## Adding VehiclesPlus to Your Project +## Example 1: Adding a Car to Someone's Garage -To use the VehiclesPlus API in your plugin, follow these steps: +```java +// Give car to garage +public void giveCar(Garage garage, String vehicleType) { + // Attempt to create a vehicle + StorageVehicle vehicle = VehiclesPlusAPI.createVehicle(vehicleType); -### Step 1: Add VehiclesPlus to Your Dependencies + if (vehicle == null) { + System.err.println("Failed to create vehicle of type: " + vehicleType); + return; // Exit if the vehicle could not be created + } -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 - + // Add the vehicle's UUID to the garage + garage.addVehicle(vehicle.getUuid()); + System.out.println("Vehicle created and added to the garage successfully."); +} ``` -Gradle (`build.gradle`): +## Example 2: Adding a Vehicle to the Player's Default Garage -```gradle -repositories { - maven { - url 'https://repo.sbdevelopment.tech/releases' +```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 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. } } +``` -dependencies { - implementation 'tech.sbdevelopment:vehiclesplus:latest' +## 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."); + } } ``` -> **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} +## Example 4: Despawning the Closest Vehicle to a Player -## Examples +```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); -For usage examples, please visit the [VehiclesPlus Examples Page](https://docs.sbdevelopment.tech/en/vehiclesplus-v3/api/gettingstarted). + // 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()))); -## API Documentation + // 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."); + } +} +``` -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 +## 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