SBDevelopment/docs
Archived
3
0
Fork 1
Code Activity

docs: update vehiclesplus-v3/api/gettingstarted

Browse source
This commit is contained in:
Cedric 2024-12-28 22:25:52 +00:00 committed by SBDeveloper
parent b715db1c1c
commit ec16339f55
1 changed files with 39 additions and 130 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

169
vehiclesplus-v3/api/gettingstarted.md
View file

@ -2,151 +2,60 @@
title: Getting Started title: Getting Started
description: Api usage description: Api usage
published: false published: false
date: 2024-12-28T22:24:06.183Z date: 2024-12-28T22:25:49.881Z
tags: developers tags: developers
editor: markdown editor: markdown
dateCreated: 2024-12-28T20:10:42.650Z 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 To use the VehiclesPlus API in your plugin, follow these steps:
// Give car to garage
public void giveCar(Garage garage, String vehicleType) {
// Attempt to create a vehicle
StorageVehicle vehicle = VehiclesPlusAPI.createVehicle(vehicleType);
if (vehicle == null) { ### Step 1: Add VehiclesPlus to Your Dependencies
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
<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'
}
} }
// Add the vehicle's UUID to the garage dependencies {
garage.addVehicle(vehicle.getUuid()); implementation 'tech.sbdevelopment:vehiclesplus:latest'
System.out.println("Vehicle created and added to the garage successfully.");
} }
``` ```
## 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 ## Examples
// 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 For usage examples, please visit the [VehiclesPlus Examples Page](https://docs.sbdevelopment.tech/en/vehiclesplus-v3/api/gettingstarted).
Optional<Garage> optionalGarage = VehiclesPlusAPI.getGarage(player.getName());
if (vehicle == null) { ## API Documentation
System.err.println("Failed to create vehicle of type: " + vehicleType);
return; // Exit if the vehicle could not be created
}
if (optionalGarage.isPresent()) { For additional details and advanced usage refer to the official [VehiclesPlus Javadoc](https://sbdevelopment.tech/javadoc/vehiclesplus-v3/index.html).
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<SpawnedVehicle> 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<Vehicle> vehiclesOfTargetPlayer = VehiclesPlusAPI.getVehicles(targetPlayer);
// Find the closest spawned vehicle to the executor player
Optional<SpawnedVehicle> 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<Garage> 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<Vehicle> 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).