Wsamiaw docs / Themes

Theming

Three theme systems share one ClickGUI Cloud catalog: full JSON packs for ClickGUI and HUD, Breeze-style INI packs that map onto ThemeDto / ClickTheme, and a separate sky JSON format documented on its own page.

Overview of the three theme systems

Wsamiaw does not use a single theme file format. ClickGUI panels, HUD plates, notifications, TargetHUD, friend/target colors, and the sky renderer each read from a different store. Knowing which system you are editing keeps local files, cloud uploads, and scripts from fighting each other.

1. ClickGUI / HUD JSON themes

Native packs live as *.json under config/Wsamiaw/themes/. The active pack id is remembered in config/Wsamiaw/theme-state.json as {"activeTheme":"sage"}. On boot the client seeds built-ins into that folder, loads the remembered name (or falls back to sage), and applies every token through ThemeManager: ClickGUI paints from clickGui, HUD module properties are bridged from hud, notifications and TargetHUD read their own objects, and friend / target / chat-prefix colors come from shared.

JSON themes are the full editor format. Theme Editor, local Apply, and host.theme.save all write this schema. Colors are stored as #AARRGGBB (or #RRGGBB on read, which forces opaque alpha).

2. Breeze / native INI themes

Cloud Themes uploads and many community packs still use a Breeze-style .ini body. The client parses that body with ThemeFile into a ThemeDto, then bridges the dto onto the live ClickTheme / Breeze store so panels, headers, accents, switches, array backgrounds, and optional HUD layout overrides update together. INI is a compact subset: it covers accent layers, panel background images, and optional HUD / layout knobs, but it does not expose every JSON token (notification severity colors, TargetHUD health stops, open-animation speed, and similar stay JSON-only).

When you upload from Cloud → Themes, the payload is the INI text. When you apply a cloud theme, the same parser rebuilds the dto and pushes it into the active ClickGUI look.

3. Sky themes

Custom skies are a separate JSON schema and command surface. They do not live under themes/ and they do not change ClickGUI or HUD colors. See the short pointer below and the dedicated page for the full property list.

SystemFilesWhat it stylesEntry point
JSON packs config/Wsamiaw/themes/*.json + theme-state.json ClickGUI, HUD color modes, notifications, TargetHUD, shared friend/target/chat colors Cloud → Themes (local JSON), Theme Editor, host.theme.set
INI packs Cloud catalog bodies; optional local .ini beside themes ThemeDto / ClickTheme layers, optional HUD plate alphas and layout anchors Cloud → Themes → Upload / Apply
Sky themes CustomSky JSON under the sky store Skybox gradients, sun/moon, stars, fog — not UI chrome /sky-theming and .sky commands

Using themes in-game

  1. Open ClickGUI (default bind RSHIFT).
  2. Open the Cloud tab, then Themes. Local packs from config/Wsamiaw/themes/ appear alongside the cloud catalog.
  3. Apply a local JSON theme, or download a cloud INI theme and press Apply. JSON Apply updates theme-state.json; INI Apply rebuilds the live ThemeDto / ClickTheme bridge.
  4. On ClickGUI accent, keep Theme mode so panels follow the pack. A fixed color locks the accent until you switch back.
  5. On the HUD module, set color to THEME so ArrayList text, bars, and pills track the pack.
  6. Optional: open Theme Editor to tweak every JSON token live, then save under a new name into themes/.

Built-ins are rewritten on each boot into the themes folder with builtIn: true. You can duplicate a built-in under a new filename to customize it; overwriting a built-in name from scripts requires an explicit overwrite path and is blocked by the normal host.theme.save call.

Sky themes

Sky packs are documented on /sky-theming. That page covers the CustomSky JSON schema, every property with type and range, the .sky commands, and cloud push. This Themes page only styles ClickGUI, HUD, and related plates.

Full JSON theme schema

A theme file is one JSON object. Unknown keys are ignored on read. Missing keys keep the fallback theme’s values (usually the built-in defaults for that object). Colors are strings: #RRGGBB (opaque) or #AARRGGBB (explicit alpha). Floats and ints are JSON numbers; booleans are JSON booleans.

Root

KeyTypeMeaning
formatintSchema version. Current writers emit 1. Older or future values still load when the object shape matches.
namestringDisplay and file id. On disk the filename is sanitized to lowercase [a-z0-9._-]; spaces become underscores.
authorstringFree-form credit shown in editors and catalogs. Empty string is fine.
builtInboolWhen true, Theme Manager treats the pack as a seeded built-in: normal saves refuse to overwrite it, and delete is blocked. User packs must keep this false.

clickGui

Every panel, row, chip, slider knob, and dim overlay in the native ClickGUI reads this object.

KeyTypeMeaning
bgcolorPanel body fill behind module rows.
headercolorCategory header strip behind the category title.
rowcolorDefault module / setting row plate.
rowHovercolorHover wash drawn over a row; usually a low-alpha accent or white tint.
innercolorNested inset surfaces (opened setting groups, inner cards).
chipcolorSmall pills, badges, and off-state switch tracks that are not full accent.
textcolorPrimary readable text on panels.
textDimcolorSecondary labels, suffixes, and muted descriptions.
knobcolorSlider thumb / toggle knob fill.
accentcolorPrimary brand accent: enabled modules, active toggles, focus rings when Theme mode is on.
accentAltcolorSecondary accent for gradients, hover emphasis, and dual-tone decorations.
dimOverlaycolorFullscreen or modal dim behind ClickGUI when the client darkens the world.
radiusfloatDefault corner radius for panels and large cards (pixels).
radiusSmfloatSmaller radius for chips and compact controls.
radiusXsfloatTightest radius for tiny badges and thin bars.
frameWidthfloatCategory panel width in GUI pixels.
headerHeightfloatHeight of the category header strip.
rowHeightfloatHeight of each module row.
settingHeightfloatHeight of expanded setting rows under a module.
gapfloatSpacing between panels / major layout gaps.
shadowboolWhether panels drop a soft shadow.
openAnimSpeedfloatHow fast panels animate open/closed. Higher is snappier; Theme Editor clamps the practical range around 4–30.

hud

On Apply, Theme Manager copies these fields into the HUD module properties so ArrayList and related plates match the pack without hand-tuning every slider.

KeyTypeMeaning
colorModestringHUD text color driver. One of RAINBOW, CHROMA, ASTOLFO, CUSTOM1, CUSTOM12, CUSTOM123. Aliases such as CUSTOM → CUSTOM1 and CUSTOM2 → CUSTOM12 are accepted on load.
custom1colorFirst solid / gradient stop. Used alone in CUSTOM1, as the start of the blend in CUSTOM12 / CUSTOM123.
custom2colorSecond stop for CUSTOM12 and CUSTOM123.
custom3colorThird stop for CUSTOM123.
colorSpeedfloatAnimation speed for rainbow / chroma / multi-stop cycling. Bridged into HUD in the 0.5–1.5 range.
saturationint0–100 saturation for animated color modes.
brightnessint0–100 brightness for animated color modes.
arraylistBackgroundint0–100 opacity of the ArrayList row background plate.
arraylistTextShadowboolDrop a text shadow under ArrayList labels.
arraylistBarboolDraw the accent side bar on ArrayList rows.
arraylistRoundedboolRound the ArrayList plates instead of sharp rectangles.
arraylistRoundRadiusint0–100 roundness amount when rounded plates are on.
watermarkBackgroundcolorFill behind the watermark plate.
watermarkUseAccentboolWhen true, watermark accents pull from the theme accent instead of a fixed white/gray.

notifications

KeyTypeMeaning
backgroundcolorToast plate fill.
textcolorPrimary notification title / body text.
textDimcolorSecondary line or timestamp text.
successcolorSeverity accent for success toasts.
warncolorSeverity accent for warnings.
errorcolorSeverity accent for errors.
infocolorSeverity accent for informational toasts (often matches ClickGUI accent).
accentBarWidthfloatWidth in pixels of the severity color bar on the toast edge.
radiusfloatCorner radius of notification plates.

targetHud

KeyTypeMeaning
backgroundcolorTargetHUD plate fill.
accentcolorAccent bar / highlight color on the plate.
textcolorPrimary name / HP text.
textDimcolorSecondary labels on the plate.
healthHighcolorHealth bar color when HP is healthy.
healthMidcolorHealth bar color in the mid band.
healthLowcolorHealth bar color when HP is critical.
outlinecolorOptional outline stroke color.
radiusfloatCorner radius of the TargetHUD card.
widthfloatCard width in GUI pixels.
heightfloatCard height in GUI pixels.
accentBarWidthfloatWidth of the side accent bar.
showOutlineboolWhen true, draw the outline stroke using outline.

shared

KeyTypeMeaning
friendcolorFriend Manager highlight color (ESP / nametags / lists that respect friends).
targetcolorTarget Manager highlight color for prioritized combat targets.
chatPrefixcolorClient chat prefix tint so messages match the active pack.

Built-in names and aliases

On init, Theme Manager seeds these packs into config/Wsamiaw/themes/:

NameLook
sageWarm graphite with a muted sage green accent — the neutral client default.
moonIce moonlight: silver-blue accent on near-black navy.
rosePink / magenta accent on deep rose charcoal.
emberWarm amber accent on charcoal brown.
krsLavender / purple accent on near-black navy (KRS-inspired ImGui dark look).

Legacy ids are rewritten when reading theme-state.json: default, midnight, ocean, and mono all migrate to moon. Prefer the modern names in new packs and scripts.

Full example JSON theme

Save as config/Wsamiaw/themes/harbor.json, then Apply from Cloud → Themes or call host.theme.set("harbor").

{
  "format": 1,
  "name": "harbor",
  "author": "docs",
  "builtIn": false,
  "clickGui": {
    "bg": "#F20E1218",
    "header": "#FF101820",
    "row": "#E6141C28",
    "rowHover": "#284FC3F7",
    "inner": "#E61A2434",
    "chip": "#FF243044",
    "text": "#FFE8EEF8",
    "textDim": "#FF8A9BB0",
    "knob": "#FFF4F7FC",
    "accent": "#FF4FC3F7",
    "accentAlt": "#FF81C784",
    "dimOverlay": "#66000000",
    "radius": 9.0,
    "radiusSm": 6.0,
    "radiusXs": 4.0,
    "frameWidth": 132.0,
    "headerHeight": 24.0,
    "rowHeight": 19.0,
    "settingHeight": 16.0,
    "gap": 10.0,
    "shadow": true,
    "openAnimSpeed": 13.0
  },
  "hud": {
    "colorMode": "CUSTOM12",
    "custom1": "#FF4FC3F7",
    "custom2": "#FF81C784",
    "custom3": "#FFE8EEF8",
    "colorSpeed": 1.0,
    "saturation": 55,
    "brightness": 100,
    "arraylistBackground": 90,
    "arraylistTextShadow": true,
    "arraylistBar": true,
    "arraylistRounded": true,
    "arraylistRoundRadius": 55,
    "watermarkBackground": "#80000000",
    "watermarkUseAccent": true
  },
  "notifications": {
    "background": "#E6121217",
    "text": "#FFEEEEF4",
    "textDim": "#FFBBBBBB",
    "success": "#FF2ECC71",
    "warn": "#FFFDD235",
    "error": "#FFE74C3C",
    "info": "#FF4FC3F7",
    "accentBarWidth": 3.0,
    "radius": 6.0
  },
  "targetHud": {
    "background": "#E6121217",
    "accent": "#FF4FC3F7",
    "text": "#FFEEEEF4",
    "textDim": "#FF9494A0",
    "healthHigh": "#FF81C784",
    "healthMid": "#FFFFD54F",
    "healthLow": "#FFFF6B6B",
    "outline": "#33FFFFFF",
    "radius": 6.0,
    "width": 140.0,
    "height": 42.0,
    "accentBarWidth": 3.0,
    "showOutline": false
  },
  "shared": {
    "friend": "#FF55FF55",
    "target": "#FFFF5555",
    "chatPrefix": "#FF4FC3F7"
  }
}

Breeze INI reference

INI themes are plain text. A [default] section is required or the file is rejected. Lines that are empty, or that start with # or ;, are comments. Section and key names are case-insensitive. Unknown sections and keys are ignored so third-party packs load without crashing. On Apply, values map into ThemeDto colors / metrics / hud / layout and then into the live ClickTheme bridge.

Color formats and references

A color value may be written in any of these literal forms:

FormExampleNotes
r,g,b255,120,200Opaque RGB, channels 0–255.
r,g,b,a14,16,22,242RGB plus alpha 0–255.
#rrggbb#ff78c8Hex RGB; treated as fully opaque.
[r,g,b] / [r,g,b,a][255,120,200]Bracket form emitted by ThemeFile.serialize when the client exports a theme.

Values may also be references instead of literals. A reference points at another key and can chain modifiers:

text-secondary = default.text-primary::darker;1
layer-one = default.layer-zero::brighter;2
accent-soft = default.accent::alpha;180

Reference grammar: section.key or bare key (searches [default] first, then other sections), followed by zero or more ::modifier or ::modifier;arg segments. Supported modifiers:

ModifierEffect
brighter / brighter;nMultiply RGB by 1 + 0.25 * n (default n = 1).
darker / darker;nMultiply RGB by 1 - 0.25 * n.
alpha;nSet alpha channel to n (0–255).
mul;fMultiply RGB (or a numeric value) by factor f.
div;fDivide by factor f (no-op if f is 0).

Modifier chains resolve up to 8 levels deep. Boolean keys accept true/false, 1/0, on/off, yes/no. Numbers are plain floats or ints. Strings that must stay exact (URLs) should be quoted with double quotes.

[default]

Required. Defines the core ClickGUI palette and corner radius.

KeyMaps toMeaning
accentThemeDto accent / switch-on fallbackPrimary accent color for enabled states and Theme-mode ClickGUI accent.
text-primarytextMain readable text on panels.
text-secondarytextDimMuted secondary text.
layer-zerobgDeepest panel background (often translucent).
layer-oneheaderBgHeader / elevated layer.
layer-twoswitchOffOff-track / tertiary surface.
corner-radiusmetrics.radiusPanel radius, clamped to 0–16.
namedisplay name on exportOptional; serializers write it for round-trips.
border-thickness(export hint)Written by serializers; not required for Apply.
background-imgsame as panelOptional fallback if [panel] is omitted; must be an https:// URL.

Accent hover is derived automatically as a brightened accent when the INI does not supply a separate hover key.

[module]

KeyMaps toMeaning
enabledswitchOnColor for enabled module indicators / on-state switches. Falls back to accent when omitted.

[panel]

KeyMaps toMeaning
background-imgbackgroundImageUrl + mode BOTHHTTPS image URL drawn behind ClickGUI panels. Non-HTTPS values are ignored. Quote the URL.

[hud]

All keys are optional. A missing key leaves the user’s current HUD module setting alone.

KeyTypeMeaning
array-text-scalefloatArrayList text scale multiplier.
array-accent-barboolShow the ArrayList accent side bar.
array-shadowboolArrayList text shadow on/off.
array-bg-alphafloat0–1 multiplier on the ArrayList plate alpha.
pill-alphafloat0–1 alpha for FPS / Island / Target style pills.

[layout]

All keys are optional. Anchors use the client’s HUD placement convention: 0 = left/top, 1 = right/bottom for the matching axis.

KeyTypeMeaning
array-pos-xintArrayList horizontal anchor (0 left, 1 right).
array-pos-yintArrayList vertical anchor (0 top, 1 bottom).
array-off-xintArrayList pixel offset from the anchor on X.
array-off-yintArrayList pixel offset from the anchor on Y.
array-scalefloatOverall ArrayList scale.
fps-pos-xintFPS pill horizontal anchor.
fps-pos-yintFPS pill vertical anchor.
fps-off-xintFPS pill X offset.
fps-off-yintFPS pill Y offset.
island-top-offsetfloatDynamic Island distance from the top edge.
island-scalefloatDynamic Island scale.

Full example INI theme

Copy into my-theme.ini, edit colors, then upload from Cloud → Themes. Every [hud] and [layout] key is optional; omit a key to leave the player’s current HUD placement untouched.

# Harbor INI — maps onto ThemeDto / ClickTheme
[default]
name = harbor
accent = [79,195,247]
text-primary = [232,238,248]
text-secondary = default.text-primary::darker;1
layer-zero = [14,18,24,242]
layer-one = [16,24,32]
layer-two = [36,48,64]
corner-radius = 9
background-img = "https://example.com/harbor-panel.png"

[module]
enabled = default.accent

[panel]
background-img = "https://example.com/harbor-panel.png"

[hud]
array-text-scale = 1.35
array-accent-bar = true
array-shadow = true
array-bg-alpha = 0.65
pill-alpha = 0.8

[layout]
array-pos-x = 1
array-pos-y = 0
array-off-x = 6
array-off-y = 6
array-scale = 1.0
fps-pos-x = 2
fps-pos-y = 0
fps-off-x = -10
fps-off-y = 8
island-top-offset = 8
island-scale = 1.0

Scripting bridge: host.theme and host.ui.claim

Scripts reach the active JSON theme through host.theme (ThemeApi). Drawing custom HUD or ClickGUI chrome goes through host.ui; claim a surface first so the built-in plate hides and your paint does not stack on top of it. Full draw helpers (rounded, text, frost, hit testing, and the rest) live on the Scripting page.

ThemeApi methods

ThemeApi exposes a ClickGUI color subset plus load / list / save helpers. It does not expose notifications, TargetHUD, or every JSON metric — read those from files or Theme Editor when you need the full bag.

MethodReturnsMeaning
name()stringSanitized id of the active theme, or empty if unset.
list()list of stringsEvery *.json basename in config/Wsamiaw/themes/, sorted.
set(name)boolLoad and activate that pack. Updates live UI and theme-state.json. Returns false when the file is missing or the name is blank.
accent()int ARGBActive clickGui.accent.
accentAlt()int ARGBActive clickGui.accentAlt.
bg()int ARGBActive clickGui.bg.
header()int ARGBActive clickGui.header.
text()int ARGBActive clickGui.text.
textDim()int ARGBActive clickGui.textDim.
row()int ARGBActive clickGui.row.
radius()floatActive clickGui.radius.
setAccent(argb)voidMutate live accent and applyLive without renaming the pack.
setBg(argb)voidMutate live background and applyLive.
save(name)boolWrite the current theme copy to themes/<name>.json and activate it. Fails on blank names and refuses to overwrite built-ins.
public void onEnable() {
    host.theme.set("sage");
    host.log("accent=" + Integer.toHexString(host.theme.accent()));
}

public void onRender2D(event) {
    host.ui.rounded(8, 8, 120, 18, host.theme.radius(), host.theme.bg());
    host.ui.text("hi", 14, 12, 9, host.theme.accent());
}

UiSurfaces claim ids

host.ui.claim(surface) registers the script as the sole owner of that surface. The matching built-in drawer stays hidden until host.ui.release(surface) or the script disables. Claiming the parent hud hides every hud.* plate. host.ui.owns(surface) is true when this script holds the surface, including when it holds parent hud and you ask about a hud.* child.

Claim idBuilt-in that yields
clickguiNative ClickGUI category panels and module rows.
hudEvery HUD plate listed below (parent claim).
hud.arraylistArrayList module list.
hud.targetTargetHUD.
hud.scoreboardCustom scoreboard plate.
hud.notificationsNotification toasts.
hud.islandDynamic Island.
hud.radarRadar.
hud.musicMusic / Spotify HUD.
hud.staffStaff list panel.
hud.potionsPotion effects list.
hud.infoInfo pills.
hud.watermarkWatermark.
hud.newNewHUD composite plate.
public void onEnable() {
    host.ui.claim("hud.arraylist");
}

public void onRender2D(event) {
    if (!host.ui.owns("hud.arraylist")) return;
    host.ui.rounded(8, 8, 140, 16, 4, host.theme.bg());
    host.ui.text("custom array", 14, 11, 9, host.theme.text());
}

public void onDisable() {
    host.ui.release("hud.arraylist");
}

ThemeApi only returns the ClickGUI subset listed above (accent, accentAlt, bg, header, text, textDim, row, radius) plus set / list / save / setAccent / setBg. For the full host.ui draw API, see /scripting.

Uploading, local paths, and cloud

Local JSON packs

  1. Create or edit a file under .minecraft/config/Wsamiaw/themes/<name>.json using the schema above.
  2. Restart is not required for a new file once Themes refreshes the folder list; Apply loads it immediately.
  3. Active id is stored in .minecraft/config/Wsamiaw/theme-state.json as activeTheme.
  4. Built-ins (sage, moon, rose, ember, krs) are re-seeded on boot. Customize by saving under a new name.

Cloud INI upload

  1. Sign in — upload requires an account.
  2. Open ClickGUI → Cloud → Themes.
  3. Press Upload and choose your .ini file (or paste/export from the current ThemeDto).
  4. The catalog stores the INI body. Download + Apply runs ThemeFile.parse and pushes the dto into ClickTheme.
  5. Local .ini files can also sit beside JSON packs for hand Apply workflows; JSON remains the native on-disk format for Theme Manager and host.theme.

Which path to pick

GoalUse
Full control of ClickGUI + HUD + notifications + TargetHUDJSON under themes/
Share a compact accent pack on the cloud catalogINI upload
Script-driven live accent / custom painted HUDhost.theme + host.ui.claim
Skybox onlySky theming