JonKazama-Hellion
1987d745d8
Every claim in the user-facing docs, checked against what the plugin actually does after A2 to A5. The two GDPR sections in PRIVACY.md describe features that only exist again as of this cycle, so they now name the screens they live on and say what the cleanup does with a channel this build does not recognise. The export sentence promised a date range; the form offers an age in days. PRIVACY.md also named "Show emotes" in Settings as the way to stop the one outbound call the plugin makes. That switch has had no control since May, and a documented opt-out that only exists in the JSON is not an opt-out, so the toggle is back in the chat tab. Both its strings were already translated. Dead paths: the README source tree still listed a file deleted in May, docs/IPC.md cited a window that no longer exists, the first-run wizard pointed at the same removed file, and the theme authoring guide sent readers to a Themes tab that is called Appearance. The changelog lost two double blank lines that were failing markdownlint and holding preflight red. Preflight is green again. Historical documents keep their old paths on purpose: the changelog and the AI disclosure describe what was true when they were written.
209 lines
11 KiB
Markdown
209 lines
11 KiB
Markdown
<p align="center">
|
||
<img src="images/hellion-forge.png" alt="Hellion Forge" width="180" />
|
||
</p>
|
||
|
||
# Theme Authoring Guide
|
||
|
||
> Built by **Hellion Forge** — the plugin workshop arm of
|
||
> [Hellion Online Media](https://hellion-media.de). HellionChat ships with nine built-in themes;
|
||
> this guide walks you through writing your own.
|
||
|
||
## TL;DR
|
||
|
||
1. Open Settings → Appearance → **Open themes folder**
|
||
2. Copy `example-theme.json` to `<your-name>.json` in the same folder
|
||
3. Edit the file with any text editor
|
||
4. Reload the plugin (toggle off/on in `/xlplugins`)
|
||
5. Your theme appears in the Custom-Themes section in Settings → Appearance
|
||
|
||
That's the whole loop. The rest of this document is reference.
|
||
|
||
## File location
|
||
|
||
```txt
|
||
%APPDATA%\XIVLauncher\pluginConfigs\HellionChat\themes\
|
||
```
|
||
|
||
(or the equivalent path on Linux/macOS — Settings → Appearance → "Open themes folder" opens it
|
||
directly).
|
||
|
||
Each `*.json` file in this folder is loaded as one theme. The `example-theme.json` that HellionChat
|
||
seeds on first launch is your starting template.
|
||
|
||
## File format
|
||
|
||
Theme JSON has four blocks:
|
||
|
||
```json
|
||
{
|
||
"schemaVersion": 1,
|
||
"slug": "your-slug",
|
||
"name": "Your Theme Name",
|
||
"author": "You",
|
||
"description": "One-line description shown under the theme name.",
|
||
"colors": { ... 21 color slots ... },
|
||
"layout": { ... 9 layout values ... },
|
||
"chatChannels": { ... optional, channel-name → hex ... }
|
||
}
|
||
```
|
||
|
||
### Top-level fields
|
||
|
||
| Field | Type | Required | Notes |
|
||
| --------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
|
||
| `schemaVersion` | int | yes | Always `1` for HellionChat 1.1.0. The plugin warns and skips themes with a different number. |
|
||
| `slug` | string | yes | Lowercase, hyphenated. Must be unique across all themes (built-in slugs are reserved). |
|
||
| `name` | string | yes | Display name in the picker. |
|
||
| `author` | string | yes | Shown small under the theme name. |
|
||
| `description` | string | yes | One short sentence. |
|
||
| `colors` | object | yes | All 21 slots required (see below). |
|
||
| `layout` | object | yes | All 9 slots required (see below). |
|
||
| `chatChannels` | object | no | Optional channel-name → hex map (see below). |
|
||
|
||
### Color slots
|
||
|
||
All values are 6-digit `#RRGGBB` or 8-digit `#RRGGBBAA` hex strings. Six-digit values get an
|
||
implicit `FF` alpha.
|
||
|
||
| Slot | Role |
|
||
| ---------------------------- | ------------------------------------------------------------------------------- |
|
||
| `primary` | Brand color — used on buttons, sliders, check marks, highlighted separators. |
|
||
| `primaryDark` | Pressed-button stage. |
|
||
| `primaryLight` | Hovered-button / link-text stage. |
|
||
| `primaryGlow` | Glow / subtle accent (typically primary with ~60% alpha). |
|
||
| `accent` | Counter-accent — scrollbar grab on hover/active, resize grip, optional CTA. |
|
||
| `accentDark` / `accentLight` | Dark/light siblings of accent. |
|
||
| `identity` | Title-bar active color and active-tab color. Often equals `primaryDark`. |
|
||
| `windowBg` | Outermost window background. |
|
||
| `childBg` | Inner panel / popup background. |
|
||
| `frameBg` | Input fields, sliders, combos. |
|
||
| `surface` | Card surfaces, headers, selectables. |
|
||
| `surfaceHover` | Hovered card / header step. |
|
||
| `border` | Panel borders. Typically primary with ~40% alpha for a brand-tinted edge. |
|
||
| `textPrimary` | Body text. Soft off-white reads better than pure `#FFFFFF` on dark backgrounds. |
|
||
| `textMuted` | Captions, secondary lines. |
|
||
| `textDim` | Disabled / hint text, separators. |
|
||
| `statusSuccess` | Green-ish for success notifications. |
|
||
| `statusDanger` | Red for errors. |
|
||
| `statusWarning` | Amber for warnings. |
|
||
| `statusInfo` | Cyan-ish info. Often equals primary. |
|
||
|
||
### Layout slots
|
||
|
||
All values are floats in pixels. `BorderSize` is 0 or 1 (no thicker borders look right with ImGui's
|
||
edge anti-aliasing).
|
||
|
||
| Slot | Typical range | Notes |
|
||
| ------------------- | ------------- | ------------------------------------------------- |
|
||
| `windowRounding` | 0–8 | 0 = sharp upstream look; 4–6 = softer "app" feel. |
|
||
| `childRounding` | 0–6 | Usually 1 less than `windowRounding`. |
|
||
| `popupRounding` | 0–6 | Same as `childRounding`. |
|
||
| `frameRounding` | 0–4 | For inputs, sliders. |
|
||
| `grabRounding` | 0–4 | Slider grab dot. |
|
||
| `tabRounding` | 0–4 | Tab corners. |
|
||
| `scrollbarRounding` | 0–4 | Scrollbar grab. |
|
||
| `windowBorderSize` | 0 or 1 | 1 reads better in dark themes. |
|
||
| `frameBorderSize` | 0 or 1 | Usually matches windowBorderSize. |
|
||
|
||
### Optional `chatChannels`
|
||
|
||
If present, your theme proposes its own chat-channel colors. Property names are `ChatType` enum
|
||
values (case-insensitive). Unknown names are skipped silently — safe for forward-compat.
|
||
|
||
```json
|
||
"chatChannels": {
|
||
"Say": "#FFFFFF",
|
||
"Yell": "#FFE066",
|
||
"Shout": "#FFA040",
|
||
"TellIncoming": "#FF99CC",
|
||
"TellOutgoing": "#FF99CC",
|
||
"Party": "#80C0E8",
|
||
"FreeCompany": "#4DD9E8",
|
||
"NoviceNetwork": "#A8E060",
|
||
"Linkshell1": "#A8E060"
|
||
}
|
||
```
|
||
|
||
The user is asked **once per theme switch** whether to apply these colors — never auto-overwriting
|
||
existing picks. The banner shows up only if your suggested colors differ from the user's current
|
||
`Configuration.ChatColours`.
|
||
|
||
#### Channel-identity rule
|
||
|
||
**Don't break FFXIV channel identity.** Players have used these conventions for over a decade:
|
||
|
||
| Channel | Convention | Why |
|
||
| ------------- | ----------------- | ------------------------ |
|
||
| Say | white / off-white | Default-readable speech. |
|
||
| Yell | yellow | Urgent broadcast. |
|
||
| Shout | orange | Local urgent. |
|
||
| Tell | pink-magenta | Whisper, must stand out. |
|
||
| Party | light blue | Group ops. |
|
||
| FreeCompany | cyan-teal | Guild ops. |
|
||
| NoviceNetwork | lime-green | Mentor channel. |
|
||
|
||
A theme can tint these toward its brand family (e.g., a purple theme can shift Tell from `#FF99CC`
|
||
to `#E090FF`), but **don't** flip them (Tell suddenly green, Yell suddenly cyan). RP groups and
|
||
combat-spec setups depend on the visual hierarchy.
|
||
|
||
The eight colored built-in themes (Hellion Arctic, Hellion Spectrum, Event Horizon, Crystal
|
||
Nocturne, Mint Grove, Night Blue, Indigo Violet, Forge Merchantman) all follow this rule — read
|
||
their source for reference. Chat 2 Klassik intentionally ships without `chatChannels` so the user
|
||
keeps their existing picks.
|
||
|
||
## Theme families
|
||
|
||
Naming convention `<color>-<modifier>` is recommended for theme families. The first member of a
|
||
family is the lightest/brightest:
|
||
|
||
- `mint-grove` (current built-in, light mint)
|
||
- `forest-grove` (planned, dark emerald)
|
||
- `moss-grove` (planned, mid muted)
|
||
|
||
Code-wise families have no special handling — only the slug naming hints at the relationship. The
|
||
picker may group families later, but that's not required.
|
||
|
||
## Validation and errors
|
||
|
||
When HellionChat loads your theme:
|
||
|
||
- **Schema mismatch** (`schemaVersion != 1`): theme is skipped, warning written to `/xllog`.
|
||
- **Missing required field** (e.g., no `slug`): theme is skipped, warning written.
|
||
- **Invalid hex** (e.g., `#GGHHII`): theme is skipped, warning written.
|
||
- **Unknown channel name** in `chatChannels`: that one channel is skipped silently, the rest of the
|
||
theme loads normally.
|
||
|
||
Check `/xllog` after a plugin reload to see what loaded and what didn't.
|
||
|
||
## Testing your theme
|
||
|
||
1. Edit the JSON, save the file.
|
||
2. Reload the plugin: `/xlplugins` → toggle HellionChat off, then on.
|
||
3. Settings → Appearance → click your theme card.
|
||
4. Watch every plugin window (chat, settings, pop-out) and pick something to fix.
|
||
5. Tweak. Reload. Repeat.
|
||
|
||
Tip: the **Settings → Appearance** picker shows a mini-mockup per theme — your colors are visible before
|
||
you switch.
|
||
|
||
## Sharing themes
|
||
|
||
Themes are JSON, so sharing is just a file. Drop it into someone's
|
||
`pluginConfigs/HellionChat/themes/` folder and their plugin picks it up on next reload.
|
||
|
||
A community theme repository is on the Hellion Forge roadmap. Until then: share via Discord or any
|
||
pastebin.
|
||
|
||
## Reference
|
||
|
||
- `docs/example-theme.json` (seeded automatically on first launch into
|
||
`pluginConfigs/HellionChat/themes/`) — minimal valid theme.
|
||
- The five built-in themes live in source under `HellionChat/Themes/Builtin/`. They are a good
|
||
reference for Color choices that work.
|
||
- [Hellion Online Media branding](https://hellion-media.de) — the Arctic Cyan + Ember Glow palette
|
||
that drives the default Hellion Arctic theme.
|
||
|
||
---
|
||
|
||
<p align="center"><sub>HellionChat is a privacy-focused fork of <a href="https://github.com/Infiziert90/ChatTwo">Chat 2</a>, distributed under the EUPL-1.2.<br/>Theme engine and authoring guide are part of <strong>Hellion Forge</strong>.</sub></p>
|