Swing Bright for Crystal Focus X

Crystal Focus X Documentation

Swing Bright Guide

Table of Contents

1. What Is Swing Bright?
2. Config Keys & Where They Live
3. mapping_audio= and mapping_move=
4. Regular Blade vs. Unstable Blade
5. Swing Dampen (style_sbright=1)
6. Putting It All Together
7. Practical Examples

1. What Is Swing Bright?

Swing Bright is a visual effect that makes the blade become brighter or change color when you move the saber, hear louder sound, or change the angle of the hilt. When you swing the saber, the blade can briefly brighten or shift toward another color, then smoothly fade back to its normal look.

It is the last visual layer applied to the blade. In simple terms: Swing Bright is added after the other visual effects are already in place.

2. Config Keys & Where They Live

Blade Profile Parameters (in config.txt, under [profile=N])

These three keys control the Swing Bright behavior and are part of the blade strip profile (BladeStripParams):

If mapping_sbright=0 (NONE), Swing Bright is completely disabled. Nothing happens visually.

Color Profile Parameters (in colors.txt, under [color=N])

Swing Bright does not have its own separate color setting. Instead, it reuses colors that are already defined in the color profile. Which color it uses depends on whether an unstable effect is active:

This is one of the most important things to understand about Swing Bright: the color it moves toward changes depending on whether an unstable effect is enabled.

Additional Mapping Range Keys (in config.txt, under [profile=N])

When using Audio or Move mapping, these keys define how much input is needed before the effect becomes visible:

3. mapping_audio= and mapping_move=

These two parameters define the input sensitivity range for audio-based and motion-based mapping. They are set in config.txt under [profile=N].

Important: these are shared profile parameters. They are not just for Swing Bright. They affect any blade effect in that blade profile that uses AUDIO or MOVE mapping, such as unstable effects, flicker, lockup, drag, and Swing Bright audio mode.

mapping_audio=LOW,HIGH

This sets the audio range used by audio-reactive effects.

Suggested range: use values between 0 and 32000 for mapping_audio=.

If the blade barely reacts to sound, lower the HIGH value. If it reacts too easily to quiet sound or ambient hum, raise the LOW value.

mapping_move=LOW,HIGH

This sets the motion range for effects that use MOVE mapping. In general, lower values make motion-reactive effects feel more sensitive, while higher values make them less sensitive.

Suggested range: use values between 0 and 1023 for mapping_move=.

Practical tuning tips

• For mapping_audio=, use values in a range between 0 and 32000.
• For mapping_move=, use values in a range between 0 and 1023.
• If flicker, unstable, or other motion effects react too easily, raise the LOW value.
• If they never seem to reach full strength, lower the HIGH value.
• Remember that changing these values affects multiple effects in the same blade profile, not just one.

4. Regular Blade vs. Unstable Blade

Regular Blade (unstable=0)

When no unstable effect is active, the blade looks normal and stable. It can still flicker or shimmer, but it will not show the chaotic fire-like patterns that unstable effects add.

Swing Bright blends the blade toward FxColor (ecolor=).

What this means visually: during swings, the blade moves toward a second color. If your BladeColor is blue and your FxColor (ecolor=) is white, the blade brightens toward white when you swing. If your FxColor (ecolor=) is a different hue, the blade shifts toward that color during motion.

Design tip: For a regular blade, ecolor= acts as your "swing highlight color." Set it to:

• White (or brighter version of BladeColor) for a cinematic brightening effect
• A contrasting color for a color-shift swing effect (e.g., blue blade with cyan FxColor)

Unstable Blade (unstable=1–18)

When an unstable effect is active, the blade already has a more chaotic look. Parts of it are being pushed away from the base blade color (color=) and toward the effect color (ecolor=), which creates that unstable appearance.

Swing Bright then blends the blade back toward the base blade color (color=) (color=), which is basically the normal blade color from color= before the unstable effect is added.

What this means visually: during swings, the unstable look is partly pushed back and the normal blade color from color= becomes more visible again. So the blade looks a bit calmer and cleaner during motion, then the unstable look comes back as the effect fades out.

Why it works this way: If Swing Bright used FxColor on an unstable blade, it would just amplify the already-present FxColor from the unstable system — pushing the entire blade toward the same color the heat already creates. Instead, by blending toward the base blade color (color=), it creates a "cutting through the chaos" effect that makes swings pop against the unstable background.

Summary Table

5. Swing Dampen (style_sbright=1)

style_sbright= has two modes:

Value 0 — Swing Bright

At rest, the blade looks normal with no extra overlay. When you move the saber, the blade blends toward the relevant target color. That happens instantly when motion starts, and then fades back gradually when motion stops. The fade-out speed is controlled by delay_sbright=.

• Regular blade (unstable=0): blends toward FxColor (ecolor=). Swinging shifts or brightens the blade toward your ecolor= color.
• Unstable blade (unstable=1–18): blends toward the base blade color (color=). Swinging temporarily calms the unstable chaos back toward the solid base color.

Value 1 — Swing Dampen

This is the opposite behavior. At rest, the blade is fully blended toward the relevant target color. During motion, that overlay is gradually lifted, revealing what is underneath. When motion stops, the overlay snaps back immediately.

• Regular blade (unstable=0): at rest, the blade shows FxColor (ecolor=). Swinging gradually reveals the normal blade color from color= underneath. Stop moving, and the ecolor= overlay snaps back immediately.
• Unstable blade (unstable=1–18): at rest, the base blade color from color= hides the unstable chaos. Swinging gradually lifts that overlay, letting the unstable fire or chaos show through. Stop moving, and the solid overlay snaps back immediately, hiding the chaos again.

Timing behavior comparison

What delay_sbright= does in each mode

• Swing Bright (style_sbright=0): delay_sbright= controls how slowly the brightness or color shift fades back after you stop swinging. Higher values create a longer glow trail.
• Swing Dampen (style_sbright=1): delay_sbright= controls how slowly the overlay lifts during a swing. Higher values make the reveal happen more slowly during motion. The snap-back when you stop is always instant, no matter what delay_sbright= is set to.

6. Putting It All Together

Visual Pipeline (per blade strip frame)

1. Pixels initialized to the base blade color (color=) (BladeColor + shimmer/FoC)
2. Unstable Fx applied (if unstable > 0) — blends toward FxColor (ecolor=) via heat
3. Flicker applied (style_flicker) — blends toward FlickerColor
4. Effect overlays (drag, stab, blaster)
5. SWING BRIGHT applied LAST
      ├─ Regular blade:  blend toward FxColor (ecolor=) (ecolor=)
      └─ Unstable blade: blend toward the base blade color (color=) from color= (color=) (base blade)

Which file controls what

7. Practical Examples

Example A: Movie-Accurate Blue Blade with Swing Brightening

Example goal: A clean blue blade that brightens toward white when swung, with a smooth fade-back.

Color profile (colors.txt):

[color=0]
color=0,0,1023,0
ecolor=401,401,1023,401

BladeColor is blue, FxColor is a brighter blue-white. No unstable effect, so Swing Bright uses ecolor=.

Blade profile (config.txt):

unstable=0
style_sbright=0
mapping_sbright=3
delay_sbright=160

• unstable=0 → regular blade, so FxColor is the swing target
• style_sbright=0 → REGULAR (swing = brighter)
• mapping_sbright=3 → MOVE (gyro speed drives it)
• delay_sbright=160 → medium-slow fade giving a glow trail

font_config.txt:

What it feels like: When you swing, the blade brightens toward blue-white and then fades back smoothly. At the same time, the hum drops and the swing sounds become more noticeable.

Example B: Kylo Unstable with Swing Stabilisation

Example goal: A chaotic unstable red blade where swinging temporarily calms the instability.

Color profile (colors.txt):

[color=1]
color=1023,0,0,0
ecolor=1023,602,0,0

BladeColor is red, FxColor is orange (used by unstable heat, NOT by Swing Bright here).

Blade profile (config.txt):

unstable=1
lcool=30
hcool=80
sparkf=150
sparkd=80
drift=1
style_sbright=0
mapping_sbright=3
delay_sbright=120

• unstable=1 → unstable active, so Swing Bright uses the base blade color (color=) (color=) (= base red)
• mapping_sbright=3 → MOVE-driven
• delay_sbright=120 → moderate fade

font_config.txt:

What it feels like: At rest, the blade is a chaotic mix of red and orange unstable sparks. During swing → Swing Bright blends all pixels back toward solid red (the base blade color (color=)), temporarily "stabilising" the blade. After the swing, the instability fades back in. Audio → hum drops 60%, swing sounds come forward.

Example C: Angular Tilt Brightness

Example goal: The blade is dimmer when pointed down, brighter when pointed up.

Blade profile (config.txt):

unstable=0
style_sbright=0
mapping_sbright=2
delay_sbright=200

• mapping_sbright=2 → ANGULAR (tilt up = bright, tilt down = dim)
• delay_sbright=200 → slow transition for a gravity-like feel

What it feels like: This creates a blade that responds to angle instead of swing speed. Holding the saber upright gives the strongest brightening effect, while pointing it down returns it closer to its normal color. The slow delay makes the change feel smooth and flowing.

Example D: Reverse Swing Bright (Dim on Swing)

Example goal: The blade dims when moved — the blade glows brightest when held still.

Blade profile (config.txt):

unstable=0
style_sbright=1
mapping_sbright=3
delay_sbright=80

• style_sbright=1 → REVERSE (high motion = darker)
• delay_sbright=80 → fairly fast recovery

What it feels like: At rest, the blade is fully bright. Swinging dims it toward FxColor (ecolor=). Holding still → brightness restores quickly. Creates an eerie, "energy containment" look.

Guide generated from Crystal Focus X firmware source code analysis (BladeStrip.cpp applySwingBright, Motion.cpp smooth swing pipeline, Profile.h BladeStripParams/MotionParams, Textfile.h/Textfile.cpp config parsing).