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.
| System | Files | What it styles | Entry 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
- Open ClickGUI (default bind RSHIFT).
- Open the Cloud tab, then Themes. Local packs from config/Wsamiaw/themes/ appear alongside the cloud catalog.
- 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.
- On ClickGUI accent, keep Theme mode so panels follow the pack. A fixed color locks the accent until you switch back.
- On the HUD module, set color to THEME so ArrayList text, bars, and pills track the pack.
- 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
| Key | Type | Meaning |
|---|---|---|
format | int | Schema version. Current writers emit 1. Older or future values still load when the object shape matches. |
name | string | Display and file id. On disk the filename is sanitized to lowercase [a-z0-9._-]; spaces become underscores. |
author | string | Free-form credit shown in editors and catalogs. Empty string is fine. |
builtIn | bool | When 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.
| Key | Type | Meaning |
|---|---|---|
bg | color | Panel body fill behind module rows. |
header | color | Category header strip behind the category title. |
row | color | Default module / setting row plate. |
rowHover | color | Hover wash drawn over a row; usually a low-alpha accent or white tint. |
inner | color | Nested inset surfaces (opened setting groups, inner cards). |
chip | color | Small pills, badges, and off-state switch tracks that are not full accent. |
text | color | Primary readable text on panels. |
textDim | color | Secondary labels, suffixes, and muted descriptions. |
knob | color | Slider thumb / toggle knob fill. |
accent | color | Primary brand accent: enabled modules, active toggles, focus rings when Theme mode is on. |
accentAlt | color | Secondary accent for gradients, hover emphasis, and dual-tone decorations. |
dimOverlay | color | Fullscreen or modal dim behind ClickGUI when the client darkens the world. |
radius | float | Default corner radius for panels and large cards (pixels). |
radiusSm | float | Smaller radius for chips and compact controls. |
radiusXs | float | Tightest radius for tiny badges and thin bars. |
frameWidth | float | Category panel width in GUI pixels. |
headerHeight | float | Height of the category header strip. |
rowHeight | float | Height of each module row. |
settingHeight | float | Height of expanded setting rows under a module. |
gap | float | Spacing between panels / major layout gaps. |
shadow | bool | Whether panels drop a soft shadow. |
openAnimSpeed | float | How 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.
| Key | Type | Meaning |
|---|---|---|
colorMode | string | HUD text color driver. One of RAINBOW, CHROMA, ASTOLFO, CUSTOM1, CUSTOM12, CUSTOM123. Aliases such as CUSTOM → CUSTOM1 and CUSTOM2 → CUSTOM12 are accepted on load. |
custom1 | color | First solid / gradient stop. Used alone in CUSTOM1, as the start of the blend in CUSTOM12 / CUSTOM123. |
custom2 | color | Second stop for CUSTOM12 and CUSTOM123. |
custom3 | color | Third stop for CUSTOM123. |
colorSpeed | float | Animation speed for rainbow / chroma / multi-stop cycling. Bridged into HUD in the 0.5–1.5 range. |
saturation | int | 0–100 saturation for animated color modes. |
brightness | int | 0–100 brightness for animated color modes. |
arraylistBackground | int | 0–100 opacity of the ArrayList row background plate. |
arraylistTextShadow | bool | Drop a text shadow under ArrayList labels. |
arraylistBar | bool | Draw the accent side bar on ArrayList rows. |
arraylistRounded | bool | Round the ArrayList plates instead of sharp rectangles. |
arraylistRoundRadius | int | 0–100 roundness amount when rounded plates are on. |
watermarkBackground | color | Fill behind the watermark plate. |
watermarkUseAccent | bool | When true, watermark accents pull from the theme accent instead of a fixed white/gray. |
notifications
| Key | Type | Meaning |
|---|---|---|
background | color | Toast plate fill. |
text | color | Primary notification title / body text. |
textDim | color | Secondary line or timestamp text. |
success | color | Severity accent for success toasts. |
warn | color | Severity accent for warnings. |
error | color | Severity accent for errors. |
info | color | Severity accent for informational toasts (often matches ClickGUI accent). |
accentBarWidth | float | Width in pixels of the severity color bar on the toast edge. |
radius | float | Corner radius of notification plates. |
targetHud
| Key | Type | Meaning |
|---|---|---|
background | color | TargetHUD plate fill. |
accent | color | Accent bar / highlight color on the plate. |
text | color | Primary name / HP text. |
textDim | color | Secondary labels on the plate. |
healthHigh | color | Health bar color when HP is healthy. |
healthMid | color | Health bar color in the mid band. |
healthLow | color | Health bar color when HP is critical. |
outline | color | Optional outline stroke color. |
radius | float | Corner radius of the TargetHUD card. |
width | float | Card width in GUI pixels. |
height | float | Card height in GUI pixels. |
accentBarWidth | float | Width of the side accent bar. |
showOutline | bool | When true, draw the outline stroke using outline. |
shared
| Key | Type | Meaning |
|---|---|---|
friend | color | Friend Manager highlight color (ESP / nametags / lists that respect friends). |
target | color | Target Manager highlight color for prioritized combat targets. |
chatPrefix | color | Client 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/:
| Name | Look |
|---|---|
sage | Warm graphite with a muted sage green accent — the neutral client default. |
moon | Ice moonlight: silver-blue accent on near-black navy. |
rose | Pink / magenta accent on deep rose charcoal. |
ember | Warm amber accent on charcoal brown. |
krs | Lavender / 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:
| Form | Example | Notes |
|---|---|---|
r,g,b | 255,120,200 | Opaque RGB, channels 0–255. |
r,g,b,a | 14,16,22,242 | RGB plus alpha 0–255. |
#rrggbb | #ff78c8 | Hex 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:
| Modifier | Effect |
|---|---|
brighter / brighter;n | Multiply RGB by 1 + 0.25 * n (default n = 1). |
darker / darker;n | Multiply RGB by 1 - 0.25 * n. |
alpha;n | Set alpha channel to n (0–255). |
mul;f | Multiply RGB (or a numeric value) by factor f. |
div;f | Divide 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.
| Key | Maps to | Meaning |
|---|---|---|
accent | ThemeDto accent / switch-on fallback | Primary accent color for enabled states and Theme-mode ClickGUI accent. |
text-primary | text | Main readable text on panels. |
text-secondary | textDim | Muted secondary text. |
layer-zero | bg | Deepest panel background (often translucent). |
layer-one | headerBg | Header / elevated layer. |
layer-two | switchOff | Off-track / tertiary surface. |
corner-radius | metrics.radius | Panel radius, clamped to 0–16. |
name | display name on export | Optional; serializers write it for round-trips. |
border-thickness | (export hint) | Written by serializers; not required for Apply. |
background-img | same as panel | Optional 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]
| Key | Maps to | Meaning |
|---|---|---|
enabled | switchOn | Color for enabled module indicators / on-state switches. Falls back to accent when omitted. |
[panel]
| Key | Maps to | Meaning |
|---|---|---|
background-img | backgroundImageUrl + mode BOTH | HTTPS 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.
| Key | Type | Meaning |
|---|---|---|
array-text-scale | float | ArrayList text scale multiplier. |
array-accent-bar | bool | Show the ArrayList accent side bar. |
array-shadow | bool | ArrayList text shadow on/off. |
array-bg-alpha | float | 0–1 multiplier on the ArrayList plate alpha. |
pill-alpha | float | 0–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.
| Key | Type | Meaning |
|---|---|---|
array-pos-x | int | ArrayList horizontal anchor (0 left, 1 right). |
array-pos-y | int | ArrayList vertical anchor (0 top, 1 bottom). |
array-off-x | int | ArrayList pixel offset from the anchor on X. |
array-off-y | int | ArrayList pixel offset from the anchor on Y. |
array-scale | float | Overall ArrayList scale. |
fps-pos-x | int | FPS pill horizontal anchor. |
fps-pos-y | int | FPS pill vertical anchor. |
fps-off-x | int | FPS pill X offset. |
fps-off-y | int | FPS pill Y offset. |
island-top-offset | float | Dynamic Island distance from the top edge. |
island-scale | float | Dynamic 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.
| Method | Returns | Meaning |
|---|---|---|
name() | string | Sanitized id of the active theme, or empty if unset. |
list() | list of strings | Every *.json basename in config/Wsamiaw/themes/, sorted. |
set(name) | bool | Load 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 ARGB | Active clickGui.accent. |
accentAlt() | int ARGB | Active clickGui.accentAlt. |
bg() | int ARGB | Active clickGui.bg. |
header() | int ARGB | Active clickGui.header. |
text() | int ARGB | Active clickGui.text. |
textDim() | int ARGB | Active clickGui.textDim. |
row() | int ARGB | Active clickGui.row. |
radius() | float | Active clickGui.radius. |
setAccent(argb) | void | Mutate live accent and applyLive without renaming the pack. |
setBg(argb) | void | Mutate live background and applyLive. |
save(name) | bool | Write 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 id | Built-in that yields |
|---|---|
clickgui | Native ClickGUI category panels and module rows. |
hud | Every HUD plate listed below (parent claim). |
hud.arraylist | ArrayList module list. |
hud.target | TargetHUD. |
hud.scoreboard | Custom scoreboard plate. |
hud.notifications | Notification toasts. |
hud.island | Dynamic Island. |
hud.radar | Radar. |
hud.music | Music / Spotify HUD. |
hud.staff | Staff list panel. |
hud.potions | Potion effects list. |
hud.info | Info pills. |
hud.watermark | Watermark. |
hud.new | NewHUD 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
- Create or edit a file under
.minecraft/config/Wsamiaw/themes/<name>.jsonusing the schema above. - Restart is not required for a new file once Themes refreshes the folder list; Apply loads it immediately.
- Active id is stored in
.minecraft/config/Wsamiaw/theme-state.jsonasactiveTheme. - Built-ins (
sage,moon,rose,ember,krs) are re-seeded on boot. Customize by saving under a new name.
Cloud INI upload
- Sign in — upload requires an account.
- Open ClickGUI → Cloud → Themes.
- Press Upload and choose your
.inifile (or paste/export from the current ThemeDto). - The catalog stores the INI body. Download + Apply runs
ThemeFile.parseand pushes the dto into ClickTheme. - Local
.inifiles can also sit beside JSON packs for hand Apply workflows; JSON remains the native on-disk format for Theme Manager andhost.theme.
Which path to pick
| Goal | Use |
|---|---|
| Full control of ClickGUI + HUD + notifications + TargetHUD | JSON under themes/ |
| Share a compact accent pack on the cloud catalog | INI upload |
| Script-driven live accent / custom painted HUD | host.theme + host.ui.claim |
| Skybox only | Sky theming |