API ?

[MrClean1337]

Hello, nice plugin ! Gotta question here! No issue :D

Is there any documentation about the API of this plugin? Or is there an API at all?

Something like InvseePlusPlusAPI.openInv (player, player) .. ?

Thanks 👍

[Jannyboy11]

The code is actually quite modular so you can do this, allthough I do need to clean up the internals at some point: I don't think the methods used in this example are going to get restructured in the future, so if you stick to the following examples you're not gonna get breaking changes from InvSee++.

InvseePlusPlus invseePlugin = (InvSeePlusPlus) Bukkit.getPluginManager().getPlugin("InvseePlusPlus");
InvseeAPI invseeApi = invseePlugin.getAPI();

To spectate the inventory of an online player:

String inventoryTitle = ...
Player adminPlayer = ...
Player targetPlayer = ...

MainSpectatorInventory spectatorInventory = invseeApi.spectateInventory(targetPlayer, inventoryTitle);
adminPlayer.openInventory(spectatorInventory);

To spectate the inventory of an offline player if you know their UUID and username (username does not have to up-to-date):

UUID targetPlayerID = ...
String targetUsername = ...

CompletableFuture<Optional<MainSpectatorInventory>> spectatorInventory = invseeApi.spectateInventory(targetPlayerID, targetUsername, inventoryTitle);
spectatorInventory.whenComplete((Optional<MainSpectatorInventory> spectatorInventory, Throwable ex) -> {
    if (ex == null) {
        if (spectatorInventory.isPresent()) {
            adminPlayer.openInventory(spectatorInventory.get());
        } else {
            //could not create the MainSpectatorInventory
        }
    } else {
        //handle error
    }
});

If you don't know the target's unique id, but just his name then you can call another overload. InvSee++ will then try to resolve the UUID for you, and I actually took some effort to make this pretty efficient.

CompletableFuture<Optional<MainSpectatorInventory>> spectatorInventory = invseeApi.spectateInventory(targetUsername, inventoryTitle);
//do the same CompletableFuture shenanigans afterwards

There are also methods for spectating the the enderchest:

EnderSpectatorInventory spectateEnderChest(HumanEntity targetPlayer, String title);
CompletableFuture<Optional<EnderSpectatorInventory>> spectateEnderChest(UUID targetPlayerID, String targetUsername, String inventoryTitle);
CompletableFuture<Optional<EnderSpectatorInventory>> spectateEnderChest(String targetUsername, String inventoryTitle);

The reason why I didn't document this api yet is that I wasn't sure whether this design would be final. I also didn't set the version of the plugin to 1.0 yet because of that, but I don't expect to be breaking those 6 methods I just mentioned.

Hope this helps you!

[MrClean1337]

Thank you! No more questions!

[Jannyboy11]

Alright. I'll close this issue when the api is stable and documented.

[Jannyboy11]

I've refactored the InvseeAPI class today, there are now alternative methods to spectate inventories: mainSpectatorInventory and enderSpectatorInventory.

These return CompletableFuture<SpectateResponse<MainSpectatorInventory>> and CompletableFuture<SpectateResponse<EnderSpectatorInventory>> instead of futures of optionals. SpectateResponse is preferred over Optional because Optional doesn't provide a good way of indicating how creating the inventory failed - SpectateResponse allows me to do just that. For example:

InvseeAPI invseeApi = //get via the same method as before
Player adminPlayer = //...

CompletableFuture<SpectateResponse<MainSpectatorInventory>> future = invseeApi.mainSpectatorInventory("Notch", "Notch's Inventory");

future.whenComplete((response, error) -> {
    if (error == null) {
        if (response.isSuccess()) { //this is just like Optional.isPresent()
             MainSpectatorInventory spectatorInventory = response.getInventory();
             adminPlayer.openInventory(spectatorInventory);
        } else {
             NotCreatedReason reason = response.getReason();
             //either the target does not exist, or the target has the exempt permission.
        }
    } else {
        //handle error
    }
});

NotCreatedReason is a sum-type that currently has three possible implemenations: TargetHasExemptPermission or TargetDoesNotExist. More may be added in the future. Unfortunately I couldn't make NotCreatedReason a sealed class, because I need to remain compatible with Java 11 still.

These new methods of creating spectator inventories are preferred over the old ones, the old ones will eventually be removed.

[Jankoekenpan]

The api is now somewhat documented on the wiki! https://github.com/Jannyboy11/InvSee-plus-plus/wiki