@@ -25,73 +25,219 @@ import org.bukkit.NamespacedKey
2525import org.bukkit.event.HandlerList
2626import org.bukkit.event.Listener
2727import org.bukkit.plugin.java.JavaPlugin
28-
28+ import org.jetbrains.annotations.ApiStatus
29+
30+ /* *
31+ *
32+ * The main entry point for the Backbone API.
33+ *
34+ * This object provides access to various Backbone systems and utilities.
35+ *
36+ * @since 1.0.0
37+ */
2938object Backbone {
30- // TODO: dialogues
39+ // TODO: dialogues, command help builder
40+ /* *
41+ * Backbones internal storage pool. **Important:** Do not use this.
42+ * Create a new pool instead:
43+ * ```kotlin
44+ * val pool = ResourcePool.fromStorage("my-server")
45+ * ```
46+ *
47+ * @since 1.0.0
48+ */
49+ @ApiStatus.Internal
3150 val STORAGE_POOL = ResourcePool .fromStorage(" backbone"
51+
52+ /* *
53+ * Backbones internal config pool. **Important:** Do not use this.
54+ * Create a new pool instead:
55+ * ```kotlin
56+ * val pool = ResourcePool.fromConfig("my-server")
57+ * ```
58+ *
59+ * @since 1.0.0
60+ */
61+ @ApiStatus.Internal
3262 val CONFIG_POOL = ResourcePool .fromConfig(" backbone"
3363
64+ /* *
65+ * Internal script pool.
66+ *
67+ * @since 1.0.0
68+ */
69+ @ApiStatus.Internal
3470 val SCRIPT_POOL = ResourcePool .getScripts()
3571
36- val ROOT_PERMISSION by lazy {
37- PermissionNode (" backbone"
38- }
39-
72+ /* *
73+ * Backbones internal logger. **Important:** Do not use this for your own logging.
74+ * Create a new logger instead:
75+ * ```kotlin
76+ * val logger = BackboneLogger("my-server")
77+ * ```
78+ *
79+ * @since 1.0.0
80+ */
81+ @ApiStatus.Internal
82+ val LOGGER = BackboneLogger (" backbone"
83+
84+ /* *
85+ * Backbones root permission. **Important:** Do not use this for your own permission checks.
86+ * Create a new node instead:
87+ * ```kotlin
88+ * val node = PermissionNode("my-server")
89+ * ```
90+ *
91+ * @since 1.0.0
92+ */
93+ @ApiStatus.Internal
94+ val ROOT_PERMISSION = PermissionNode (" backbone"
95+
96+ /* *
97+ * Backbones placeholders. **Important:** Do not use this for your own custom placeholders.
98+ * Create a new group instead:
99+ * ```kotlin
100+ * val group = PlaceholderGroup("1.0.0", "my-server")
101+ * ```
102+ *
103+ * @since 1.0.0
104+ */
105+ @get:ApiStatus.Internal
40106 val PLACEHOLDER_GROUP by lazy {
41107 PlaceholderGroup (VERSION , " backbone"
42108 }
43109
110+ /* *
111+ * The internally checked plugin instance.
112+ * Null if we are in a testing environment.
113+ *
114+ * @since 1.0.0
115+ */
44116 private val pluginInternal: JavaPlugin ? by lazy {
45117 Utils .tryOrNull { JavaPlugin .getPlugin(BackboneServer ::class .java) } // For testing purposes
46118 }
47119
120+ /* *
121+ * The global backbone plugin instance.
122+ *
123+ * @since 1.0.0
124+ */
48125 val PLUGIN
49126 get() = pluginInternal!!
50127
128+ /* *
129+ * The global server instance.
130+ *
131+ * @since 1.0.0
132+ */
51133 val SERVER
52134 get() = PLUGIN .server
53135
136+ /* *
137+ * The version of the backbone plugin.
138+ *
139+ * @since 1.0.0
140+ */
54141 val VERSION
55142 get() = PLUGIN .pluginMeta.version
56143
57- val LOGGER : BackboneLogger by lazy {
58- BackboneLogger (" backbone"
59- }
60144
145+ /* *
146+ * Registers a listener to the server's plugin manager and the internal event bus.
147+ *
148+ * @param listener The listener to register.
149+ *
150+ * @since 1.0.0
151+ */
61152 fun registerListener (listener : Listener ) {
62153 LOGGER .info(" Registering listener: ${listener.javaClass.name} "
63154 SERVER .pluginManager.registerEvents(listener, PLUGIN )
64155 EventBus .register(listener)
65156 }
66157
158+ /* *
159+ * Removes a listener from the server's plugin manager and the internal event bus.
160+ *
161+ * @param listener The listener to register.
162+ *
163+ * @since 1.0.0
164+ */
67165 fun unregisterListener (listener : Listener ) {
68166 LOGGER .info(" Unregistering listener: ${listener.javaClass.name} "
69167 HandlerList .unregisterAll(listener)
70168 EventBus .unregister(listener)
71169 }
72170
171+ /* *
172+ * Dispatches a task to be run on the main thread of the server.
173+ *
174+ * @param block The block of code to run.
175+ *
176+ * @since 1.0.0
177+ */
73178 fun dispatchMain (block : () -> Unit ) {
74179 SERVER .scheduler.runTask(PLUGIN , block)
75180 }
76181
182+ /* *
183+ * Dispatches a task to be run asynchronously on the server.
184+ *
185+ * @param block The block of code to run.
186+ *
187+ * @since 1.0.0
188+ */
77189 fun dispatch (block : () -> Unit ) {
78190 SERVER .scheduler.runTaskAsynchronously(PLUGIN , block)
79191 }
80192
193+ /* *
194+ * Gets a namespaced key.
195+ *
196+ * @param namespace The namespace of the key.
197+ * @param key The key.
198+ * @return A namespaced key.
199+ *
200+ * @since 1.0.0
201+ */
81202 fun getKey (namespace : String , key : String ): NamespacedKey {
82203 return NamespacedKey (namespace, key)
83204 }
84205
206+ /* *
207+ * Backbone's handlers for use in your scripts.
208+ *
209+ * @since 1.1.0
210+ */
85211 object Handler {
212+ /* *
213+ * The command handler used to register and manage commands.
214+ *
215+ * @since 1.1.0
216+ */
86217 val COMMAND
87218 get() = CommandHandler
88219
220+ /* *
221+ * The item handler used to manage items.
222+ *
223+ * @since 1.1.0
224+ */
89225 val ITEM
90226 get() = ItemHandler
91227
228+ /* *
229+ * The entity handler used to manage entities.
230+ *
231+ * @since 1.1.0
232+ */
92233 val ENTITY
93234 get() = EntityHandler
94235
236+ /* *
237+ * The gui handler used to manage guis.
238+ *
239+ * @since 1.1.0
240+ */
95241 val GUI
96242 get() = GuiHandler
97243 }
0 commit comments