SBDocs/vehiclesplus-v3/api/examples.md

sidebar_label	sidebar_position
Examples	2

API Examples

In this section, you'll find additional examples of how to use the VehiclesPlus API (v3) for various tasks.

Example 1: Adding a Car to Someone's Garage

public void giveVehicleToGarage(Garage targetGarage, String vehicleType) {
    // Attempt to create a new vehicle of the given type
    StorageVehicle createdVehicle = VehiclesPlusAPI.createVehicle(vehicleType);

    // If vehicle creation fails, log the error and exit
    if (createdVehicle == null) {
        Bukkit.getLogger().warning("Failed to create vehicle of type: " + vehicleType);
        return; // Exit if the vehicle could not be created
    }

    // Add the created vehicle's UUID to the target garage
    targetGarage.addVehicle(createdVehicle.getUuid());
    Bukkit.getLogger().info("Vehicle created and added to the garage successfully.");
}

Example 2: Adding a Vehicle to the Player's Default Garage

// Give car to player's default garage
public void giveVehicleToPlayerGarage(Player player, String vehicleType) {
    // Attempt to create a new vehicle of the given type
    StorageVehicle createdVehicle = VehiclesPlusAPI.createVehicle(vehicleType);

    // Retrieve the player's personal garage (will create a new garage if none exists)
    Garage playerGarage = VehiclesPlusAPI.getPersonalGarage(player);

    // If vehicle creation fails, log the error and exit
    if (createdVehicle == null) {
        Bukkit.getLogger().warning("Failed to create vehicle of type: " + vehicleType);
        return; // Exit if the vehicle could not be created
    }

    // Add the created vehicle's UUID to the player's personal garage
    playerGarage.addVehicle(createdVehicle.getUuid());
    Bukkit.getLogger().info("Vehicle created and added to the player's personal garage successfully.");
}

Example 3: Despawning the First Vehicle of a Player

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);
        Bukkit.getLogger().info("Vehicle despawned successfully.");
    } else {
        // Handle the case where the player doesn't have a spawned vehicle
        Bukkit.getLogger().warning("Player does not have a spawned vehicle.");
    }
}

Example 4: Despawning the Closest Vehicle to a Player

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);
        Bukkit.getLogger().info("Closest vehicle despawned successfully.");
    } else {
        // Handle the case where no spawned vehicles are found for the target player
        Bukkit.getLogger().warning("Target player does not have any spawned vehicles.");
    }
}

Example 5: Removing a Vehicle from the Police Garage

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()) {
        Bukkit.getLogger().warning("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(VehiclesPlusAPI::getVehicle)
            // 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();
            Bukkit.getLogger().info("Vehicle with model '" + vehicleModelName + "' has been successfully removed from the police garage.");
        } catch (DataStorageException e) {
            // Handle any errors that occur during the removal process
            Bukkit.getLogger().log(Level.WARNING, "Error: Failed to remove vehicle with model '" + vehicleModelName + "' from the garage.", e);
        }
    } else {
        // If no matching vehicle was found, print an error message
        Bukkit.getLogger().warning("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.