[WIP] Multiblock Display System

[joazlazer]

Features (Some Still WIP)

Adds the new <multiblock> tag which represents a MultiblockPanel element and allows guidebook authors to display a multiblock structure:

<multiblock structures="[gbook:furnace_brick,gbook:furnace_nether_brick]" transformation="t[-1,-1.35,-1] q[0,1,0,0] s[0.9]">

• With the structure attribute, an array of resource locations can be specified that point to *.nbt structure files within the folder assets/<domain>/structures/
  • These structures are parsed and stored in a 3-D matrix of generic MultiblockComponents, each of which represents one object in one position within the multiblock structure
    • Custom BlockComponent extensions can be registered via a Factory system in order to correctly display non-standard blocks, such as fluids (as is done with BlockFluidComponent) and tile-entities
• With the transformation attribute, a translation, scale, and/or rotation/quaternion can be specified to offset, scale, and/or rotate the structure
  • For example, the XML transformation="t[-1,-1.35,-1] q[0,1,0,0] s[0.9]" specifies:
    • a translation towards -x by 1, down -y by 1.35, and towards -z by 1
    • a quaternion rotation that rotates the structure 180° about the y-axis
    • a scale in all directions by a factor of 0.9
• With the height attribute, authors specify the target height that the guidebook is rendered to. Note that this height is not used to GL_SCISSOR or anything that creates a viewport; it exists only for spacing and it is up to the author to ensure the structure fits within
• To the side of the rendered structure in the guidebook, a panel of icons exists to manipulate the view of the multiblock
  • The first set, with two arrows, two numbers, and a line indicates the top display layer of the multiblock, which can be lowered in order to show the structure layer-by-layer
  • The second button, which switches between expansion and collapsing mode, allows users to view the multiblock structure in both an "exploded" and "condensed" state, as is shown in the gifs below
• In addition, users can also view manipulated views of the multiblock by clicking and dragging to orbit their view as well as with a static turntable-like spin that shows the structure from each yaw angle.
• By hovering over different MultiblockComponents, the component under the user's cursor becomes highlighted and a descriptive tooltip of the component's contents is displayed (as is shown in one of the images below)
• Underneath the multiblock, a grid floor is rendered and can be turned on or off, as well as have its modes changed via the floor attribute
• Between layers in the multiblock, thin beacon-like poles can be rendered either on the corners of the structure or directly underneath ItemComponents. This behavior is specified via the poles attribute
• Within the <multiblock> tag, additional tags can be nested as follows:

<multiblock structures="[gbook:furnace_brick,gbook:furnace_nether_brick]" transformation="t[-1,-1.35,-1] q[0,1,0,0] s[0.9]">
  <stack position="0,4,0" item="minecraft:chest" transformation="s[1.1]"/>
  <stack position="2,4,0" item="minecraft:bucket" transformation="s[1.1] q[0,-0.383,0,0.924]"/>
</multiblock>

• An extension of MultiblockComponent, ParsableMultiblockComponent provides a way to register parsing factories (called Parsers) for custom multiblock components that are specified via XML, such as ItemStacks
  • ItemComponent parses a <stack> node similar to how normal Stack elements are parsed within guidebooks, except it includes two additional attributes:
    • position, which is an attribute for all ParsableMultiblockComponents and specifys the component's position within the multiblock structure
    • transformation, which allows authors to specify render transformations and is described above

Example

<multiblock structures="[gbook:furnace_brick,gbook:furnace_nether_brick]" transformation="t[-1,-1.35,-1] q[0,1,0,0] s[0.9]">
  <stack position="0,4,0" item="minecraft:chest" transformation="s[1.1]"/>
  <stack position="2,4,0" item="minecraft:bucket" transformation="s[1.1] q[0,-0.383,0,0.924]"/>
  <stack position="2,4,2" item="minecraft:dye" meta="10" transformation="s[1.1]"/>
  <stack position="0,4,2" item="minecraft:iron_ore" transformation="t[0,-0.09,0] s[1.6]"/>
</multiblock>

Produces the following multiblock:

In addition, a mouseHover system is in the works, with the current iteration appearing as follows:

Tasks

• Fix for panes / bars / probably fences / redstone / grass
  • Will probably involve some registry system for mapping Block implementation Classes to custom BlockComponent implementations
  • These custom BlockComponents would be able to correctly parse the IBlockState and render the correct models for connecting blocks (which for some reason doesn't happen)
• Add orbit via drag as well as static turntable spin
• Add a transparent grid floor to easily view structure size
• Add thin beacons either under items or under to corners of the multiblock (option for either)
• Add parsing of child elements for ItemStack rendering
  • Potentially will make a Factory registry system to parse custom MultiblockComponents from the child elements of the <multiblock> node
• Tooltips for each MultiblockComponent type and the ray-tracing needed for it
• Dynamic scene-order block sorting algorithm to render translucent blocks correctly, as well as a restructure of how translucent blocks are rendered
  • Will use dynamically ordered List<> instead of another MultiblockComponent[][][] matrix)
• Comprehensive javadoc documentation
• In-game Guidebook documentation (WIP)
• Refactor offset and initialRot to an initialTransform attribute which parses a TRSRTransformation

[gigaherz]

I don't dislike the PR, but I was always picturing people using templates for this, like I did on the Ender-Rift manual: https://github.com/gigaherz/Ender-Rift/blob/master/src/main/resources/assets/enderrift/xml/book.xml#L3

[joazlazer]

Interesting. I wanted to see if I could support more interactive features within the book such as spin, z-layer hiding via a slider, and an option to view both expanded and compacted. To do this, I was thinking of rendering in 3d and then translating to screen space via transforms. What do you think about these features?

[gigaherz]

Interesting. I wanted to see if I could support more interactive features within the book such as spin, z-layer hiding via a slider, and an option to view both expanded and compacted. To do this, I was thinking of rendering in 3d and then translating to screen space via transforms. What do you think about these features?

Oops never answered to this: Yeah I do like it. It's quite a lot more interesting than just a static template, even if it deviates from the "pseudo-html" that I originally had in mind.