GUI¶
GUI building blocks: draggable windows, scrolling, stacked panels with pan and zoom, slide animations, placing things out of the way of the rest of the screen, 3D scene viewports and drawing helpers. Packages under net.ixdarklord.coolcatcanvas.api.client: gui.widget (windows and widgets), gui.panel (panels), gui.animation, gui.placement, viewport and render (drawing helpers).
Moved in 9.0.0
Before 9.0.0, these were in gui.components (and its widgets, widgets.panel and animations subpackages) and utils. The class names are the same.
Warning
AbstractMultiPanelWidget, Panel, ScrollPanel, ViewportPanel, SceneViewport and SceneViewportWidget are marked @ApiStatus.Experimental: they may still change.
Windows¶
AbstractDraggableWidget is a self-contained window with its own children, which the player can optionally drag around. Add it to a screen like any widget.
| Class | Description |
|---|---|
AbstractDraggableWidget |
Constructor (Component title, int x, int y, int width, int height, boolean isMovable). Implement init(), renderBackground(...), getDraggingRectangle() (the area that drags it) and layoutRectangle(). Optional hooks: renderLabels, renderContents, postInit, updateChildren. Children are added with addRenderableWidget, addWidget, removeWidget and clearWidgets. Also has toggleVisibility(), setVisible(boolean) and moveTo(x, y). |
AbstractScrollableWidget |
A draggable window with a scrollable area and scrollbar. Override renderScrollableContents(...), getContentSize(ScreenAxis) and getScrollStep(ScreenAxis). Also has setBorderColor, setScrollBgColor, setScrollColor and enableScrollingHorizontally(). |
AbstractMultiPanelWidget |
A window whose content is a stack of Panels, drawn bottom to top. Input goes to the window's own widgets first, then to panels from the top down. A modal panel blocks the panels under it and dims them. Add panels with addPanel(panel) and removePanel(panel); also has getPanels(), getTopPanel(), setOverlayColor(argb) and setBounds(...). |
MovableElement |
Anything with moveTo(x, y). |
Panels¶
| Class | Description |
|---|---|
Panel |
One layer. Implement extractContents(graphics, mouseX, mouseY, partialTick); hooks onResized() (lay out children here), onShown(), onHidden(). setModal(boolean), setVisible(boolean), addChild(widget) (children draw over the contents and get the mouse first). |
ScrollPanel |
Vertical scrolling: implement getContentHeight() and extractScrolled(graphics, left, top, width, mouseX, mouseY, partialTick). setScrollStep, setScrollbarColors, getScroll, setScroll. |
ViewportPanel |
A 2D world the player pans (drag) and zooms (the mouse wheel, anchored at the cursor; +/-; 0 or Home to fit; the arrow keys pan). Implement getContentBounds() and extractWorld(graphics, mouseWorldX, mouseWorldY, mouseInView, partialTick); optionally worldClicked(...), extractViewBackground, extractViewForeground. Setters: setZoomLimits, setZoomStep, setVignette, setEdgeFade, setMargin. Control: zoomTo, zoomBy, centerOn, requestFit; coordinates with toWorldX/Y and toScreenX/Y. |
class MapWindow extends AbstractMultiPanelWidget {
MapWindow() { super(Component.literal("Map"), 20, 20, 300, 200, true); }
@Override protected void init() { this.addPanel(new MapPanel()); }
@Override protected void renderBackground(GuiGraphicsExtractor graphics, float partialTick, int mouseX, int mouseY) {
RenderUtils.fillRect(graphics, this.getX(), this.getY(), this.getWidth(), this.getHeight(), 0xC0101010);
}
@Override public ScreenRectangle getDraggingRectangle() { return new ScreenRectangle(this.getX(), this.getY(), this.getWidth(), 12); }
@Override protected ScreenRectangle layoutRectangle() { return new ScreenRectangle(this.getX(), this.getY() + 12, this.getWidth(), this.getHeight() - 12); }
}
class MapPanel extends ViewportPanel {
@Override protected ScreenRectangle getContentBounds() { return new ScreenRectangle(0, 0, 512, 512); }
@Override protected void extractWorld(GuiGraphicsExtractor graphics, double mouseWorldX, double mouseWorldY, boolean mouseInView, float partialTick) {
// Draw in world coordinates; the panel applies the pan and zoom.
}
}
Animations and anchors¶
| Class | Description |
|---|---|
gui.animation.AnimatedComponent |
A timeline in seconds that pauses with the game: play(reverse[, AnimMode]), update() every frame, isPlaying(), isFinished(). Modes: LOOP, PING_PONG, HOLD_LAST_FRAME. |
gui.animation.SlideAnimation |
Slides an element in from off-screen, horizontally or vertically, anchored with a ScreenAnchor. |
gui.placement.ScreenAnchor |
TOP_LEFT … BOTTOM_RIGHT and CENTER: getX(screenWidth, width, padding), getY(...), next(), previous(). |
Out of the way¶
GuiPlacement (gui.placement) finds where to put something of your own, a HUD card or a toast, so it doesn't cover what else is on the screen. Give it a size and where you'd like it; it comes back there if that's clear, or at the nearest clear place, slid in the directions you allow.
GuiPlacement.Position at = GuiPlacement.hud()
.size(width, 16).at(x, 4).gap(2)
.directions(GuiPlacement.Direction.DOWN)
.find();
GuiAreas.unrecorded(() -> drawCard(graphics, at.x(), at.y())); // so the card isn't in its own way next frame
GuiAreas.hud() and screen() are the boxes of what the HUD and the open screen drew last frame: the game's own, every mod's HUD layers (a minimap, a block tooltip, the boss bars), the screen's widgets, slots and items, though not its background or the tooltip under the mouse. GuiPlacement reads them: hud(), screen() or among(areas), then within(...) to stay inside bounds, ignore(...) and ignoreOverlays(share) (anything covering more than 40% of the screen is left out by default), and find(), whose moved() says whether it had to move. Client and render thread only.
Items at an opacity¶
The game draws items in a GUI fully opaque, with no way to ask for less, and solid models (blocks, beds, block entity items) stay bright or turn into black shapes when you try. ItemOpacityRenderer (api.client.gui) draws them at an opacity, flat and solid items alike: a HUD card fading in with its icon, a slot greyed out.
ItemOpacityRenderer.render(graphics, stack, x, y, 0.5F); // half see-through
ItemOpacityRenderer.renderWithDecorations(graphics, font, stack, x, y, 0.5F); // with its count and durability bar
// Anything that draws items, at an opacity:
ItemOpacityRenderer.withOpacity(0.5F, () -> graphics.item(stack, x, y)); // renderItem on 1.21.1 and 1.20.1
Opacities run from 0 to 1, on top of any opacity already in force; under about 0.004 nothing is drawn. Inside withOpacity, the text and filled rectangles drawn fade too, so an item's count and its bar go with it.
Fades¶
An OpacityTween eases an item's opacity from one value to another over a number of ticks. Keep it with whatever draws the item, and pass it each frame:
OpacityTween fade = ItemOpacityRenderer.OpacityTween.in(10).start(); // fades in over half a second
// every frame:
ItemOpacityRenderer.render(graphics, stack, x, y, fade);
if (fade.finished()) { /* fully shown */ }
| Method | What it does |
|---|---|
OpacityTween.in(ticks) |
From unseen to fully shown, easing out (Easing.SINE_OUT). |
OpacityTween.out(ticks) |
From fully shown to unseen, easing in (Easing.SINE_IN). |
OpacityTween.between(from, to, ticks, easing) |
From one opacity to another on any Easing. |
start() |
Starts it now (again, if it had run); returns the tween. Until then it sits at its first value. |
opacity(), started(), finished() |
Where it is now. |
It runs on the clock rather than on ticks, so it stays smooth at any frame rate.
Only the items¶
On 26.1.2, 26.2 and 26.3, pushItemOpacity(opacity) and popItemOpacity() fade just the items drawn between them, for code that fades the rest of what it draws itself, such as a whole HUD faded between two hooks. They nest, and each push needs its pop.
Since
Coming in 8.0.0, on every version. On 1.21.1 and 1.20.1 the methods take a GuiGraphics, and there's no pushItemOpacity.
1.21.1 and 1.20.1
There, items fade with the shader color's alpha: any item drawn while it's under 1 is drawn see-through, including the game's own, such as the hotbar under a HUD you've faded.
Scene viewports¶
A SceneViewport (api.client.viewport) is a small 3D scene drawn into a texture of its own: blocks, whole structures, block entities, entities and items' icons, seen from a camera that circles them. As a texture, it stays inside the rectangle it's drawn in: a GUI, through SceneViewportWidget, or a face in the world, with texture() and any textured render type.
SceneViewport view = SceneViewport.create(MyMod.id("altar_view"), 256, 256);
view.blocks(structureBlocks).camera(35, 28).spin(16);
addRenderableWidget(new SceneViewportWidget(x, y, 128, 128, view)); // drag to turn, scroll to zoom
// when the screen closes:
view.close();
The widget doesn't own the viewport: close it yourself. For a sharp picture, make the viewport as large as the widget is on screen (its size times the GUI scale). Drawn anywhere else, call view.use() every frame it's shown; a viewport nobody has used for a couple of seconds isn't drawn. Make and change viewports on the render thread.
A viewport is drawn again only when its scene or camera changes, or, while it spins or holds entities or block entities, refreshRate times a second (60 by default).
| Method | What it adds or sets |
|---|---|
block(pos, state), blocks(map) |
A block, or every block of a structure. |
blockEntity(pos, blockEntity) |
A block entity, drawn by its renderer as in the world: a chest's lid, a sign's text, a mod's pedestal and its effects. Its block goes in with block. It's never in a world, only drawn: its renderer reads it each time the viewport is drawn, so change it to animate it. What faces the camera faces the viewport's camera. |
entity(entity, x, y, z, yaw) |
An entity with its feet at a place. Tick it to animate it. |
item(stack, x, y, z, size) |
An item's icon, size across. |
sprite(texture, x, y, z, width, height, roll, argb) |
A glowing picture facing the camera: rays, halos, flares. It's added on as light, shaped by its texture's alpha, and hidden by blocks and entities nearer the camera. |
uprightSprite(texture, x, y, z, width, height, argb) |
The same, standing straight up and turning only about its vertical: a beam of light, a column of mist. |
text(line, x, y, color, scale) |
Text laid flat on the picture, in the texture's own pixels. |
ground(y, margin, floorArgb, lineArgb, shadows), noGround() |
A floor under the scene with a grid of lines, and soft shadows under entities. |
frame(span, x, y, z) |
Fixes what the picture shows (span blocks across, a point at its middle) instead of fitting the scene to it; 0 goes back to fitting. |
camera(yaw, pitch), zoom(z), spin(degreesPerSecond), perspective(fov) |
Where the camera stands, how large the scene is drawn, turning it by itself, and drawing it in perspective (0, the default, is flat). |
clear(), clearText(), clearSprites() |
Takes away the whole scene, or just its text or its sprites (to place them again each frame as they move). |
view.block(BlockPos.ZERO, MyBlocks.PEDESTAL.get().defaultBlockState())
.blockEntity(BlockPos.ZERO, pedestal)
.uprightSprite(MyMod.id("textures/effect/beam.png"), 0.5, 2.5, 0.5, 1.0F, 3.0F, 0x80FFE0A0);
Since
SceneViewport and SceneViewportWidget: since 26.1.2-5 (and 26.2, 26.3), 2100.4.0.0 (1.21.1) and 2001.4.0.0 (1.20.1). perspective: since 8.0.0 on 26.1.2, 26.2 and 26.3, 8.2.0 on 1.21.1 and 1.20.1.
sprite, uprightSprite, clearSprites and blockEntity: since 8.2.0, on every version.
Drawing helpers¶
In render, except ColorableImageButton (gui.widget):
| Class | Description |
|---|---|
RenderUtils |
Shapes: fillRect, drawHollowRect, drawLine, drawInsideRect (optionally clipped). Gradients: fillVerticalGradient, fillHorizontalGradient, drawDiagonalGradient. Text: drawString, drawCenteredString, drawScrollingString, and textColor(color), which makes alpha-less RGB colors opaque, since 26.1 skips text whose alpha is 0. Textures: blitNineSliced, blitRepeating, blitWithBorder, blitInscribed (aspect-fit). |
NineSliceInfo |
Parameter holders for nine-slice blits: SliceBounds, TextureRegion, TextureInfo. |
ColorableImageButton |
An ImageButton whose sprite is tinted with setColor(java.awt.Color). |