From 3ee4b30621e29c5f9212e407d714fda081838e3c Mon Sep 17 00:00:00 2001 From: Cedric Date: Sat, 28 Dec 2024 22:26:50 +0000 Subject: [PATCH] docs: update vehiclesplus-v3/api/examples --- vehiclesplus-v3/api/examples.md | 125 ++++++++++++++++++++++++++++---- 1 file changed, 111 insertions(+), 14 deletions(-) diff --git a/vehiclesplus-v3/api/examples.md b/vehiclesplus-v3/api/examples.md index 011e2a6..d681cae 100644 --- a/vehiclesplus-v3/api/examples.md +++ b/vehiclesplus-v3/api/examples.md @@ -2,7 +2,7 @@ title: Examples description: Example usages of the api published: false -date: 2024-12-28T21:29:47.658Z +date: 2024-12-28T22:26:48.261Z tags: developers editor: markdown dateCreated: 2024-12-28T21:11:02.102Z @@ -35,21 +35,118 @@ public void giveCar(Garage garage, String vehicleType) { ```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); +public void giveCar(Player player, String vehicleType) { + // Attempt to create a vehicle + StorageVehicle vehicle = VehiclesPlusAPI.createVehicle(vehicleType); - // Retrieve the player's default garage - // Note: This method will always return a garage, even if the player does not have one. - // If the player does not have a garage, the garage will be created. - Garage garage = VehiclesPlusAPI.getPersonalGarage(player); + // 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 (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. } -``` \ No newline at end of file +} +``` + +## 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