Finalizing docs

Shadows-of-Fire · Nov 9, 2023 · 2d9077b · 2d9077b
1 parent bdd3e01
commit 2d9077b
Show file tree

Hide file tree

Showing 19 changed files with 498 additions and 37 deletions.
diff --git a/changelog.md b/changelog.md
@@ -1,13 +1,12 @@
-## 4.2.0 - WIP
+## 4.2.0
 * This update brings a substantial refactor to the Gateway json format - you will need to update your files accordingly!
   * Many new controls have been added, and some old controls have been adjusted. The default values of things have also changed.
-  * The Schema document has been updated to reflect these changes.
+  * The new schema files are located [here](./schema/).
 * Gateways now depends on Apothic Attributes.
 * Removed all default Gateways and replaced them with new ones.
   * Added the Gate of the Emerald Grove.
   * Added the Gate of Overworldian Nights.
 * Jared: Added native CraftTweaker support, including bindings for the gateway entity and all of the gateway events.
-* Updated to Placebo 8.5.2 and made `Gateway` a record class.
 * Added an event handler to prevent Wave entities from despawning while the gate is alive.
   * Wave Entities always have `Mob#setPersistenceRequired` called, but mobs could bypass this via event.
 * Removed the 25 block exclusion radius for Gateways.
@@ -19,9 +18,10 @@
 * Wave entities may now specify a `desc` key to change what is shown in the tooltip.
 * Top-level `rewards` will now be displayed as `Key Rewards` and are always shown on the pearl.
   * Most rewards should be in the wave, but noteworthy completion rewards should be placed in this section.
-* Rewards and Failures now enforce usage of the namespace in their type tags. The namespace for all the defaults is `gateways`.
+* Rewards and Failures now enforce usage of the namespace in their type keys. The namespace for all the defaults is `gateways`.
 * Redid Gate Pearl tooltips.
 * Gate Pearls can now stack to 64.
+* Oh, and as a side effect, it is now possible for addons to be created which register custom gateway types.
 
 ## 4.1.1
 * Removed forge dependency line from the mods.toml and marked as Forge and NeoForge for CF.

diff --git a/schema/Gateway.md b/schema/Gateway.md
@@ -0,0 +1,65 @@
+# Description
+A Gateway is the core object you will create when working with Gateways to Eternity.
+
+# Dependencies
+This object references the following objects:
+1. [Size](./components/Size.md)
+2. [Color](../../../../Placebo/blob/-/schema/Color.md)
+3. [WaveEntity](./components/WaveEntity.md)
+4. [Wave](./components/Wave.md)
+5. [Reward](./components/Reward.md)
+6. [Failure](./components/Failure.md)
+7. [SpawnAlgorithm](./components/SpawnAlgorithm.md)
+8. [GateRules](./components/GateRules.md)
+9. [BossEventSettings](./components/BossEventSettings.md)
+10. [EndlessModifier](./components/EndlessModifier.md)
+
+# Subtypes
+Gateways are subtyped, meaning each subtype declares a `"type"` key and its own parameters.
+
+## Normal Gateways
+A Normal (or "Classic") Gateway defines a predefined list of waves, modifiers, rewards, and failure penalties.
+
+### Schema
+```js
+{
+    "size": Size,                        // [Mandatory] || The size of the Gateway.
+    "color": Color,                      // [Mandatory] || The color of the Gateway.
+    "waves": [                           // [Mandatory] || The list of waves for this Gateway.
+        Wave
+    ],
+    "rewards": [                         // [Optional]  || Rewards that will be granted upon completion of the entire gateway. Default value = empty list.
+        Reward
+    ],
+    "failures": [                        // [Optional]  || Failure penalties that will be applied if the Gateway is not completed. Default value = empty list.
+        Failure
+    ]
+    "spawn_algorithm": SpawnAlgorithm,   // [Optional]  || The Spawn Algorithm to use. Default value = "gateways:open_field".
+    "rules": GateRules,                  // [Optional]  || Potential rule edits for this Gateway. Default value = The default GateRules object.
+    "boss_event": BossEventSettings,     // [Optional]  || Potential boss event settings for this Gateway. Default value = The default BossEventSettings object.
+}
+```
+
+## Endless Gateways
+An Endless Gateway defines a base waves and a series of Endless Modifiers, which will augment the Gateway as it runs.  
+The Gateway will continue running until a wave fails, at which point it will close.
+
+### Schema
+```js
+{
+    "size": Size,                        // [Mandatory] || The size of the Gateway.
+    "color": Color,                      // [Mandatory] || The color of the Gateway.
+    "base_wave": Wave,                   // [Mandatory] || The base wave for this Gateway. It will be augmented by the provided Endless Modifiers as waves pass.
+    "modifiers": [                       // [Mandatory] || The modifiers, which define the rules for how the wave will change over time.
+        EndlessModifier
+    ],
+    "failures": [                        // [Optional]  || Failure penalties that will be applied if the Gateway is not completed. Default value = empty list.
+        Failure
+    ]
+    "spawn_algorithm": SpawnAlgorithm,   // [Optional]  || The Spawn Algorithm to use. Default value = "gateways:open_field".
+    "rules": GateRules,                  // [Optional]  || Potential rule edits for this Gateway. Default value = The default GateRules object.
+    "boss_event": BossEventSettings,     // [Optional]  || Potential boss event settings for this Gateway. Default value = The default BossEventSettings object.
+}
+```
+
+Note that it is almost guaranteed that an Endless Gateway fails at some point (unless it is kept open until the end of time), so failures should be added cautiously since users may not always avoid them.
diff --git a/schema/components/ApplicationMode.md b/schema/components/ApplicationMode.md
@@ -0,0 +1,50 @@
+# Description
+An Application Mode is utilized by an Endless Modifier to specify how and when it applies during an Endless Gateway.
+
+# Subtypes
+Application Modes are subtyped, meaning each subtype declares a `"type"` key and its own parameters.
+
+## After Wave Mode
+Adds the modifier(s) on the specified wave, remaining for all subsequent waves.
+
+### Schema
+```js
+{
+    "type": "gateways:after_wave",
+    "wave": integer      // [Mandatory] || The wave on which the modifier(s) are applied. The modifier remains applied on subsequent waves.
+}
+```
+
+## After Every N Waves Mode
+Applies the modifier(s) once every N waves, stacking with prior applications, up to M total applications.
+
+### Schema
+```js
+{
+    "type": "gateways:after_every_n_waves",
+    "waves": integer,    // [Mandatory] || The number of waves that must elapse before the modifier(s) are applied and reapplied.
+    "max": integer       // [Mandatory] || The maximum number of times the modifier(s) will be applied.
+}
+```
+
+## Only On Wave Mode
+Applies the modifier only on the specified wave, and not on subsequent waves.
+
+### Schema
+```js
+{
+    "type": "gateways:only_on_wave",
+    "wave": integer      // [Mandatory] || The wave on which the modifier(s) apply.
+}
+```
+
+## Only On Every N Waves Mode
+Applies the modifier once every N waves, but not on any others.
+
+### Schema
+```js
+{
+    "type": "gateways:after_every_n_waves",
+    "waves": integer,    // [Mandatory] || The number of waves that must elapse between applications.
+}
+```
diff --git a/schema/components/BossEventSettings.md b/schema/components/BossEventSettings.md
@@ -0,0 +1,10 @@
+# Description
+Boss Event Settings hold flags relating to the boss bar used by Gateways. Every field on this object is optional, meaning that `{}` is a legal definition of a Boss Event Settings object.
+
+# Schema
+```js
+{
+    "mode": "string",  // [Optional] || The drawing mode of the boss bar. Either "boss_bar" or "name_plate". Default value = "boss_bar".
+    "fog": boolean     // [Optional] || If the current mode is "boss_bar", this controls if fog is enabled. Has no effect when the mode is "name_plate". Default value = true.
+}
+```
diff --git a/schema/components/EndlessModifier.md b/schema/components/EndlessModifier.md
@@ -0,0 +1,48 @@
+# Description
+An Endless Modifier is the core building block of an Endless Gateway, and controls what changes are applied on each endless wave.  
+
+# Dependencies
+This object references the following objects:
+1. [ApplicationMode](./ApplicationMode.md)
+2. [WaveEntity](./WaveEntity.md)
+3. [Reward](./Reward.md)
+4. [WaveModifier](./WaveModifier.md)
+
+# Schema
+```js
+{
+    "application_mode": ApplicationMode,  // [Mandatory] || The application mode for this modifier.
+    "entities": [                         // [Optional]  || A list of additional entities that will be spawned each time the modifier is applied.
+        WaveEntity
+    ],
+    "rewards": [                          // [Optional]  || A list of rewards that will be added to the wave rewards each tim the modifier is applied.
+        Reward
+    ],
+    "modifiers": [                        // [Optional]  || A list of wave modifiers that will be applied to all entities each time the modifier is applied.
+        WaveModifier
+    ]
+}
+```
+
+One of the three optional components must be present for a modifier to be valid.
+
+# Examples
+An endless modifier that adds three blazes and five blaze loot rolls every 3 waves, up to 15 max applications.
+```json
+{
+    "application_mode": {
+        "type": "gateways:after_every_n_waves",
+        "waves": 3,
+        "max": 15
+    },
+    "entities": [{
+        "entity": "minecraft:blaze",
+        "count": 3
+    }],
+    "rewards": [{
+        "type": "gateways:entity_loot",
+        "entity": "minecraft:blaze",
+        "rolls": 5
+    }]
+}
+```
diff --git a/schema/components/Failure.md b/schema/components/Failure.md
@@ -0,0 +1,73 @@
+# Description
+A Failure is an event that occurs when a Gateway fails for any reason.  
+
+# Dependencies
+This object references the following objects:
+1. [WaveEntity](./WaveEntity.md)
+
+# Subtypes
+Failures are subtyped, meaning each subtype declares a `"type"` key and its own parameters.
+
+## Explosion Failure
+Triggers an explosion at the position of the Gateway.
+
+### Schema
+```js
+{
+    "type": "gateways:explosion",
+    "strength": float,             // [Mandatory] || Strength of the explosion. Creepers are 3, TNT is 4.
+    "fire": boolean,               // [Mandatory] || If the explosion will cause fire to spawn.
+    "block_damage": boolean        // [Mandatory] || If the explosion will damage blocks.
+}
+```
+
+## Mob Effect Failure
+Applies an effect instance to all nearby players.
+
+### Schema
+```js
+{
+    "type": "gateways:mob_effect",
+    "effect": "string",            // [Mandatory] || Registry name of the mob effect.
+    "duration": integer,           // [Mandatory] || Duration, in ticks, of the effect.
+    "amplifier": integer           // [Mandatory] || Effect amplifier. A value of zero corresponds to level 1.
+}
+```
+
+## Summon Failure
+Summons a wave entity using the spawn algorithm of the Gateway.
+
+### Schema
+```js
+{
+    "type": "gateways:summon",
+    "entity": WaveEntity           // [Mandatory] || The entity to summon.
+}
+```
+
+## Command Failure
+Executes a command when the Gateway fails. The keyphrase `<summoner>` will be replaced with the summoning player's name before command execution.  
+If the summoner is absent, the closest player will be used instead.
+
+The command will be executed as the gateway entity with a permission level of 2. If you need to execute it as the player, use `execute as <summoner> run ...`.
+
+### Schema
+```js
+{
+    "type": "gateways:command",
+    "command": "string",           // [Mandatory] || The command string, without a leading slash.
+    "desc": "string"               // [Mandatory] || Lang Key (or english text) which will be used to display the failure in the tooltip.
+}
+```
+
+## Chanced Failure
+Provides a chance to trigger any other failure.
+
+### Schema
+```js
+{
+    "type": "gateways:chanced",
+    "chance": float,               // [Mandatory] || The chance the reward is granted, in the range [0, 1].  0.5 is 50%
+    "failure": Failure             // [Mandatory] || The underlying failure.
+}
+```
diff --git a/schema/components/GateRules.md b/schema/components/GateRules.md
@@ -0,0 +1,16 @@
+# Description
+Gate Rules hold various behavioral flags common to all Gateway types. Every field on this object is optional, meaning that `{}` is a legal definition of a Gate Rules object.
+
+# Schema
+```js
+{
+    "spawn_range": float,              // [Optional] || The spawn range as a radius in blocks in which mobs may spawn around the gateway, from the edges of the gateway. Default value = 8.
+    "leash_range": float,              // [Optional] || The distance that a wave entity may be from the center of the Gateway before out-of-bounds rules are triggered. Default value = 32.
+    "allow_discarding": boolean,       // [Optional] || If entities marked as discarded are counted as valid kills. Default value = false.
+    "allow_dim_change": boolean        // [Optional] || If entities marked as changed dimension are counted as valid kills. Default value = false.
+    "player_damage_only": boolean,     // [Optional] || If wave entities may only be hurt by damage that is sourced to a player. Default value = false.
+    "remove_mobs_on_failure": boolean  // [Optional] || If the wave entities will be removed if the Gateway is failed. Default value = true.
+    "fail_on_out_of_bounds": boolean   // [Optional] || If true, when out-of-bounds rules are triggered, the Gateway will fail. If false, the entity will be re-placed using the spawn algorithm. Default value = false.
+    "spacing": float                   // [Optional] || The distance that this gateway must be from another Gateway. Default value = 0.
+}
+```
diff --git a/schema/Reward.md → schema/components/Reward.md b/schema/Reward.md → schema/components/Reward.md
@@ -3,20 +3,20 @@ A Reward is something provided by a Gateway when an objective is completed.
 
 # Dependencies
 This object references the following objects:
-1. [CompoundTag](../../../../Placebo/blob/-/schema/CompoundTag.md)
-2. [ItemStack](../../../../Placebo/blob/-/schema/ItemStack.md)
+1. [CompoundTag](../../../../../Placebo/blob/-/schema/CompoundTag.md)
+2. [ItemStack](../../../../../Placebo/blob/-/schema/ItemStack.md)
 3. [WaveEntity](./WaveEntity.md)
 
 # Subtypes
-Reward objects are subtyped, meaning each subtype declares a `"type"` key and its own parameters.
+Rewards are subtyped, meaning each subtype declares a `"type"` key and its own parameters.
 
 ## Stack Reward
 Rewards a single ItemStack.
 
 ### Schema
 ```js
 {
-    "type": "stack",
+    "type": "gateways:stack",
     "stack": ItemStack      // [Mandatory] || The ItemStack this reward will provide.
 }
 ```
@@ -27,7 +27,7 @@ Rewards one or more ItemStacks.
 ### Schema
 ```js
 {
-    "type": "stack_list",
+    "type": "gateways:stack_list",
     "stacks": [             // [Mandatory] || List of all stacks this reward will provide.
         ItemStack
     ]
@@ -40,7 +40,7 @@ Rewards the loot of a specific entity, as if the summoner had killed it.
 ### Schema
 ```js
 {
-    "type": "entity_loot",
+    "type": "gateways:entity_loot",
     "entity": "string",     // [Mandatory] || Registry name of the entity to use.
     "nbt": CompoundTag,     // [Optional]  || NBT data that will be loaded onto the entity before evaluating the loot table.
     "rolls": integer        // [Optional]  || The number of times the loot table will be rolled. Default value = 1.
@@ -54,7 +54,7 @@ Do not use this for entity loot tables, only use it for chests/block drops or si
 ### Schema
 ```js
 {
-    "type": "loot_table",
+    "type": "gateways:loot_table",
     "loot_table": "string", // [Mandatory] || Registry name of the target loot table.
     "rolls": integer,       // [Optional]  || The number of times the loot table will be rolled. Default value = 1.
     "desc": "string"        // [Mandatory] || Lang key (or english text) which will be used to display the reward in the tooltip.
@@ -70,7 +70,7 @@ The command will be executed as the gateway entity with a permission level of 2.
 ### Schema
 ```js
 {
-    "type": "command",
+    "type": "gateways:command",
     "command": "string",    // [Mandatory] || The command string, without a leading slash.
     "desc": "string"        // [Mandatory] || Lang Key (or english text) which will be used to display the reward in the tooltip.
 }
@@ -82,7 +82,7 @@ Rewards a certain amount of experience.
 ### Schema
 ```js
 {
-    "type": "experience",
+    "type": "gateways:experience",
     "experience": integer,  // [Mandatory] || The amount of experience that will be granted.
     "orb_size": integer     // [Optional]  || The size of the experience orbs that will be generated. A larger value will cause fewer individual orbs to generate. Default value = 5.
 }
@@ -94,7 +94,7 @@ Summons a wave entity when rewards would be generated.
 ### Schema
 ```js
 {
-    "type": "summon",
+    "type": "gateways:summon",
     "entity": WaveEntity    // [Mandatory] || The wave entity being spawned.
 }
 ```
@@ -105,7 +105,7 @@ Provides a chance to receive any other reward.
 ### Schema
 ```js
 {
-    "type": "chanced",
+    "type": "gateways:chanced",
     "chance": float,        // [Mandatory] || The chance the reward is granted, in the range [0, 1].  0.5 is 50%
     "reward": Reward        // [Mandatory] || The underlying reward.
 }