diff --git a/public/wiki/blabber/debug-anchors.png b/public/wiki/blabber/debug-anchors.png new file mode 100644 index 00000000..783e9529 Binary files /dev/null and b/public/wiki/blabber/debug-anchors.png differ diff --git a/public/wiki/blabber/index.md b/public/wiki/blabber/index.md index 3ad75a7b..4b7009f0 100644 --- a/public/wiki/blabber/index.md +++ b/public/wiki/blabber/index.md @@ -37,6 +37,8 @@ Blabber adds the `/blabber` command, allowing server operators and mapmakers to - `` : the unique identifier for the dialogue - `[]` (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, `[]` is not optional. - `[]` (optional) : If specified, must be a target selector for a single entity. If unspecified, defaults to no interlocutor. + - `/blabber settings set ` : Toggles a debug 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 %}
Simple layout JSON
{% 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 %}
Parameterized layout JSON
{% 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 %}
Positioning Illustrations
{% 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 %}
Illustration Types
{% 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) >1.6.0: 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`) >1.6.0 + +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`) >1.6.0 + +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 `:`, where `` 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. + +
+Debug Anchors Mode +
+ ## 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) diff --git a/svelte_sprinkles/src/sprinkles/parlour/Parlour.svelte b/svelte_sprinkles/src/sprinkles/parlour/Parlour.svelte index 9fc19a7a..ea163a5d 100644 --- a/svelte_sprinkles/src/sprinkles/parlour/Parlour.svelte +++ b/svelte_sprinkles/src/sprinkles/parlour/Parlour.svelte @@ -41,6 +41,10 @@ {/if} +
+ 🚧 This page is still under construction! + Illustrations (added in Blabber 1.5) are not yet available in this editor. +
{#if (!$dialogueFilename)} diff --git a/svelte_sprinkles/src/sprinkles/rolodex/PlayerProfileLookup.svelte b/svelte_sprinkles/src/sprinkles/rolodex/PlayerProfileLookup.svelte index 7116d572..a7899a52 100644 --- a/svelte_sprinkles/src/sprinkles/rolodex/PlayerProfileLookup.svelte +++ b/svelte_sprinkles/src/sprinkles/rolodex/PlayerProfileLookup.svelte @@ -8,6 +8,7 @@