feat(04-01): add VolumeCurve with hardcoded VFX-02 spec curve

- VolumeCurve.volumeFor(int) returns spec values [1.0, 0.8, 0.6, 0.5, 0.4]
- High indices clamp to 0.4f (last value)
- Negative indices throw IllegalArgumentException
- 3 JUnit cases (specValues, indexClamp, negativeIndexThrows), all green
- Zero Hytale imports — chain/ frontier preserved
This commit is contained in:
2026-04-27 13:01:38 +02:00
parent 8d868a28ca
commit ddc08fb14c
2 changed files with 71 additions and 0 deletions
@@ -0,0 +1,40 @@
package com.mythlane.chainlightning.chain;
/**
* Pure-Java volume curve for the chain-lightning sound emission.
* <p>
* Each successive hop in the chain emits its sound at a progressively lower
* volume, per VFX-02. The curve is hard-coded to the spec values
* {@code [1.0, 0.8, 0.6, 0.5, 0.4]} indexed by hop number.
* <p>
* This class has ZERO Hytale imports — Phase 2 sealed-frontier rule preserved.
*/
public final class VolumeCurve {
/** Spec curve from VFX-02. Order and values are exact. */
private static final float[] CURVE = {1.0f, 0.8f, 0.6f, 0.5f, 0.4f};
private VolumeCurve() {
// utility class — no instances
}
/**
* Volume for a given hop index in the chain.
* <ul>
* <li>Indices 0..4 return the spec values {@code 1.0, 0.8, 0.6, 0.5, 0.4}.</li>
* <li>Indices &ge; 5 clamp to the last value {@code 0.4f}.</li>
* <li>Negative indices throw {@link IllegalArgumentException}.</li>
* </ul>
*
* @param hopIndex zero-based hop index
* @return volume scalar in the range (0, 1]
* @throws IllegalArgumentException if {@code hopIndex < 0}
*/
public static float volumeFor(int hopIndex) {
if (hopIndex < 0) {
throw new IllegalArgumentException("hopIndex must be >= 0, got " + hopIndex);
}
int clamped = Math.min(hopIndex, CURVE.length - 1);
return CURVE[clamped];
}
}