refactor

kiln-core/src/player.rs

@@ -1,5 +1,12 @@
 use crate::keys::Keyring;
 
+/// The game-global player state: stats that follow the player across boards.
+///
+/// Owned by [`GameState::player`](crate::game::GameState) (a single value, not
+/// per-board), so health, gems, and keys persist through board transitions.
+/// Distinct from [`PlayerPos`](crate::utils::PlayerPos), which is the player's
+/// position *on a particular board*. A `Copy` snapshot is handed to each script
+/// hook and exposed to Rhai (read-only) as the `Player` constant.
 #[derive(Copy, Clone)]
 pub struct Player {
     /// The player's current health. Game-global (not per-board), so it persists
@@ -15,7 +22,7 @@ pub struct Player {
     pub keys: Keyring,
 
     /// The number of gems the player has collected. Game-global like
-    /// [`player_health`](GameState::player_health); starts at `0`.
+    /// [`health`](Player::health); starts at `0`.
     pub gems: i64,
 }