From b715db1c1cd47d3ad8c43bf92bb71181b9ff998d Mon Sep 17 00:00:00 2001 From: Cedric Date: Sat, 28 Dec 2024 22:24:08 +0000 Subject: [PATCH 1/4] 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 From ec16339f5561f8e7f0f978ce1a0e5f1087c7e1cf Mon Sep 17 00:00:00 2001 From: Cedric Date: Sat, 28 Dec 2024 22:25:52 +0000 Subject: [PATCH 2/4] 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 From b0825cf35755daea1a9aa8cf57ac101d928948cc Mon Sep 17 00:00:00 2001 From: Cedric Date: Sat, 28 Dec 2024 22:26:20 +0000 Subject: [PATCH 3/4] docs: update vehiclesplus-v3/api/gettingstarted --- vehiclesplus-v3/api/gettingstarted.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vehiclesplus-v3/api/gettingstarted.md b/vehiclesplus-v3/api/gettingstarted.md index 0a58e1c..88ce96f 100644 --- a/vehiclesplus-v3/api/gettingstarted.md +++ b/vehiclesplus-v3/api/gettingstarted.md @@ -2,7 +2,7 @@ title: Getting Started description: Api usage published: false -date: 2024-12-28T22:25:49.881Z +date: 2024-12-28T22:26:17.950Z tags: developers editor: markdown dateCreated: 2024-12-28T20:10:42.650Z @@ -54,7 +54,7 @@ dependencies { ## Examples -For usage examples, please visit the [VehiclesPlus Examples Page](https://docs.sbdevelopment.tech/en/vehiclesplus-v3/api/gettingstarted). +For usage examples, please visit the [VehiclesPlus Examples Page](https://docs.sbdevelopment.tech/en/vehiclesplus-v3/api/examples). ## API Documentation From 3ee4b30621e29c5f9212e407d714fda081838e3c Mon Sep 17 00:00:00 2001 From: Cedric Date: Sat, 28 Dec 2024 22:26:50 +0000 Subject: [PATCH 4/4] 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