Wsamiaw docs / Sky themes

Sky theming

A sky theme is one JSON file that sets every CustomSky property at once — dome, stars, aurora, sun and moon, milky way and meteors.

Overview

CustomSky draws its own 3D dome, star field and effects instead of the vanilla sky. A theme freezes a set of its property values under one name, so you can swap a whole look without moving a single slider. Applying a theme writes into the live module — your config keeps saving exactly as before, and nothing about the theme is stored inside it.

Theme files

A theme lives in config/Wsamiaw/sky-themes/<name>.json, inside the game directory — .minecraft on a vanilla launcher, the instance folder on a modded launcher. The file name (without .json) is the name you pass to .sky load. Built-in themes ship with the client and always sit at the top of the list.

Drop a file in, run .sky reload, and it appears — no restart needed.

File format

One object with metadata and a values map. Property names are the kebab-case identifiers the client uses internally, not the labels printed in the ClickGUI.

{
  "name": "Aurora Night",
  "author": "deniz",
  "description": "Green curtains over a navy dome",
  "version": 1,
  "values": {
    "dome-alpha": 1.0,
    "zenith-color": "#081A2E",
    "horizon-color": "#14435E",
    "accent-color": "#66F2CE",
    "star-count": 220,
    "aurora-bands": 3
  }
}

name — the label in the theme picker and in .sky list.
author — free text, shown next to the theme.
description — one line, shown next to the theme.
version — format version; 1 is the current one.
values — property name to value. This is the only required part.

Colors are six-digit #RRGGBB strings and become ARGB with alpha 0xFF. Numbers outside the property range are clamped, values a property rejects are skipped, and unknown keys are ignored — the command output lists both.

A theme can set any subset of properties; anything you leave out keeps its current value.

Properties

Generated from the client's own schema, so the ranges and defaults below match the build you are running.

Property	Type	Range	Default	Group

Colour keys only drive the dome when preset is Custom. A theme that sets its own colours should include "preset": "Custom"; the built-in themes keep their preset palettes.

Built-in themes

These ship with the client, so .sky load works for them without any file on disk.

Built-in names appear here once the schema file is loaded.

Commands

Everything runs from the in-game chat with the usual dot prefix.

Command	What it does
`.sky list`	Lists built-in and file themes and marks the active one.
`.sky load <name>`	Applies a theme to CustomSky.
`.sky save <name>`	Captures the current CustomSky values into sky-themes/<name>.json.
`.sky delete <name>`	Deletes a theme file. Built-in themes cannot be deleted.
`.sky reload`	Re-reads the sky-themes folder without restarting the game.
`.sky export`	Prints the current values as theme JSON you can paste into a file.

Names are file-safe: letters, digits, dash and underscore. Saving under an existing name overwrites that file.

Examples

Three complete files. Save each as sky-themes/<name>.json, or paste the values into .sky save output.

Aurora Night

Navy dome with green curtains — the reference theme.

{
  "name": "Aurora Night",
  "author": "deniz",
  "description": "Green curtains over a navy dome",
  "version": 1,
  "values": {
    "dome-alpha": 1.0,
    "zenith-color": "#081A2E",
    "horizon-color": "#14435E",
    "accent-color": "#66F2CE",
    "star-count": 220,
    "star-size": 1.2,
    "aurora": true,
    "aurora-bands": 3,
    "aurora-speed": 0.6,
    "sun-moon": false,
    "milky-way": true,
    "shooting-stars": true,
    "horizon-ring": true,
    "overworld-only": true
  }
}

Deep Space

Near-black sky, dense stars, wide milky way and no aurora.

{
  "name": "Deep Space",
  "author": "wsamiaw",
  "description": "Near-black dome, dense stars, wide milky way",
  "version": 1,
  "values": {
    "dome-alpha": 0.96,
    "zenith-color": "#02040A",
    "horizon-color": "#0A1224",
    "accent-color": "#7FB2FF",
    "star-count": 900,
    "star-size": 1.0,
    "aurora": false,
    "sun-moon": false,
    "milky-way": true,
    "shooting-stars": true,
    "horizon-ring": false,
    "overworld-only": true
  }
}

Desert Noon

Warm horizon, pale zenith, small sun and a thin horizon ring.

{
  "name": "Desert Noon",
  "author": "wsamiaw",
  "description": "Warm haze over a pale blue dome",
  "version": 1,
  "values": {
    "dome-alpha": 1.0,
    "zenith-color": "#4F86C6",
    "horizon-color": "#E8C48A",
    "accent-color": "#FFE2A8",
    "star-count": 0,
    "aurora": false,
    "sun-moon": true,
    "milky-way": false,
    "shooting-stars": false,
    "horizon-ring": true,
    "overworld-only": true
  }
}

Cloud push

A sky theme can be sent from the site to a running client. The client polls for pushes, downloads the JSON and writes it into the theme folder.

The site queues a push with type skytheme and the theme name.
The client polls the push endpoint every 20 seconds while it is running.
It downloads the theme JSON for that name.
It writes config/Wsamiaw/sky-themes/<name>.json.
The push is acknowledged, and you apply it with .sky load <name>.

Endpoint	Role
`POST /client/push`	Queues a theme for a client; body carries type skytheme and the name.
`GET /client/pushes`	What the client polls to find pending pushes.
`GET /user/cloud-configs/<name>?type=skytheme`	Returns the theme JSON that gets written to disk.
`POST /client/pushes/ack`	Marks a push as delivered so it is not repeated.

A push only writes the file. It never switches the active theme on its own.

FAQ

Where do I put a theme so the client sees it?

In config/Wsamiaw/sky-themes/ next to your config files. Run .sky reload afterwards; the list refreshes without a restart.

Why did .sky load skip some values?

The value was outside the property range, had the wrong shape, or the key does not exist. The command output lists what was skipped or ignored.

Does a theme change my saved config?

No. The theme writes into the live CustomSky properties, and your config keeps saving those properties the way it always does.

Can I edit a built-in theme?

Load it, change what you want in the ClickGUI, then .sky save under a new name. Built-in files cannot be overwritten or deleted.

Do sky themes work on servers?

Yes, they are client-side only. Nobody else sees your sky, and server weather or time still applies on top of it.

Do I need CustomSky enabled?

Yes. A theme only sets CustomSky properties, so the module has to be on for the dome and its effects to render.