Skip to main content

Overview

Minecraft Community Edition’s GUI system consists of reusable components for building user interfaces. The system is built around the GuiComponent base class, with specialized components for buttons, HUD elements, and visual effects.

GuiComponent Base Class

The GuiComponent class (GuiComponent.h) provides fundamental rendering utilities used by all GUI elements:
Source: Minecraft.Client/GuiComponent.h:5

Drawing Methods

Line Drawing
Filled Rectangles
Text Rendering
Texture Blitting
Copies a rectangular region from the currently bound texture to screen coordinates.

Button Component

The Button class provides interactive button elements for screens.

Button Properties

Source: Minecraft.Client/Button.h:5

Creating Buttons

Constructor with default size (200x20):
Constructor with custom size:
Example:
Source: Minecraft.Client/Button.cpp:5

Button States

Buttons have three visual states:
Source: Minecraft.Client/Button.cpp:30
  • State 0 (Disabled): Gray, non-interactive
  • State 1 (Normal): Default appearance
  • State 2 (Hovered): Highlighted when mouse over

Button Rendering

Buttons render using the gui.png texture:
Source: Minecraft.Client/Button.cpp:38

Button Interaction

Click Detection:
Source: Minecraft.Client/Button.cpp:82 Release Handling:
Source: Minecraft.Client/Button.cpp:78

Button Customization

renderBg() - Override for custom button appearance:
Used by specialized button types to add custom rendering. Source: Minecraft.Client/Button.cpp:74

Gui (HUD) Class

The Gui class manages the in-game heads-up display (HUD), including health, hunger, hotbar, and messages.

Gui Overview

Source: Minecraft.Client/Gui.h:8

HUD Rendering

The main render method handles all HUD elements:
Parameters:
  • a - Alpha/interpolation value
  • mouseFree - Whether cursor is visible
  • xMouse, yMouse - Cursor position
Source: Minecraft.Client/Gui.cpp:57

GUI Scaling

The HUD adapts to different screen configurations:
Source: Minecraft.Client/Gui.cpp:68 Supports:
  • Fullscreen GUI scaling (scale 2-4)
  • Split-screen adjustments
  • Safe zones for different viewports
  • Dynamic scaling for up to 4 players

Chat Messages

Adding Messages:
Adds a message to the chat overlay for a specific player. Clearing Messages:
Clears messages for a player (or all players if iPad=-1). Message Access:
Source: Minecraft.Client/Gui.h:52

GuiMessage Structure

Source: Minecraft.Client/GuiMessage.h:4 Messages automatically fade out over time based on their tick count.

Overlay Messages

Setting Overlay Text:
Displays a large centered message (used for jukebox “Now Playing” text). Getting Overlay State:
Source: Minecraft.Client/Gui.h:54

HUD Elements

The Gui class renders various HUD components: Hotbar - Item quick-select bar
  • 9 slots for quick access
  • Selected slot highlighting
  • Item icons and counts
Health Bar - Player health display
  • Heart icons
  • Damage flash animation
  • Regeneration effect
Hunger Bar - Food level display
  • Food icons (drumsticks)
  • Saturation overlay
Armor Bar - Armor protection display
  • Armor icons
  • Durability indication
Experience Bar - XP progress display
  • Progress bar
  • Level number
Vignette - Screen darkening effect
  • Damage indication
  • Low health warning
  • Portal overlay
Crosshair - Center-screen targeting reticle Debug Overlay - F3 debug information
  • FPS counter
  • Position/rotation
  • Chunk information
  • Memory usage

Specialized Rendering

renderSlot() - Renders a single inventory slot:
renderPumpkin() - Renders pumpkin head overlay:
renderVignette() - Renders screen vignette effect:
Source: Minecraft.Client/Gui.h:44

Debug Graphs

For performance monitoring:
Source: Minecraft.Client/Gui.h:66

Update Loop

Called every game tick to:
  • Update message timers
  • Fade out old messages
  • Animate HUD elements
  • Update overlay message timer

GuiParticles System

The GuiParticles class manages particle effects for UI elements, primarily used in achievement notifications.

GuiParticles Class

Source: Minecraft.Client/GuiParticles.h:8

GuiParticle

Individual particle in the UI:
Source: Minecraft.Client/GuiParticle.h:5

Using Particles

Particles automatically:
  • Apply velocity and friction
  • Fade out over lifetime
  • Remove themselves when expired
  • Interpolate position and color for smooth rendering

Achievement Popup System

While not in a dedicated class, achievement notifications use the GUI system: Components:
  • Toast-style popup in corner
  • Achievement icon and title
  • Slide-in animation
  • GuiParticles for celebratory effect
  • Auto-dismiss timer
Implementation: Typically handled through the HUD rendering system with special overlay logic.

Item Rendering

The ItemRenderer class handles rendering items in GUI contexts:
Used for:
  • Hotbar item icons
  • Inventory slot items
  • Achievement icons
  • Item tooltips

Color Format

Colors in the GUI system use 32-bit ARGB format:

Best Practices

Creating Custom GUI Components

  1. Extend GuiComponent for rendering utilities
  2. Use blit() for texture-based rendering
  3. Use fill() for solid color rectangles
  4. Cache Font references for text rendering
  5. Handle visibility with visible flags
  6. Support scaling using currentGuiScaleFactor

Button Usage

  1. Use unique IDs for each button
  2. Set active=false to disable buttons
  3. Set visible=false to hide buttons
  4. Position relative to screen width/height
  5. Standard spacing: 24 pixels between buttons vertically

HUD Rendering

  1. Respect safe zones for console rendering
  2. Scale appropriately for split-screen
  3. Use blitOffset for layered rendering
  4. Interpolate animations using alpha parameter
  5. Optimize rendering - avoid overdraw