Add startup scripts guide & event-side docs

Author: HollowHorizon

docs/assets/pictures/ide/client-reload-script.webp

@@ -37,6 +37,26 @@ When the Project panel is focused, these shortcuts are available:
 
 ![Project tree and context menu](/hollowengine/pictures/ide/project-tree.webp)
 
+## Creating scripts
+
+Right-clicking the `scripts` folder or any folder inside it shows the **New Script** item. Hover over it and pick a type:
+
+| Item                     | File                                  | What it contains                                   |
+|--------------------------|---------------------------------------|----------------------------------------------------|
+| **Script**               | `.kts`                                | a function and a call to it                        |
+| **Server Reload Script** | `.reload.kts`                         | a chat greeting for joining players                |
+| **Client Reload Script** | `.reload.kts` with `@file:ClientSide` | a line of text on the HUD                          |
+| **Startup Script**       | `.startup.kts`                        | an item registered under the file's name           |
+| **Node Script**          | `.node.kts`                           | start, stop, and once-a-second handlers            |
+| **UI Script**            | `.ui.kts`                             | a simple screen                                    |
+| **Dialogue**             | `.story`                              | a dialogue with two answers                        |
+
+Then enter the file name. The extension can be omitted, the IDE adds it. The new file opens in the editor right away with a working example to start from.
+
+![The new script menu](/hollowengine/pictures/ide/new-script-menu.webp)
+
+The item is only offered inside `scripts`, because the engine loads scripts and dialogues from there only.
+
 ## Code editor
 
 Opening `.kts`, `.story`, `.hss`, and other supported text files starts the built-in editor. Depending on the file type, it provides syntax highlighting, diagnostics, completion, signature help, inlay hints, and navigation. Diagnostics are shown in the editor and in a resizable problems panel.
@@ -59,8 +79,9 @@ Useful editor shortcuts:
 
 Saving a file writes it to the `hollowengine` directory. What must be reloaded depends on the file:
 
-- use **File > Reload Client Resources** or `F3 + T` for models, textures, HSS, UI declarations, and other client resources;
-- use **File > Reload Server Resources** or `/reload` for datapack content and reloadable server scripts;
+- use **File > Reload Client Resources** or `F3 + T` for models, textures, HSS, UI declarations, client reloadable scripts (`@file:ClientSide`), and other client resources;
+- use **File > Reload Server Resources** or `/reload` for datapack content and server reloadable scripts;
+- `.startup.kts` changes only apply after restarting the game;
 - ordinary `.kts` scripts are started explicitly with `/hollowengine scripting run <path>`.
 
 The compiler addon is required to compile edited scripts. A modpack can instead ship scripts that were compiled ahead of time.

docs/assets/pictures/ide/new-script-menu.webp

@@ -11,6 +11,8 @@ order: 3
 
 ## Placement
 
+**Side:** both sides
+
 *This event can be canceled (`event.isCanceled = true`).*
 
 ```kotlin
@@ -26,6 +28,8 @@ fun onBlockPlace(event: BlockEvent.Placed) {
 
 ## Breaking
 
+**Side:** server
+
 *This event can be canceled (`event.isCanceled = true`).*
 
 ```kotlin
@@ -42,6 +46,8 @@ fun onBlockBreak(event: BlockEvent.Break) {
 
 ## Updates
 
+**Side:** server
+
 *This event can be canceled (`event.isCanceled = true`).*
 
 ```kotlin

docs/assets/pictures/startup/item-files.webp

@@ -11,6 +11,8 @@ order: 4
 
 ## Spawned in the world
 
+**Side:** server
+
 ```kotlin
 @SubscribeEvent
 fun onEntitySpawn(event: EntityLoadedEvent) {
@@ -23,6 +25,8 @@ fun onEntitySpawn(event: EntityLoadedEvent) {
 
 ## Entity death
 
+**Side:** server
+
 *This event can be canceled (`event.isCanceled = true`).*
 
 ```kotlin
@@ -37,6 +41,8 @@ fun onEntitySpawn(event: LivingEntityDeathEvent) {
 
 ## Moving between dimensions
 
+**Side:** server
+
 ```kotlin
 @SubscribeEvent
 fun onEntityTeleport(event: EntityEvent.ChangeDimension) {
@@ -55,6 +61,8 @@ Typed [`.data`](/docs/hollowengine/scripting/npc/data) carries over on its own,
 
 ## Taking damage
 
+**Side:** server
+
 *This event can be canceled (`event.isCanceled = true`).*
 
 ```kotlin
@@ -70,6 +78,8 @@ fun onEntityHurt(event: EntityEvent.Hurt) {
 
 ## Entity breeding
 
+**Side:** server
+
 *This event can be canceled (`event.isCanceled = true`).*
 
 ```kotlin

docs/assets/pictures/startup/item-in-game.webp

@@ -11,42 +11,66 @@ order: 1
 
 The HollowEngine event system lets you inject custom logic into specific in-game actions, including player actions, entity actions, block updates, and more.
 
+## Which side an event fires on
+
+Minecraft is split into two sides: the **server** runs the world and the players, the **client** draws the picture and takes input. Even singleplayer runs a separate server inside. That is why every event in this section states its side, and it has to be listened to from a matching script:
+
+| Side             | Where to listen                                                                   |
+|------------------|-----------------------------------------------------------------------------------|
+| **Server**       | a plain `.reload.kts`                                                             |
+| **Client**       | a `.reload.kts` with `@file:ClientSide`                                           |
+| **Both sides**   | either of them: a server script gets the server copy of the event, a client script the client copy |
+| **Game startup** | only `.startup.kts`: the event fires once, before any reloadable script exists    |
+
+If you subscribe to an event from the wrong side, the engine logs an error when the script starts. That makes it easy to see why a handler "does not fire on the server".
+
+:::advice
+`.startup.kts` scripts and addons are not bound to a side and receive events of both sides. When such code listens to a "both sides" event, check the side yourself, for example with `event.player.level().isClientSide`.
+:::
+
 ## Creating a handler
 
-There are two ways to create a handler: automatically (see [reloadable scripts](/docs/hollowengine/scripting/reload)) or manually by creating and registering a function:
+The simplest way to subscribe is the `@SubscribeEvent` annotation in a [reloadable script](/docs/hollowengine/scripting/reload). If a handler has to be added from code, for example only under some condition, subscribe through the script's scope:
 
 ```kotlin
 fun onPlayerJoin(event: PlayerEvent.Join) {
     event.player.send("Welcome back!")
 }
 
-val handle = PlayerEvent.Join.register(::onPlayerJoin) // Start listening for the event and store the handler
-PlayerEvent.Join.unregister(handle) // Stop listening for the event (the method will no longer be called)
+PlayerEvent.Join.subscribe(this, listener = ::onPlayerJoin)
 
 // You can also pass a lambda instead of a function:
-PlayerEvent.Join.register { event ->
+PlayerEvent.Join.subscribe(this) { event ->
     event.player.send("Welcome back!")
 }
 ```
 
+`this` here is the reloadable script itself: the subscription lives as long as the script and is removed when it restarts. It respects the script's side just like `@SubscribeEvent`.
+
+:::warning
+`PlayerEvent.Join.register { ... }` without a scope subscribes forever, until the game exits. In scripts such a handler is not removed on `/reload` and fires once more after every restart.
+:::
+
 ## Priorities
 
 Sometimes an event needs to run before other handlers, especially if it may cancel the event.
-You can change the handler order by configuring its priority:
+Pass a priority: the higher it is, the earlier the handler runs. The default priority is zero.
 
 ```kotlin
-val handler = eventListenerOf(10, ::onPlayerJoin)
+@SubscribeEvent(10)
+fun onPlayerJoin(event: PlayerEvent.Join) { }
 
-PlayerEvent.Join.register(handler)
-PlayerEvent.Join.unregister(handler)
+// Or when subscribing from code:
+PlayerEvent.Join.subscribe(this, priority = 10) { event -> }
 ```
 
 ## Canceling events
 
 Some events are cancelable, meaning their default action can be prevented. For example:
 
 ```kotlin
-BlockEvent.Break.register { event ->
+@SubscribeEvent
+fun onBreak(event: BlockEvent.Break) {
     event.player.send("You cannot break blocks!")
     event.isCanceled = true
 }

docs/assets/pictures/startup/startup-script.webp

@@ -5,6 +5,23 @@ order: 6
 
 *Events that allow integration with Just Enough Items (JEI): registering categories and recipes, hiding them, or adding item descriptions.*
 
+**Side:** client (every event on this page)
+
+:::warning
+JEI only runs in the player's game, so these events have to be listened to from a client script: add `@file:ClientSide` at the top of the `.reload.kts`. A server script cannot subscribe to them, and the engine logs an error saying so.
+:::
+
+```kotlin
+@file:ClientSide
+
+import ru.hollowhorizon.hollowengine.common.events.ModifyRecipeViewerEvent
+
+@SubscribeEvent
+fun onRuntimeAvailable(event: ModifyRecipeViewerEvent.RegisterOnRuntimeAvailable) {
+    // ...
+}
+```
+
 ## Registering subtypes and ingredients
 
 ### Registering item subtypes