[Ongoing] New API Ideas

[lokka30]

New API Ideas!

Hey there everyone, if you have any ideas for new APIs to go into Treasury, feel free to chat below! If it is regarding an existing API idea, please reply to it rather than create a new comment.

Q/A

What APIs won't be added?

• Anything that can't be scaled to multiple platforms (including proxies)

• Anything handling Minecraft internals (NMS)

  • Yes, including packets

• Utility APIs such as database management. Treasury is a library for integrations, not utilities.

How can I be alerted when any of these APIs are released?

Simply 'Watch Resource' on Treasury's SpigotMC page and see the top of the changelogs. We rarely update so you won't get spammed. :)

[lokka30]

Permissions+Chat API

Likelihood:

🟢

Features:

• ?

Code ideas:

• ?

[lokka30]

I think the only thing we need to note down for permissions at least is the ability to retrieve it whilst the user is offline of course. Should be very easy for permission plugins to handle. My only concern is of the permission plugins that are conditional, e.g. you have this permission but only in this world. So maybe the offline permissions need to be an optional feature. This will require more discussion it seems.

[A248]

To revive this discussion, here are some suggestions:

• Regarding conditional permissions, the approach used by the SpongeAPI and LuckPerms utilizes key-value pairs called "contexts." Treasury's API, accordingly, could accept a Set<PermissionContext> or a Map<String, String> when a permission is requested for a possibly offline player. For example, this map might be Map.of("world", "world_the_end", "server", "lobby") to indicate the world world_the_end and the backend server lobby.
• There should be also be a method, for online players only, which checks for a permission node using the player's currently active contexts.
• Another aspect of the permissions API should be the ability to request permission data for a possibly offline user before performing any permission checks. This way, the caller may indicate a desire to have the data loaded in-memory before performing a specific query.

On Sponge, if or rather when Treasury is implemented for that platform, there should be a default implementation of the Treasury permissions API which delegates to Sponge's PermissionService.

[lokka30]

Land Protection API

Likelihood:

🟡 Partial

Features:

• Region Permissions enum states what a player can do in a region (claim).
• Check what Region Permissions a player has for a specific location.
• Get the names of the plugins that affect a player's Region Permissions for a specific location. Allows plugins to be configured e.g. 'ignore worldguard regions for random teleport'.

Code ideas:

• ?

[lokka30]

I don't see why 'content' is an issue - our APIs can be simple yet highly effective. I also believe this is the case for the proposed Vanish API. I can elaborate on that if you like under that post.

The first method I can think of is obviously something like hasRegionPermission(player, RegionPermission.BREAK_BLOCKS, location, new RegionSubscriber<TriState>(subscription -> {...}));.

[MrNemo64]

Content is an issue because why should we have a unified api if it has no more than 3 methods?

I think this API could have more than 3 methods. My ideas are this:
The LandProtector interface. This is what would be implemented by providers and has methods like void canPerformAction(Entiry, Action, Position, LandProtectorSubscriber<TriState>), void reteiveRegisteredAreas(LandProtectorSubscriber<Collection<ProtectedArea>>), Set<OptionalLandProtectionFeatures> getSupportedOptionalLandProtectionApiFeatures() etc
The ProtectedArea interface would represent a protected area/zone in the world and it's somewhat inspired by the Shape class. This interface would define methods like void canPerformAction(Entity, Action, LandProtectorSubscriber<TriState>), void containsPosition(Position, LandProtectorSubscriber<Boolean>), void intersects(Cube, LandProtectorSubscriber<Boolean>) void getPathIterator(LandProtectorSubscriber<Iterator<Segment>>), void getBlockIterator(LandProtectorSubscriber<Iterator<Block>>) (dangerous as interactions with blocks normaly can only be performed onthe main thread) and maybe some more

[lokka30]

Vanish API

Likelihood:

🌕 Partial

Features:

• Check if an online/offline player can see another online/offline player (vanished state)

Code ideas:

• record VanishedState(UUID playerId, Map<UUID otherPlayerId, TriState visibility)
• retrieveVanishedState(UUID playerId, VanishSubscriber<VanishedState> subscriber);
• retrieveVanishedState(UUID playerId, UUID targetId, VanishSubscriber<TriState> subscriber);]

Note: TriStates shall be used because:

• TriState.TRUE = the viewer is said to must be able to see the target
• TriState.UNSPECIFIED = the default value: the viewer can see the target but this can change
• TriState.FALSE = the viewer can't see the target

[lokka30]

Block Logging API

I am unsure what this API would do, but it involves interfacing with block logging plugins like CoreProtect and Prism.

Likelihood:

Unsure.

Features:

Unsure.

Code ideas:

Unsure.

[MrNemo64]

The idea for this came to my mind when thinking about the protections API. I couldn't think of a scenario where you would need it but thought that it was worth mentioning to see what you think. I wouldn't consider developing this further unless we see a necesity to do so

[Jikoo]

Yeah, I've had requests to support block loggers similarly to protection plugins for my use case, would see some niche use. Not sure if it's worth writing though given how different block logger APIs are, would need to research.

[MrIvanPlays]

I have no ideas how to write a block logger api too. We shall skip this until demand is my opinion.

[lokka30]

Should probably contact block logging plugin developers to see if they are interested in such an API.

[lokka30]

I don't believe we should develop such an API. What plugins need to use block logging plugin APIs? There are only a few block logging plugins that are popular at the moment, so I don't think a central API would help much.

[MrIvanPlays]

if you have anything better multi platform i'd like code. if you dont then this is not getting into treasury.

[MrNemo64]

I don't have time right now to write code but this may give an idea

classDiagram

    InputProcess --> InputSender
    InputProcess --> InputProcessor
    InputProcess --> InputListener
    InputProcess --> InputProcessState
    InputProcess --> InputProcessEndReason
    InputProcess --> InputProcessResponse
    InputProcessManager --> InputProcess

    class InputProcessManager {
        + startInputProcess(InputProcess~?, ?~ inputProcess)
        + Collection~InputProcess~ getQueuedInputProcessesFor(InputSender sender)
    }

    class InputProcess~InputType, ValueType~ {
        - InputProcessor~InputType, ValueType~ processor
        - InputListener~InputType~ listener
        - InputSender sender
        + boolean isRunning()
        + InputProcessState getInputProcessState()
        + void getInputProcessEndReason(InputProcessResponse~InputProcessEndReason~ subscriber)
        + void whenFinished(InputProcessResponse~ValueType~ subscriber)
    }

    class InputProcessEndReason {
        INPUT_ACCEPTED
        CANCELLED
        FORCE_CANCELLED
        COMPLETED_EXCEPTIONALLY
    }

    class InputProcessState {
        CREATED
        QUEUED
        RUNNING
        FINISHED
    }

    class InputSender {
        + UUID getUniqueId()
        + void sendMessage(String message)
    }

    class InputProcessor~InputType, ValueType~ {
        + boolean isValidInput(InputType input)
        + ValueType convertInput(InputType input)
    }

    class InputListener~InputType~ {
        + void receiveInput(InputType input)
    }

Loading

[MrIvanPlays]

thanks but my position here is no.

[lokka30]

The idea is great, but it is probably difficult or impossible to execute in a way that pertains with our high standard for quality. I'm currently neutral for this API idea.

[lokka30]

I have thought about this further and I have come to the conclusion that although this API would be brilliant, unfortunately there are some key issues which prevent me from adding a conversations API.

1. Treasury is a library for service integrations. It adds specific APIs to make certain services such as economy plugin cores easier to integrate with. It however does not add utility APIs such as conversations, logging, database management, etc.
2. Low adoption. This does not sway me much but it is nevertheless something worth noting. Only a handful of plugins would benefit from such an API.

Thus, as we concluded with the Item Registry API, I believe this is worth being separate from Treasury, as much as it would be awesome to have both inside one central package.

[Jannyboy11]

Alternatives:

I don't know of any existing item registry APIs, but I also haven't tried searching.

I know of one, but it doesn't seem widely used: https://polymart.org/resource/item-bridge.4

[lokka30]

Alternatives:

I don't know of any existing item registry APIs, but I also haven't tried searching.

I know of one, but it doesn't seem widely used: https://polymart.org/resource/item-bridge.4

I forgot to update this post, but I did start on an idea for Registry, I just haven't had the time to work on it yet. I've still yet to be able to pick up #180 and #167 😦

[Hellscaped]

Punishments API

An API where advanced forms of punishment could possibly happen. ex: push a large cobblestone cube up a mountain to get your rights back

Likelihood:

Unsure.

Features:

PunishmentProvider: Like EconomyProvider but is used to deal punishments and their types.

Code ideas:

PunishmentProvider, Punishment, PunishmentSubscriber (EconomySubscriber but called when the punishment is handed out/completed)

[lokka30]

Thanks for the suggestion @Hellscaped. More likely a punishments API would be very general and aim to cover mutes, warnings, bans, etc. I'm sure A248 would be very knowledgable about this if Ivan thinks it's a good idea to proceed with this idea.

[MrIvanPlays]

Noting that there are many ban plugins out there it'd be a good idea, however I can't see much use of it.

[lokka30]

( See OP's reply here which was posted as a reply to the discussion rather than this existing thread ).

Noting that there are many ban plugins out there it'd be a good idea, however I can't see much use of it.

Most ban plugins have their punishment logic in them, this would separate the punishing from the punishment logic, making ban plugins able to have custom punishments (like the Sisyphus boulder idea) provided by additional plugins

So in other words, this would allow other plugins ("punishment consumers") to view, create, and edit punishments from ban plugins ("punishment providers")?

[Hellscaped]

( See OP's reply here which was posted as a reply to the discussion rather than this existing thread ).

Noting that there are many ban plugins out there it'd be a good idea, however I can't see much use of it.

Most ban plugins have their punishment logic in them, this would separate the punishing from the punishment logic, making ban plugins able to have custom punishments (like the Sisyphus boulder idea) provided by additional plugins

So in other words, this would allow other plugins ("punishment consumers") to view, create, and edit punishments from ban plugins ("punishment providers")?

Oops, didn't realize I posted it as a reply to the discussion, sorry about that!

And yes, thats the idea in a nutshell.