API per sviluppatori

L'API di EndlessVehicles permette a un altro plugin di leggere e usare ogni funzione: veicoli, garage, carburante, modelli, negozio ed eventi.

Aggiungere la dipendenza

Il modulo endlessvehicles-api contiene solo interfacce, record, enumerazioni ed eventi: l'implementazione sta nel plugin. Si dichiara come provided (non va incluso nel tuo jar) e nel plugin.yml del tuo plugin serve depend (o softdepend) su EndlessVehicles.

Maven

<repositories>
  <repository>
    <id>endless</id>
    <url>https://endlesshorizons.it/maven</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>it.endlesshorizons.endlessvehicles</groupId>
    <artifactId>endlessvehicles-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

Gradle

repositories {
    maven { url = uri("https://endlesshorizons.it/maven") }
}

dependencies {
    compileOnly("it.endlesshorizons.endlessvehicles:endlessvehicles-api:1.0.0")
}

plugin.yml

name: MyPlugin
main: com.example.MyPlugin
api-version: '1.21'
depend: [EndlessVehicles]

Come si usa

Ottieni l'API con EndlessVehiclesApi.get() (dopo che EndlessVehicles è attivo, per esempio nell'onEnable). Con EndlessVehiclesApi.find() ricevi un Optional invece di un'eccezione.

EndlessVehiclesApi api = EndlessVehiclesApi.get();

// the vehicle a player is driving
api.vehicles().getRiddenBy(player.getUniqueId()).ifPresent(vehicle ->
        player.sendMessage(vehicle.plate() + ": " + vehicle.fuelLiters() + " L"));

// give a vehicle to a garage
GiveResult result = api.vehicles().give("police", "crown_victoria", null, false, GiveSource.COMMAND);
if (result.isOk()) {
    api.fuel().addFuel(result.vehicleId(), 20);
}

// sell a vehicle to a player (payments go through Vault)
PurchaseResult bought = api.shop().buy(player, "offroad_black", new VehicleColor(200, 30, 30), null, false);

I servizi

Servizio	Cosa fa
`api.vehicles()`	Leggere un veicolo (per id, targa, proprietario, garage, giocatore a bordo); darne uno a un garage; farlo uscire o rientrare; far salire un giocatore; bloccare, rinominare, trasferire; limite di velocità; riparare; salute; potenziamenti; bagagliaio; aprire il menu.
`api.garages()`	Leggere i garage; crearli, eliminarli, rinominarli, cambiare proprietario; membri e ruoli con i loro permessi; controllare un permesso; aprire il menu.
`api.fuel()`	Tipi di carburante, livello e capacità, aggiungere o impostare il carburante, creare e leggere una tanica, elenco dei distributori.
`api.models()`	Elenco e dettagli dei modelli (prezzi, velocità, serbatoio, hitbox, colori) e ricarica dei file.
`api.shop()`	Modelli acquistabili da un giocatore, acquisto con pagamento tramite Vault, apertura del negozio.

Risultati e snapshot

Le operazioni che cambiano qualcosa restituiscono un valore (ApiResult, PurchaseResult, UpgradeResult, RepairResult, EnterResult) invece di lanciare eccezioni: OK è l'unico caso di successo. Gestisci sempre anche il caso default, perché possono comparire nuovi valori.
I record come VehicleInfo, GarageInfo e ModelInfo sono istantanee immutabili: non si aggiornano da sole, richiedi di nuovo il dato.

Regole da conoscere

Thread principale. Tutti i metodi vanno chiamati dal thread principale del server.
Permessi. Le operazioni sono "fidate", come un comando eseguito da un amministratore: non controllano i ruoli del garage né i permessi ev.*. Le uniche eccezioni sono i metodi che agiscono a nome di un giocatore che paga o sale a bordo (buy, repair(id, giocatore), upgrade, enter), che rispettano i permessi di quel giocatore.
Eventi cancellabili. Anche le chiamate dell'API fanno partire gli eventi cancellabili: un altro plugin può bloccarle (risultato CANCELLED).
Versione. EndlessVehiclesApi.API_VERSION cresce solo quando l'API cambia; api.getApiVersion() dice la versione del plugin installato. Una versione pubblicata non si modifica mai.

Eventi

Gli eventi sono eventi Bukkit normali, nel pacchetto it.endlesshorizons.endlessvehicles.api.event, sincroni e sul thread principale. Si ascoltano con @EventHandler; quelli cancellabili si bloccano con setCancelled(true).

@EventHandler
public void onEnter(VehicleEnterEvent event) {
    var vehicle = EndlessVehiclesApi.get().vehicles().getVehicle(event.getVehicleId()).orElse(null);
    if (vehicle != null && vehicle.category() == VehicleCategory.EMERGENCY && !event.getPlayer().hasPermission("police.drive")) {
        event.setCancelled(true);
    }
}

Evento	Quando parte	Cancellabile
`VehiclePreSpawnEvent`	Un giocatore sta per far uscire un veicolo dal garage	sì
`VehicleSpawnedEvent`	Il veicolo è comparso nel mondo	no
`VehicleDespawnEvent`	Il veicolo sta per essere rimosso dal mondo (motivo e se è forzato)	sì (non se forzato)
`VehicleEnterEvent`, `VehicleLeaveEvent`	Un giocatore sale o scende da un sedile	sì
`VehicleClickEvent`	Un giocatore fa clic destro su un veicolo	sì
`VehicleLockStateChangeEvent`	Un veicolo sta per essere chiuso o aperto	sì
`VehicleCollisionEvent`	Urto contro un blocco, un essere vivente o un altro veicolo	sì (toglie danno e spinta)
`VehicleDestroyEvent`	La salute arriva a zero	sì (lascia 1 di salute)
`VehicleRefuelEvent`	Sta per essere aggiunto carburante	sì
`VehicleUpgradeEvent`	Un potenziamento sta per essere acquistato, prima del pagamento	sì
`VehicleBuyEvent`	Un giocatore sta per comprare un veicolo, prima del pagamento	sì
`VehicleGiveEvent`	Un veicolo sta per entrare in un garage (comando, voucher, negozio, trasferimento)	sì
`VehicleDeleteEvent`	Un veicolo sta per essere eliminato per sempre	sì
`GarageOpenEvent`	Il menu di un garage sta per aprirsi	sì

Gli eventi dell'API partono prima di quelli interni del plugin: se cancelli un evento dell'API, l'operazione si ferma.

Per chi pubblica il modulo

Il modulo è endlessvehicles-api (versione propria, indipendente dal plugin). Le istruzioni per generare la cartella del repository Maven e caricarla sul server web sono in API-PUBLISHING.md nella radice del progetto.

PrecedenteDomande frequenti