docs(comments): rewrite comments across all crates to the guidelines
Sweep every first-party crate source (1956 .rs files) to the project comment guidelines: delete redundant restatements, decorative banners, change narration, and end-of-line comments; keep and tighten the crucial ones (invariants, bug rationale, SAFETY blocks, ported-source attribution). No functional code changed. Every edit is proven comment-only against the prior tree by a comment-stripping lexer (string/char/raw-string aware) plus a separate doctest-fence check. Where removing a comment made rustfmt or clippy want to re-lay-out adjacent code, the minimal triggering comment is restored so code tokens stay byte-identical. Gates green: cargo fmt --all --check (0 diffs), cargo check and cargo clippy --workspace --all-targets (0 warnings). Adds scripts/check_codegen_comment_guidelines.py — the enforcement gate for these guidelines (flags banners, end-of-line comments, change narration, and commented-out code).
This commit is contained in:
1 parent
ff0fb56c67
commit
a02b555e66
1458 files changed
+10729
-21750
No files matched your search
@@ -28,7 +28,8 @@ pub(super) struct XorShift64(u64);
|
||||
|
||||
impl XorShift64 {
|
||||
pub fn new(seed: u64) -> Self {
|
||||
Self(seed.max(1)) // xorshift state must be non-zero
|
||||
// xorshift state must be non-zero
|
||||
Self(seed.max(1))
|
||||
}
|
||||
|
||||
pub fn next_u32(&mut self) -> u32 {
|
||||
@@ -239,30 +240,34 @@ fn hellstone() -> Texture {
|
||||
Texture { pixels }
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------------------
|
||||
// Sprite art (char-map pixel art)
|
||||
// -------------------------------------------------------------------------
|
||||
|
||||
/// Map a sprite art character to a color. `.` is transparent.
|
||||
fn sprite_color(ch: u8) -> Option<Rgb> {
|
||||
match ch {
|
||||
b'.' => None,
|
||||
b'B' => Some([146, 90, 50]), // imp body, brown
|
||||
b'b' => Some([104, 62, 34]), // imp body, shaded
|
||||
b'H' => Some([222, 214, 188]), // horn / bone
|
||||
b'E' => Some(EYE_GLOW), // glowing eye (fog-exempt in renderer)
|
||||
b'M' => Some([34, 20, 16]), // mouth / dark recess
|
||||
b'T' => Some([236, 232, 220]), // teeth
|
||||
b'C' => Some([214, 196, 160]), // claw
|
||||
b'R' => Some([186, 28, 24]), // blood
|
||||
b'r' => Some([120, 16, 14]), // blood, dark
|
||||
b'G' => Some([96, 104, 112]), // gunmetal
|
||||
b'g' => Some([52, 58, 66]), // gunmetal, dark
|
||||
b'W' => Some([224, 228, 232]), // highlight
|
||||
b'S' => Some([212, 160, 116]), // skin
|
||||
b's' => Some([164, 116, 80]), // skin, shaded
|
||||
b'F' => Some([255, 244, 160]), // muzzle flash core
|
||||
b'f' => Some([255, 168, 48]), // muzzle flash fringe
|
||||
// imp body, brown
|
||||
b'B' => Some([146, 90, 50]),
|
||||
// imp body, shaded
|
||||
b'b' => Some([104, 62, 34]),
|
||||
b'H' => Some([222, 214, 188]),
|
||||
// glowing eye (fog-exempt in renderer)
|
||||
b'E' => Some(EYE_GLOW),
|
||||
// mouth / dark recess
|
||||
b'M' => Some([34, 20, 16]),
|
||||
b'T' => Some([236, 232, 220]),
|
||||
b'C' => Some([214, 196, 160]),
|
||||
b'R' => Some([186, 28, 24]),
|
||||
b'r' => Some([120, 16, 14]),
|
||||
b'G' => Some([96, 104, 112]),
|
||||
b'g' => Some([52, 58, 66]),
|
||||
b'W' => Some([224, 228, 232]),
|
||||
b'S' => Some([212, 160, 116]),
|
||||
b's' => Some([164, 116, 80]),
|
||||
// muzzle flash core
|
||||
b'F' => Some([255, 244, 160]),
|
||||
// muzzle flash fringe
|
||||
b'f' => Some([255, 168, 48]),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
@@ -530,9 +535,7 @@ pub(super) fn build_gun_sprites() -> GunSprites {
|
||||
GunSprites { idle, fire }
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------------------
|
||||
// 5x7 pixel font (uppercase + the few symbols the game needs)
|
||||
// -------------------------------------------------------------------------
|
||||
|
||||
/// Return the 5x7 glyph rows for a character, MSB-left in the low 5 bits.
|
||||
/// Unknown characters render as blank.
|
||||
|
||||
@@ -24,8 +24,10 @@ const VIGNETTE: f32 = 0.11;
|
||||
pub(super) struct FrameBuffer {
|
||||
pub w: usize,
|
||||
pub h: usize,
|
||||
pub pixels: Vec<u8>, // RGB8, row-major
|
||||
zbuf: Vec<f32>, // per-column wall depth
|
||||
// RGB8, row-major
|
||||
pub pixels: Vec<u8>,
|
||||
// per-column wall depth
|
||||
zbuf: Vec<f32>,
|
||||
/// Per-column wall strip bounds `[top, bottom)` in screen rows, written
|
||||
/// by `draw_walls` and read by `draw_floor_ceiling` to skip the pixels
|
||||
/// walls already cover (avoids texturing them twice).
|
||||
@@ -33,7 +35,7 @@ pub(super) struct FrameBuffer {
|
||||
wall_bottom: Vec<i32>,
|
||||
/// Scratch for painter's-order sprite sorting, reused across frames.
|
||||
sprite_order: Vec<(usize, f32)>,
|
||||
/// Separable vignette factors, rebuilt on dimension change.
|
||||
/// Separable vignette factors, rebuilt on dimension shift.
|
||||
vig_x: Vec<f32>,
|
||||
vig_y: Vec<f32>,
|
||||
}
|
||||
@@ -369,7 +371,8 @@ impl Renderer {
|
||||
let tx = inv_det * (dir_y * rel_x - dir_x * rel_y);
|
||||
let ty = inv_det * (-plane_y * rel_x + plane_x * rel_y);
|
||||
if ty <= 0.08 {
|
||||
continue; // behind or on top of the camera
|
||||
// behind or on top of the camera
|
||||
continue;
|
||||
}
|
||||
|
||||
let sprite = match imp.visual() {
|
||||
@@ -411,7 +414,8 @@ impl Renderer {
|
||||
|
||||
for sx in x0.max(0)..x1.min(w as i32) {
|
||||
if fb.zbuf[sx as usize] <= ty {
|
||||
continue; // occluded by a wall
|
||||
// occluded by a wall
|
||||
continue;
|
||||
}
|
||||
let u = (sx as f32 - x0 as f32) / (x1 - x0).max(1) as f32;
|
||||
for sy in y0.max(0)..y1.min(h as i32) {
|
||||
@@ -520,9 +524,7 @@ fn draw_contact_shadow(
|
||||
}
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------------------
|
||||
// Title / end screens: animated fire + 5x7 pixel text
|
||||
// -------------------------------------------------------------------------
|
||||
|
||||
/// The classic PSX-style fire effect: a cellular automaton on a coarse
|
||||
/// grid, upscaled at draw time. Heat values 0..=36 index a fire palette.
|
||||
@@ -557,8 +559,9 @@ impl FireSim {
|
||||
for x in 0..self.w {
|
||||
let src = y * self.w + x;
|
||||
let r = self.rng.next_u32();
|
||||
let decay = (r & 1) as i32; // cool by 0 or 1
|
||||
let drift = (r >> 2) % 3; // 0, 1, 2 → left, stay, right
|
||||
let decay = (r & 1) as i32;
|
||||
// 0, 1, 2 → left, stay, right
|
||||
let drift = (r >> 2) % 3;
|
||||
let dst_x = (x as i32 + drift as i32 - 1).rem_euclid(self.w as i32) as usize;
|
||||
let dst = (y - 1) * self.w + dst_x;
|
||||
self.heat[dst] = (self.heat[src] as i32 - decay).max(0) as u8;
|
||||
@@ -696,7 +699,7 @@ mod tests {
|
||||
let renderer = Renderer::new();
|
||||
let mut game = Game::new();
|
||||
// Move all imps far behind the player so none are visible, render,
|
||||
// then put one directly in front and confirm pixels change.
|
||||
// then put one directly in front and confirm pixels differ.
|
||||
for imp in &mut game.imps {
|
||||
imp.x = game.player.x - 8.0;
|
||||
imp.y = game.player.y;
|
||||
|
||||
@@ -44,8 +44,10 @@ const IMP_RADIUS: f32 = 0.30;
|
||||
/// hold timer ([`HOLD_WINDOW`]); while it's positive, velocity eases toward
|
||||
/// a steady target. A constant target while held means speed doesn't
|
||||
/// sawtooth with the OS key-repeat cadence, yet releasing glides to a stop.
|
||||
const MOVE_SPEED: f32 = 3.3; // tiles/s while a move key is held
|
||||
const TURN_SPEED: f32 = 2.2; // rad/s (~125°/s) while a turn key is held
|
||||
// tiles/s while a move key is held
|
||||
const MOVE_SPEED: f32 = 3.3;
|
||||
// rad/s (~125°/s) while a turn key is held
|
||||
const TURN_SPEED: f32 = 2.2;
|
||||
/// Velocity-smoothing time constants (seconds). Small = snappy response
|
||||
/// with just enough ramp to read as momentum rather than teleporting.
|
||||
const MOVE_ACCEL_TAU: f32 = 0.08;
|
||||
@@ -78,7 +80,8 @@ const IMP_BITE_DAMAGE: i32 = 7;
|
||||
pub(super) struct Map {
|
||||
pub w: usize,
|
||||
pub h: usize,
|
||||
cells: Vec<u8>, // 0 = floor, 1..=4 = wall texture id
|
||||
// 0 = floor, 1..=4 = wall texture id
|
||||
cells: Vec<u8>,
|
||||
}
|
||||
|
||||
impl Map {
|
||||
@@ -166,7 +169,6 @@ impl Map {
|
||||
}
|
||||
}
|
||||
|
||||
/// Player state.
|
||||
pub(super) struct Player {
|
||||
pub x: f32,
|
||||
pub y: f32,
|
||||
@@ -330,7 +332,8 @@ impl Game {
|
||||
y: center.1,
|
||||
hp: IMP_HP,
|
||||
state: ImpState::Idle,
|
||||
anim: (x * 7 + y * 13) as f32 * 0.1, // desync walk cycles
|
||||
// desync walk cycles
|
||||
anim: (x * 7 + y * 13) as f32 * 0.1,
|
||||
attack_cooldown: 0.0,
|
||||
}),
|
||||
_ => {}
|
||||
@@ -728,7 +731,8 @@ mod tests {
|
||||
assert!(game.imps[0].hp < hp_before, "first shot must connect");
|
||||
|
||||
for _ in 0..20 {
|
||||
game.step(FIRE_COOLDOWN + 0.01); // let cooldown lapse
|
||||
// let cooldown lapse
|
||||
game.step(FIRE_COOLDOWN + 0.01);
|
||||
game.queue_fire();
|
||||
game.step(0.016);
|
||||
if !game.imps[0].alive() {
|
||||
@@ -807,7 +811,7 @@ mod tests {
|
||||
// and then stay there — no sawtooth.
|
||||
let mut game = Game::new();
|
||||
// Aim down an open stretch so walls don't cap velocity.
|
||||
game.player.angle = std::f32::consts::FRAC_PI_2; // +y
|
||||
game.player.angle = std::f32::consts::FRAC_PI_2;
|
||||
let dt = 1.0 / 30.0;
|
||||
for _ in 0..40 {
|
||||
game.press(Control::Forward);
|
||||
@@ -837,13 +841,14 @@ mod tests {
|
||||
// on press (release-aware) keeps it moving without repeats.
|
||||
let mut game = Game::new();
|
||||
game.set_release_aware(true);
|
||||
game.player.angle = 0.0; // facing +x
|
||||
game.player.angle = 0.0;
|
||||
game.press(Control::Forward);
|
||||
game.press(Control::TurnLeft);
|
||||
|
||||
let angle0 = game.player.angle;
|
||||
for _ in 0..30 {
|
||||
game.step(1.0 / 30.0); // no further presses
|
||||
// no further presses
|
||||
game.step(1.0 / 30.0);
|
||||
}
|
||||
assert!(
|
||||
game.player.vel_forward > 1.0,
|
||||
@@ -893,7 +898,8 @@ mod tests {
|
||||
let mut game = Game::new();
|
||||
game.player.angle = std::f32::consts::FRAC_PI_2;
|
||||
let dt = 1.0 / 60.0;
|
||||
let mut since_repeat = repeat_interval; // press on the first frame
|
||||
// press on the first frame
|
||||
let mut since_repeat = repeat_interval;
|
||||
// Run 2s of simulation, pressing every `repeat_interval`.
|
||||
for _ in 0..120 {
|
||||
since_repeat += dt;
|
||||
@@ -905,8 +911,9 @@ mod tests {
|
||||
}
|
||||
game.player.vel_forward
|
||||
}
|
||||
let fast = sustained_speed(0.03); // ~33 Hz
|
||||
let slow = sustained_speed(0.12); // ~8 Hz, still under HOLD_WINDOW
|
||||
let fast = sustained_speed(0.03);
|
||||
// ~8 Hz, still under HOLD_WINDOW
|
||||
let slow = sustained_speed(0.12);
|
||||
assert!((fast - MOVE_SPEED).abs() < 0.1, "fast cadence: {fast}");
|
||||
assert!(
|
||||
(fast - slow).abs() < 0.25,
|
||||
|
||||
@@ -498,7 +498,7 @@ mod tests {
|
||||
#[test]
|
||||
fn playing_to_dead_transition() {
|
||||
let mut state = GboomState::new();
|
||||
state.handle_key(&key(KeyCode::Char('w'))); // leave title
|
||||
state.handle_key(&key(KeyCode::Char('w')));
|
||||
state.game.player.hp = 0;
|
||||
state.tick();
|
||||
assert_eq!(state.phase, Phase::Dead);
|
||||
@@ -682,9 +682,9 @@ mod tests {
|
||||
|
||||
// Corridor vantage: spawn looking south down the long west corridor.
|
||||
let mut state = GboomState::new();
|
||||
state.handle_key(&key(KeyCode::Char('w'))); // leave title
|
||||
state.handle_key(&key(KeyCode::Char('w')));
|
||||
state.phase = Phase::Playing;
|
||||
state.game.player.angle = std::f32::consts::FRAC_PI_2; // +y, south
|
||||
state.game.player.angle = std::f32::consts::FRAC_PI_2;
|
||||
state.game.step(0.016);
|
||||
dump("game.png", &mut state);
|
||||
|
||||
|
||||
Reference in new issue
Block a user