Themed Saber Setup

What Is a Theme?

A theme is a self-contained saber personality that lives in a single folder on the SD card. It bundles together sound fonts, blade colors, accent LED sequences, pixel animations, display graphics, audio tracks, and configuration files into one package.

Without themes, all of these pieces live at the SD card root and apply globally. With themes, you can build multiple complete saber identities and switch between them on the fly, such as a Jedi theme and a Sith theme.

Important: Themes are completely optional. If you never set one up, the CFX keeps using the traditional root-level files exactly as before.

How Themes Work

When a theme is active, the CFX redirects almost every important file path into the theme folder instead of reading from the SD card root. That includes configs, display assets, accents, GraFx sequences, VU meter art, UI sounds, tracks, and more.

Sound fonts also live inside the theme folder, so each theme has its own independent set of fonts.

Switching themes causes the saber to fully reboot. This is normal. A theme changes so many things at once that a clean restart is the safest way to load everything correctly.

Theme Folder Naming

Theme folders sit at the root of the SD card and follow a strict naming pattern:

<number>-<name>

• The number is a single digit from 0 to 9.
• A dash immediately follows the number.
• The name is a descriptive label for your own convenience.

Examples

0-Jedi
1-Sith
2-Mandalorian
3-MyCustomTheme

Tip: Keep theme folder names short and avoid spaces or unusual special characters.

What Goes Inside a Theme Folder

A theme folder mirrors the structure you would normally have at the SD card root.

1-Sith/
├── config.txt
├── colors.txt
├── prefs.txt
├── special.txt
├── theme.bmp
├── theme.wav
│
├── 1-DarkLord/
│   ├── font_config.txt
│   ├── boot.wav
│   ├── hum.wav
│   ├── clash1.wav
│   ├── ...
│   ├── crystal.bmp
│   ├── bladeon.bmp
│   └── bladeoff.bmp
│
├── 2-Emperor/
│   ├── font_config.txt
│   ├── hum.wav
│   └── ...
│
├── tracks/
│   ├── track1.wav
│   └── ...
│
└── extra/
    ├── UI/
    │   ├── font.wav
    │   ├── font.bmp
    │   ├── themeswitch.wav
    │   └── ...
    ├── PLI/
    ├── GRAFX/
    ├── ACCENTS/
    ├── PIXIES/
    ├── VUMETER/
    │   └── vumeter.bmp
    ├── SCSV/
    ├── IDs/
    ├── OBJ/
    │   └── display.obj
    ├── accent0.bmp
    ├── accent1.bmp
    ├── crystal.bmp
    ├── bladeon.bmp
    └── bladeoff.bmp

Sound Fonts Within a Theme

Font folders inside a theme use the same naming convention as normal root-level fonts: <number>-<name>. When a theme is active, the CFX scans only the theme folder for fonts. Root-level fonts are ignored.

OLED Display Asset Fallback

For crystal.bmp, bladeon.bmp, and bladeoff.bmp, the CFX uses a two-step lookup:

1. Font folder first, such as 1-Sith/2-Emperor/crystal.bmp
2. Theme extra fallback, such as 1-Sith/extra/crystal.bmp

This lets you provide theme-wide default OLED assets while still allowing individual fonts to override them.

accent0.bmp, accent1.bmp, and display.obj are always loaded from the theme’s extra/ folder.

What a Theme Can Override

Important: A theme’s config.txt completely replaces the root config.txt. There is no merging. The same applies to prefs.txt, colors.txt, and special.txt.

font_config.txt stays per-font. It is always read from the individual font folder.

The theme_prefs.txt File

theme_prefs.txt lives at the root of the SD card and tells the CFX which theme to load at boot.

Contents

bank=1

The number after bank= matches the number prefix of the theme folder. For example, bank=1 loads 1-Sith/.

How It Gets Updated

You normally do not edit theme_prefs.txt by hand. It is written automatically when you select a theme through the vocal menu or via serial. If you delete it, the saber boots without any theme active and goes back to root-level files.

Selecting and Switching Themes

Vocal Menu

If the CFX detects at least one valid theme folder, a Theme entry appears automatically in the vocal menu.

1. Each discovered theme is listed as a selectable item.
2. The OLED shows the theme’s theme.bmp while you browse.
3. The theme’s theme.wav plays as a preview while you browse.
4. The menu starts at the currently active theme.

When you confirm a selection, the saber writes the new bank=N value to theme_prefs.txt, plays the theme switching sound, and then reboots.

Serial Command

selecttheme=N

This writes theme_prefs.txt and reboots, just like the menu does.

Diagnostic Command

dirthemes

This prints all detected theme folders and their index numbers.

Boot Sequence

1. The CFX reads theme_prefs.txt from the SD root.
2. It scans the SD root for a folder whose name starts with N-.
3. That folder becomes the active theme folder.
4. All redirected paths now point into the theme.
5. Font scanning runs inside the theme folder.
6. config.txt, prefs.txt, colors.txt, and special.txt are loaded from the theme.

If theme_prefs.txt does not exist or contains an invalid value, the saber boots without a theme and uses root-level files as normal.

Setting Up Your First Theme

Step 1 — Create the Theme Folder

0-Jedi

Step 2 — Add Your Configuration Files

0-Jedi/
├── config.txt
├── colors.txt
├── prefs.txt
└── special.txt

Step 3 — Add Sound Fonts

0-Jedi/
├── 1-Guardian/
│   ├── font_config.txt
│   ├── boot.wav
│   ├── hum.wav
│   └── ...
└── 2-ConsularSage/
    ├── font_config.txt
    ├── hum.wav
    └── ...

Step 4 — Add Display and Visual Assets (Optional)

0-Jedi/
└── extra/
    ├── UI/
    ├── PLI/
    ├── GRAFX/
    ├── ACCENTS/
    ├── PIXIES/
    └── ...

Step 5 — Add Theme Identity Files (Optional)

0-Jedi/
├── theme.bmp
└── theme.wav

Step 6 — Add Track Files (Optional)

0-Jedi/
└── tracks/
    ├── track1.wav
    └── track2.wav

Step 7 — Activate the Theme

• Create theme_prefs.txt at the SD root with bank=0, or
• Boot the saber and select the theme in the vocal menu.

Multiple Themes Example

SD Card Root/
├── theme_prefs.txt
│
├── 0-Jedi/
│   ├── config.txt
│   ├── colors.txt
│   ├── prefs.txt
│   ├── theme.bmp
│   ├── theme.wav
│   ├── 1-Guardian/
│   ├── 2-Sentinel/
│   ├── tracks/
│   └── extra/
│       ├── UI/
│       ├── GRAFX/
│       └── ACCENTS/
│
├── 1-Sith/
│   ├── config.txt
│   ├── colors.txt
│   ├── prefs.txt
│   ├── theme.bmp
│   ├── theme.wav
│   ├── 1-DarkLord/
│   ├── 2-Emperor/
│   ├── tracks/
│   └── extra/
│       ├── UI/
│       ├── GRAFX/
│       └── ACCENTS/
│
└── 2-Mandalorian/
    ├── config.txt
    ├── prefs.txt
    ├── theme.bmp
    ├── theme.wav
    ├── 1-Whistling/
    └── extra/
        └── ACCENTS/

Each theme is fully independent. Switching between them swaps everything at once.

Minimal Theme

You do not have to override everything. A minimal theme only needs:

• At least one sound font folder
• A config.txt

Everything else is optional.

Minimal Example

0-SimpleTheme/
├── config.txt
└── 1-MyFont/
    ├── font_config.txt
    ├── boot.wav
    ├── hum.wav
    ├── poweron.wav
    ├── poweroff.wav
    └── clash1.wav

Quick Reference

Tips

• Switching themes always reboots the saber. That is by design.
• Config changes made through the menu are saved to the themed file. For example, if theme 1-Sith is active, color changes are saved to 1-Sith/colors.txt.
• Root-level files still matter when no theme is active.
• Each theme can have its own font count. One theme may have 5 fonts while another has 2.
• Theme detection is automatic. Any SD root folder that starts with a digit followed by a dash is recognized as a theme.
• You can mix themed and non-themed use. Delete theme_prefs.txt anytime to return to a root-level setup.

Crystal Focus X firmware guide · Themed Saber Setup