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:24:08 +00:00 committed by SBDeveloper
parent 7c6ad99b54
commit b715db1c1c
1 changed files with 125 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -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
<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>
// 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<Garage> 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<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.");
}
}
```
> **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<Vehicle> 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<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())));
## 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).
## 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).