-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
📝 finished most of the important docs
Co-Authored-By: Sammi Deftu <[email protected]>
- Loading branch information
Showing
23 changed files
with
254 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,5 @@ | ||
# About Configs | ||
<format style="italic">by asojidev</format> | ||
|
||
## Why are these configs needed? | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,84 @@ | ||
# Module Loader | ||
<format style="italic">by Deftu</format> | ||
|
||
## Initial setup | ||
|
||
For the module loader to know where and how to discover modules, you need to register [discoverers](#discovery), and then call the `ModuleLoader#discover` function. This function will give you a set of module metadata objects which contain all relevant information needed to set up a module and have it interact with our main runner. | ||
|
||
## Entrypoints | ||
|
||
The module loader uses an entrypoint system to allow modules to have their own logic run elsewhere (including inside other modules!). Using it is as simple as loading the module into the current classpath then passing a reference to their class into `ModuleLoader#loadEntrypoint`. Not only does this create an instance of the class given to it, but it allows the caller to pass their own constructor arguments to it. This **IS** validated at creation time to ensure that there are no future issues. | ||
|
||
## Loading your own entrypoints | ||
|
||
To create your own entrypoint instance, you'll need a reference to a class implements it. For example, | ||
|
||
```kotlin | ||
package com.example | ||
|
||
import one.devos.yiski.module.loader.api.entrypoints.Entrypoint | ||
|
||
interface MyEntrypoint : Entrypoint { | ||
|
||
fun meow() | ||
|
||
} | ||
|
||
class MyEntrypointImpl : MyEntrypoint { | ||
|
||
override fun meow() { | ||
println("Meow") | ||
} | ||
|
||
} | ||
``` | ||
|
||
|
||
```kotlin | ||
package com.example | ||
|
||
import one.devos.yiski.module.loader.impl.ModuleLoader | ||
|
||
val moduleLoader: ModuleLoader = ... | ||
val clz: Class<*> = Class.forName("com.example.MyEntrypointImpl") | ||
val entrypoint = moduleLoader.loadEntrypoint(clz) as MyEntrypoint | ||
``` | ||
|
||
## Obtaining another module's metadata | ||
|
||
Each module has its own ID, which is unique to that module. This ID can be used to obtain other modules' metadata (and thus, their entrypoints). This can be achieved using `ModuleLoader#getMetadataFor`. | ||
|
||
Alternatively, if you need the metadata of all currently loaded modules, `ModuleLoader#getModules` is exposed. | ||
|
||
## Discovery | ||
|
||
Modules are discovered via implementations of `ModuleDiscoverer`, which provides a set of paths (either physical or virtual) in which modules _will_ be stored. Potential duplicate modules will overwrite one another, the last found duplicate taking precedence. | ||
|
||
> At least one discoverer is required for any modules to be discovered! Without a discoverer registered, no modules will be loaded. | ||
{style="note"} | ||
|
||
### Default discoverers | ||
|
||
`ClasspathModuleDiscoverer` | ||
: Discovers any modules currently loaded. It's best practice to always register this loader first to avoid unnecessary duplicates. | ||
|
||
`JarModuleDiscoverer` | ||
: Loads all modules within JAR files in it's given path. For example, if given the `modules` relative path, it would iterate through every `.jar` file inside that path in an attempt to identify a module. (f.ex, `/home/example/yiski/modules/module1.jar`, `/home/example/yiski/modules/module2.jar`, etc) | ||
|
||
### Discovery pipeline | ||
|
||
- First, all module discovers are called (and forcibly made distinct to avoid duplicates) | ||
- Then, we begin iterating through each path returned by the module discoverers | ||
- If the path is for a file, | ||
- We load the file as a JAR file, then searching it's root for a `yiski.metadata.toml` ([see the module metadata](Modules-Metadata.md)) | ||
- If we find one, we read its contents into our metadata list and load the JAR file into our current classpath | ||
- Otherwise, if the path points to a directory, | ||
- We simply look for a `yiski.metadata.toml` inside the directory, and read its contents into our metadata list | ||
- Finally, we read and validate all the sources in our metadata list, creating a list of all of our newly parsed `ModuleMetadata` objects | ||
- These are then added to our loaded modules list and returned to the call of the `ModuleLoader#discover` function | ||
|
||
<seealso style="cards"> | ||
<category ref="related-modules-data" > | ||
<a href="Modules-Metadata.md" summary="Take a look at how the Modules Metadata is done and its relevancy."></a> | ||
</category> | ||
</seealso> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Modules | ||
<format style="italic">by Deftu</format> | ||
|
||
Each module must provide its own implementation of `YiskiModuleEntrypoint` and `ConfigSetupEntrypoint`, and then provide the full path to both implementations in their respective fields of its `yiski.metadata.toml`. | ||
|
||
## Creating your main entrypoint | ||
|
||
Implementations of `YiskiModuleEntrypoint` **must** take a `DatabaseManager`, `Aviation`, `JDA` and `AbstractYiskiConfig` (in that order) in their constructor. | ||
|
||
The `setup` function from the entrypoint can be used for listening to JDA/Aviation events, checking properties in the module's entrypoint, etc. It's good practice to perform any Discord-relating logic inside a listener for `ReadyEvent`. | ||
|
||
## Creating your config setup entrypoint | ||
|
||
No constructor arguments are passed down to `ConfigSetupEntrypoint`s, making their implementation very simple. Your module **must** provide some kind of implementation of `AbstractYiskiConfig`, that being the object which contains config data. The `read` function itself does not return anything, instead `ConfigSetupEntrypoint` opts for you to use that function to set the `config` property found inside of your implementation. | ||
|
||
<seealso style="cards"> | ||
<category ref="related-modules-data" > | ||
<a href="Modules-Metadata.md" summary="Take a look at how the Modules Metadata is done and its relevancy."></a> | ||
</category> | ||
</seealso> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,27 @@ | ||
# Yiski's Main Runner | ||
<format style="italic">by Deftu</format> | ||
|
||
The bot's launch entrypoint, or main runner, is responsible for initially setting up JDA, database management, etc. | ||
Of course, it is also responsible for managing each of the bot's modules using the module loading system. | ||
|
||
## Initial startup | ||
|
||
In order of its functionality: | ||
|
||
- It will first discover and load any available modules, | ||
- Then extract any necessary initial startup entrypoints (these being the `ConfigSetupEntrypoint` and the `YiskiModuleEntrypoint`). | ||
- Available `ConfigSetupEntrypoint`s will then be read and validated to ensure that all config files are correct. | ||
- Each module's database package will then have all of its tables registered with Exposed. | ||
- Finally, we can now begin setting up JDA and Aviation. Inside which, all modules will have their slash commands registered. | ||
- After we have a functioning instance of JDA, we can then inform each of our modules that it's time for setup. **At this stage, we are unaware of if JDA was able to log in. The setup function call is not done in alignment with JDA's `ReadyEvent`.** | ||
|
||
## Consequent interference | ||
|
||
After the main runner has done its purpose in allowing the modules to interface with its centralized instance of JDA, it will not be interfering with the functionality of the bot any further. The only events the main runner listens to inside of JDA are for logging out the bot's current online state and syncing commands in **test guilds**. | ||
|
||
<seealso style="cards"> | ||
<category ref="modules"> | ||
<a href="Modules-Loader.md" summary="How the Module Loader works"></a> | ||
<a href="Modules.md" summary="How Modules work"></a> | ||
</category> | ||
</seealso> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,5 @@ | ||
# Yiski1 | ||
<format style="italic">by asojidev</format> | ||
|
||
# Basic | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,4 @@ | ||
# Yiski2 | ||
<format style="italic">by asojidev</format> | ||
|
||
Currently empty for now as work on Yiski2 has not started yet. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,4 @@ | ||
# Yiski2 | ||
<format style="italic">by asojidev</format> | ||
|
||
Currently empty for now as work on Yiski2 has not started yet. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,5 @@ | ||
# Yiski3 | ||
<format style="italic">by asojidev</format> | ||
|
||
## Silly | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,4 @@ | ||
# Yiski4 | ||
<format style="italic">by asojidev</format> | ||
|
||
Currently empty for now as work on Yiski4 has been indecisive. |
Oops, something went wrong.