yang-pcg 0.2.0

个人使用地图生成
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
// 配置摘要生成
// 用于生成配置的稳定哈希,用于缓存和回归验证

use crate::config::GenerationConfig;
use crate::error::{PcgError, PcgResult};
use crate::model::request::Constraint;
use crate::rng::fnv1a_64;
use serde::{Deserialize, Deserializer, Serialize, Serializer};

/// 验证配置中所有 f32 字段不含 NaN。
///
/// serde_json 将 f32::NAN 序列化为 `null`(JSON 不支持 NaN),
/// 这会导致两个问题:(1) 序列化后的 JSON 丢失原始值信息;
/// (2) 不同 NaN 位的 NaN 值产生相同摘要,违反摘要唯一性契约。
/// 本函数在序列化前做显式校验,提供清晰的错误信息。
fn validate_no_nan(config: &GenerationConfig) -> PcgResult<()> {
    if config.terrain.obstacle_density.is_nan() {
        return Err(PcgError::config_with_field(
            "obstacle_density 不能为 NaN",
            "terrain.obstacle_density",
        ));
    }
    if config.terrain.min_walkable_ratio.is_nan() {
        return Err(PcgError::config_with_field(
            "min_walkable_ratio 不能为 NaN",
            "terrain.min_walkable_ratio",
        ));
    }
    if config.item_spawns.rarity_weights.iter().any(|w| w.is_nan()) {
        return Err(PcgError::config_with_field(
            "rarity_weights 不能包含 NaN",
            "item_spawns.rarity_weights",
        ));
    }
    Ok(())
}

/// 配置摘要
///
/// 为生成配置生成稳定的哈希值,用于:
/// - 缓存键生成
/// - 回归验证
/// - 导出签名
///
/// 摘要保证:
/// - 相同配置生成相同摘要(同一编译二进制内确定)
/// - 不同配置生成不同摘要(高概率)
/// - 跨 Rust 版本稳定性取决于 FNV-1a (fnv1a_64) 的算法不变性——FNV 是固定规范,不随 Rust 版本变化
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct ConfigDigest {
    /// 十六进制哈希字符串
    hash: String,
}

impl ConfigDigest {
    /// 从配置生成摘要
    ///
    /// # 错误
    ///
    /// - 当配置包含 NaN 的 `f32` 字段时返回 `PcgError::Config`
    /// - 当配置序列化失败时返回 `PcgError::Config`
    ///
    /// # 示例
    ///
    /// ```rust
    /// use yang_pcg::config::GenerationConfig;
    /// use yang_pcg::digest::ConfigDigest;
    ///
    /// let config = GenerationConfig::default();
    /// let digest = ConfigDigest::from_config(&config).expect("默认配置应可序列化");
    /// println!("配置摘要: {}", digest.as_str());
    /// ```
    pub fn from_config(config: &GenerationConfig) -> PcgResult<Self> {
        let (_, hash) = Self::seed_and_digest_from_config(config)?;
        Ok(Self { hash })
    }

    /// 从配置派生确定性种子(u64)。
    ///
    /// 当生成请求未显式提供 `seed` 时,用本方法从配置派生一个**确定性**的兜底种子,
    /// 保证「相同 config + 不提供 seed」始终产出相同地图——符合确定性库的契约。
    /// 与 [`from_config`](Self::from_config) 使用相同的稳定哈希逻辑。
    ///
    /// # 错误
    ///
    /// - 当配置包含 NaN 的 `f32` 字段时返回 `PcgError::Config`
    /// - 当配置序列化失败时返回 `PcgError::Config`
    ///
    /// # 示例
    ///
    /// ```rust
    /// use yang_pcg::config::GenerationConfig;
    /// use yang_pcg::digest::ConfigDigest;
    ///
    /// let config = GenerationConfig::default();
    /// // 同一 config 多次派生得到相同种子
    /// assert_eq!(
    ///     ConfigDigest::seed_from_config(&config).unwrap(),
    ///     ConfigDigest::seed_from_config(&config).unwrap()
    /// );
    /// ```
    pub fn seed_from_config(config: &GenerationConfig) -> PcgResult<u64> {
        let (seed, _) = Self::seed_and_digest_from_config(config)?;
        Ok(seed)
    }

    /// 一次性从配置派生种子和摘要字符串。
    ///
    /// 内部只做一次 `serde_json::to_string`,避免调用方分别调用
    /// `seed_from_config` + `from_config` 导致重复序列化。
    ///
    /// # 错误
    ///
    /// - 当配置包含 NaN 的 `f32` 字段时返回 `PcgError::Config`
    /// - 当配置序列化失败时返回 `PcgError::Config`
    pub fn seed_and_digest_from_config(config: &GenerationConfig) -> PcgResult<(u64, String)> {
        validate_no_nan(config)?;
        let json = serde_json::to_string(config)
            .map_err(|e| PcgError::config(format!("GenerationConfig 序列化失败: {}", e)))?;
        let hash_value = fnv1a_64(json.as_bytes());
        Ok((hash_value, format!("{:016x}", hash_value)))
    }

    /// 从字符串创建摘要
    ///
    /// 用于从缓存或导出数据中恢复摘要。
    pub fn from_string(hash: String) -> Self {
        Self { hash }
    }

    /// 获取摘要字符串
    pub fn as_str(&self) -> &str {
        &self.hash
    }

    /// 转换为字符串
    pub fn into_string(self) -> String {
        self.hash
    }

    /// 验证摘要是否匹配配置
    ///
    /// # 示例
    ///
    /// ```rust
    /// use yang_pcg::config::GenerationConfig;
    /// use yang_pcg::digest::ConfigDigest;
    ///
    /// let config = GenerationConfig::default();
    /// let digest = ConfigDigest::from_config(&config);
    ///
    /// assert!(digest.matches(&config));
    /// ```
    pub fn matches(&self, config: &GenerationConfig) -> bool {
        Self::from_config(config).is_ok_and(|expected| self.hash == expected.hash)
    }
}

/// 约束列表摘要(与 ConfigDigest 同一套稳定哈希:FNV-1a over serde_json)。
///
/// constraints 会实质改变输出(锚点改写 room_type → 地形策略/敌人预算;排除区删除点位),
/// 必须参与缓存键,否则键相同而地图不同。
/// 不做排序归一化:模板约束取「第一个匹配房间」,顺序本身是语义的一部分。
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct ConstraintDigest {
    hash: String,
}

impl ConstraintDigest {
    pub fn from_constraints(constraints: &[Constraint]) -> PcgResult<Self> {
        let json = serde_json::to_string(constraints)
            .map_err(|e| PcgError::config(format!("constraints 序列化失败: {}", e)))?;
        Ok(Self {
            hash: format!("{:016x}", fnv1a_64(json.as_bytes())),
        })
    }

    pub fn as_str(&self) -> &str {
        &self.hash
    }

    pub fn into_string(self) -> String {
        self.hash
    }
}

impl std::fmt::Display for ConfigDigest {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.hash)
    }
}

impl Serialize for ConfigDigest {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(&self.hash)
    }
}

impl<'de> Deserialize<'de> for ConfigDigest {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let hash = String::deserialize(deserializer)?;
        Ok(Self::from_string(hash))
    }
}

impl TryFrom<&GenerationConfig> for ConfigDigest {
    type Error = Box<PcgError>;

    /// 从配置生成摘要(可失败版本)。
    ///
    /// 与 [`ConfigDigest::from_config`] 完全等价。`From` 是无失败签名的 trait,
    /// 无法表达 NaN / 序列化失败,只能靠 `expect` 兜底(生产 panic,违反
    /// 「不新增生产 expect()」反模式);这里改用 `TryFrom` 暴露同一失败语义,
    /// 调用方用 `?` 传播。
    ///
    /// # 错误
    ///
    /// 同 [`ConfigDigest::from_config`](Self::from_config):配置含 NaN 的 f32 字段
    /// 或序列化失败时返回 `PcgError::Config`。
    fn try_from(config: &GenerationConfig) -> Result<Self, Self::Error> {
        Self::from_config(config)
    }
}

impl From<String> for ConfigDigest {
    fn from(hash: String) -> Self {
        Self::from_string(hash)
    }
}

impl From<&str> for ConfigDigest {
    fn from(hash: &str) -> Self {
        Self::from_string(hash.to_string())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::{GenerationConfig, RangeU16};

    #[test]
    fn test_digest_from_config() {
        let config = GenerationConfig::default();
        let digest = ConfigDigest::from_config(&config).expect("默认配置应可序列化");

        // 摘要应该是 16 个十六进制字符
        assert_eq!(digest.as_str().len(), 16);
        assert!(digest.as_str().chars().all(|c| c.is_ascii_hexdigit()));
    }

    #[test]
    fn test_digest_stability() {
        let config = GenerationConfig::default();

        // 多次生成摘要应该得到相同结果
        let digest1 = ConfigDigest::from_config(&config).expect("默认配置应可序列化");
        let digest2 = ConfigDigest::from_config(&config).expect("默认配置应可序列化");

        assert_eq!(digest1, digest2);
        assert_eq!(digest1.as_str(), digest2.as_str());
    }

    #[test]
    fn test_digest_uniqueness() {
        let config1 = GenerationConfig::default();
        let config2 = GenerationConfig {
            room_count: RangeU16 { min: 15, max: 25 },
            ..Default::default()
        };

        let digest1 = ConfigDigest::from_config(&config1).expect("配置应可序列化");
        let digest2 = ConfigDigest::from_config(&config2).expect("配置应可序列化");

        // 不同配置应该生成不同摘要
        assert_ne!(digest1, digest2);
        assert_ne!(digest1.as_str(), digest2.as_str());
    }

    #[test]
    fn test_digest_matches() {
        let config = GenerationConfig::default();
        let digest = ConfigDigest::from_config(&config).expect("默认配置应可序列化");

        assert!(digest.matches(&config));

        let different_config = GenerationConfig {
            room_count: RangeU16 { min: 15, max: 25 },
            ..Default::default()
        };

        assert!(!digest.matches(&different_config));
    }

    #[test]
    fn test_digest_from_string() {
        let hash_str = "0123456789abcdef";
        let digest = ConfigDigest::from_string(hash_str.to_string());

        assert_eq!(digest.as_str(), hash_str);
    }

    #[test]
    fn test_digest_display() {
        let config = GenerationConfig::default();
        let digest = ConfigDigest::from_config(&config).expect("默认配置应可序列化");

        let display_str = format!("{}", digest);
        assert_eq!(display_str, digest.as_str());
    }

    #[test]
    fn test_digest_conversions() {
        let config = GenerationConfig::default();

        // From &GenerationConfig(TryFrom)
        let digest1 = ConfigDigest::try_from(&config).expect("默认配置应可序列化");

        // From String
        let digest2: ConfigDigest = digest1.as_str().to_string().into();

        // From &str
        let digest3: ConfigDigest = digest1.as_str().into();

        assert_eq!(digest1, digest2);
        assert_eq!(digest2, digest3);
    }

    #[test]
    fn test_digest_try_from_config_rejects_nan() {
        let mut config = GenerationConfig::default();
        config.terrain.obstacle_density = f32::NAN;

        // 不再 panic,而是返回 Config 错误
        let err = ConfigDigest::try_from(&config).expect_err("NaN 配置应返回错误");
        assert_eq!(err.error_code(), "PCG-CONFIG-001");
    }

    #[test]
    fn test_constraint_digest_differs_by_constraints() {
        use crate::model::request::ExclusionZoneConstraint;

        let empty = ConstraintDigest::from_constraints(&[]).expect("空约束应可序列化");
        let with_zone = ConstraintDigest::from_constraints(&[Constraint::ExclusionZone(
            ExclusionZoneConstraint {
                label: "zone".to_string(),
                min: crate::model::geometry::GridPoint { x: 0, y: 0 },
                max: crate::model::geometry::GridPoint { x: 5, y: 5 },
                exclude_rooms: false,
                exclude_spawns: true,
            },
        )])
        .expect("约束应可序列化");

        // 相同输入确定性
        assert_eq!(
            empty.as_str(),
            ConstraintDigest::from_constraints(&[])
                .expect("空约束应可序列化")
                .as_str()
        );
        // 不同约束 → 不同摘要
        assert_ne!(empty.as_str(), with_zone.as_str());
    }

    #[test]
    fn test_digest_sensitivity_to_nested_changes() {
        let config1 = GenerationConfig::default();
        let mut config2 = GenerationConfig::default();
        config2.terrain.obstacle_density = 0.3;

        let digest1 = ConfigDigest::from_config(&config1).expect("配置应可序列化");
        let digest2 = ConfigDigest::from_config(&config2).expect("配置应可序列化");

        // 嵌套字段的变化也应该影响摘要
        assert_ne!(digest1, digest2);
    }

    #[test]
    fn test_digest_sensitivity_to_theme_tags() {
        let config1 = GenerationConfig::default();
        let config2 = GenerationConfig {
            theme_tags: vec!["dungeon".to_string(), "dark".to_string()],
            ..Default::default()
        };

        let digest1 = ConfigDigest::from_config(&config1).expect("配置应可序列化");
        let digest2 = ConfigDigest::from_config(&config2).expect("配置应可序列化");

        // 主题标签的变化也应该影响摘要
        assert_ne!(digest1, digest2);
    }

    #[test]
    fn test_digest_into_string() {
        let config = GenerationConfig::default();
        let digest = ConfigDigest::from_config(&config).expect("默认配置应可序列化");
        let hash_str = digest.as_str().to_string();

        let owned_str = digest.into_string();
        assert_eq!(owned_str, hash_str);
    }
}