Skip to main content

yang_pcg/
lib.rs

1//! # yang-pcg
2//!
3//! YANG Procedural Content Generation - UE5 Roguelike 地图生成算法库
4//!
5//! 本库提供可复现、可测试、可缓存、可导出、可分块加载的地图生成核心,
6//! 并通过独立适配层与 UE5 PCG 工作流对接。
7//!
8//! ## 核心特性
9//!
10//! - **确定性生成**:相同种子和配置生成相同结果
11//! - **分层架构**:算法核心与 UE5 集成解耦
12//! - **可观测性**:完整的调试和追踪支持
13//! - **可扩展性**:支持约束、模板、分块等增强能力
14//!
15//! ## 模块组织
16//!
17//! - `config`: 配置管理与归一化
18//! - `generator`: 核心生成器编排
19//! - `rng`: 确定性随机数生成
20//! - `topology`: 房间拓扑与路径规划
21//! - `layout`: 空间布局与走廊生成
22//! - `terrain`: 房间地形生成
23//! - `spawn`: 交互物与敌人点位生成
24//! - `constraint`: 约束求解(锚点、排除区、模板)
25//! - `model`: 核心数据模型
26//! - `ue`: UE5 适配层
27//! - `debug`: 调试与分析输出
28//! - `cache`: 缓存管理(调用方自管工具类,`generate()` 不自动读写缓存)
29//! - `error`: 错误类型定义
30//! - `validation`: 结果验证与不变量检查
31//!
32//! ## 使用示例
33//!
34//! ```rust,ignore
35//! use yang_pcg::{GenerationRequest, GenerationConfig, MapGenerator};
36//!
37//! // 创建生成请求
38//! let request = GenerationRequest {
39//!     seed: Some(12345),
40//!     config: GenerationConfig::default(),
41//!     constraints: vec![],
42//!     runtime_context: None,
43//!     trace_id: None,
44//! };
45//!
46//! // 生成地图
47//! let generator = MapGenerator::new();
48//! let result = generator.generate(request)?;
49//!
50//! // 导出为 JSON
51//! let json = serde_json::to_string_pretty(&result)?;
52//! ```
53
54// 核心模块
55pub mod backend;
56pub mod cache;
57pub mod chunked;
58pub mod config;
59pub mod debug;
60pub mod digest;
61pub mod error;
62pub mod export;
63pub mod generator;
64pub mod grammar;
65pub mod rng;
66pub mod validation;
67
68// 生成流程模块
69pub mod constraint;
70pub mod layout;
71pub(crate) mod spawn;
72pub mod terrain;
73pub mod topology;
74
75// 数据模型
76pub mod model;
77
78// UE5 集成
79pub mod ue;
80
81// 重新导出常用类型
82pub use chunked::{ChunkDetailResult, TopologyResult};
83pub use config::{GenerationConfig, GenerationMode, NormalizedConfig};
84pub use digest::{ConfigDigest, ConstraintDigest};
85pub use error::{PcgError, PcgResult};
86pub use export::{
87    export_binary, export_json, export_json_compact, import_binary, import_json,
88    CURRENT_SCHEMA_VERSION,
89};
90pub use generator::MapGenerator;
91pub use grammar::{GrammarContext, GrammarRule, WeightedRuleSelector};
92pub use model::{
93    geometry::{CardinalDir, GridPoint, WorldPoint},
94    request::{GenerationRequest, RuntimeContext},
95    result::{GenerationResult, ResultMetadata},
96    room::{Room, RoomType},
97};
98pub use rng::StableRng;
99pub use validation::{ValidationItem, ValidationReport};
100
101// 任务 26 测试模块
102#[cfg(test)]
103mod tests_task26;
104
105// 任务 27 属性测试模块
106#[cfg(test)]
107mod tests_task27;
108
109// 基础功能测试
110#[cfg(test)]
111mod tests {
112    use super::*;
113    use crate::config::GenerationConfig;
114
115    #[test]
116    fn test_basic_types_creation() {
117        // 测试基本类型可以创建
118        let config = GenerationConfig::default();
119        assert_eq!(config.room_count.min, 10);
120        assert_eq!(config.room_count.max, 20);
121
122        let request = GenerationRequest {
123            seed: Some(12345),
124            config,
125            constraints: vec![],
126            runtime_context: None,
127            trace_id: None,
128        };
129        assert_eq!(request.seed, Some(12345));
130
131        let generator = MapGenerator::new();
132        // MapGenerator::generate() 已完整实现全流程 6 阶段(拓扑→布局→地形→spawn→分块→校验)
133        let _ = generator;
134    }
135
136    #[test]
137    fn test_room_types() {
138        use crate::model::room::RoomType;
139
140        // 测试房间类型枚举
141        let room_types = vec![
142            RoomType::Start,
143            RoomType::Combat,
144            RoomType::Treasure,
145            RoomType::Shop,
146            RoomType::Elite,
147            RoomType::Puzzle,
148            RoomType::Safe,
149            RoomType::Boss,
150            RoomType::Event,
151            RoomType::Secret,
152        ];
153
154        assert_eq!(room_types.len(), 10);
155        assert_eq!(room_types[0], RoomType::Start);
156        assert_eq!(room_types[7], RoomType::Boss);
157    }
158
159    #[test]
160    fn test_generation_modes() {
161        use crate::config::GenerationMode;
162
163        let modes = [
164            GenerationMode::OfflineFullFloor,
165            GenerationMode::RuntimeChunked,
166            GenerationMode::HybridPrecompute,
167        ];
168
169        assert_eq!(modes.len(), 3);
170        assert_eq!(modes[0], GenerationMode::OfflineFullFloor);
171    }
172}