Merge branch 'main' into 1.20.1

# Conflicts: # src/main/java/guideme/compiler/LinkParser.java # src/main/java/guideme/internal/GuideMEClient.java # src/main/java/guideme/internal/MutableGuide.java # src/main/java/guideme/internal/util/Platform.java # src/main/java/guideme/render/SpriteLayer.java # src/main/java/guideme/scene/level/GuidebookLevel.java # src/main/resources/META-INF/accesstransformer.cfg # src/test/java/guideme/compiler/LinkParserTest.java # src/test/java/guideme/compiler/PageCompilerTest.java
AppliedEnergistics · Feb 23, 2025 · 9196dcd · 9196dcd
2 parents 6bec709 + fcd0897
commit 9196dcd
Show file tree

Hide file tree

Showing 123 changed files with 4,455 additions and 245 deletions.
diff --git a/build.gradle b/build.gradle
@@ -46,8 +46,16 @@ configurations {
     testRuntimeClasspath.extendsFrom localImplementation
 }
 
+// All jar files from this folder will be added automatically as runtime mod dependencies
+def extraModsDir = "extra-mods-${minecraft_version}"
+file(extraModsDir).mkdir()
+
 repositories {
     mavenCentral()
+    flatDir {
+        name = "extra-mods"
+        dir file(extraModsDir)
+    }
 }
 
 dependencies {
@@ -95,6 +103,17 @@ dependencies {
     testImplementation("org.mockito:mockito-junit-jupiter:5.12.0")
 
     testmodRuntimeOnly sourceSets.main.output
+
+    // Locally sourced extra mods for runtime (i.e. testing)
+    for (extraModJar in fileTree(dir: extraModsDir, include: '*.jar')) {
+        def basename = extraModJar.name.substring(0, extraModJar.name.length() - ".jar".length())
+        def versionSep = basename.lastIndexOf('-')
+        assert versionSep != -1
+        def artifactId = basename.substring(0, versionSep)
+        def version = basename.substring(versionSep + 1)
+        logger.lifecycle("Adding extra mod {}", extraModJar)
+        testmodRuntimeOnly "extra-mods:$artifactId:$version"
+    }
 }
 
 ///////////////////
@@ -135,6 +154,9 @@ legacyForge {
         enabledSourceSets = [sourceSets.main, sourceSets.testmod, sourceSets.test]
     }
 
+    // can't do that in 1.20.1 since Forges own ATs are broken
+    // validateAccessTransformers = true
+
     mods {
         guideme {
             sourceSet sourceSets.main

diff --git a/docs/docs/02-changelog.md b/docs/docs/02-changelog.md
@@ -3,12 +3,37 @@ import Video from '@site/src/components/Video';
 
 # Changelog
 
+## 21.1.1 (Minecraft 1.21.1)
+
+- Added support for [translating guides](./60-translation.md).
+- Added an option for Players to disable loading of guide translations.
+- Added support for the strikethrough Markdown extension (`~~text~~` or `~text~`).
+- Added rendering for Markdown blockquotes.
+- Added support for entities in game scenes using `<Entity />`. See [game scenes](./30-authoring/game-scenes.md#entities) for details.
+  ![entity in game scene](./30-authoring/game-scene-entity.png)
+- Add `<CommandLink command="/command" [title="tooltip"] [close={true}]>...</CommandLink>` that runs a command when clicked.
+- Added a [tag for coloring text](./30-authoring/index.md#colored-text) using pre-defined colors, for use with the 16 default Minecraft colors.
+- Fix several search issues relating to not analyzing queries properly, which reduced the number of relevant results.
+- Fix returning to the original screen when the guide is closed.
+- Improved visibility of the debug overlay text and outlines.
+- Fix background panels in guide being drawn without depth test enabled, sometimes hiding other elements.
+- Fix "Crafting (shapeless)" sometimes overflowing the recipe box and design an easier to use API for
+  integrating custom recipe types.
+- Fix a hidden navbar in guides without navigation still blocking interaction with elements below.
+- Floating point attributes to custom tags can now be specified using MDX expression syntax too (i.e.: `<GameScene zoom={2.5}>`). 
+  Please note that only bare floating point values are supported, no actual expressions.   
+- Fatal Markdown parsing errors will now no longer crash the resource reload and instead replace the offending page with an error page.
+- Cycles in the navigation tree will now be reported and no longer cause a stack overflow during resource reload.
+- Fix scaling in `<ItemImage />` also scaling normals, which made items with 3d models appear too dark.
+
 ## 21.1.0 (Minecraft 1.21.1)
 
 - Switching to the NeoForge versioning scheme, this version is equivalent to version 2.6.0, except for the following changes.
 - Improved query parsing for full-text search. Search will now always apply "incremental" search for the last entered word,
   assuming the user might not have entered it fully yet. This means searching for "io po" will search for both "io po"
   and "io po*", although it will score an exact hit for "po" higher than a hit for "port" (for example).
+- Fix parsing of links to pages where the mod-id contained underscores (i.e. `modern_industrialization:some_page.md`).
+- Fix tooltip crash caused by wrong access transformer.
 
 ## 2.6.0 (Minecraft 1.21.1)
 

diff --git a/docs/docs/03-downloads.md b/docs/docs/03-downloads.md
@@ -0,0 +1,58 @@
+import DownloadCurseforge from '@site/src/components/DownloadCurseforge';
+import DownloadModrinth from '@site/src/components/DownloadModrinth';
+
+# Downloads
+
+## For Players
+
+The mod can be downloaded from both Curseforge and Modrinth.
+
+<p>
+    <DownloadCurseforge />
+</p>
+
+<p>
+    <DownloadModrinth />
+</p>
+
+## For Developers
+
+### Releases
+
+GuideME publishes Maven artifacts on both [Github Packages](https://github.com/AppliedEnergistics/GuideME/packages/2384035) 
+and [Maven Central](https://central.sonatype.com/artifact/org.appliedenergistics/guideme).
+
+![GuideME](https://img.shields.io/maven-central/v/org.appliedenergistics/guideme)
+
+How you can use GuideME in your build script will depend on which build tool you use.
+
+If you use ModDevGradle, this snippet will include GuideMEs API during compile-time, and its full package during runtime:
+
+```gradle
+repositories {
+    mavenCentral() // You might already have this
+}
+
+dependencies {
+    compileOnly 'org.appliedenergistics:guideme:<version>:api'
+    runtimeOnly 'org.appliedenergistics:guideme:<version>'
+}
+```
+
+### Snapshots
+
+We publish every commit on the main branch to the Maven Central Snapshot repository.
+
+You can see the [list of versions](https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/org/appliedenergistics/guideme/).
+
+To use these versions, you can use this repository in Gradle:
+
+```gradle
+maven {
+    name = 'GuideME Snapshots'
+    url = 'https://central.sonatype.com/repository/maven-snapshots/'
+    content {
+        includeModule('org.appliedenergistics', 'guideme')
+    }
+}
+```
diff --git a/docs/docs/20-data-driven-guides.md b/docs/docs/20-data-driven-guides.md
@@ -47,6 +47,13 @@ the item and additional tooltip lines in the JSON text component format.
 All settings of the `item_settings` block are optional. If you do not set a `display_name`,
 the name will just be "Guide". If you don't set a model, it will use the default GuideME model.
 
+## Default Language
+
+You can set the language of your guides default pages to something other than english by setting the `default_language`
+key to the appropriate [Minecraft language code](https://minecraft.wiki/w/Language) for your language.
+
+This makes the [full-text search](./40-search.md) use language-specific text analysis logic for your default pages.
+
 ## Writing Pages
 
 See [authoring pages](30-authoring/index.md).
diff --git a/docs/docs/20-integration/recipe-types.md b/docs/docs/20-integration/recipe-types.md
@@ -22,9 +22,16 @@ package appeng.client.guidebook;
 public class RecipeTypeContributions implements RecipeTypeMappingSupplier {
     @Override
     public void collect(RecipeTypeMappings mappings) {
-        mappings.add(AERecipeTypes.INSCRIBER, LytInscriberRecipe::new);
         mappings.add(AERecipeTypes.CHARGER, LytChargerRecipe::new);
-        mappings.add(AERecipeTypes.TRANSFORM, LytTransformRecipe::new);
+    }
+
+    private static LytStandardRecipeBox<ChargerRecipe> charging(RecipeHolder<ChargerRecipe> holder) {
+        return LytStandardRecipeBox.builder()
+                .icon(AEBlocks.CHARGER)
+                .title(AEBlocks.CHARGER.asItem().getDescription().getString())
+                .input(holder.value().getIngredient())
+                .outputFromResultOf(holder)
+                .build(holder);
     }
 }
 ```
@@ -35,6 +42,5 @@ project:
 
 ## Custom Layout Blocks
 
-If your recipe requires a custom layout block, you can use the
-existing [recipe layouts in GuideME](https://github.com/AppliedEnergistics/GuideME/tree/main/src/main/java/guideme/document/block/recipes)
-as a starting point.
+While your recipe can be any custom layout block, GuideME offers a [builder](https://guideme.appliedenergistics.org/javadoc/guideme/document/block/recipes/LytStandardRecipeBox.html) to quickly build recipe blocks
+that adhere to the standard input, arrow, output pattern.
diff --git a/docs/docs/30-authoring/game-scene-entity.png b/docs/docs/30-authoring/game-scene-entity.png
diff --git a/docs/docs/30-authoring/game-scenes.md b/docs/docs/30-authoring/game-scenes.md
@@ -66,6 +66,34 @@ The tag also supports the following attributes:
 | z          | z coordinate of the block. Defaults to 0.                                                                           |
 | `p:<name>` | Allows setting arbitrary block state properties on the block, where `<name>` is the name of a block state property. |
 
+## Entity
+
+You can add entities to your scene as well, using the `Entity` tag.
+
+The attributes follow the format used by the `/summon` command:
+
+| Attribute | Description                                                                                                           |
+|-----------|-----------------------------------------------------------------------------------------------------------------------|
+| id        | Entity type id as used by `/summon`. For example `minecraft:sheep`.                                                   |
+| x         | x coordinate the entity is centered on. Defaults to 0.5.                                                              |
+| y         | y coordinate at the bottom of the entity. Defaults to 0.                                                              |
+| z         | z coordinate the entity is centered on. Defaults to 0.5.                                                              |
+| rotationY | Sets the rotation around the Y axis of the entity in degrees. Defaults to -45.                                        |
+| rotationX | Sets the rotation around the X axis of the entity in degrees. What effect this has depends on the entity.             |
+| data      | Allows setting the initial NBT data of the entity. Uses the same format as `/summon`. Example: `{Color:2}` for sheep. |
+
+Example:
+
+```
+<GameScene zoom={4} interactive={true}>
+    <Entity id="minecraft:sheep" data="{Color: 2}" />
+</GameScene>
+```
+
+Which shows as:
+
+![sheep example](./game-scene-entity.png)
+
 ## IsometricCamera
 
 This tag allows more fine-grained control over the isometric camera used to render the scene.

diff --git a/docs/docs/30-authoring/index.md b/docs/docs/30-authoring/index.md
@@ -2,6 +2,8 @@
 description: How to create content for a GuideME guide.
 ---
 
+import ColorPreview from '@site/src/components/ColorPreview';
+
 # Authoring Pages
 
 Pages for a guidebook are read from *all resource packs* across *all namespace*.
@@ -12,13 +14,13 @@ Each file with the extension `.md` in this directory and any subdirectory is con
 
 :::note
 
-Like all files in Minecraft resource packs, page filenames must be [valid resource ids](https://minecraft.wiki/w/Resource_location).
+Like all files in Minecraft resource packs, page filenames must
+be [valid resource ids](https://minecraft.wiki/w/Resource_location).
 Your filenames must all be lowercase, for example.
 
 :::
 
-Pages are written in Markdown and follow the [Commonmark](https://commonmark.org/) specification.
-We also support [Github Tables](https://github.github.com/gfm/#tables-extension-).
+Pages are written in Markdown. See [supported Markdown](./markdown.md) for details.
 
 Every page should usually declare its title as a level 1 heading at the start (`# Page Title`).
 
@@ -123,10 +125,25 @@ Example for horizontally centering an image on the page:
 ### Item Links
 
 To automatically show the translated item name, including an appropriate tooltip, and have the item name link to the
-primary guidebook page for that item, use the  `<ItemLink id="item_id" />` tag. The id can omit the `ae2` namespace.
+primary guidebook page for that item, use the  `<ItemLink id="item_id" />` tag. The id can omit the guides default
+namespace.
 
 [Pages need to be set as the primary target for certain item ids manually](#declaring-pages-as-itemlink-targets).
 
+### Command Links
+
+You can make links that run a command when clicked using `<CommandLink command="/command">text text</CommandLink>`.
+
+The specified command is sent from the client normally and does not bypass permission checks. It has to start with a
+slash.
+
+There are optional attributes:
+
+| Attribute | Description                                                                                       |
+|-----------|---------------------------------------------------------------------------------------------------|
+| title     | An optional tooltip to show for the link. The command itself will always be shown in the tooltip. |
+| close     | If set to `{true}`, the current screen will be closed when the link is clicked.                   |
+
 ### Recipes
 
 To show the recipes used to create a certain item, use the `<RecipeFor id="item_id" />` tag.
@@ -211,3 +228,32 @@ The tag also supports the following attributes:
 | float       | Allows the block image to be floated like `FloatingImage` to make it show to the left or right with a block of text. (Allows values: left, right)                                               |
 | perspective | Allows the orientation of the block to be changed. By default, the north-east corner of the block will be facing forward. Allowed values: isometric-north-east (default), isometric-north-west. |
 | `p:<name>`  | Allows setting arbitrary block state properties on the rendered block, where `<name>` is the name of a block state property.                                                                    |
+
+### Colored Text
+
+:::warning
+
+The following should be used sparingly since it may not provide great contrast when switching between light- and dark-mode.
+
+:::
+
+You can use the `<Color id="<id>">...</Color>` tag to color text using the following pre-defined symbolic colors:
+
+| ID             | Light-Mode                    | Dark-Mode                     |
+|----------------|-------------------------------|-------------------------------|
+| `black`        | <ColorPreview color="#000" /> | <ColorPreview color="#000" /> |
+| `dark_blue`    | <ColorPreview color="#00A" /> | <ColorPreview color="#00A" /> |
+| `dark_green`   | <ColorPreview color="#0A0" /> | <ColorPreview color="#0A0" /> |
+| `dark_aqua`    | <ColorPreview color="#0AA" /> | <ColorPreview color="#0AA" /> |
+| `dark_red`     | <ColorPreview color="#A00" /> | <ColorPreview color="#A00" /> |
+| `dark_purple`  | <ColorPreview color="#A0A" /> | <ColorPreview color="#A0A" /> |
+| `gold`         | <ColorPreview color="#AA0" /> | <ColorPreview color="#AA0" /> |
+| `gray`         | <ColorPreview color="#AAA" /> | <ColorPreview color="#AAA" /> |
+| `dark_gray`    | <ColorPreview color="#555" /> | <ColorPreview color="#555" /> |
+| `blue`         | <ColorPreview color="#55F" /> | <ColorPreview color="#55F" /> |
+| `green`        | <ColorPreview color="#5F5" /> | <ColorPreview color="#5F5" /> |
+| `aqua`         | <ColorPreview color="#5FF" /> | <ColorPreview color="#5FF" /> |
+| `red`          | <ColorPreview color="#F55" /> | <ColorPreview color="#F55" /> |
+| `light_purple` | <ColorPreview color="#F5F" /> | <ColorPreview color="#F5F" /> |
+| `yellow`       | <ColorPreview color="#FF5" /> | <ColorPreview color="#FF5" /> |
+| `white`        | <ColorPreview color="#FFF" /> | <ColorPreview color="#FFF" /> |