Render subtitles exactly as vanilla's SubtitleOverlay

The overlay listens to the sound engine from the frame that renders it with
Show Subtitles on until one renders with it off (keeping its captions),
forgets plays as it renders, picks the latest play in range (the first of
full ties), fades in float arithmetic, lays the boxes out in integers under
the pose translation and takes its background from the text background
opacity options. Translations now apply the game's deprecated.json renames,
as ClientLanguage does ("Chick hurts"). tools/test_subtitle_parity.py runs
vanilla's SubtitleOverlay on 1500 scripted cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-12 17:07:47 +02:00
parent 4a2d801d2b
commit bbae62fc4b
6 changed files with 901 additions and 275 deletions
@@ -0,0 +1,106 @@
//! The subtitle overlay for differential tests against vanilla's
//! `SubtitleOverlay` (tools/test_subtitle_parity.py): replays each case's
//! sound plays, clock changes and frames through
//! `horizon_client::subtitles` and prints every frame's fills and texts with
//! their pose, in VanillaSubtitleOracle's JSON lines.
//!
//! usage: subtitle_fixture RESOURCES INPUTS OUTPUT
use horizon_client::{
hud::HudAtlas,
lang,
subtitles::{Draw, Frame, SubtitleOverlay, background_color},
};
use serde_json::{Value, json};
use std::{fs, io::Write, path::PathBuf};
fn vec3(v: &Value) -> [f64; 3] {
std::array::from_fn(|i| v[i].as_f64().unwrap_or(0.0))
}
fn pose(t: [f32; 2]) -> Value {
json!([1.0, 0.0, 0.0, 1.0, t[0], t[1]])
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let args: Vec<PathBuf> = std::env::args_os().skip(1).map(PathBuf::from).collect();
let [root, inputs, output] = args.as_slice() else {
return Err("usage: subtitle_fixture RESOURCES INPUTS OUTPUT".into());
};
lang::set(lang::Language::load(&[root], lang::DEFAULT));
let atlas = HudAtlas::build(root)?;
let mut out = std::io::BufWriter::new(fs::File::create(output)?);
for line in fs::read_to_string(inputs)?
.lines()
.filter(|l| !l.is_empty())
{
let c: Value = serde_json::from_str(line)?;
let mut overlay = SubtitleOverlay::default();
let mut now = 0i64;
let mut frames = Vec::new();
for op in c["ops"].as_array().into_iter().flatten() {
match op["op"].as_str().unwrap_or_default() {
// Util.getMillis: nanoseconds / 1_000_000.
"time" => now = op["ms"].as_i64().unwrap_or(0),
"play" => {
if overlay.listening() {
let range = op["range"].as_f64().map_or(f32::INFINITY, |r| r as f32);
overlay.on_play(
op["key"].as_str(),
vec3(&op["at"]),
range,
op["looping"].as_bool().unwrap_or(false),
now,
);
}
}
"frame" => {
let frame = Frame {
show: op["show"].as_bool().unwrap_or(false),
position: vec3(&op["pos"]),
forward: vec3(&op["forward"]),
up: vec3(&op["up"]),
multiplier: op["mult"].as_f64().unwrap_or(1.0),
background: background_color(
0.8,
op["opacity"].as_f64().unwrap_or(0.5) as f32,
op["chat_only"].as_bool().unwrap_or(true),
),
width: op["w"].as_i64().unwrap_or(0) as i32,
height: op["h"].as_i64().unwrap_or(0) as i32,
};
let draws: Vec<Value> = overlay
.extract(&frame, &atlas.font, now)
.into_iter()
.map(|d| match d {
Draw::Stratum => json!({"type": "stratum"}),
Draw::Fill {
x0,
y0,
x1,
y1,
color,
translate,
} => json!({
"type": "fill", "x0": x0, "y0": y0, "x1": x1, "y1": y1,
"color": format!("{color:x}"), "pose": pose(translate),
}),
Draw::Text {
text,
x,
y,
color,
translate,
} => json!({
"type": "text", "text": text.plain(), "x": x, "y": y,
"color": format!("{color:x}"), "shadow": true, "pose": pose(translate),
}),
})
.collect();
frames.push(Value::Array(draws));
}
other => return Err(format!("op {other}").into()),
}
}
writeln!(out, "{}", json!({"case": c["case"], "frames": frames}))?;
}
Ok(())
}
+83 -33
View File
@@ -1,52 +1,102 @@
//! The subtitle overlay in the game (`Hud` -> `SubtitleOverlay`): sounds the
//! audio engine plays feed it, the HUD draws it.
//! The subtitle overlay in the game (`Hud` -> `SubtitleOverlay`): the sound
//! engine reports the sounds it plays while the overlay listens, the HUD
//! renders it (which starts or stops the listening as the "Show Subtitles"
//! option says).
use super::Game;
use horizon_client::{
hud::HudBatch,
subtitles::{self, SubtitleOverlay},
hud::{HudBatch, rgba},
subtitles::{self, Draw, Frame, SubtitleOverlay},
};
use std::cell::RefCell;
#[derive(Default)]
pub(super) struct SubtitleState {
overlay: SubtitleOverlay,
listening: bool,
overlay: RefCell<SubtitleOverlay>,
}
impl Game<'_> {
/// Feed the sounds played since the last tick to the overlay while the
/// `showSubtitles` option is on.
/// Feed the sounds the engine reported since the last tick
/// (`SoundEventListener.onPlaySound`) while the overlay listens.
pub(super) fn tick_subtitles(&mut self) {
let on = self.settings.show_subtitles;
self.audio.record_heard = on;
if !on {
if self.subtitles.listening {
self.subtitles.listening = false;
self.subtitles.overlay.clear();
}
self.audio.take_heard();
let mut overlay = self.subtitles.overlay.borrow_mut();
let listening = overlay.listening();
self.audio.record_heard = listening;
let heard = self.audio.take_heard();
if !listening {
return;
}
self.subtitles.listening = true;
let now = subtitles::now_ms();
let listener = self.audio.listener;
for heard in self.audio.take_heard() {
self.subtitles.overlay.on_play(&heard, listener, now);
for h in heard {
let at = h.at.unwrap_or(self.audio.listener);
overlay.on_play(Some(&h.subtitle), at, h.range, h.looping, now);
}
self.subtitles
.overlay
.purge(f64::from(self.settings.notification_display_time), now);
}
pub(super) fn draw_subtitles(&self, batch: &mut HudBatch) {
if !self.settings.show_subtitles {
// Hud.extractRenderState: hidden with the rest of the HUD (F1).
if self.ui.hide_gui {
return;
}
self.subtitles.overlay.draw(
batch,
&self.res.atlas,
self.audio.listener,
self.yaw,
self.pitch,
f64::from(self.settings.notification_display_time),
subtitles::now_ms(),
);
let v = &self.view;
let frame = Frame {
show: self.settings.show_subtitles,
position: v.position,
forward: v.forwards.map(f64::from),
up: v.up.map(f64::from),
multiplier: f64::from(self.settings.notification_display_time),
background: subtitles::background_color(
0.8,
self.settings.text_background_opacity,
self.settings.file.bool("backgroundForChatOnly"),
),
width: batch.width as i32,
height: batch.height as i32,
};
let atlas = &self.res.atlas;
let draws =
self.subtitles
.overlay
.borrow_mut()
.extract(&frame, &atlas.font, subtitles::now_ms());
let argb = |c: u32| {
let [a, r, g, b] = c.to_be_bytes();
rgba(r, g, b, a)
};
for d in draws {
match d {
Draw::Stratum => (),
Draw::Fill {
x0,
y0,
x1,
y1,
color,
translate: [tx, ty],
} => {
batch.fill(
atlas,
tx + x0 as f32,
ty + y0 as f32,
(x1 - x0) as f32,
(y1 - y0) as f32,
argb(color),
);
}
Draw::Text {
text,
x,
y,
color,
translate: [tx, ty],
} => {
batch.text_styled(
atlas,
&text,
tx + x as f32,
ty + y as f32,
argb(color),
true,
);
}
}
}
}
}
+24
View File
@@ -64,6 +64,30 @@ impl Language {
}
}
}
// DeprecatedTranslationsInfo.loadFromDefaultResource().applyToMap: the
// game's own deprecated.json drops removed keys and renames others.
if let Some(bytes) = sources
.iter()
.find_map(|s| s.read("assets/minecraft/lang/deprecated.json"))
&& let Ok(info) = serde_json::from_slice::<serde_json::Value>(&bytes)
{
for key in info["removed"].as_array().into_iter().flatten() {
if let Some(key) = key.as_str() {
map.remove(key);
}
}
for (from, to) in info["renamed"].as_object().into_iter().flatten() {
let Some(to) = to.as_str() else { continue };
match map.remove(from) {
Some(value) => {
map.insert(to.to_owned(), value);
}
None => {
map.remove(to);
}
}
}
}
Self {
code: code.to_owned(),
map,
+267 -242
View File
@@ -1,53 +1,81 @@
//! The subtitle overlay (`SubtitleOverlay`): closed captions for the sounds
//! the player could hear, with direction arrows and a fade over the
//! notification display time.
use crate::{
audio::Heard,
hud::{HudAtlas, HudBatch, rgba},
text::Text,
};
//!
//! Like vanilla, the overlay listens to the sound engine only from the frame
//! that renders it with the "Show Subtitles" option on until a frame renders
//! with it off; turning it off keeps the captions it has (they show again if
//! the option comes back before they expire).
use crate::{font::Font, text::Text};
/// How long a subtitle shows before it is dropped (milliseconds).
const DISPLAY_TIME: f64 = 3000.0;
/// Looping sounds stay at full brightness this long.
const LOOPING_FULL_BRIGHTNESS: f64 = 500.0;
/// `SubtitleOverlay.DISPLAY_TIME` (milliseconds).
const DISPLAY_TIME: i64 = 3000;
/// `LOOPING_DISPLAY_FULL_BRIGHTNESS_TIME`: looping sounds stay at full brightness this long.
const LOOPING_FULL_BRIGHTNESS: i64 = 500;
#[derive(Clone, Debug, PartialEq)]
#[derive(Clone, Copy, Debug, PartialEq)]
struct PlayedAt {
location: [f64; 3],
time: u64,
time: i64,
}
#[derive(Clone, Debug)]
struct Subtitle {
/// The translation key of the sound event's subtitle (`Component.translatable`).
key: String,
range: f32,
played: Vec<PlayedAt>,
looping: bool,
}
fn distance_sqr(a: [f64; 3], b: [f64; 3]) -> f64 {
(0..3).map(|i| (a[i] - b[i]).powi(2)).sum()
let (dx, dy, dz) = (a[0] - b[0], a[1] - b[1], a[2] - b[2]);
dx * dx + dy * dy + dz * dz
}
/// `Vec3.closerThan`.
/// `Vec3.closerThan(pos, distance)`.
fn closer_than(a: [f64; 3], b: [f64; 3], range: f32) -> bool {
distance_sqr(a, b) < f64::from(range) * f64::from(range)
let r = f64::from(range);
distance_sqr(a, b) < r * r
}
/// `Vec3.equals`: `Double.compare` on each axis.
fn same_location(a: [f64; 3], b: [f64; 3]) -> bool {
let bits = |v: f64| {
if v.is_nan() {
f64::NAN.to_bits()
} else {
v.to_bits()
}
};
(0..3).all(|i| bits(a[i]) == bits(b[i]))
}
impl Subtitle {
fn best_candidate(&self, position: [f64; 3]) -> Option<&PlayedAt> {
match self.played.len() {
0 => None,
1 => self.played.first(),
_ => self
.played
/// `getBestSubtitleCandidate`: the only play, else the latest in range
/// (the farthest of equally recent ones; the first among full ties).
fn best_candidate(&self, position: [f64; 3]) -> Option<PlayedAt> {
match self.played.as_slice() {
[] => None,
[only] => Some(*only),
many => many
.iter()
.filter(|p| closer_than(p.location, position, self.range))
.max_by(|a, b| {
a.time.cmp(&b.time).then_with(|| {
distance_sqr(a.location, position)
.total_cmp(&distance_sqr(b.location, position))
})
.fold(None, |best: Option<PlayedAt>, p| match best {
Some(b)
if b.time > p.time
|| b.time == p.time
&& distance_sqr(b.location, position).sqrt()
>= distance_sqr(p.location, position).sqrt() =>
{
Some(b)
}
_ => Some(*p),
}),
}
}
fn refresh(&mut self, location: [f64; 3], now: i64) {
self.played.retain(|p| !same_location(location, p.location));
self.played.push(PlayedAt {
location,
time: now,
});
}
fn audible_from(&self, camera: [f64; 3]) -> bool {
if self.range.is_infinite() {
return true;
@@ -55,278 +83,275 @@ impl Subtitle {
self.best_candidate(camera)
.is_some_and(|p| closer_than(camera, p.location, self.range))
}
fn still_active(&self, multiplier: f64, now: u64) -> bool {
let max_age = DISPLAY_TIME * multiplier;
self.played
.iter()
.any(|p| (now.saturating_sub(p.time) as f64) <= max_age)
fn purge_old_instances(&mut self, max_age: f64, now: i64) {
self.played.retain(|p| ((now - p.time) as f64) <= max_age);
}
/// `getBrightness`: fades from 255 to 75 over the display time.
fn brightness(&self, at: &PlayedAt, multiplier: f64, now: u64) -> i32 {
fn brightness(&self, at: PlayedAt, multiplier: f64, now: i64) -> i32 {
let full = if self.looping {
LOOPING_FULL_BRIGHTNESS
} else {
0.0
0
};
let age = (now.saturating_sub(at.time) as f64 - full).max(0.0);
let t = (age / ((DISPLAY_TIME - full) * multiplier)) as f32;
let t = t.clamp(0.0, 1.0);
(255.0_f32 + (75.0_f32 - 255.0_f32) * t).floor() as i32
let age = (now - at.time - full).max(0) as f32;
let t = age / (((DISPLAY_TIME - full) as f64) * multiplier) as f32;
let v = if t < 0.0 {
255.0
} else if t > 1.0 {
75.0
} else {
255.0 + t * (75.0 - 255.0_f32)
};
v.floor() as i32
}
}
/// A row to draw.
#[derive(Clone, Debug, PartialEq)]
pub struct Row {
pub text: Text,
pub brightness: i32,
pub arrow: Arrow,
/// What a frame needs to render the overlay: the sound listener, the
/// accessibility options and the GUI size.
#[derive(Clone, Copy, Debug)]
pub struct Frame {
/// `options.showSubtitles`.
pub show: bool,
/// `SoundManager.getListenerTransform`: position, forward and up.
pub position: [f64; 3],
pub forward: [f64; 3],
pub up: [f64; 3],
/// `options.notificationDisplayTime`.
pub multiplier: f64,
/// `options.getBackgroundColor(0.8F)` (ARGB).
pub background: u32,
pub width: i32,
pub height: i32,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Arrow {
None,
Left,
Right,
/// `Options.getBackgroundColor(defaultOpacity)`: the text background opacity
/// unless the background is for chat only.
pub fn background_color(
default_opacity: f32,
text_background_opacity: f32,
chat_only: bool,
) -> u32 {
let alpha = if chat_only {
default_opacity
} else {
text_background_opacity
};
((alpha * 255.0).floor() as i32 as u32) << 24
}
/// One call the overlay makes, with the pose translation it is made under.
#[derive(Clone, Debug, PartialEq)]
pub enum Draw {
/// `graphics.nextStratum()`.
Stratum,
Fill {
x0: i32,
y0: i32,
x1: i32,
y1: i32,
color: u32,
translate: [f32; 2],
},
/// Text with a drop shadow.
Text {
text: Text,
x: i32,
y: i32,
color: u32,
translate: [f32; 2],
},
}
/// Milliseconds on a monotonic clock (`Util.getMillis`).
pub fn now_ms() -> u64 {
pub fn now_ms() -> i64 {
static START: std::sync::OnceLock<std::time::Instant> = std::sync::OnceLock::new();
START
.get_or_init(std::time::Instant::now)
.elapsed()
.as_millis() as u64
.as_millis() as i64
}
#[derive(Default)]
pub struct SubtitleOverlay {
subtitles: Vec<Subtitle>,
listening: bool,
}
impl SubtitleOverlay {
/// `onPlaySound`: a repeated subtitle refreshes its location.
pub fn on_play(&mut self, heard: &Heard, listener: [f64; 3], now: u64) {
let location = heard.at.unwrap_or(listener);
if let Some(s) = self.subtitles.iter_mut().find(|s| s.key == heard.subtitle) {
s.played.retain(|p| p.location != location);
s.played.push(PlayedAt {
location,
time: now,
});
/// Whether the overlay is one of the sound engine's listeners.
pub fn listening(&self) -> bool {
self.listening
}
/// `onPlaySound` for a sound the engine played while the overlay listens:
/// a subtitle already listed (by its text) refreshes its location.
pub fn on_play(
&mut self,
subtitle: Option<&str>,
location: [f64; 3],
range: f32,
looping: bool,
now: i64,
) {
let Some(key) = subtitle else {
return;
};
if let Some(s) = self.subtitles.iter_mut().find(|s| s.key == key) {
s.refresh(location, now);
return;
}
self.subtitles.push(Subtitle {
key: heard.subtitle.clone(),
range: heard.range,
key: key.to_owned(),
range,
played: vec![PlayedAt {
location,
time: now,
}],
looping: heard.looping,
looping,
});
}
pub fn clear(&mut self) {
self.subtitles.clear();
}
/// `purgeOldInstances`: forget sounds older than the display time.
pub fn purge(&mut self, multiplier: f64, now: u64) {
let max_age = DISPLAY_TIME * multiplier;
for s in &mut self.subtitles {
s.played
.retain(|p| (now.saturating_sub(p.time) as f64) <= max_age);
}
}
/// The audible subtitles for a listener looking along `forward` with
/// `right` to the right, and the width the box needs.
pub fn rows(
&self,
position: [f64; 3],
forward: [f64; 3],
right: [f64; 3],
multiplier: f64,
now: u64,
) -> Vec<Row> {
/// `extractRenderState`: starts or stops listening as the option says,
/// forgets old plays and lays out the boxes at the bottom right.
pub fn extract(&mut self, frame: &Frame, font: &Font, now: i64) -> Vec<Draw> {
let mut out = Vec::new();
for s in &self.subtitles {
if !(s.audible_from(position) && s.still_active(multiplier, now)) {
continue;
if self.listening != frame.show {
self.listening = frame.show;
}
if !self.listening {
return out;
}
let position = frame.position;
let (f, u) = (frame.forward, frame.up);
// ListenerTransform.right: forward x up.
let right = [
f[1] * u[2] - f[2] * u[1],
f[2] * u[0] - f[0] * u[2],
f[0] * u[1] - f[1] * u[0],
];
let width_of = |t: &Text| font.width_text(t) as i32;
let mut audible = Vec::new();
let mut width = 0;
for (i, s) in self.subtitles.iter_mut().enumerate() {
if !s.played.is_empty() {
s.purge_old_instances(3000.0 * frame.multiplier, now);
}
let Some(at) = s.best_candidate(position) else {
if s.audible_from(position) && !s.played.is_empty() {
width = width.max(width_of(&Text::translate(&s.key, &[])));
audible.push(i);
}
}
if audible.is_empty() {
return out;
}
let w = |s: &str| font.width(s) as i32;
width += w("<") + w(" ") + w(">") + w(" ");
out.push(Draw::Stratum);
let mut row = 0;
for i in audible {
let s = &self.subtitles[i];
let text = Text::translate(&s.key, &[]);
let Some(closest) = s.best_candidate(position) else {
continue;
};
let mut delta = [
at.location[0] - position[0],
at.location[1] - position[1],
at.location[2] - position[2],
closest.location[0] - position[0],
closest.location[1] - position[1],
closest.location[2] - position[2],
];
// Vec3.normalize.
let length = distance_sqr(delta, [0.0; 3]).sqrt();
if length >= 1.0e-4 {
delta = delta.map(|v| v / length);
delta = if length < f64::from(1.0e-5_f32) {
[0.0; 3]
} else {
delta = [0.0; 3];
}
let dot = |a: [f64; 3]| a[0] * delta[0] + a[1] * delta[1] + a[2] * delta[2];
let (rightness, forwardness) = (dot(right), dot(forward));
let arrow = if forwardness > 0.5 {
Arrow::None
} else if rightness > 0.0 {
Arrow::Right
} else if rightness < 0.0 {
Arrow::Left
} else {
Arrow::None
delta.map(|v| v / length)
};
out.push(Row {
text: Text::translate(&s.key, &[]),
brightness: s.brightness(at, multiplier, now),
arrow,
let dot = |a: [f64; 3]| a[0] * delta[0] + a[1] * delta[1] + a[2] * delta[2];
let (rightness, forwardness) = (dot(right), dot(f));
let in_view = forwardness > 0.5;
let half_width = width / 2;
let height = 9;
let half_height = height / 2;
let text_width = width_of(&text);
let brightness = s.brightness(closest, frame.multiplier, now);
let translate = [
frame.width as f32 - half_width as f32 * 1.0 - 2.0,
(frame.height - 35) as f32 - (row * (height + 1)) as f32 * 1.0,
];
out.push(Draw::Fill {
x0: -half_width - 1,
y0: -half_height - 1,
x1: half_width + 1,
y1: half_height + 1,
color: frame.background,
translate,
});
let b = brightness as u32 & 0xFF;
let color = 0xFF00_0000 | b << 16 | b << 8 | b;
if !in_view {
if rightness > 0.0 {
out.push(Draw::Text {
text: Text::literal(">"),
x: half_width - w(">"),
y: -half_height,
color,
translate,
});
} else if rightness < 0.0 {
out.push(Draw::Text {
text: Text::literal("<"),
x: -half_width,
y: -half_height,
color,
translate,
});
}
}
out.push(Draw::Text {
text,
x: -text_width / 2,
y: -half_height,
color,
translate,
});
row += 1;
}
out
}
/// `extractRenderState`: the boxes at the bottom right.
#[allow(clippy::too_many_arguments)]
pub fn draw(
&self,
batch: &mut HudBatch,
atlas: &HudAtlas,
position: [f64; 3],
yaw: f32,
pitch: f32,
multiplier: f64,
now: u64,
) {
let (forward, right) = listener_vectors(yaw, pitch);
let rows = self.rows(position, forward, right, multiplier, now);
if rows.is_empty() {
return;
}
let font = &atlas.font;
let mut width = rows
.iter()
.map(|r| font.width_text(&r.text))
.fold(0.0_f32, f32::max);
width += font.width("<") + font.width(" ") + font.width(">") + font.width(" ");
let half_width = (width / 2.0).trunc();
let background = rgba(0, 0, 0, (0.8 * 255.0) as u8);
for (row, r) in rows.iter().enumerate() {
let bx = batch.width - half_width - 2.0;
let by = batch.height - 35.0 - row as f32 * 10.0;
batch.fill(
atlas,
bx - half_width - 1.0,
by - 4.0 - 1.0,
half_width * 2.0 + 2.0,
10.0,
background,
);
let b = r.brightness.clamp(0, 255) as u8;
let color = rgba(b, b, b, 255);
match r.arrow {
Arrow::Right => {
batch.text(
atlas,
">",
bx + half_width - font.width(">"),
by - 4.0,
color,
true,
);
}
Arrow::Left => {
batch.text(atlas, "<", bx - half_width, by - 4.0, color, true);
}
Arrow::None => {}
}
let text_width = font.width_text(&r.text);
batch.text_styled(
atlas,
&r.text,
bx - (text_width / 2.0).trunc(),
by - 4.0,
color,
true,
);
}
}
}
/// The listener's forward and right vectors for a Minecraft yaw and pitch
/// (degrees): `ListenerTransform.forward()` and `.right()`.
pub fn listener_vectors(yaw: f32, pitch: f32) -> ([f64; 3], [f64; 3]) {
let (yaw, pitch) = (f64::from(yaw).to_radians(), f64::from(pitch).to_radians());
let (sy, cy, sp, cp) = (yaw.sin(), yaw.cos(), pitch.sin(), pitch.cos());
([-sy * cp, -sp, cy * cp], [-cy, 0.0, -sy])
}
#[cfg(test)]
mod tests {
use super::*;
fn heard(key: &str, at: Option<[f64; 3]>, range: f32) -> Heard {
Heard {
subtitle: key.into(),
at,
range,
#[test]
fn candidates_and_brightness() {
let mut s = Subtitle {
key: "a".into(),
range: 16.0,
played: vec![PlayedAt {
location: [0.0, 0.0, 3.0],
time: 1000,
}],
looping: false,
}
}
const ORIGIN: [f64; 3] = [0.0; 3];
#[test]
fn arrows_follow_the_sound_direction() {
// Looking south (yaw 0): forward +z, right -x.
let (forward, right) = listener_vectors(0.0, 0.0);
assert_eq!(forward, [0.0, 0.0, 1.0]);
assert!((right[0] + 1.0).abs() < 1e-9);
let mut o = SubtitleOverlay::default();
o.on_play(&heard("a", Some([0.0, 0.0, 5.0]), 16.0), ORIGIN, 0);
o.on_play(&heard("b", Some([-5.0, 0.0, 0.0]), 16.0), ORIGIN, 0);
o.on_play(&heard("c", Some([5.0, 0.0, 0.0]), 16.0), ORIGIN, 0);
let rows = o.rows(ORIGIN, forward, right, 1.0, 0);
let arrows: Vec<Arrow> = rows.iter().map(|r| r.arrow).collect();
// in front, to the right (west is -x), to the left.
assert_eq!(arrows, vec![Arrow::None, Arrow::Right, Arrow::Left]);
};
assert_eq!(s.brightness(s.played[0], 1.0, 1000), 255);
assert_eq!(s.brightness(s.played[0], 1.0, 2500), 165);
assert_eq!(s.brightness(s.played[0], 2.0, 2500), 210);
assert_eq!(s.brightness(s.played[0], 1.0, 9000), 75);
// Equally recent plays: the farthest in range wins.
s.refresh([0.0, 0.0, 5.0], 1000);
s.refresh([0.0, 0.0, 40.0], 1000);
let best = s.best_candidate([0.0; 3]).unwrap();
assert_eq!(best.location, [0.0, 0.0, 5.0]);
s.purge_old_instances(3000.0, 4001);
assert!(s.played.is_empty());
assert!(!s.audible_from([0.0; 3]));
}
#[test]
fn range_fade_and_expiry() {
fn listening_follows_the_option() {
let mut o = SubtitleOverlay::default();
let (f, r) = listener_vectors(0.0, 0.0);
o.on_play(&heard("near", Some([0.0, 0.0, 3.0]), 16.0), ORIGIN, 1000);
o.on_play(&heard("far", Some([0.0, 0.0, 40.0]), 16.0), ORIGIN, 1000);
let rows = o.rows(ORIGIN, f, r, 1.0, 1000);
assert_eq!(rows.len(), 1);
assert_eq!(rows[0].brightness, 255);
// Halfway through the display time the colour is halfway to 75.
let rows = o.rows(ORIGIN, f, r, 1.0, 2500);
assert_eq!(rows[0].brightness, 165);
// A longer notification time stretches the fade.
let rows = o.rows(ORIGIN, f, r, 2.0, 2500);
assert_eq!(rows[0].brightness, 210);
// Gone after three seconds.
assert!(o.rows(ORIGIN, f, r, 1.0, 4001).is_empty());
}
#[test]
fn repeats_refresh_instead_of_stacking() {
let mut o = SubtitleOverlay::default();
let (f, r) = listener_vectors(0.0, 0.0);
o.on_play(&heard("a", Some([0.0, 0.0, 3.0]), 16.0), ORIGIN, 0);
o.on_play(&heard("a", Some([0.0, 0.0, 3.0]), 16.0), ORIGIN, 2000);
o.on_play(&heard("a", Some([0.0, 0.0, 4.0]), 16.0), ORIGIN, 2500);
let rows = o.rows(ORIGIN, f, r, 1.0, 3000);
assert_eq!(rows.len(), 1);
// The newest candidate in range is the reference for the fade.
assert_eq!(rows[0].brightness, 225);
}
#[test]
fn looping_sounds_stay_bright_longer() {
let mut o = SubtitleOverlay::default();
let (f, r) = listener_vectors(0.0, 0.0);
let mut h = heard("loop", None, f32::INFINITY);
h.looping = true;
o.on_play(&h, ORIGIN, 0);
assert_eq!(o.rows(ORIGIN, f, r, 1.0, 500)[0].brightness, 255);
// Non-positional sounds are always audible and never show an arrow.
assert_eq!(o.rows(ORIGIN, f, r, 1.0, 500)[0].arrow, Arrow::None);
o.on_play(Some("a"), [0.0; 3], 16.0, false, 0);
assert_eq!(o.subtitles.len(), 1);
o.on_play(None, [0.0; 3], 16.0, false, 0);
o.on_play(Some("a"), [1.0; 3], 16.0, false, 5);
assert_eq!(o.subtitles.len(), 1);
assert_eq!(o.subtitles[0].played.len(), 2);
assert!(!o.listening());
}
}
@@ -0,0 +1,249 @@
package dev.horizonlab.parity;
import com.google.gson.*;
import com.mojang.blaze3d.audio.ListenerTransform;
import java.lang.reflect.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.util.*;
import net.minecraft.client.Minecraft;
import net.minecraft.client.OptionInstance;
import net.minecraft.client.Options;
import net.minecraft.client.gui.Font;
import net.minecraft.client.gui.GuiGraphicsExtractor;
import net.minecraft.client.gui.components.SubtitleOverlay;
import net.minecraft.client.resources.sounds.SimpleSoundInstance;
import net.minecraft.client.resources.sounds.SoundInstance;
import net.minecraft.client.sounds.SoundEventListener;
import net.minecraft.client.sounds.SoundManager;
import net.minecraft.client.sounds.WeighedSoundEvents;
import net.minecraft.resources.Identifier;
import net.minecraft.sounds.SoundSource;
import net.minecraft.util.FormattedCharSequence;
import net.minecraft.util.RandomSource;
import net.minecraft.util.Util;
import net.minecraft.world.phys.Vec3;
import org.joml.Matrix3x2f;
import org.joml.Matrix3x2fStack;
/**
* Runs vanilla's own {@link SubtitleOverlay} on scripted cases: sounds the sound engine reports to its listeners
* (subtitle, position, range, looping) at chosen times of {@code Util.getMillis}, and frames that render the
* overlay for a listener transform, the subtitle options (shown or not, notification display time, text
* background opacity and "chat only") and a GUI size. A sound reaches the overlay only while it listens, as with
* the real {@code SoundEngine}; it starts and stops listening when a frame renders with the option on or off.
* Every frame records each fill and text call with the pose translation, in order.
*
* <pre> INPUTS OUTPUT</pre>
*/
public final class VanillaSubtitleOracle {
static Object unsafe;
static Method allocate;
static long nanos;
@SuppressWarnings("unchecked")
static <T> T alloc(Class<T> type) throws Exception {
return (T) allocate.invoke(unsafe, type);
}
static Field field(Class<?> type, String name) throws NoSuchFieldException {
for (Class<?> k = type; k != null; k = k.getSuperclass()) {
try {
Field f = k.getDeclaredField(name);
f.setAccessible(true);
return f;
} catch (NoSuchFieldException e) {
}
}
throw new NoSuchFieldException(name + " on " + type);
}
static void put(Object target, Class<?> owner, String name, Object value) throws Exception {
Field f = field(owner, name);
long offset = (long) unsafe.getClass().getMethod("objectFieldOffset", Field.class).invoke(unsafe, f);
Class<?> t = f.getType();
String setter = t == int.class ? "putInt" : t == boolean.class ? "putBoolean" : t == float.class ? "putFloat" : t == long.class ? "putLong" : "putObject";
Class<?> param = t.isPrimitive() ? t : Object.class;
unsafe.getClass().getMethod(setter, Object.class, long.class, param).invoke(unsafe, target, offset, value);
}
/** The sound manager's listener list and listener transform. */
public static final class Sounds extends SoundManager {
List<SoundEventListener> listeners;
ListenerTransform transform;
private Sounds() {
super(null);
}
@Override
public void addListener(final SoundEventListener listener) {
this.listeners.add(listener);
}
@Override
public void removeListener(final SoundEventListener listener) {
this.listeners.remove(listener);
}
@Override
public ListenerTransform getListenerTransform() {
return this.transform;
}
}
/** Records fill and text calls with the pose. */
public static final class Capture extends GuiGraphicsExtractor {
JsonArray draws;
Matrix3x2fStack stack;
int width, height;
private Capture() {
super(null, null, 0, 0);
}
@Override
public int guiWidth() {
return this.width;
}
@Override
public int guiHeight() {
return this.height;
}
@Override
public Matrix3x2fStack pose() {
return this.stack;
}
@Override
public void nextStratum() {
JsonObject o = new JsonObject();
o.addProperty("type", "stratum");
this.draws.add(o);
}
void pose(JsonObject o) {
Matrix3x2f m = this.stack;
JsonArray a = new JsonArray();
for (float v : new float[] {m.m00, m.m01, m.m10, m.m11, m.m20, m.m21}) {
a.add(v);
}
o.add("pose", a);
}
@Override
public void fill(final int x0, final int y0, final int x1, final int y1, final int color) {
JsonObject o = new JsonObject();
o.addProperty("type", "fill");
o.addProperty("x0", x0);
o.addProperty("y0", y0);
o.addProperty("x1", x1);
o.addProperty("y1", y1);
o.addProperty("color", Integer.toUnsignedString(color, 16));
this.pose(o);
this.draws.add(o);
}
@Override
public void text(final Font font, final FormattedCharSequence str, final int x, final int y, final int color, final boolean shadow) {
JsonObject o = new JsonObject();
o.addProperty("type", "text");
StringBuilder sb = new StringBuilder();
str.accept((index, style, cp) -> {
sb.appendCodePoint(cp);
return true;
});
o.addProperty("text", sb.toString());
o.addProperty("x", x);
o.addProperty("y", y);
o.addProperty("color", Integer.toUnsignedString(color, 16));
o.addProperty("shadow", shadow);
this.pose(o);
this.draws.add(o);
}
}
@SuppressWarnings("unchecked")
static <T> void option(Options options, String name, T value) throws Exception {
OptionInstance<T> instance = (OptionInstance<T>) alloc(OptionInstance.class);
put(instance, OptionInstance.class, "value", value);
put(options, Options.class, name, instance);
}
static Vec3 vec(JsonElement e) {
JsonArray a = e.getAsJsonArray();
return new Vec3(a.get(0).getAsDouble(), a.get(1).getAsDouble(), a.get(2).getAsDouble());
}
public static void main(String[] args) throws Exception {
net.minecraft.SharedConstants.tryDetectVersion();
net.minecraft.server.Bootstrap.bootStrap();
var unsafeField = Class.forName("sun.misc.Unsafe").getDeclaredField("theUnsafe");
unsafeField.setAccessible(true);
unsafe = unsafeField.get(null);
allocate = unsafe.getClass().getMethod("allocateInstance", Class.class);
Font font = ParityFont.create(ParityFont.resources());
Util.setTimeSource(() -> nanos);
Gson gson = new GsonBuilder().disableHtmlEscaping().serializeNulls().create();
StringBuilder out = new StringBuilder();
for (String line : Files.readAllLines(Path.of(args[0]), StandardCharsets.UTF_8)) {
if (line.isBlank()) {
continue;
}
JsonObject c = JsonParser.parseString(line).getAsJsonObject();
JsonObject result = new JsonObject();
result.add("case", c.get("case"));
JsonArray frames = new JsonArray();
try {
Minecraft mc = alloc(Minecraft.class);
Sounds sounds = alloc(Sounds.class);
sounds.listeners = new ArrayList<>();
sounds.transform = ListenerTransform.INITIAL;
put(mc, Minecraft.class, "soundManager", sounds);
put(mc, Minecraft.class, "font", font);
Options options = alloc(Options.class);
put(mc, Minecraft.class, "options", options);
SubtitleOverlay overlay = new SubtitleOverlay(mc);
for (JsonElement e : c.getAsJsonArray("ops")) {
JsonObject op = e.getAsJsonObject();
switch (op.get("op").getAsString()) {
case "time" -> nanos = op.get("ms").getAsLong() * 1_000_000L + op.get("sub").getAsLong();
case "play" -> {
Vec3 at = vec(op.get("at"));
JsonElement key = op.get("key");
WeighedSoundEvents event = new WeighedSoundEvents(Identifier.withDefaultNamespace("test"), key.isJsonNull() ? null : key.getAsString());
SoundInstance sound = new SimpleSoundInstance(Identifier.withDefaultNamespace("test"), SoundSource.MASTER, 1.0F, 1.0F,
RandomSource.create(0L), op.get("looping").getAsBoolean(), 0, SoundInstance.Attenuation.LINEAR, at.x, at.y, at.z, false);
float range = op.get("range").isJsonNull() ? Float.POSITIVE_INFINITY : op.get("range").getAsFloat();
for (SoundEventListener listener : List.copyOf(sounds.listeners)) {
listener.onPlaySound(sound, event, range);
}
}
case "frame" -> {
sounds.transform = new ListenerTransform(vec(op.get("pos")), vec(op.get("forward")), vec(op.get("up")));
option(options, "showSubtitles", op.get("show").getAsBoolean());
option(options, "notificationDisplayTime", op.get("mult").getAsDouble());
option(options, "textBackgroundOpacity", op.get("opacity").getAsDouble());
option(options, "backgroundForChatOnly", op.get("chat_only").getAsBoolean());
Capture g = alloc(Capture.class);
g.draws = new JsonArray();
g.stack = new Matrix3x2fStack(16);
g.width = op.get("w").getAsInt();
g.height = op.get("h").getAsInt();
overlay.extractRenderState(g);
frames.add(g.draws);
}
default -> throw new IllegalArgumentException(op.toString());
}
}
result.add("frames", frames);
} catch (Throwable t) {
result.addProperty("error", t.toString());
}
out.append(gson.toJson(result)).append('\n');
}
Files.writeString(Path.of(args[1]), out.toString(), StandardCharsets.UTF_8);
}
}
+172
View File
@@ -0,0 +1,172 @@
#!/usr/bin/env python3
"""Compare Horizon's subtitle overlay with the vanilla 26.3 client's SubtitleOverlay.
The Java oracle (VanillaSubtitleOracle) runs vanilla's own SubtitleOverlay with a
stand-in client: sounds the sound engine reports to its listeners (subtitles from
sounds.json, unknown keys and sounds without one; positions; ranges, infinite for
relative and unattenuated sounds; looping) at controlled times of Util.getMillis,
and frames that render it for a listener transform (position, forward and up
vectors), the subtitle option turned on or off (it starts and stops listening as
it renders), the notification display time, the text background opacity and its
"chat only" setting, and a GUI size. Each frame records the fills and texts in
order with the pose: which subtitles show, their order, merging of repeats,
expiry, the fade by age (looping sounds stay bright longer), the direction
arrows and the box width. `examples/subtitle_fixture` replays the cases through
`horizon_client::subtitles`; the frames must agree exactly.
test_subtitle_parity.py [--count N] [--detail N]
"""
import argparse
import json
import math
import os
import random
import subprocess
import sys
from pathlib import Path
try:
from . import lab, test_rust_parity as base, test_model_baking_parity as baking
except ImportError:
import lab
import test_rust_parity as base
import test_model_baking_parity as baking
PARITY = lab.ROOT / 'mods/horizon/src/test/java/dev/horizonlab/parity'
def subtitle_keys(resources):
sounds = json.loads((resources / 'assets/minecraft/sounds.json').read_text())
keys = sorted({v['subtitle'] for v in sounds.values() if isinstance(v, dict) and 'subtitle' in v})
return keys
def unit(rng):
while True:
v = [rng.uniform(-1, 1) for _ in range(3)]
n = math.sqrt(sum(x * x for x in v))
if n > 0.1:
return [x / n for x in v]
def listener(rng, pos):
yaw, pitch = rng.uniform(-180, 180), rng.uniform(-90, 90)
y, p = math.radians(yaw), math.radians(pitch)
forward = [-math.sin(y) * math.cos(p), -math.sin(p), math.cos(y) * math.cos(p)]
up = [-math.sin(y) * -math.sin(p), math.cos(p), math.cos(y) * -math.sin(p)]
if rng.random() < 0.2:
forward, up = rng.choice([([0.0, 0.0, -1.0], [0.0, 1.0, 0.0]), ([1.0, 0.0, 0.0], [0.0, 1.0, 0.0]),
([0.0, -1.0, 0.0], [0.0, 0.0, 1.0])])
return {'pos': pos, 'forward': forward, 'up': up}
def cases(count, keys):
rng = random.Random(0x5355425449544c45)
out = []
for n in range(count):
pool = rng.sample(keys, rng.choice([1, 3, 8, 20])) + ['subtitles.horizon.unknown']
t = rng.randint(0, 10_000_000)
pos = [rng.uniform(-100, 100), rng.uniform(-60, 300), rng.uniform(-100, 100)]
here = listener(rng, pos)
mult = rng.choice([0.5, 1.0, 1.0, 1.5, 2.0, 3.5, 10.0])
show = rng.random() < 0.9
opacity, chat_only = rng.choice([0.5, 0.0, 1.0, 0.25]), rng.random() < 0.6
size = rng.choice([(427, 240), (320, 240), (480, 270), (961, 501)])
ops = [{'op': 'time', 'ms': t, 'sub': rng.randint(0, 999999)}]
locations = [[pos[i] + rng.uniform(-30, 30) for i in range(3)] for _ in range(6)]
def frame():
nonlocal here
if rng.random() < 0.3:
here = listener(rng, [p + rng.uniform(-2, 2) for p in here['pos']])
return {'op': 'frame', **here, 'show': show, 'mult': mult, 'opacity': opacity, 'chat_only': chat_only,
'w': size[0], 'h': size[1]}
ops.append(frame())
for _ in range(rng.choice([5, 20, 60])):
r = rng.random()
if r < 0.45:
at = rng.choice(locations) if rng.random() < 0.6 else [here['pos'][i] + rng.uniform(-20, 20) for i in range(3)]
if rng.random() < 0.05:
at = list(here['pos'])
key = rng.choice(pool) if rng.random() < 0.9 else None
rng_range = rng.choice([16.0, 16.0, 8.0, 48.0, 2.5, 100.0, None])
ops.append({'op': 'play', 'key': key, 'at': at, 'range': rng_range, 'looping': rng.random() < 0.15})
elif r < 0.75:
t += rng.choice([0, 1, 16, 50, 499, 500, 501, 1000, 2999, 3000, 3001, rng.randint(0, 8000)])
ops.append({'op': 'time', 'ms': t, 'sub': rng.randint(0, 999999)})
else:
if rng.random() < 0.08:
show = not show
if rng.random() < 0.05:
mult = rng.choice([0.5, 1.0, 2.0, 10.0])
ops.append(frame())
ops.append(frame())
out.append({'case': n, 'ops': ops})
return out
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--count', type=int, default=1500)
parser.add_argument('--detail', type=int, default=3)
args = parser.parse_args()
lock, jars, _ = base.verify_artifacts()
libraries = baking.client_libraries()
resources = lab.LOCAL / 'horizon-client' / '26.3'
build = lab.LOCAL / 'subtitle-parity'
build.mkdir(parents=True, exist_ok=True)
classes = build / 'classes'
classes.mkdir(exist_ok=True)
dependencies = os.pathsep.join(map(str, [jars['client'], *libraries]))
def run(command, name):
with (build / (name + '.log')).open('w') as log:
result = subprocess.run(list(map(str, command)), cwd=lab.ROOT, timeout=3600, stdout=log, stderr=subprocess.STDOUT)
if result.returncode:
print((build / (name + '.log')).read_text()[-4000:])
sys.exit(f'{name} failed')
chosen = cases(args.count, subtitle_keys(resources))
inputs = build / 'inputs.jsonl'
inputs.write_text(''.join(json.dumps(c) + '\n' for c in chosen))
run(['javac', '--release', lock['minecraft']['java_major'], '-proc:none', '-nowarn', '-cp', dependencies, '-d', classes,
*(PARITY / f'{n}.java' for n in ('ParityFont', 'VanillaSubtitleOracle'))], 'compile-java')
run(['java', '-Xmx1G', '-cp', str(classes) + os.pathsep + dependencies, 'dev.horizonlab.parity.VanillaSubtitleOracle',
inputs, build / 'vanilla.jsonl'], 'vanilla')
run(['cargo', 'build', '--release', '-p', 'horizon-client', '--example', 'subtitle_fixture'], 'compile-rust')
metadata = json.loads(subprocess.check_output(['cargo', 'metadata', '--no-deps', '--format-version', '1'], cwd=lab.ROOT, text=True))
binary = Path(metadata['target_directory']) / 'release/examples' / ('subtitle_fixture.exe' if os.name == 'nt' else 'subtitle_fixture')
run([binary, resources, inputs, build / 'rust.jsonl'], 'rust')
vanilla = [json.loads(l) for l in (build / 'vanilla.jsonl').read_text(encoding='utf-8').splitlines()]
rust = [json.loads(l) for l in (build / 'rust.jsonl').read_text(encoding='utf-8').splitlines()]
assert len(vanilla) == len(rust) == len(chosen)
errors = [v for v in vanilla if 'error' in v]
bad, frames, drawn = [], 0, 0
for c, v, r in zip(chosen, vanilla, rust):
if 'error' in v:
continue
frames += len(v['frames'])
drawn += sum(1 for f in v['frames'] if f)
for i, (a, b) in enumerate(zip(v['frames'], r['frames'])):
if a != b:
bad.append((c, i, a, b))
break
else:
if len(v['frames']) != len(r['frames']):
bad.append((c, len(r['frames']), v['frames'][len(r['frames']):][:1], []))
for v in errors[:3]:
print('ORACLE ERROR', v['case'], v['error'])
for c, i, a, b in bad[:args.detail]:
first = next((j for j, (x, y) in enumerate(zip(a, b)) if x != y), min(len(a), len(b)))
print(f'MISMATCH case {c["case"]} frame {i} at draw {first} ({len(a)} vanilla, {len(b)} Horizon draws)')
print(' vanilla', json.dumps(a[first:first + 2], ensure_ascii=False))
print(' horizon', json.dumps(b[first:first + 2], ensure_ascii=False))
print(f'{len(chosen) - len(bad) - len(errors)}/{len(chosen)} subtitle cases match '
f'({frames} frames, {drawn} with subtitles); {len(errors)} oracle errors')
if bad or errors:
sys.exit(1)
print('subtitle parity ok')
if __name__ == '__main__':
main()