CloudNet v4: API User-Documentation/Examples #1287

Activity

1. DasBabyPixel

   added

   s: needs triageIssue waiting for triageIssue waiting for triage

   t: feature requestA request of a feature someone wants to see in a future release.A request of a feature someone wants to see in a future release.

   on Aug 16, 2023
2. derklaro commented on Aug 17, 2023

   

   derklaro

   on Aug 17, 2023

   Member

   More actions

   It's planned when the api is considered stable. As there are still some changes planned, it doesn't make much sense to write full guides just to change them again accordingly.
   I will keep this open - if someone has suggestions or even code examples that we should put into the documentation feel free to post them here 😄
3. derklaro

   added

   v: 4.XThis pull should be included in the 4.0 releaseThis pull should be included in the 4.0 release

   and removed

   s: needs triageIssue waiting for triageIssue waiting for triage

   on Aug 17, 2023
4. derklaro

   pinned this issue on Aug 17, 2023
5. DasBabyPixel commented on Aug 17, 2023

   

   DasBabyPixel

   on Aug 17, 2023

   ContributorAuthor

   More actions

   Any forecast on how long it is going to take until there is a release?

   👎React with 👎1Reacted by Pasqual Koschmieder
6. DasBabyPixel commented on Sep 16, 2023

   

   DasBabyPixel

   on Sep 16, 2023

   ContributorAuthor

   More actions

   This thread is about examples for CloudNet 4.
   Anyone looking for examples for CloudNet 3 can find them here.
   (There are also "official" examples for the permission system, but thanks for trying to provide examples 👍 )

   As far as I know the cloud permission system is going to be removed. Anyone actively using it might want to migrate to luckperms
7. derklaro

   changed the title [-]API Examples[/-] [+]CloudNet v4: API User-Documentation/Examples[/+] on Sep 16, 2023
8. derklaro

   added

   t: trackingTracking issue for an experimental or scheduled for removal api.Tracking issue for an experimental or scheduled for removal api.

   on Sep 16, 2023
9. dizzyelk commented on Apr 3, 2024

   

   dizzyelk

   on Apr 3, 2024

   More actions

   I have not used dependency injection before, and I hope to provide an example as soon as possible
10. DasBabyPixel commented on Apr 3, 2024

    

    DasBabyPixel

    on Apr 3, 2024

    ContributorAuthor

    More actions

    A quick summary for most use cases:
    If you want to develop a CN-Module, you can acquire object instances in the methods annotated with @ModuleTask.
    If you want to develop a server plugin that uses CN api, see examples later in this post
    This gives you access to pretty much everything that used to be in CloudNetDriver

    @ModuleTask(lifecycle = ModuleLifeCycle.STARTED)
    public void start(@Name("module") InjectionLayer<SpecifiedInjector> injectionLayer, ComponentInfo componentInfo, DatabaseProvider databaseProvider) {
    }
    

    You can add as many parameters as you need.
    The first parameter in this example is the InjectionLayer for the module. (Parameter can also be omitted if not required)
    This InjectionLayer is the thing behind the scenes that gets you the instances.
    If you want an instance and you do not have the option of getting it in a @ModuleTask method, you can use the InjectionLayer to do so:

    DatabaseProvider databaseProvider = injectionLayer.instance(DatabaseProvider.class)
    

    The InjectionLayer with @name("module") is an InjectionLayer specifically for YOUR module. It inherits from the default CN InjectionLayers (ext).
    These default InjectionLayers are InjectionLayer.ext() and InjectionLayer.boot(). ext inherits from boot and is meant for extension use cases.
    Because ext inherits from boot, the InjectionLayer of your module implicitly inherits from boot. (module < ext < boot)
    All the object instances you usually need are installed in boot.
    If you want access from a server plugin (and not a CN-module), you can use these InjectionLayers to get instances:
    InjectionLayer.boot().instance(DatabaseProvider.class)

    Services I have used so far

    • ServiceInfoHolder
    • EventManager
    • DatabaseProvider
    • ComponentInfo
    • ServiceTaskProvider
    • TemplateStorageProvider
    • GroupConfigurationProvider
    • ServiceRegistry
    • BridgeServiceHelper

    The PlayerManager is bridge specific and thus hidden behind the ServicesRegistry:
    Example for use inside bukkit plugin:

    private final PlayerManager playerManager = InjectionLayer.boot().instance(ServiceRegistry.class).firstProvider(PlayerManager.class);
    

    Little more advanced
    You can install custom Bindings (basically object instances/object instance suppliers) into any InjectionLayer.
    This can be done by using

    injectionLayer.install(BindingBuilder.create().bind(ProviderInterface.class).toInstance(new ProviderImplementation()))
    

    You can also inject object instances in constructors, to understand how that works I recommend taking a closer look at existing CloudNet modules like bridge, which are good examples of recommended usage. These modules take it a step further and do not constructors, they instead let the DI framework construct all the objects. They only say: "Hey, gimme an instance of XYZ".

    If you need more information on DI, I can recommend the jakarta specs and the Aerogel github README
    JSR 330 is also an option, but IMO thats the worse documentation

    This should pretty much cover all basic usage.

    @derklaro correct me if I'm wrong about anything here pls

    🎉React with 🎉1Reacted by DizzyElk
11. dizzyelk commented on Apr 3, 2024

    

    dizzyelk

    on Apr 3, 2024

    More actions

    very think @

    A quick summary for most use cases: If you want to develop a CN-Module, you can acquire object instances in the methods annotated with @ModuleTask. If you want to develop a server plugin that uses CN api, see examples later in this post This gives you access to pretty much everything that used to be in CloudNetDriver

    @ModuleTask(lifecycle = ModuleLifeCycle.STARTED)
    public void start(@Name("module") InjectionLayer<SpecifiedInjector> injectionLayer, ComponentInfo componentInfo, DatabaseProvider databaseProvider) {
    }
    

    You can add as many parameters as you need. The first parameter in this example is the InjectionLayer for the module. (Parameter can also be omitted if not required) This InjectionLayer is the thing behind the scenes that gets you the instances. If you want an instance and you do not have the option of getting it in a @ModuleTask method, you can use the InjectionLayer to do so:

    DatabaseProvider databaseProvider = injectionLayer.instance(DatabaseProvider.class)
    

    The InjectionLayer with @name("module") is an InjectionLayer specifically for YOUR module. It inherits from the default CN InjectionLayers (). These default InjectionLayers are and . inherits from and is meant for extension use cases. Because inherits from , the InjectionLayer of your module implicitly inherits from . ( < < ) All the object instances you usually need are installed in . If you want access from a server plugin (and not a CN-module), you can use these InjectionLayers to get instances:ext``InjectionLayer.ext()``InjectionLayer.boot()``ext``boot``ext``boot``boot``module``ext``boot``boot InjectionLayer.boot().instance(DatabaseProvider.class)

    Services I have used so far

    • ServiceInfoHolder
    • EventManager
    • DatabaseProvider
    • ComponentInfo
    • ServiceTaskProvider
    • TemplateStorageProvider
    • GroupConfigurationProvider
    • ServiceRegistry
    • BridgeServiceHelper

    The PlayerManager is specific and thus hidden behind the ServicesRegistry: Example for use inside bukkit plugin:bridge

    private final PlayerManager playerManager = InjectionLayer.boot().instance(ServiceRegistry.class).firstProvider(PlayerManager.class);
    

    Little more advanced You can install custom Bindings (basically object instances/object instance suppliers) into any InjectionLayer. This can be done by using

    injectionLayer.install(BindingBuilder.create().bind(ProviderInterface.class).toInstance(new ProviderImplementation()))
    

    You can also inject object instances in constructors, to understand how that works I recommend taking a closer look at existing CloudNet modules like , which are good examples of recommended usage. These modules take it a step further and do not constructors, they instead let the DI framework construct all the objects. They only say: "Hey, gimme an instance of XYZ".bridge

    If you need more information on DI, I can recommend the jakarta specs and the Aerogel github README JSR 330 is also an option, but IMO thats the worse documentation

    This should pretty much cover all basic usage.

    @derklaro correct me if I'm wrong about anything here pls

    very think u !!!!!!
12. Funasitien commented on Apr 8, 2025

    

    Funasitien

    on Apr 8, 2025

    Last edited by Funasitien

    More actions

    Would also be interesting to have some basic - not injection - use cases. Like how to connect a player to a lobby. This would help developers integrate CloudNet to their minigames plugins for example.
13. Funasitien commented on Apr 8, 2025

    

    Funasitien

    on Apr 8, 2025

    More actions

    Would love to organise the developers doc, but I'm waiting first to know which software is planned to be used for the generation of the official doc, if we stick to docausorus of change over to vitepress or smth else...