Merge pull request #87 from Ladysnake/blabber-1-6

Update documentation for Blabber 1.6.0

public/wiki/blabber/index.md

@@ -37,6 +37,8 @@ Blabber adds the `/blabber` command, allowing server operators and mapmakers to
         - `<dialogue>` : the unique identifier for the dialogue
         - `[<targets>]` (optional) : If specified, must be either a player's username or a target selector. If unspecified, defaults to the player using the command. When used in a command block, `[<targets>]` is not optional.
         - `[<interlocutor>]` (optional) : If specified, must be a target selector for a single entity. If unspecified, defaults to no interlocutor.
+    - `/blabber settings set <setting> <true|false>` : Toggles a debug setting.
+      - `<setting>` : the name of a [debug setting](#debug-modes) - currently, the only possible value is `debug.anchors`.
 
 ### Format
 
@@ -113,6 +115,9 @@ on the screen just fine in languages like English, they may take up too much spa
 (this also applies to the classic layout, though to a lesser degree).
 {:.admonition.admonition-important.admonition-icon}
 
+Starting in version 1.6.0, layouts can take additional parameters to customize their render.
+Currently (1.6.0), the only supported parameter is `main_text_margins` on the `blabber:rpg` layout.
+
 The JSON looks like this (goes at the top level, replace `"blabber:classic"` with `"blabber:rpg"` for the alternative look):
 
 {% capture summary %}<h5 id="simple-layout-json" class="no_anchor">Simple layout JSON</h5>{% endcapture %}
@@ -126,6 +131,25 @@ The JSON looks like this (goes at the top level, replace `"blabber:classic"` wit
 ```
 {% endcapture %}
 {% include details.liquid summary=summary content=example_json %}
+{% capture summary %}<h5 id="parameterized-layout-json" class="no_anchor">Parameterized layout JSON</h5>{% endcapture %}
+{% capture example_json %}
+```json
+{
+  "layout": {
+    "type": "blabber:rpg",
+    "params": {
+      "main_text_margins": {
+        "left": 52,
+        "right": -4,
+        "top": 10,
+        "bottom": 5
+      }
+    }
+  }
+}
+```
+{% endcapture %}
+{% include details.liquid summary=summary content=example_json %}
 
 #### Illustrations
 
@@ -135,41 +159,114 @@ bring them to life 🧑‍🎨
 ![Example of illustrations, featuring a player talking to an illager](example-illustrations.png){:.rounded.wiki}
 
 Illustrations can be set for a regular dialogue state, or for individual choices within a state.
-In the former case they are positioned relative to the window, in the latter they are positioned relative to the choice's
-text (which is notably useful to keep up with localization shifting those around).
 
-There are currently 3 types of illustrations, plus the group type:
+This feature is still experimental - the JSON format and mod API are subject to evolve in future versions.
+{:.admonition.admonition-warning.admonition-icon}
+
+{% capture summary %}<h5 id="positioning-illustrations" class="no_anchor">Positioning Illustrations</h5>{% endcapture %}
+{% capture positioning_illustrations %}
+Illustrations are positioned on the screen by setting their `x` and `y` coordinates, in "logical pixels".
+By default, **coordinates start at `(0, 0)` in the top-left corner** of the screen, and *increase towards the bottom-right corner* of the screen.
+
+"Logical pixels" are Minecraft's way of dealing with screen resolution and GUI scales.
+They are only loosely related to the actual size of your screen, the main factors being the ratio of your game's window and your GUI scale option.
+When adding illustrations to a dialogue, you should try setting the GUI Scale option to "Auto" and resizing the game window in various ways to confirm that your dialogue
+displays decently on other devices.
+{:.admonition.admonition-important.admonition-icon}
+
+To help you position your illustrations, Blabber provides several *anchors* other than the window's top-left corner.
+When using a specific anchor, coordinates are translated such that `(0, 0)` is the position of the anchor itself.
+
+Available anchors are currently as follows:
+
+- Generic anchors: When using these anchors, general illustrations are positioned relative to a point of the window,
+  while illustrations attached to specific choices are positioned relative to the choice's
+  text (which is notably useful to keep up with localization shifting those around).
+  - `top_left` (the default)
+  - `top_right`
+  - `bottom_left`
+  - `bottom_right`
+  - `center`
+- Specific anchors: the position of these anchors is dictated by the [layout](#layout). Some layouts may not support them at all.
+  - `before_main_text`: matches the top-left corner of the main textbox for a given layout.
+  - `spot_1`, `spot_2`: arbitrary positions that are considered "good spots" for an illustration in the current layout.
+    The exact position of these spots for each default layout is not yet set in stone - feedback welcome.
+
+To better visualize the position of each anchor, you can enable the [relevant debug mode](#debug-modes).
+
+{% endcapture %}
+{% include details.liquid summary=summary content=positioning_illustrations %}
 
 {% capture summary %}<h5 id="illustration-types" class="no_anchor">Illustration Types</h5>{% endcapture %}
 {% capture illustration_types %}
+There are currently 3 types of illustrations, plus the group type:
+
 ###### Item (`blabber:item`)
 
-Renders an item stack with optional NBT. Properties:
+Renders an item stack with optional NBT, as if within an inventory slot. Properties:
 - `item` (type: [`item stack`](https://minecraft.wiki/w/Item_format)): the data for the item to render
-- `x` (type: `integer`): the `X` coordinate for rendering the stack on the screen
-- `y` (type: `integer`): the `Y` coordinate for rendering the stack on the screen
+- `anchor` (type: `IllustrationAnchor`): the point of the screen relative to which the `x` and `y` coordinates are computed. By default, will be the top-left corner of the screen.
+- `x` (type: `integer`): the `X` coordinate of the top-left corner for the drawn item
+- `y` (type: `integer`): the `Y` coordinate of the top-left corner for the drawn item
+- `scale` (type: `float`, optional) <span class="badge badge-secondary">&gt;1.6.0</span>: the size of the rendered item will be multiplied by this amount. By default, the item will be drawn at the same size as within an inventory slot.
 - `show_tooltip` (type: `boolean`, optional): if set to `true`, will render the item tooltip when the illustration is hovered in the dialogue screen
 
 ###### Entity (`blabber:entity`)
 
 Renders an entity taken from the player's world, in a frame similar to the inventory's player rendering. Properties:
 - `entity` (type: `string`): an entity selector (compatible with [`@interlocutor`](#interlocutors)). If this selector finds nothing at the time the dialogue starts, the illustration will not be drawn.
-- `x1` (type: `integer`): the `X` coordinate of the frame's upper left corner
-- `y1` (type: `integer`): the `Y` coordinate of the frame's upper left corner
-- `x2` (type: `integer`): the `Y` coordinate of the frame's lower right corner
-- `y2` (type: `integer`): the `Y` coordinate of the frame's lower right corner
-- `size` (type: `integer`, optional): the scaling factor for the entity (`1` is the default size)
+- `anchor` (type: `IllustrationAnchor`): the point of the screen relative to which the `x` and `y` coordinates are computed. By default, will be the top-left corner of the screen.
+- `x` (type: `integer`): the `X` coordinate of the frame's upper left corner
+- `y` (type: `integer`): the `Y` coordinate of the frame's upper left corner
+- `width` (type: `integer`): the width of the frame, in logical pixels
+- `height` (type: `integer`): the height of the frame, in logical pixels
+- `entity_size` (type: `integer`): the size of the entity within the frame (values should stay within the ballpark of the frame's width/height)
 - `y_offset` (type: `decimal number`): how far down the entity should be pushed within the frame
-- `stare_at_x` (type: `integer`, optional): the `X` coordinate, relative to the frame's center, towards which the entity should look. If left unspecified, the entity's stare will horizontally follow the player's cursor.
-- `stare_at_y` (type: `integer`, optional): the `Y` coordinate, relative to the frame's center, towards which the entity should look. If left unspecified, the entity's stare will vertically follow the player's cursor.
-- {:.admonition.admonition-warning.admonition-icon}The backport of Blabber for Minecraft 1.20.1 does not support cropping the entity nor pushing it down in the frame.
+- `stare_at` (type: `object`)
+  - `anchor` (type: `IllustrationAnchor`, optional): the point of the screen relative to which the `x` and `y` coordinates are computed. If left unspecified, will be the entity frame's center.
+  - `x` (type: `integer`, optional): the `X` coordinate, relative to the `anchor`, towards which the entity should look. If left unspecified, the entity's stare will horizontally follow the player's cursor.
+  - `y` (type: `integer`, optional): the `Y` coordinate, relative to the `anchor`, towards which the entity should look. If left unspecified, the entity's stare will vertically follow the player's cursor.
 
 ###### Fake Entity (`blabber:fake_entity`)
 
 Just like `blabber:entity`, but renders a fake entity of the desired type, with optional NBT. Properties:
 - `id` (type: `string`): the ID for the entity's type (e.g. `minecraft:villager`)
 - `data` (type: `object`, optional): NBT data to apply to the rendered entity
-- `x1`, `y1`, `x2`, `y2`, `size`, `y_offset`, `stare_at_x`, `stare_at_y`: refer to the documentation for `blabber:entity`
+- `anchor`, `x`, `y`, `width`, `height`, `entity_size`, `y_offset`, `stare_at`: refer to the documentation for `blabber:entity`
+
+###### Fake Player (`blabber:fake_player`) <span class="badge badge-secondary">&gt;1.6.0</span>
+
+Just like `blabber:entity`, but renders a fake player with the desired profile, with optional NBT. Properties:
+- `profile` (type: `object`): the full profile of the player. You can get it using [this tool](/tools/rolodex).
+  - `id` (type: `string`): the UUID of the player, without dashes
+  - `name` (type: `string`): the name of the player - does not have to match the real player's name
+  - `properties` (type: `array`): additional properties, most relevant of which is the encoded player skin and the associated signature.
+    **Blabber will not be able to render the right skin without a valid value here.**
+- `data` (type: `object`, optional): NBT data to apply to the rendered entity
+- `model_customization` (type: `object`): options for the player model
+  - `main_hand` (type: `string`, optional): set to `"left"` to render the fake player as left-handed. Defaults to `"right"`.
+  - `visible_parts` (type: `array`, optional): a list that can contain the values `"cape"`, `"jacket"` `"left_sleeve"`, `"right_sleeve"`, `"left_pants_leg"`, `"right_pants_leg"`, and `"hat"`.
+    Parts that are *not* in this list will be hidden. By default, all parts are visible.
+- `anchor`, `x`, `y`, `width`, `height`, `entity_size`, `y_offset`, `stare_at`: refer to the documentation for `blabber:entity`
+
+###### Texture (`blabber:texture`) <span class="badge badge-secondary">&gt;1.6.0</span>
+
+Renders a rectangular texture or an area thereof. The texture can come from the base game, a mod, or a resourcepack that clients have installed.
+Textures may be animated using a `pack.mcmeta` file. Properties:
+- `texture` (type: `string`): the ID of the texture in the format `<namespace>:<path>`, where `<path>` is the path of the PNG image relative to the `assets` directory (extension included)
+- `anchor` (type: `IllustrationAnchor`): the point of the screen relative to which the `x` and `y` coordinates are computed. By default, will be the top-left corner of the screen.
+- `x` (type: `integer`): the `X` coordinate of the drawn area's upper left corner
+- `y` (type: `integer`): the `Y` coordinate of the drawn area's upper left corner
+- `width` (type: `integer`): the width of the drawn area, in logical pixels
+- `height` (type: `integer`): the height of the drawn area, in logical pixels
+
+The following properties are optional and allow you to draw a specific region of a texture file:
+- `u` (type: `integer`, optional): the `X` coordinate of the upper left corner in the texture file, in real pixels (defaults to 0)
+- `v` (type: `integer`, optional): the `Y` coordinate of the upper left corner in the texture file, in real pixels (defaults to 0)
+- `textureWidth` (type: `integer`, optional): the actual width of the texture file, in real pixels (defaults to `width`)
+- `textureHeight` (type: `integer`, optional): the actual height of the texture file, in real pixels (defaults to `height`)
+- `regionWidth` (type: `integer`, optional): the width of the region to draw from the file, in real pixels (defaults to `width`)
+- `regionHeight` (type: `integer`, optional): the height of the region to draw from the file, in real pixels (defaults to `height`)
 
 ###### Composition (`blabber:group`)
 
@@ -386,11 +483,23 @@ The validation process checks for the following issues and reports them by eithe
 **Errors:**
 - **States with no choices:** Every non-end state must have at least one choice leading out of it. If any state has no choices defined, an error will be thrown.
 - **Softlock states:** Every state must have a path leading to an ending (no infinite loops). If any state is lacking a path to an end state, an error will be thrown.
+- **Nonexistent illustrations:** Illustrations must be defined in the appropriate section before getting referenced in a state. If any state is referencing an inexistant illustration, an error will be thrown.
+- **Invalid illustrated states:** Only regular dialogue states are allowed to have illustrations. If any confirmation or end state is using illustrations, an error will be thrown.
 
 **Warnings:**
 - **Conditional softlock states:** Any state that only has *conditional* paths leading to an ending will be reported. Blabber cannot tell whether a condition will necessarily be fulfilled when getting to such a state, and thus cannot prove that the player *will not* be softlocked.
 - **Unreachable states:** Any state that is disconnected from the main dialogue graph will be reported with a warning message. While they do not cause immediate issues for players, you may want to connect or remove such orphan states.
 
+### Debug Modes
+
+Blabber ships with a debug feature for dialogue screens, which can be enabled using the [`/blabber settings` command](#commands).
+Currently, the only debug mode available is `debug.anchors`, which displays the position of anchors, as well as the position of the cursor
+relative to each anchor.
+
+<figure>
+<img src="debug-anchors.png" alt="Debug Anchors Mode"/>
+</figure>
+
 ## Mod Compatibility
 
 ### Heracles
@@ -561,10 +670,14 @@ The two most relevant methods are as follow:
 
 #### Custom layouts
 
-It is possible to register your own custom layout with its completely custom screen by calling `BlabberScreenRegistry#register`
-in your client entrypoint. The API is however marked unstable, as the layout system is susceptible to being refactored to allow arbitrary data being passed to the screen
-(contributions welcome).
+It is possible to register your own custom layout with its completely custom screen by calling both `Blabber#registerLayout` in your main entrypoint and
+`BlabberScreenRegistry#register` in your client entrypoint. The API is currently marked as experimental, so some refactors may happen in future updates.
+
+#### Custom illustrations
+
+It is possible to register entirely custom illustrations by calling both `Blabber#registerIllustration` in your main entrypoint and
+`DialogueIllustrationRenderer#register` in your client entrypoint. The API is currently marked as experimental, so some refactors may happen in future updates.
 
 ### JSON Schema
 
-The schema for Blabber dialogue files is available here: [dialogue.schema.json](../../schemas/blabber/dialogue.schema.json)
+The schema for Blabber dialogue files is available here: [dialogue.schema.json](/schemas/blabber/dialogue.schema.json)

svelte_sprinkles/src/sprinkles/parlour/Parlour.svelte

@@ -41,6 +41,10 @@
     {/if}
   </ol>
 </nav>
+<div class="admonition admonition-warning">
+    <strong class="admonition-heading">🚧 This page is still under construction!</strong>
+    <span>Illustrations (added in Blabber 1.5) are not yet available in this editor.</span>
+</div>
 <main>
   {#if (!$dialogueFilename)}
     <Landing/>

svelte_sprinkles/src/sprinkles/rolodex/PlayerProfileLookup.svelte

@@ -8,6 +8,7 @@
 </script>
 <script lang="ts">
   import type {PlayerDbResponse} from "./PlayerDbResponse.js";
+  import {darkModeEnabled} from "../../lib/darkMode";
 
   let uuidOrUsername: string = '';
   let log: string = '';
@@ -35,7 +36,7 @@
           icon: playerData.avatar,
           username: playerData.username,
           uuid: playerData.id,
-          // We can't fetch from that, CORS won't allow us - best we can do is display a link
+          // We can't fetch from that, CORS won't allow us - best we can do is display a link and an iframe
           mojangDataUrl: `https://sessionserver.mojang.com/session/minecraft/profile/${playerData.id}?unsigned=false`,
         }
         window.history.replaceState(playerInfo, '');
@@ -69,7 +70,7 @@
   <fieldset disabled={loading}>
     <label>
       UUID or Username
-      <input type="text" bind:value={uuidOrUsername}/>
+      <input type="text" bind:value={uuidOrUsername} autocomplete="off"/>
     </label>
     <input type="submit"/><br/>
     <output>{log}</output>
@@ -84,7 +85,15 @@
   </span>
   </h2>
   <p><span class="uuid-label">UUID: </span><code>{playerInfo.uuid}</code></p>
-  <p><a href={playerInfo.mojangDataUrl}>Get the full JSON serialized form for Blabber's illustrations</a></p>
+  <p><a href={playerInfo.mojangDataUrl}>JSON GameProfile for Blabber's illustrations:</a></p>
+
+  <iframe
+    class:dark={$darkModeEnabled}
+    src="{playerInfo.mojangDataUrl}"
+    title="Game Profile data from Mojang"
+    width="800"
+    height="320">
+  </iframe>
 {/if}
 
 <style>
@@ -103,4 +112,17 @@
   .uuid-label {
     font-weight: bold;
   }
+
+  iframe {
+    background: white;
+    width: 100%;
+    border: 1px solid black;
+  }
+
+  /* Firefox shows JSON in white theme by default - other browsers do whatever */
+  @supports (-moz-appearance:none) {
+    iframe.dark {
+      filter: invert();
+    }
+  }
 </style>