Merge pull request #12 from integr-dev/develop

This pull request introduces several new features and improvements to the Backbone scripting system, focusing on enhancing script lifecycle management, HTTP request handling, and JSON construction. It also refactors event handling for inter-script communication and simplifies command, item, and entity registration. The documentation (README.md) has been updated to reflect these changes and provide new usage examples.

Key changes include:

1. HTTP Request Utilities and Documentation
Added new utility functions (request, requestSync, and requestAndThen) for making HTTP requests from scripts, including both synchronous and asynchronous variants. These utilities are now documented in the README.md with usage examples. 
2. Script Lifecycle and Registration DSL Improvements
Extracted the LifecycleBuilder and lifecycle DSL entrypoint into a dedicated file, improving modularity and clarity.
Added new DSL functions: useCommand, useItem, and useEntity for simplified registration and unregistration of commands, items, and entities in script lifecycles.
Updated the documentation to demonstrate the new registration DSL and improved lifecycle examples.
3. Inter-Script Communication Refactor
Renamed InterScriptDuckTypedEvent to IscEvent and moved it to a new package for clarity and consistency. Updated all usages accordingly.
Renamed the DSL function from interScript to interScriptListener to better reflect its purpose and updated the documentation. 
4. JSON Builder Utility
Introduced a new JsonBuilder utility and DSL for constructing JSON objects and arrays in scripts, along with helper functions jsonTree and json.
5. Minor Documentation and Logging Updates
Improved logging in lifecycle hooks for better debugging.
Minor documentation and formatting updates in README.md, including placeholder section cleanup.
These changes collectively make scripting with Backbone more powerful, modular, and user-friendly.

Author: integr-dev

README.md

@@ -90,11 +90,11 @@ lifecycle {
     var otherCounter = 0
 
     onLoad {
-        Backbone.registerListener(this)
+        println("Script loaded! Counter: $counter | Other Counter: $otherCounter")
     }
 
     onUnload {
-        Backbone.unregisterListener(this)
+        println("Script unloaded! Counter: $counter | Other Counter: $otherCounter")
     }
 
     // This event fires every server tick while the script is enabled.
@@ -279,7 +279,7 @@ Use `interScript` to listen for messages with a specific id. The handler receive
 
 ```kotlin
 lifecycle {
-    interScript("abc") { map ->
+    interScriptListener("abc") { map ->
         val abc = map.pull<String>("abc")
         println("Received inter-script message: $abc")
     }
@@ -291,6 +291,34 @@ lifecycle {
 - The data is passed as an immutable `IscMap`, which supports type-safe retrieval with `pull<T>(key)`.
 - This system is ideal for modular scripts, cross-script events, and decoupled communication.
 
+### HTTP Requests in Scripts
+
+Backbone scripts can easily make HTTP requests and handle responses using the built-in DSL. This is useful for integrating with web APIs, fetching data, or interacting with external services directly from your scripts.
+
+#### Example: Making an HTTP Request in a Script
+
+You can use the `requestAndThen` function inside your script's lifecycle to perform HTTP requests asynchronously. The response is provided to a callback, where you can process the result and interact with the server.
+
+```kotlin
+lifecycle {
+    onLoad {
+        requestAndThen("https://httpbin.org/get", HttpMethod.GET, {
+            header("User-Agent", "Backbone Script Handler")
+        }) { response ->
+            Backbone.SERVER.broadcast(component {
+                append("HTTP Response: ${response.json()}") {
+                    color(Color.GREEN)
+                }
+            })
+        }
+    }
+}
+```
+
+- `requestAndThen(url, method, { ...headers... }) { response -> ... }` performs an HTTP request and provides the response to the callback.
+- The `response` object supports JSON parsing and mapping, making it easy to work with API responses.
+- You can use this in any lifecycle hook, such as `onLoad`, or in event listeners.
+
 ### Commands
 
 Backbone's command framework makes it easy to create and manage commands with arguments, subcommands, and permission checks.
@@ -331,14 +359,9 @@ object MyCommand : Command("mycommand", "My first command") {
     }
 }
 
-// In your ManagedLifecycle's onLoad:
+// In your ManagedLifecycle:
 lifecycle {
-    onLoad {
-        Backbone.Handler.COMMAND.register(MyCommand)
-    }
-    onUnload {
-        Backbone.Handler.COMMAND.unregister(MyCommand)
-    }
+    useCommand(MyCommand)
 }
 ```
 
@@ -396,11 +419,9 @@ object MyItemState : CustomItemState(Material.DIAMOND_SWORD, "default") {
     }
 }
 
-// In your ManagedLifecycle's onLoad:
+// In your ManagedLifecycle:
 lifecycle {
-    onLoad {
-        Backbone.Handler.ITEM.register(MyItem)
-    }
+    useItem(MyItem)
 }
 ```
 
@@ -429,11 +450,9 @@ object GuardEntity : CustomEntity<Zombie>("guard", EntityType.ZOMBIE) {
     }
 }
 
-// In your ManagedLifecycle's onLoad:
+// In your ManagedLifecycle:
 lifecycle {
-    onLoad {
-        Backbone.Handler.ENTITY.register(GuardEntity)
-    }
+    useEntity(GuardEntity)
 }
 
 // You can then spawn the entity, for example, using a command
@@ -581,5 +600,4 @@ Backbone provides a set of placeholders through its soft dependency on Placehold
 
 - `%backbone_version%`: Displays the current version of the Backbone plugin.
 
-More placeholders are planned for future releases.
-
+More placeholders are planned for future releases.

build.gradle.kts

@@ -7,7 +7,7 @@ plugins {
 }
 
 group = "net.integr"
-version = "1.6.1"
+version = "1.7.0"
 
 repositories {
     mavenCentral()

…tloader/isc/InterScriptDuckTypedEvent.kt …n/net/integr/backbone/events/IscEvent.ktsrc/main/kotlin/net/integr/backbone/systems/hotloader/isc/InterScriptDuckTypedEvent.kt renamed to src/main/kotlin/net/integr/backbone/events/IscEvent.kt src/main/kotlin/net/integr/backbone/systems/hotloader/isc/InterScriptDuckTypedEvent.kt renamed to src/main/kotlin/net/integr/backbone/events/IscEvent.kt

@@ -11,16 +11,17 @@
  * limitations under the License.
  */
 
-package net.integr.backbone.systems.hotloader.isc
+package net.integr.backbone.events
 
 import net.integr.backbone.systems.event.Event
+import net.integr.backbone.systems.hotloader.isc.IscMap
 
 /**
  * Event for inter-script communication, carrying a message id and data.
  *
  * Used internally by the lifecycle DSL for inter-script messaging.
  * @property id The message id.
- * @property data The message data as [IscMap].
+ * @property data The message data as [net.integr.backbone.systems.hotloader.isc.IscMap].
  * @since 1.6.0
  */
-class InterScriptDuckTypedEvent(val id: String, val data: IscMap) : Event()
+class IscEvent(val id: String, val data: IscMap) : Event()

src/main/kotlin/net/integr/backbone/systems/hotloader/GlobalScriptFunctions.kt

@@ -14,114 +14,141 @@
 package net.integr.backbone.systems.hotloader
 
 import net.integr.backbone.Backbone
-import net.integr.backbone.systems.event.BackboneEventHandler
-import net.integr.backbone.systems.hotloader.isc.InterScriptDuckTypedEvent
+import net.integr.backbone.events.IscEvent
+import net.integr.backbone.systems.command.Command
+import net.integr.backbone.systems.entity.CustomEntity
 import net.integr.backbone.systems.hotloader.isc.IscMap
 import net.integr.backbone.systems.hotloader.isc.IscMapBuilder
-import net.integr.backbone.systems.hotloader.lifecycle.LifecycleSustainedState
-import net.integr.backbone.systems.hotloader.lifecycle.ManagedLifecycle
-import net.integr.backbone.systems.hotloader.lifecycle.sustained
-import net.integr.backbone.systems.text.component
-import java.awt.Color
-import kotlin.inc
+import net.integr.backbone.systems.item.CustomItem
+import net.integr.backbone.systems.network.http.HttpMethod
+import net.integr.backbone.systems.network.http.Requestor
+import net.integr.backbone.systems.network.http.request.RequestBuilder
+import net.integr.backbone.systems.network.http.response.Response
+import org.bukkit.entity.Mob
 import kotlin.reflect.full.starProjectedType
-import kotlin.toString
 
 /**
- * DSL entrypoint for defining a script lifecycle.
+ * Makes an asynchronous HTTP request to the given URI with the specified method and request builder block.
  *
- * @param block The lifecycle configuration block.
- * @return The constructed [ManagedLifecycle].
+ * @param uri The target URI for the HTTP request.
+ * @param method The HTTP method to use (e.g., GET, POST).
+ * @param builderBlock An optional block to configure the request using a [RequestBuilder].
+ * @return A [Response] containing the response data as a string.
  * @since 1.6.0
  */
-fun lifecycle(block: LifecycleBuilder.() -> Unit): ManagedLifecycle {
-    val builder = LifecycleBuilder()
-    block(builder)
-    return builder
-}
+suspend fun request(uri: String, method: HttpMethod, builderBlock: RequestBuilder.() -> Unit = {}) =
+    Requestor.request(uri, method, builderBlock)
 
 /**
- * Builder for script lifecycle and event/listener registration DSL.
+ * Makes a synchronous HTTP request to the given URI with the specified method and request builder block.
  *
- * Provides methods for registering load/unload hooks, event listeners, and inter-script communication handlers.
+ * @param uri The target URI for the HTTP request.
+ * @param method The HTTP method to use (e.g., GET, POST).
+ * @param builderBlock An optional block to configure the request using a [RequestBuilder].
+ * @return A [Response] containing the response data as a string.
  * @since 1.6.0
  */
-class LifecycleBuilder : ManagedLifecycle() {
-    val onLoadCalls: MutableList<() -> Unit> = mutableListOf()
-    val onUnloadCalls: MutableList<() -> Unit> = mutableListOf()
+fun requestSync(uri: String, method: HttpMethod, builderBlock: RequestBuilder.() -> Unit = {}) =
+    Requestor.requestSync(uri, method, builderBlock)
 
-    override fun onLoad() {
-        onLoadCalls.forEach { it() }
-    }
+/**
+ * Makes an asynchronous HTTP request to the given URI with the specified method and request builder block, then executes a callback with the response.
+ *
+ * @param uri The target URI for the HTTP request.
+ * @param method The HTTP method to use (e.g., GET, POST).
+ * @param builderBlock An optional block to configure the request using a [RequestBuilder].
+ * @param then A callback block that receives the [Response] containing the response data as a string.
+ * @since 1.6.0
+ */
+fun requestAndThen(uri: String, method: HttpMethod, builderBlock: RequestBuilder.() -> Unit = {}, then: (Response<String>) -> Unit)
+    = Requestor.requestAndThen(uri, method, builderBlock, then)
 
-    override fun onUnload() {
-        onUnloadCalls.forEach { it() }
-    }
+/**
+ * Registers a Bukkit event listener for the given event type.
+ *
+ * @param priority The Bukkit event priority (default: NORMAL).
+ * @param block The event handler block.
+ * @since 1.6.0
+ */
+inline fun <reified T : org.bukkit.event.Event> LifecycleBuilder.listener(
+    priority: org.bukkit.event.EventPriority = org.bukkit.event.EventPriority.NORMAL,
+    noinline block: (T) -> Unit
+) {
+    onLoad { Backbone.SERVER.pluginManager.registerEvent(T::class.java, this, priority, { _, event -> if (event is T) block(event) }, Backbone.PLUGIN) }
+    onUnload { Backbone.unregisterListener(this) }
+}
 
-    /**
-     * Registers a block to run when the script is loaded.
-     * @since 1.6.0
-     */
-    fun onLoad(block: () -> Unit) {
-        onLoadCalls += block
-    }
+/**
+ * Registers a Backbone event listener for the given event type.
+ *
+ * @param priority The Backbone event priority (default: NORMAL).
+ * @param block The event handler block.
+ * @since 1.6.0
+ */
+inline fun <reified T : net.integr.backbone.systems.event.Event> LifecycleBuilder.backboneListener(
+    priority: net.integr.backbone.systems.event.EventPriority = net.integr.backbone.systems.event.EventPriority.NORMAL,
+    noinline block: (T) -> Unit
+) {
+    onLoad { Backbone.EVENT_BUS.registerLambda(T::class.starProjectedType, priority, this) { event -> if (event is T) block(event) } }
+    onUnload { Backbone.unregisterListener(this) }
+}
 
-    /**
-     * Registers a block to run when the script is unloaded.
-     * @since 1.6.0
-     */
-    fun onUnload(block: () -> Unit) {
-        onUnloadCalls += block
+/**
+ * Registers a handler for inter-script communication events with the given id.
+ *
+ * @param id The message id to listen for.
+ * @param block The handler block, receiving the message data as [IscMap].
+ * @since 1.6.0
+ */
+fun LifecycleBuilder.interScriptListener(id: String, block: (IscMap) -> Unit) {
+    backboneListener<IscEvent> {
+        if (it.id == id) block(it.data)
     }
+}
 
-    /**
-     * Registers a Bukkit event listener for the given event type.
-     *
-     * @param priority The Bukkit event priority (default: NORMAL).
-     * @param block The event handler block.
-     * @since 1.6.0
-     */
-    inline fun <reified T : org.bukkit.event.Event> listener(priority: org.bukkit.event.EventPriority = org.bukkit.event.EventPriority.NORMAL, crossinline block: (T) -> Unit) {
-        onLoadCalls += { Backbone.SERVER.pluginManager.registerEvent(T::class.java, this, priority, { _, event -> if (event is T) block(event) }, Backbone.PLUGIN) }
-        onUnloadCalls += { Backbone.unregisterListener(this) }
-    }
+/**
+ * Dispatches an inter-script communication event with the given id and data.
+ *
+ * @param id The message id to send.
+ * @param data The data builder block for the message.
+ * @since 1.6.0
+ */
+fun dispatchInterScript(id: String, data: IscMapBuilder.() -> Unit) {
+    val builder = IscMapBuilder()
+    builder.data()
+    val isc = builder.build()
+    Backbone.EVENT_BUS.post(IscEvent(id, isc))
+}
 
-    /**
-     * Registers a Backbone event listener for the given event type.
-     *
-     * @param priority The Backbone event priority (default: NORMAL).
-     * @param block The event handler block.
-     * @since 1.6.0
-     */
-    inline fun <reified T : net.integr.backbone.systems.event.Event> backboneListener(priority: net.integr.backbone.systems.event.EventPriority = net.integr.backbone.systems.event.EventPriority.NORMAL, noinline block: (T) -> Unit) {
-        onLoadCalls += { Backbone.EVENT_BUS.registerLambda(T::class.starProjectedType, priority, this) { event -> if (event is T) block(event) } }
-        onUnloadCalls += { Backbone.unregisterListener(this) }
-    }
+/**
+ * Registers a command handler for the given command.
+ *
+ * @param command The command to register.
+ * @since 1.6.0
+ */
+fun LifecycleBuilder.useCommand(command: Command) {
+    onLoad { Backbone.Handler.COMMAND.register(command) }
+    onUnload { Backbone.Handler.COMMAND.unregister(command) }
+}
 
-    /**
-     * Registers a handler for inter-script communication events with the given id.
-     *
-     * @param id The message id to listen for.
-     * @param block The handler block, receiving the message data as [IscMap].
-     * @since 1.6.0
-     */
-    fun interScript(id: String, block: (IscMap) -> Unit) {
-        backboneListener<InterScriptDuckTypedEvent> {
-            if (it.id == id) block(it.data)
-        }
-    }
+/**
+ * Registers an entity handler for the given custom entity.
+ *
+ * @param entity The custom entity to register.
+ * @since 1.6.0
+ */
+fun <T : Mob> LifecycleBuilder.useEntity(entity: CustomEntity<T>) {
+    onLoad { Backbone.Handler.ENTITY.register(entity) }
+    onUnload { Backbone.Handler.ENTITY.unregister(entity) }
+}
 
-    /**
-     * Dispatches an inter-script communication event with the given id and data.
-     *
-     * @param id The message id to send.
-     * @param data The data builder block for the message.
-     * @since 1.6.0
-     */
-    fun dispatchInterScript(id: String, data: IscMapBuilder.() -> Unit) {
-        val builder = IscMapBuilder()
-        builder.data()
-        val isc = builder.build()
-        Backbone.EVENT_BUS.post(InterScriptDuckTypedEvent(id, isc))
-    }
+/**
+ * Registers an item handler for the given custom item.
+ *
+ * @param item The custom item to register.
+ * @since 1.6.0
+ */
+fun LifecycleBuilder.useItem(item: CustomItem) {
+    onLoad { Backbone.Handler.ITEM.register(item) }
+    onUnload { Backbone.Handler.ITEM.unregister(item) }
 }