@@ -8,7 +8,6 @@ import top.katton.Katton
88import top.katton.util.Event
99import java.util.concurrent.ConcurrentHashMap
1010
11-
1211internal val LOGGER = LogUtils .getLogger()
1312
1413private val onceRegistry = ConcurrentHashMap <String , MutableSet <String >>()
@@ -23,6 +22,8 @@ private fun onceNamespace(namespace: String?): String {
2322/* *
2423 * Execute [block] only once for a given [key] under the current script owner namespace.
2524 *
25+ * When script is reloaded, the markers won't be cleared, so the block won't execute again until the marker is reset with [resetOnce] or [clearOnce].
26+ *
2627 * When called inside a script execution, the default namespace is that script's owner id;
2728 * outside script execution, the default namespace is "global".
2829 *
@@ -66,11 +67,25 @@ fun clearOnce(namespace: String? = null) {
6667
6768/* *
6869 * Current minecraft server instance. Maybe null during client-side execution.
70+ *
71+ * Use this property when you need optional access to the server.
72+ * For cases where the server must be available, use [requireServer] instead.
73+ *
74+ * @return The current MinecraftServer instance, or null if not available
6975 */
7076val server: MinecraftServer ?
7177 get() = Katton .server
7278
73-
79+ /* *
80+ * Requires the Minecraft server instance to be available.
81+ *
82+ * Use this function when the server must be present for the operation to succeed.
83+ * Throws an error if the server is not available (e.g., during client-side execution
84+ * or before the server has started).
85+ *
86+ * @return The current MinecraftServer instance
87+ * @throws IllegalStateException if the server is not available
88+ */
7489fun requireServer (): MinecraftServer =
7590 server ? : error(" MinecraftServer is not available (client-side or not started)" )
7691
0 commit comments