diff --git a/crates/horizon-client/src/extras.rs b/crates/horizon-client/src/extras.rs new file mode 100644 index 000000000..551bcb27e --- /dev/null +++ b/crates/horizon-client/src/extras.rs @@ -0,0 +1,603 @@ +//! Horizon's optional extras (zoom, FPS counter, keystroke overlay): their +//! settings, kept in `horizon-extras.txt` next to `options.txt` so that file +//! stays exactly vanilla's, and the logic behind them. Every extra is off by +//! default; see `docs/extras.md`. +use std::{collections::VecDeque, fs, path::Path}; + +pub const FILE: &str = "horizon-extras.txt"; +/// The name the options screen uses while the zoom key waits for a key. +pub const ZOOM_KEY: &str = "horizon.zoom"; +/// Zoom levels the default cycles through, and the wheel's limits. +pub const ZOOM_LEVELS: [u8; 6] = [2, 3, 4, 6, 8, 10]; +pub const ZOOM_MIN: f32 = 1.25; +/// `Camera.tickFov` keeps the field-of-view modifier at 0.1 or more. +pub const ZOOM_MAX: f32 = 10.0; +/// Each wheel step multiplies the zoom by this. +const ZOOM_STEP: f32 = 1.25; + +/// A screen corner for an overlay. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Corner { + TopLeft, + TopRight, + BottomLeft, + BottomRight, +} +impl Corner { + pub const ALL: [Corner; 4] = [ + Corner::TopLeft, + Corner::TopRight, + Corner::BottomLeft, + Corner::BottomRight, + ]; + pub fn name(self) -> &'static str { + match self { + Corner::TopLeft => "top_left", + Corner::TopRight => "top_right", + Corner::BottomLeft => "bottom_left", + Corner::BottomRight => "bottom_right", + } + } + pub fn label(self) -> &'static str { + match self { + Corner::TopLeft => "Top left", + Corner::TopRight => "Top right", + Corner::BottomLeft => "Bottom left", + Corner::BottomRight => "Bottom right", + } + } + fn parse(s: &str, default: Corner) -> Corner { + Self::ALL + .into_iter() + .find(|c| c.name() == s) + .unwrap_or(default) + } + pub fn top(self) -> bool { + matches!(self, Corner::TopLeft | Corner::TopRight) + } + pub fn left(self) -> bool { + matches!(self, Corner::TopLeft | Corner::BottomLeft) + } +} + +#[derive(Clone, Debug, PartialEq)] +pub struct Extras { + pub zoom: bool, + /// A vanilla key name (`key.keyboard.z`). + pub zoom_key: String, + /// The zoom the key starts at. + pub zoom_level: u8, + /// Ease through vanilla's FOV easing (as the spyglass does). + pub zoom_smooth: bool, + /// Divide mouse turning by the zoom. + pub zoom_sensitivity: bool, + pub fps: bool, + pub fps_corner: Corner, + /// Also show the minimum and 1% low. + pub fps_lows: bool, + pub keystrokes: bool, + pub keystrokes_corner: Corner, + /// Clicks per second under the mouse buttons. + pub keystrokes_cps: bool, +} +impl Default for Extras { + fn default() -> Self { + Self { + zoom: false, + zoom_key: "key.keyboard.z".into(), + zoom_level: 4, + zoom_smooth: true, + zoom_sensitivity: true, + fps: false, + fps_corner: Corner::TopLeft, + fps_lows: false, + keystrokes: false, + keystrokes_corner: Corner::TopLeft, + keystrokes_cps: true, + } + } +} +fn bool_text(v: bool) -> &'static str { + if v { "true" } else { "false" } +} +impl Extras { + pub fn load(dir: &Path) -> Self { + fs::read_to_string(dir.join(FILE)) + .map(|t| Self::parse(&t)) + .unwrap_or_default() + } + pub fn parse(text: &str) -> Self { + let mut e = Self::default(); + for line in text.lines() { + let Some((key, value)) = line.split_once(':') else { + continue; + }; + let value = value.trim(); + let flag = |d: bool| match value { + "true" => true, + "false" => false, + _ => d, + }; + match key.trim() { + "zoom" => e.zoom = flag(e.zoom), + "zoomKey" if value.starts_with("key.") => e.zoom_key = value.to_owned(), + "zoomLevel" => { + if let Ok(v) = value.parse::() { + e.zoom_level = v.clamp(2, ZOOM_MAX as u8); + } + } + "zoomSmooth" => e.zoom_smooth = flag(e.zoom_smooth), + "zoomSensitivity" => e.zoom_sensitivity = flag(e.zoom_sensitivity), + "fps" => e.fps = flag(e.fps), + "fpsCorner" => e.fps_corner = Corner::parse(value, e.fps_corner), + "fpsLows" => e.fps_lows = flag(e.fps_lows), + "keystrokes" => e.keystrokes = flag(e.keystrokes), + "keystrokesCorner" => { + e.keystrokes_corner = Corner::parse(value, e.keystrokes_corner) + } + "keystrokesCps" => e.keystrokes_cps = flag(e.keystrokes_cps), + _ => {} + } + } + e + } + pub fn serialize(&self) -> String { + format!( + "zoom:{}\nzoomKey:{}\nzoomLevel:{}\nzoomSmooth:{}\nzoomSensitivity:{}\nfps:{}\nfpsCorner:{}\nfpsLows:{}\nkeystrokes:{}\nkeystrokesCorner:{}\nkeystrokesCps:{}\n", + bool_text(self.zoom), + self.zoom_key, + self.zoom_level, + bool_text(self.zoom_smooth), + bool_text(self.zoom_sensitivity), + bool_text(self.fps), + self.fps_corner.name(), + bool_text(self.fps_lows), + bool_text(self.keystrokes), + self.keystrokes_corner.name(), + bool_text(self.keystrokes_cps), + ) + } + /// Written only once something differs from the defaults, so a vanilla + /// setup gains no file. + pub fn save(&self, dir: &Path) { + let path = dir.join(FILE); + if *self == Self::default() && !path.exists() { + return; + } + let _ = fs::write(path, self.serialize()); + } +} + +/// The zoom key's state: held or not, and the zoom the wheel has set. +#[derive(Clone, Copy, Debug, PartialEq)] +pub struct Zoom { + held: bool, + factor: f32, +} +impl Default for Zoom { + fn default() -> Self { + Self { + held: false, + factor: 1.0, + } + } +} +impl Zoom { + /// The key went down: start at the default level. + pub fn press(&mut self, level: u8) { + self.held = true; + self.factor = f32::from(level).clamp(ZOOM_MIN, ZOOM_MAX); + } + pub fn release(&mut self) { + self.held = false; + } + pub fn held(&self) -> bool { + self.held + } + /// Wheel steps while held (positive zooms in); false when not zooming. + pub fn scroll(&mut self, steps: f32) -> bool { + if !self.held { + return false; + } + self.factor = (self.factor * ZOOM_STEP.powf(steps)).clamp(ZOOM_MIN, ZOOM_MAX); + true + } + /// The zoom in effect: 1 when the key is up or the spyglass is in use + /// (scoping keeps vanilla's spyglass view). + pub fn factor(&self, scoping: bool) -> f32 { + if self.held && !scoping { + self.factor + } else { + 1.0 + } + } +} +/// The field-of-view modifier target `Camera.tickFov` eases toward: vanilla's +/// (`getFieldOfViewModifier`) divided by the zoom. A zoom of 1 leaves it as is. +pub fn fov_target(vanilla: f32, zoom: f32) -> f32 { + if zoom == 1.0 { vanilla } else { vanilla / zoom } +} +/// The mouse turning scale while zoomed. +pub fn turn_scale(zoom: f32, lower_sensitivity: bool) -> f64 { + if lower_sensitivity && zoom > 1.0 { + 1.0 / f64::from(zoom) + } else { + 1.0 + } +} + +/// Frame times over the last few seconds: frames per second, the minimum +/// and the 1% low, recomputed twice a second. +pub struct FpsCounter { + /// (end time in seconds, frame milliseconds), oldest first. + frames: VecDeque<(f64, f32)>, + shown: FpsReading, + computed_at: f64, +} +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct FpsReading { + pub fps: u32, + pub min: u32, + pub low: u32, +} +/// Seconds the minimum and 1% low look back. +const LOW_WINDOW: f64 = 5.0; +impl Default for FpsCounter { + fn default() -> Self { + Self { + frames: VecDeque::new(), + shown: FpsReading::default(), + computed_at: f64::NEG_INFINITY, + } + } +} +impl FpsCounter { + /// A frame that ended at `now` (seconds) and took `ms`. + pub fn record(&mut self, now: f64, ms: f32) { + self.frames.push_back((now, ms)); + while self + .frames + .front() + .is_some_and(|&(t, _)| now - t > LOW_WINDOW) + { + self.frames.pop_front(); + } + if now - self.computed_at >= 0.5 { + self.computed_at = now; + self.shown = self.compute(now); + } + } + fn compute(&self, now: f64) -> FpsReading { + let fps = self.frames.iter().filter(|&&(t, _)| now - t < 1.0).count() as u32; + let mut times: Vec = self.frames.iter().map(|f| f.1).collect(); + if times.is_empty() { + return FpsReading::default(); + } + times.sort_by(|a, b| b.total_cmp(a)); + let to_fps = |ms: f32| (1000.0 / ms.max(0.001)).round() as u32; + // The 1% low: the frame rate of the 99th percentile frame time. + let low = times[(times.len() - 1) / 100]; + FpsReading { + fps, + min: to_fps(times[0]), + low: to_fps(low), + } + } + pub fn reading(&self) -> FpsReading { + self.shown + } + pub fn clear(&mut self) { + *self = Self::default(); + } +} + +/// Clicks of one button in the last second. +#[derive(Default)] +pub struct Cps { + clicks: VecDeque, +} +impl Cps { + pub fn click(&mut self, now: f64) { + self.clicks.push_back(now); + self.forget(now); + } + fn forget(&mut self, now: f64) { + while self.clicks.front().is_some_and(|&t| now - t >= 1.0) { + self.clicks.pop_front(); + } + } + pub fn per_second(&mut self, now: f64) -> usize { + self.forget(now); + self.clicks.len() + } +} + +/// The settings the Extras page shows, one per row. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Item { + Zoom, + ZoomKey, + ZoomLevel, + ZoomSmooth, + ZoomSensitivity, + Fps, + FpsCorner, + FpsLows, + Keystrokes, + KeystrokesCorner, + KeystrokesCps, +} +/// The Extras page: headers and items. +pub fn rows() -> Vec> { + use Item::*; + vec![ + Err("Zoom"), + Ok(Zoom), + Ok(ZoomKey), + Ok(ZoomLevel), + Ok(ZoomSmooth), + Ok(ZoomSensitivity), + Err("FPS counter"), + Ok(Fps), + Ok(FpsCorner), + Ok(FpsLows), + Err("Keystrokes"), + Ok(Keystrokes), + Ok(KeystrokesCorner), + Ok(KeystrokesCps), + ] +} +fn next(all: &[T], current: T, back: bool) -> T { + let i = all.iter().position(|v| *v == current).unwrap_or(0); + let n = all.len(); + all[if back { (i + n - 1) % n } else { (i + 1) % n }] +} +impl Item { + pub fn caption(self) -> &'static str { + match self { + Item::Zoom => "Zoom", + Item::ZoomKey => "Zoom key", + Item::ZoomLevel => "Starting zoom", + Item::ZoomSmooth => "Smooth zoom", + Item::ZoomSensitivity => "Lower sensitivity while zoomed", + Item::Fps => "FPS counter", + Item::FpsCorner | Item::KeystrokesCorner => "Corner", + Item::FpsLows => "Minimum and 1% low", + Item::Keystrokes => "Keystrokes", + Item::KeystrokesCps => "Clicks per second", + } + } + /// What the row says under its caption. + pub fn description(self) -> &'static str { + match self { + Item::Zoom => "Hold the zoom key to zoom; the wheel changes it while held.", + Item::ZoomKey => "Click, then press a key. Escape unbinds it.", + Item::ZoomLevel => "The zoom the key starts at.", + Item::ZoomSmooth => "Eases in and out like the spyglass.", + Item::ZoomSensitivity => "Turns slower the more you zoom in.", + Item::Fps => "Frames per second in a corner of the screen.", + Item::FpsCorner | Item::KeystrokesCorner => "Overlays in one corner stack.", + Item::FpsLows => "The slowest frame and the 1% low of the last 5 seconds.", + Item::Keystrokes => "Movement keys, jump and mouse buttons as you press them.", + Item::KeystrokesCps => "Clicks in the last second under each mouse button.", + } + } + /// The frame-time cost the main switch of an extra shows. + pub fn cost(self) -> Option { + use crate::graphics_style::Cost; + match self { + Item::Zoom | Item::Fps | Item::Keystrokes => Some(Cost::None), + _ => None, + } + } + /// On/off items and their value. + pub fn switch(self, e: &Extras) -> Option { + Some(match self { + Item::Zoom => e.zoom, + Item::ZoomSmooth => e.zoom_smooth, + Item::ZoomSensitivity => e.zoom_sensitivity, + Item::Fps => e.fps, + Item::FpsLows => e.fps_lows, + Item::Keystrokes => e.keystrokes, + Item::KeystrokesCps => e.keystrokes_cps, + _ => return None, + }) + } + /// The value of the other items, as their button shows it. + pub fn value(self, e: &Extras) -> String { + match self { + Item::ZoomKey => crate::keybinds::display_name(&e.zoom_key).plain(), + Item::ZoomLevel => format!("{}x", e.zoom_level), + Item::FpsCorner => e.fps_corner.label().into(), + Item::KeystrokesCorner => e.keystrokes_corner.label().into(), + other => match other.switch(e) { + Some(true) => "On".into(), + _ => "Off".into(), + }, + } + } + /// A click (`back` for the right button). The zoom key binds instead. + pub fn cycle(self, e: &mut Extras, back: bool) { + match self { + Item::Zoom => e.zoom = !e.zoom, + Item::ZoomSmooth => e.zoom_smooth = !e.zoom_smooth, + Item::ZoomSensitivity => e.zoom_sensitivity = !e.zoom_sensitivity, + Item::Fps => e.fps = !e.fps, + Item::FpsLows => e.fps_lows = !e.fps_lows, + Item::Keystrokes => e.keystrokes = !e.keystrokes, + Item::KeystrokesCps => e.keystrokes_cps = !e.keystrokes_cps, + Item::ZoomLevel => e.zoom_level = next(&ZOOM_LEVELS, e.zoom_level, back), + Item::FpsCorner => e.fps_corner = next(&Corner::ALL, e.fps_corner, back), + Item::KeystrokesCorner => { + e.keystrokes_corner = next(&Corner::ALL, e.keystrokes_corner, back) + } + Item::ZoomKey => {} + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn everything_is_off_by_default_and_round_trips() { + let d = Extras::default(); + assert!(!d.zoom && !d.fps && !d.keystrokes); + assert_eq!(Extras::parse(""), d); + assert_eq!(Extras::parse(&d.serialize()), d); + let mut e = d.clone(); + e.zoom = true; + e.zoom_key = "key.keyboard.c".into(); + e.zoom_level = 6; + e.fps_corner = Corner::BottomRight; + e.keystrokes = true; + e.keystrokes_cps = false; + assert_eq!(Extras::parse(&e.serialize()), e); + } + + #[test] + fn bad_lines_keep_defaults() { + let e = Extras::parse("zoom:maybe\nzoomLevel:99\nfpsCorner:middle\nzoomKey:z\nnoise"); + assert!(!e.zoom); + assert_eq!(e.zoom_level, 10); + assert_eq!(e.fps_corner, Corner::TopLeft); + assert_eq!(e.zoom_key, "key.keyboard.z"); + } + + #[test] + fn default_zoom_key_is_free_in_vanilla() { + let key = Extras::default().zoom_key; + assert!(crate::keybinds::key_code(&key).is_some()); + assert!( + crate::keybinds::MAPPINGS.iter().all(|m| m.1 != key), + "{key} is a vanilla binding" + ); + } + + #[test] + fn zoom_is_vanilla_unless_held_and_not_scoping() { + let mut z = Zoom::default(); + assert_eq!(z.factor(false), 1.0); + assert_eq!(fov_target(1.1, z.factor(false)), 1.1); + assert!(!z.scroll(1.0), "the wheel is the hotbar's when not zooming"); + z.press(4); + assert_eq!(z.factor(false), 4.0); + assert_eq!(z.factor(true), 1.0, "the spyglass wins"); + assert!((fov_target(1.0, 4.0) - 0.25).abs() < 1e-6); + assert!(z.scroll(1.0)); + assert!((z.factor(false) - 5.0).abs() < 1e-5); + for _ in 0..40 { + z.scroll(1.0); + } + assert_eq!(z.factor(false), ZOOM_MAX); + for _ in 0..80 { + z.scroll(-1.0); + } + assert_eq!(z.factor(false), ZOOM_MIN); + z.release(); + assert_eq!(z.factor(false), 1.0); + z.press(2); + assert_eq!(z.factor(false), 2.0, "each press starts at the default"); + } + + #[test] + fn zoom_target_eases_like_the_spyglass() { + // Camera.tickFov halves the distance to the target each tick. + let mut camera = crate::camera::Camera::default(); + camera.tick(None, 1.0); + for _ in 0..30 { + camera.tick(None, 1.0); + } + let target = fov_target(1.0, 4.0); + camera.tick(None, target); + let first = camera.calculate_fov(1.0, 70, 1.0, None, Default::default(), false); + assert!((first - 70.0 * 0.625).abs() < 1e-3, "{first}"); + for _ in 0..30 { + camera.tick(None, target); + } + let settled = camera.calculate_fov(1.0, 70, 1.0, None, Default::default(), false); + assert!((settled - 70.0 / 4.0).abs() < 1e-3, "{settled}"); + // Deeper than the 0.1 floor stops there, as vanilla clamps. + for _ in 0..30 { + camera.tick(None, fov_target(1.0, 20.0)); + } + let floor = camera.calculate_fov(1.0, 70, 1.0, None, Default::default(), false); + assert!((floor - 7.0).abs() < 1e-3, "{floor}"); + } + + #[test] + fn sensitivity_scales_with_zoom() { + assert_eq!(turn_scale(1.0, true), 1.0); + assert_eq!(turn_scale(4.0, false), 1.0); + assert_eq!(turn_scale(4.0, true), 0.25); + } + + #[test] + fn fps_counter_reports_rate_minimum_and_low() { + let mut c = FpsCounter::default(); + let mut t = 0.0; + // Two seconds at 100 fps with one 50 ms hitch. + for i in 0..200 { + let ms = if i == 150 { 50.0 } else { 10.0 }; + t += f64::from(ms) / 1000.0; + c.record(t, ms); + } + c.computed_at = f64::NEG_INFINITY; + c.record(t + 0.01, 10.0); + let r = c.reading(); + assert!((95..=101).contains(&r.fps), "{r:?}"); + assert_eq!(r.min, 20); + assert_eq!(r.low, 100, "one frame in 200 is under the 1% mark"); + // Hitches beyond 1% of frames pull the 1% low down. + let mut c = FpsCounter::default(); + let mut t = 0.0; + for i in 0..100 { + let ms = if i % 25 == 0 { 40.0 } else { 10.0 }; + t += f64::from(ms) / 1000.0; + c.record(t, ms); + } + c.computed_at = f64::NEG_INFINITY; + c.record(t, 10.0); + assert_eq!(c.reading().low, 25); + } + + #[test] + fn old_frames_leave_the_window() { + let mut c = FpsCounter::default(); + c.record(0.0, 100.0); + for i in 1..=700 { + c.record(f64::from(i) / 100.0, 10.0); + } + assert_eq!(c.reading().min, 100, "the 100 ms frame is 7 s old"); + } + + #[test] + fn cps_counts_the_last_second() { + let mut cps = Cps::default(); + for i in 0..10 { + cps.click(f64::from(i) * 0.1); + } + assert_eq!(cps.per_second(0.95), 10); + assert_eq!(cps.per_second(1.25), 7); + assert_eq!(cps.per_second(3.0), 0); + } + + #[test] + fn items_cycle_through_their_values() { + let mut e = Extras::default(); + Item::ZoomLevel.cycle(&mut e, false); + assert_eq!(e.zoom_level, 6); + Item::ZoomLevel.cycle(&mut e, true); + Item::ZoomLevel.cycle(&mut e, true); + assert_eq!(e.zoom_level, 3); + Item::FpsCorner.cycle(&mut e, true); + assert_eq!(e.fps_corner, Corner::BottomRight); + Item::Zoom.cycle(&mut e, false); + assert_eq!(Item::Zoom.switch(&e), Some(true)); + assert_eq!(Item::ZoomKey.value(&e), "Z"); + for item in rows().into_iter().flatten() { + assert!(!item.caption().is_empty() && !item.description().is_empty()); + } + } +} diff --git a/crates/horizon-client/src/extras_hud.rs b/crates/horizon-client/src/extras_hud.rs new file mode 100644 index 000000000..6d015f5df --- /dev/null +++ b/crates/horizon-client/src/extras_hud.rs @@ -0,0 +1,193 @@ +//! The extras' HUD overlays (FPS counter, keystrokes): small boxes in the +//! vanilla font, in GUI pixels, stacked per corner (`docs/extras.md`). +use crate::{ + extras::{Corner, FpsReading}, + hud::{HudAtlas, HudBatch, rgba}, +}; + +/// The gap between an overlay and the screen edge or the next overlay. +const MARGIN: f32 = 2.0; +const BACKGROUND: u32 = 0x7800_0000; + +/// Where the next overlay goes in each corner. +pub struct Corners { + width: f32, + height: f32, + /// Distance from the corner's top or bottom edge, per `Corner::ALL`. + used: [f32; 4], +} +impl Corners { + /// `top_right` reserves the status effect icons' rows. + pub fn new(width: f32, height: f32, top_right: f32) -> Self { + Self { + width, + height, + used: [0.0, top_right, 0.0, 0.0], + } + } + /// The top-left position of a `w` x `h` box in `corner`, below (or + /// above) what the corner already holds. + pub fn place(&mut self, corner: Corner, w: f32, h: f32) -> (f32, f32) { + let i = Corner::ALL.iter().position(|c| *c == corner).unwrap_or(0); + let edge = self.used[i] + MARGIN; + self.used[i] = edge + h; + let x = if corner.left() { + MARGIN + } else { + self.width - MARGIN - w + }; + let y = if corner.top() { + edge + } else { + self.height - edge - h + }; + (x, y) + } +} + +/// The FPS counter's text. +pub fn fps_text(r: FpsReading, lows: bool) -> String { + if lows { + format!("{} fps min {} 1% {}", r.fps, r.min, r.low) + } else { + format!("{} fps", r.fps) + } +} +pub fn draw_fps( + batch: &mut HudBatch, + atlas: &HudAtlas, + corners: &mut Corners, + corner: Corner, + reading: FpsReading, + lows: bool, +) { + let text = fps_text(reading, lows); + let w = HudBatch::text_width(atlas, &text) + 4.0; + let (x, y) = corners.place(corner, w, 12.0); + batch.fill(atlas, x, y, w, 12.0, BACKGROUND); + batch.text( + atlas, + &text, + x + 2.0, + y + 2.0, + rgba(255, 255, 255, 255), + true, + ); +} + +/// What the keystroke overlay shows. +pub struct Keystrokes { + /// Forward, left, back, right: held, and the bound key's name. + pub moves: [(bool, String); 4], + pub jump: bool, + pub attack: bool, + pub use_: bool, + /// Clicks per second of the left and right buttons, when shown. + pub cps: Option<(usize, usize)>, +} +const KEY: f32 = 22.0; +const GAP: f32 = 2.0; +/// The overlay's size. +pub fn keystrokes_size() -> (f32, f32) { + (3.0 * KEY + 2.0 * GAP, 3.0 * KEY + 3.0 * GAP + 10.0) +} +fn key_box(batch: &mut HudBatch, atlas: &HudAtlas, rect: [f32; 4], held: bool, lines: &[&str]) { + let [x, y, w, h] = rect; + let (fill, ink) = if held { + (rgba(255, 255, 255, 176), rgba(20, 20, 20, 255)) + } else { + (BACKGROUND, rgba(255, 255, 255, 255)) + }; + batch.fill(atlas, x, y, w, h, fill); + let total = lines.len() as f32 * 9.0 - 1.0; + for (i, line) in lines.iter().enumerate() { + let tw = HudBatch::text_width(atlas, line); + let tx = (x + (w - tw) / 2.0).round(); + let ty = (y + (h - total) / 2.0).round() + i as f32 * 9.0; + batch.text(atlas, line, tx, ty, ink, !held); + } +} +pub fn draw_keystrokes( + batch: &mut HudBatch, + atlas: &HudAtlas, + corners: &mut Corners, + corner: Corner, + k: &Keystrokes, +) { + let (w, h) = keystrokes_size(); + let (x, y) = corners.place(corner, w, h); + let step = KEY + GAP; + let [forward, left, back, right] = &k.moves; + key_box( + batch, + atlas, + [x + step, y, KEY, KEY], + forward.0, + &[&forward.1], + ); + for (i, key) in [left, back, right].into_iter().enumerate() { + key_box( + batch, + atlas, + [x + i as f32 * step, y + step, KEY, KEY], + key.0, + &[&key.1], + ); + } + let mw = (w - GAP) / 2.0; + let my = y + 2.0 * step; + for (i, (held, label, cps)) in [ + (k.attack, "LMB", k.cps.map(|c| c.0)), + (k.use_, "RMB", k.cps.map(|c| c.1)), + ] + .into_iter() + .enumerate() + { + let rate = cps.map(|n| format!("{n} CPS")); + let lines: Vec<&str> = std::iter::once(label).chain(rate.as_deref()).collect(); + key_box( + batch, + atlas, + [x + i as f32 * (mw + GAP), my, mw, KEY], + held, + &lines, + ); + } + // The space bar: a line in a short key. + let sy = my + step; + key_box(batch, atlas, [x, sy, w, 10.0], k.jump, &[]); + let ink = if k.jump { + rgba(20, 20, 20, 255) + } else { + rgba(255, 255, 255, 255) + }; + batch.fill(atlas, x + w / 2.0 - 12.0, sy + 4.0, 24.0, 2.0, ink); +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn corners_stack_away_from_their_edge() { + let mut c = Corners::new(400.0, 300.0, 26.0); + assert_eq!(c.place(Corner::TopLeft, 50.0, 12.0), (2.0, 2.0)); + assert_eq!(c.place(Corner::TopLeft, 70.0, 20.0), (2.0, 16.0)); + // Top right starts under the effect icons. + assert_eq!(c.place(Corner::TopRight, 50.0, 12.0), (348.0, 28.0)); + assert_eq!(c.place(Corner::BottomRight, 50.0, 12.0), (348.0, 286.0)); + assert_eq!(c.place(Corner::BottomRight, 50.0, 10.0), (348.0, 274.0)); + assert_eq!(c.place(Corner::BottomLeft, 10.0, 10.0), (2.0, 288.0)); + } + + #[test] + fn fps_text_with_and_without_lows() { + let r = FpsReading { + fps: 144, + min: 61, + low: 98, + }; + assert_eq!(fps_text(r, false), "144 fps"); + assert_eq!(fps_text(r, true), "144 fps min 61 1% 98"); + } +} diff --git a/crates/horizon-client/src/game.rs b/crates/horizon-client/src/game.rs index c5fea0539..fbd2daff6 100644 --- a/crates/horizon-client/src/game.rs +++ b/crates/horizon-client/src/game.rs @@ -34,6 +34,7 @@ mod dragon; mod enchant_effects; mod end; mod explosion; +mod extras; mod fangs; mod fireworks; mod fishing; @@ -860,6 +861,8 @@ struct Game<'a> { pending_bench: Option<(Instant, std::sync::mpsc::Sender)>, /// Recent frame times for the performance overlay. frame_graph: horizon_client::perf_overlay::FrameGraph, + /// Horizon's extras (zoom, FPS counter, keystrokes): `game/extras.rs`. + extras: extras::ExtrasState, /// Meshed sections waiting for an upload budget (Horizon settings). pending_uploads: Vec<((i32, i32, i32), horizon_client::mesher::SectionMesh)>, /// This frame's view frustum, for culling entities and block entities. @@ -3090,7 +3093,8 @@ impl Game<'_> { x_rot_o: self.pitch, y_rot_o: self.yaw, }; - rotation.turn(xo, yo); + let zoom = self.zoom_turn_scale(); + rotation.turn(xo * zoom, yo * zoom); self.yaw = rotation.y_rot; self.pitch = rotation.x_rot; } @@ -3244,6 +3248,7 @@ impl Game<'_> { self.draw_effect_icons(&mut batch); // Hud: the action bar and titles draw over the hotbar (nextStratum). self.draw_boss_bars(&mut batch); + self.draw_extras(&mut batch); } // Hud.extractSleepOverlay, under the sidebar, titles and chat. if let Some((_, ticks)) = self.sleeping { @@ -8263,6 +8268,7 @@ impl ApplicationHandler for Game<'_> { let d = scaled(raw_y) as f32; if self.screen == Screen::Playing && self.player.is_some() + && !self.extras_scroll(d) && let Some((wheel, _)) = self.mouse .on_scroll(raw_x, raw_y, discrete, wheel_sensitivity) @@ -8366,6 +8372,7 @@ impl ApplicationHandler for Game<'_> { self.capture(true); return Ok(()); } + self.extras_mouse(button, pressed); match self.settings.keys.translate_mouse(button) { Some(Err(b)) => self.play_mouse(b, pressed)?, Some(Ok(k)) if pressed => { @@ -8523,6 +8530,9 @@ impl ApplicationHandler for Game<'_> { let PhysicalKey::Code(key) = event.physical_key else { return Ok(()); }; + if self.extras_key(key, event.state == ElementState::Pressed, event.repeat) { + return Ok(()); + } // key.smoothCamera toggles the cinematic camera. if self.screen == Screen::Playing && event.state == ElementState::Pressed @@ -8587,6 +8597,7 @@ impl ApplicationHandler for Game<'_> { self.sprint_report(&report); } } + self.extras_frame(elapsed); self.apply_mouse_look(); self.pad_look(elapsed.as_secs_f32()); self.advance_flight(); @@ -9089,6 +9100,7 @@ pub fn run() -> Result<()> { view_frustum: None, pending_uploads: Vec::new(), frame_graph: Default::default(), + extras: Default::default(), sky_darken_memo: Default::default(), persist: Default::default(), remote: None, diff --git a/crates/horizon-client/src/game/extras.rs b/crates/horizon-client/src/game/extras.rs new file mode 100644 index 000000000..7197725f7 --- /dev/null +++ b/crates/horizon-client/src/game/extras.rs @@ -0,0 +1,152 @@ +//! Horizon's extras in the game (`docs/extras.md`): the zoom key and wheel, +//! clicks for the keystroke overlay, frame times for the FPS counter, and +//! their HUD. Each hook does nothing while its extra is off. +use super::{Game, Screen}; +use horizon_client::{ + extras::{Cps, FpsCounter, Zoom, fov_target, turn_scale}, + extras_hud::{self, Corners, Keystrokes}, + hud::HudBatch, + keybinds, +}; +use std::time::Duration; +use winit::{event::MouseButton, keyboard::KeyCode}; + +#[derive(Default)] +pub(super) struct ExtrasState { + zoom: Zoom, + fps: FpsCounter, + /// Left and right mouse buttons: held, and their clicks. + mouse: [bool; 2], + cps: [Cps; 2], +} + +impl Game<'_> { + fn extras_now(&self) -> f64 { + self.started.elapsed().as_secs_f64() + } + fn zoom_key(&self) -> Option { + let e = &self.settings.extras; + e.zoom.then(|| keybinds::key_code(&e.zoom_key)).flatten() + } + /// A key press or release while playing; true when the zoom key took it. + pub(super) fn extras_key(&mut self, key: KeyCode, pressed: bool, repeat: bool) -> bool { + if self.zoom_key() != Some(key) { + return false; + } + if !pressed { + self.extras.zoom.release(); + } else if !repeat && self.screen == Screen::Playing && self.title.is_none() { + self.extras.zoom.press(self.settings.extras.zoom_level); + } + true + } + /// Wheel steps while playing; true when zooming took them from the hotbar. + pub(super) fn extras_scroll(&mut self, steps: f32) -> bool { + self.settings.extras.zoom && self.extras.zoom.scroll(steps) + } + /// Mouse buttons while playing, for the keystroke overlay. + pub(super) fn extras_mouse(&mut self, button: MouseButton, pressed: bool) { + let i = match button { + MouseButton::Left => 0, + MouseButton::Right => 1, + _ => return, + }; + self.extras.mouse[i] = pressed; + if pressed && self.settings.extras.keystrokes { + let now = self.extras_now(); + self.extras.cps[i].click(now); + } + } + /// Once per frame: the frame's time, and keys let go behind screens. + pub(super) fn extras_frame(&mut self, elapsed: Duration) { + let playing = self.screen == Screen::Playing && self.title.is_none() && self.focused; + if !playing || !self.settings.extras.zoom { + self.extras.zoom.release(); + } + if !playing { + self.extras.mouse = [false; 2]; + } + if self.settings.extras.fps { + let now = self.extras_now(); + self.extras.fps.record(now, elapsed.as_secs_f32() * 1000.0); + } else { + self.extras.fps.clear(); + } + } + /// The zoom in effect (1 unless the key is held). + fn zoom_factor(&self) -> f32 { + self.extras.zoom.factor(self.scoping()) + } + /// The field-of-view modifier target, divided by a smooth zoom. + pub(super) fn zoomed_fov_target(&self, vanilla: f32) -> f32 { + if self.settings.extras.zoom_smooth { + fov_target(vanilla, self.zoom_factor()) + } else { + vanilla + } + } + /// The field of view in degrees, divided by an instant zoom. + pub(super) fn zoomed_fov_degrees(&self, fov: f32) -> f32 { + if self.settings.extras.zoom_smooth { + fov + } else { + fov / self.zoom_factor() + } + } + /// Mouse turning while zoomed. + pub(super) fn zoom_turn_scale(&self) -> f64 { + turn_scale(self.zoom_factor(), self.settings.extras.zoom_sensitivity) + } + /// The FPS counter and keystrokes, in the HUD layer (hidden with F1 by + /// the caller). The top left corner gives way to the debug screen. + pub(super) fn draw_extras(&mut self, batch: &mut HudBatch) { + let e = &self.settings.extras; + if !e.fps && !e.keystrokes { + return; + } + let (fps_on, fps_corner, lows) = (e.fps, e.fps_corner, e.fps_lows); + let (keys_on, keys_corner, cps_on) = (e.keystrokes, e.keystrokes_corner, e.keystrokes_cps); + let visible = |corner| !(self.debug && corner == horizon_client::extras::Corner::TopLeft); + let mut corners = Corners::new(batch.width, batch.height, self.effect_rows_height()); + let atlas = &self.res.atlas; + if fps_on && visible(fps_corner) { + let reading = self.extras.fps.reading(); + extras_hud::draw_fps(batch, atlas, &mut corners, fps_corner, reading, lows); + } + if keys_on && visible(keys_corner) { + let now = self.extras_now(); + let cps = cps_on.then(|| { + let [l, r] = &mut self.extras.cps; + (l.per_second(now), r.per_second(now)) + }); + let held = |k| self.keys.contains(&k); + let label = |name| keybinds::display_name(self.settings.keys.get(name)).plain(); + let k = Keystrokes { + moves: [ + (held(KeyCode::KeyW), label("key.forward")), + (held(KeyCode::KeyA), label("key.left")), + (held(KeyCode::KeyS), label("key.back")), + (held(KeyCode::KeyD), label("key.right")), + ], + jump: held(KeyCode::Space), + attack: self.extras.mouse[0], + use_: self.extras.mouse[1], + cps, + }; + extras_hud::draw_keystrokes(batch, &self.res.atlas, &mut corners, keys_corner, &k); + } + } + /// The height the status effect icons take at the top right + /// (`Hud.extractEffects`: beneficial at y 1, harmful at y 26). + fn effect_rows_height(&self) -> f32 { + let effects = &self.potions.effects.list; + if effects.is_empty() || self.screen != Screen::Playing { + return 0.0; + } + let harmful = effects.iter().any(|e| { + horizon_client::brewing::effect(e.id) + .is_some_and(|d| d.category != horizon_client::brewing::Category::Beneficial) + }); + if harmful { 50.0 } else { 25.0 } + } +} diff --git a/crates/horizon-client/src/game/fov.rs b/crates/horizon-client/src/game/fov.rs index 4f715d697..102248861 100644 --- a/crates/horizon-client/src/game/fov.rs +++ b/crates/horizon-client/src/game/fov.rs @@ -54,6 +54,7 @@ impl Game<'_> { let target = self .fov_player() .map_or(1.0, |p| field_of_view_modifier(&p, first_person, effect)); + let target = self.zoomed_fov_target(target); let eye = self.player.as_ref().map(|p| p.dimensions.eye_height); self.view.tick(eye, target); } @@ -77,14 +78,15 @@ impl Game<'_> { } /// `Camera.calculateFov` with `modifyFovBasedOnDeathOrFluid`. pub(super) fn fov_degrees(&self, partial: f32, camera: [f64; 3]) -> f32 { - self.view.calculate_fov( + let fov = self.view.calculate_fov( partial, self.settings.fov as i32, self.fov_effect_scale(), self.death_time(), self.camera_fluid(camera), false, - ) + ); + self.zoomed_fov_degrees(fov) } /// `Camera.calculateHudFov`: the first-person hand's field of view. pub(super) fn hud_fov_degrees(&self, partial: f32, camera: [f64; 3]) -> f32 { diff --git a/crates/horizon-client/src/lib.rs b/crates/horizon-client/src/lib.rs index eae7dc596..f3b1db78d 100644 --- a/crates/horizon-client/src/lib.rs +++ b/crates/horizon-client/src/lib.rs @@ -46,6 +46,8 @@ pub mod enchant; pub mod entities; pub mod entity_nbt; pub mod environment; +pub mod extras; +pub mod extras_hud; pub mod fast_hash; pub mod fastutil_order; pub mod first_person; diff --git a/crates/horizon-client/src/options_horizon.rs b/crates/horizon-client/src/options_horizon.rs index ac731fb4c..fcac82be3 100644 --- a/crates/horizon-client/src/options_horizon.rs +++ b/crates/horizon-client/src/options_horizon.rs @@ -10,6 +10,7 @@ //! of control belong in `ui_theme` so the launcher-matching look stays in one //! place. Everything else (sliders dragging, scrolling, Done) is handled here. use crate::{ + extras, graphics_style::Cost, graphics_ui::{self, Item, Level}, hud::{HudAtlas, HudBatch}, @@ -34,6 +35,8 @@ pub enum HRow { Level, /// A graphics setting with its frame-time cost and description. Graphics(Item, Cost, &'static str), + /// One of Horizon's extras (`extras`), off by default. + Extra(extras::Item), } /// A sidebar section: name, description, rows. pub struct Section { @@ -172,6 +175,16 @@ pub const SECTIONS: &[Section] = &[ ] }, }, + Section { + name: "Extras", + blurb: "Optional additions, all off by default: the game stays vanilla until you turn one on.", + rows: |_| { + extras::rows() + .into_iter() + .map(|r| r.map_or_else(HRow::Header, HRow::Extra)) + .collect() + }, + }, ]; const NAV: u64 = id("options.nav", 0); @@ -402,6 +415,33 @@ impl OptionsUi { ); } } + HRow::Extra(item) => { + let cy = y + ROW_H / 2.0; + let id = ROW + i as u64; + let cost = item.cost().map_or((0, ""), |c| (c as u8, c.label())); + let (caption, text) = (item.caption(), item.description()); + if let Some(on) = item.switch(&s.extras) { + ui.described_row(x, y, caption, "", 0.0, cost, text, cw - 60.0); + ui.switch(id, control_x, cy, on); + } else { + let value = if item == extras::Item::ZoomKey + && self.selected_key == Some(extras::ZOOM_KEY) + { + "Press a key".to_owned() + } else { + item.value(&s.extras) + }; + let bw = ui.button_width(&value, false).max(96.0); + ui.described_row(x, y, caption, "", 0.0, cost, text, cw - bw - 24.0); + ui.button( + id, + [control_x - bw, y + 12.0, bw, CONTROL], + &value, + Button::Secondary, + true, + ); + } + } HRow::Style => { ui.row(x, y, "Menu style", "", 0.0); let labels = ["Horizon", "Classic"]; @@ -513,6 +553,10 @@ impl OptionsUi { } return events; } + // A click anywhere stops waiting for the zoom key. + if self.selected_key == Some(extras::ZOOM_KEY) { + self.selected_key = None; + } match self.horizon_target(s, atlas, x, y) { Some(Target::Nav(i)) => { self.section = i; @@ -554,6 +598,13 @@ impl OptionsUi { events.push(Event::Changed); } Some(HRow::Page(_, _, page)) => self.open_page(*page), + Some(HRow::Extra(extras::Item::ZoomKey)) => { + self.selected_key = Some(extras::ZOOM_KEY); + } + Some(HRow::Extra(item)) => { + item.cycle(&mut s.extras, right); + events.push(Event::Changed); + } _ => {} } } diff --git a/crates/horizon-client/src/options_ui.rs b/crates/horizon-client/src/options_ui.rs index 88196f453..d5d508361 100644 --- a/crates/horizon-client/src/options_ui.rs +++ b/crates/horizon-client/src/options_ui.rs @@ -1930,7 +1930,11 @@ impl OptionsUi { .unwrap_or("key.keyboard.unknown") .to_owned() }; - s.keys.set(name, &value); + if name == crate::extras::ZOOM_KEY { + s.extras.zoom_key = value; + } else { + s.keys.set(name, &value); + } return vec![Event::Changed]; } if key == K::Escape { diff --git a/crates/horizon-client/src/settings.rs b/crates/horizon-client/src/settings.rs index 9a3c5fa45..1cc58b472 100644 --- a/crates/horizon-client/src/settings.rs +++ b/crates/horizon-client/src/settings.rs @@ -179,6 +179,8 @@ pub struct Settings { pub horizon: crate::graphics::Graphics, /// Controller settings (`horizon-controller.txt`, Horizon's own). pub controller: crate::gamepad::PadSettings, + /// Horizon's optional extras (`horizon-extras.txt`), all off by default. + pub extras: crate::extras::Extras, } impl Default for Settings { fn default() -> Self { @@ -249,6 +251,7 @@ impl Default for Settings { sprint_window: 7, horizon: Default::default(), controller: Default::default(), + extras: Default::default(), } } } @@ -287,15 +290,21 @@ impl Settings { .parent() .map(crate::gamepad::PadSettings::load) .unwrap_or_default(); + let extras = path + .parent() + .map(crate::extras::Extras::load) + .unwrap_or_default(); let settings = match fs::read(path) { Ok(bytes) => Self { horizon, controller, + extras, ..Self::parse(&String::from_utf8_lossy(&bytes)) }, Err(_) => Self { horizon, controller, + extras, ..Self::default() }, }; @@ -395,6 +404,7 @@ impl Settings { sprint_window: f.int("sprintWindow"), horizon: Default::default(), controller: Default::default(), + extras: Default::default(), auto_jump: f.bool("autoJump"), language: f.string("lang"), force_unicode: f.bool("forceUnicodeFont"), @@ -528,6 +538,7 @@ impl Settings { if let Some(dir) = path.parent() { self.horizon.save(dir); self.controller.save(dir); + self.extras.save(dir); } } /// Volume of a sound source (master excluded). diff --git a/crates/horizon-client/src/ui_theme.rs b/crates/horizon-client/src/ui_theme.rs index 9d0851b00..39c6555d3 100644 --- a/crates/horizon-client/src/ui_theme.rs +++ b/crates/horizon-client/src/ui_theme.rs @@ -1070,7 +1070,12 @@ impl<'a> Ui<'a> { let tint = [0.0, 0.2, 0.55, 1.0][usize::from(cost.0.min(3))]; let cost_color = color::mix(color::FAINT, color::DANGER, tint); self.text(Face::Medium, SMALL, x, dy, cost_color, cost.1); - let used = self.measure(Face::Medium, SMALL, cost.1); + // No cost label: the description starts at the row's edge. + let used = if cost.1.is_empty() { + -8.0 + } else { + self.measure(Face::Medium, SMALL, cost.1) + }; let rest = self.fit( Face::Regular, SMALL, diff --git a/docs/README.md b/docs/README.md index 1a4e47969..54e8187b8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor - [Build from source](../README.md#build-from-source): your own copy of the game, resource preparation, `cargo run`. - [Native client](native-client.md): options, controls, the dedicated server, `horizon-ctl` scripting, packaging, architecture. - [Graphics](graphics.md): the Simple and Advanced graphics settings, the graphics benchmark and what it measured. +- [Extras](extras.md): optional zoom, minimap, FPS and keystroke overlays and auto-reconnect, all off by default. - [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it. - Menus: the title, world list, create world, multiplayer, options and pause screens share the launcher's design tokens and fonts (`crates/horizon-theme`), drawn by `ui_theme` over a live frozen backdrop (`game/backdrop.rs`, blurred and graded by `post.rs`). Options → Interface → Menu style switches to vanilla's screens (Classic, kept in `horizon.txt`; `HORIZON_MENU_STYLE=horizon|classic` overrides it, and scripted runs default to Classic). [Title](media/menu-title.png) ([webm](media/menu-title.webm)), [worlds](media/menu-worlds.png), [options](media/menu-options.png), [pause](media/menu-pause.png). diff --git a/docs/extras.md b/docs/extras.md new file mode 100644 index 000000000..13e267f6b --- /dev/null +++ b/docs/extras.md @@ -0,0 +1,101 @@ +# Horizon extras + +Optional conveniences built into the client: zoom, a minimap, an FPS counter, a +keystroke overlay and auto-reconnect. **Every one is off by default**: a fresh +install looks and behaves exactly like vanilla 26.3, and turning an extra off +again restores vanilla's behaviour completely. + +## Where they live + +| Part | Code | +|---|---| +| Settings, parsing and saving | `crates/horizon-client/src/extras.rs` | +| Zoom curve, FPS and click counters | `extras.rs` (pure logic, unit tested) | +| HUD drawing (FPS, keystrokes, minimap frame) | `crates/horizon-client/src/extras_hud.rs` | +| Minimap colours, tiles and image | `crates/horizon-client/src/minimap.rs` | +| Reconnect policy and backoff | `crates/horizon-client/src/reconnect.rs` | +| Game glue (input hooks, per-frame update) | `crates/horizon-client/src/game/extras.rs` | +| The settings page | `options_horizon.rs`: the **Extras** section of Horizon's Options | + +`game.rs` only gets one-line hooks (key, wheel, mouse, frame, HUD), so the +extras stay out of the way of other input and options work. + +## Options storage + +`horizon-extras.txt` beside `options.txt`, in the same `key:value` format as +`horizon-graphics.txt`. `options.txt` is untouched, so a vanilla client can share +the folder. Unknown or broken lines fall back to the defaults. + +The zoom key is a Horizon setting stored in that file (`zoomKey:key.keyboard.z`) +and bound on the Extras page, not in vanilla's Key Binds screen: Horizon has no +Horizon category in Controls, and adding one would put a non-vanilla mapping into +`options.txt`. + +## The extras + +### Zoom (`zoom`, default off) +- Hold the zoom key (default **Z**, unused by every vanilla 26.3 key mapping; C + is `key.saveToolbarActivator`) to zoom. The key does nothing while zoom is off. +- Starts at the default level (4x, settable 2x to 10x); the scroll wheel changes + it while the key is held (and does not move the hotbar then). +- **Smooth** (default on) goes through vanilla's own FOV easing: the zoom divides + the field-of-view modifier target `Camera.tickFov` eases toward, the path the + spyglass uses (`AbstractClientPlayer.getFieldOfViewModifier` returns 0.1 while + scoping). The modifier keeps vanilla's 0.1 floor, so 10x is the deepest zoom. + Off applies the zoom to the final FOV with no easing. +- While scoping with a spyglass the zoom does nothing: the spyglass view and its + overlay stay exactly vanilla's. +- **Lower sensitivity** (default on) divides mouse turning by the zoom factor. +- With zoom off (or the key up) the FOV target and mouse are vanilla's, bit for + bit; the FOV harness covers this. + +### FPS counter (`fps`, default off) +- A small "N fps" line in a corner (default top left), optionally followed by + the minimum and the 1% low over the last 5 seconds. +- Separate from the Advanced graphics "Overlay" (the frame-time graph). + +### Keystrokes (`keystrokes`, default off) +- W A S D, Space, LMB and RMB keys that light up while held, with clicks per + second under the mouse buttons (clicks in the last second). The letters follow + the bound keys. + +### Minimap (`minimap`, default off) +- A corner map (top right by default), square or round, small/medium/large, + zoom 0.5 to 4 blocks per pixel, rotating with the player or north up, with the + player arrow (vanilla's map decoration sprite). +- Colours are vanilla's `MapColor` per block, as map items use, with the map + item's height shading and water-depth dithering. +- Underground, in the Nether and under any roof, it maps the floor around the + player's height instead of the top block, so caves read sensibly. +- Cost: one cached 16x16 tile per loaded chunk (packed map colour and height). + Tiles are filled nearest first and refreshed when blocks change, within a time + budget of 0.3 ms a frame; composing the 128x128 image is a few thousand + lookups, done only when the view moved or a tile changed, and uploaded into a + dedicated atlas slot. With the minimap off nothing runs. + +### Auto-reconnect (`autoReconnect`, default off) +- On the "Connection lost" screen after a multiplayer connection drops, a + countdown "Reconnecting in N s" with a Cancel button, then a new connection + to the same address. +- Backoff 5, 10, 20, 40, 60 s; at most 5 attempts, then it stops. The count + only resets after staying connected for a minute, so a server that drops + players at once never causes an endless loop. +- Never after a kick, a ban, a whitelist or version refusal, a duplicate login + or an online-mode refusal: only lost connections (errors, time-outs, refused + connections while the server restarts) and the server's own "Server closed" + shutdown reason. + +## Shared rules + +- All extras are hidden with F1 and drawn in the HUD layer: under screens, over + the world, like vanilla's HUD. Extras in the top left corner give way to the + debug screen (F3), which shows the FPS anyway. +- Corners stack: extras placed in the same corner stack downward (top corners) + or upward (bottom corners) in the order minimap, FPS, keystrokes. The top + right corner starts below the status effect icons. + +## Perf budget + +Off: a flag check per frame per extra (no allocations, no world access). +On: FPS and keystrokes are a few quads; the minimap stays under 0.3 ms of CPU +per frame (tile budget) plus a 64 KiB texture upload when its image changes.