use crate::backend::{select_backend, PipelineBackend, ValidationScope};
use crate::debug::{elapsed_ms, stage_stat, stage_stat_timed, DebugBundle, DebugChannels};
use crate::digest::ConfigDigest;
use crate::error::{PcgError, PcgResult};
use crate::export::CURRENT_SCHEMA_VERSION;
use crate::model::request::GenerationRequest;
use crate::model::result::{GenerationResult, ResultMetadata};
use crate::model::room::CorridorPath;
use crate::rng::StableRng;
use crate::spawn::SpawnOutput;
use crate::validation::{run_full_validation, validate_request};
use crate::{chunked, constraint, topology, ue};
use std::time::Instant;
use crate::chunked::{ChunkDetailResult, TopologyResult};
#[non_exhaustive]
pub struct MapGenerator {
debug_enabled: bool,
}
impl MapGenerator {
pub fn new() -> Self {
Self {
debug_enabled: false,
}
}
pub fn set_debug(&mut self, enabled: bool) {
self.debug_enabled = enabled;
}
pub fn debug_enabled(&self) -> bool {
self.debug_enabled
}
pub fn generate(&self, request: GenerationRequest) -> PcgResult<GenerationResult> {
if request.config.generation_mode == crate::config::GenerationMode::RuntimeChunked {
return self.generate_chunk(request);
}
if request.config.generation_mode == crate::config::GenerationMode::HybridPrecompute {
return Err(PcgError::config(
"HybridPrecompute须经generate_topology_only()+fill_chunk_details()两阶段调用",
));
}
let normalized = validate_request(&request)?;
let (seed, config_digest) = match request.seed {
Some(s) => (
s,
ConfigDigest::from_config(&normalized.config)?.into_string(),
),
None => ConfigDigest::seed_and_digest_from_config(&normalized.config)?,
};
let root_rng = StableRng::from_seed(seed);
constraint::validate_constraints(&request.constraints)?;
let backend = select_backend(&normalized);
let topology_start = self.debug_enabled.then(Instant::now);
let mut topology_rng = root_rng.derive("topology");
let mut graph = topology::generate_topology(&normalized, &mut topology_rng)?;
constraint::apply_room_constraints(&mut graph.nodes, &request.constraints);
let topology_ms = topology_start.map(elapsed_ms);
let layout_start = self.debug_enabled.then(Instant::now);
let mut layout_rng = root_rng.derive("layout");
let layout_output = backend.solve_layout(&graph, &normalized, &mut layout_rng)?;
let layout_ms = layout_start.map(elapsed_ms);
let terrain_start = self.debug_enabled.then(Instant::now);
let mut terrain_rng = root_rng.derive("terrain");
let terrains = backend.generate_terrains(
&layout_output.rooms,
&layout_output.door_anchors,
&normalized,
&mut terrain_rng,
)?;
let terrain_ms = terrain_start.map(elapsed_ms);
let spawn_start = self.debug_enabled.then(Instant::now);
let spawn_rng = root_rng.derive("spawn");
let (item_spawns, enemy_spawns, spawn_debug_info) = if self.debug_enabled {
let spawn_result = backend.generate_spawns_with_debug(
&layout_output.rooms,
&terrains,
&normalized,
&spawn_rng,
)?;
let (items, enemies) = constraint::apply_spawn_constraints(
spawn_result.output.item_spawns,
spawn_result.output.enemy_spawns,
&request.constraints,
);
(items, enemies, Some(spawn_result.debug_info))
} else {
let SpawnOutput {
item_spawns,
enemy_spawns,
} = backend.generate_spawns(
&layout_output.rooms,
&terrains,
&normalized,
&spawn_rng,
)?;
let (items, enemies) = constraint::apply_spawn_constraints(
item_spawns,
enemy_spawns,
&request.constraints,
);
(items, enemies, None)
};
let spawn_ms = spawn_start.map(elapsed_ms);
let chunks = ue::streaming::build_chunks(&layout_output.rooms, &normalized)?;
let debug = self.debug_enabled.then(|| {
let critical_path_nodes = graph.critical_path.clone();
let door_anchor_positions = layout_output
.door_anchors
.iter()
.map(|anchor| anchor.grid_pos)
.collect();
let corridor_centerlines = layout_output
.corridors
.iter()
.map(|corridor| match &corridor.path {
CorridorPath::Straight(pts) => pts.clone(),
CorridorPath::Orthogonal(pts) => pts.clone(),
CorridorPath::Polyline(pts) => pts.clone(),
})
.collect();
let debug_channels = DebugChannels {
critical_path_nodes,
door_anchor_positions,
corridor_centerlines,
rejected_rooms: Vec::new(),
spawn_debug: spawn_debug_info.clone(),
};
DebugBundle {
trace_id: request.trace_id.clone(),
stage_stats: vec![
stage_stat_timed("topology", graph.nodes.len(), topology_ms.unwrap_or(0)),
stage_stat_timed("layout", layout_output.rooms.len(), layout_ms.unwrap_or(0)),
stage_stat_timed("terrain", terrains.len(), terrain_ms.unwrap_or(0)),
stage_stat_timed("spawn_items", item_spawns.len(), spawn_ms.unwrap_or(0)),
stage_stat("spawn_enemies", enemy_spawns.len()),
],
notes: vec!["MVP 生成流程已执行".to_string()],
validation_report: None, debug_channels: Some(debug_channels),
}
});
let result = GenerationResult {
metadata: ResultMetadata {
seed,
config_digest,
schema_version: CURRENT_SCHEMA_VERSION.to_string(),
algorithm_version: env!("CARGO_PKG_VERSION").to_string(),
target_engine_version: None,
trace_id: request.trace_id,
},
topology: graph,
rooms: layout_output.rooms,
door_anchors: layout_output.door_anchors,
corridors: layout_output.corridors,
terrains,
item_spawns,
enemy_spawns,
chunks,
debug,
};
backend.validate(
&result,
&normalized,
&request.constraints,
ValidationScope::FullFloor,
)?;
let mut result = result;
if result.debug.is_some() {
let report = run_full_validation(&result, &request.constraints, None);
if let Some(ref mut debug_bundle) = result.debug {
debug_bundle.validation_report = Some(report);
}
}
Ok(result)
}
}
impl Default for MapGenerator {
fn default() -> Self {
Self::new()
}
}
impl MapGenerator {
pub fn generate_chunk(&self, request: GenerationRequest) -> PcgResult<GenerationResult> {
if request.config.generation_mode != crate::config::GenerationMode::RuntimeChunked {
return Err(PcgError::config(
"generate_chunk()仅适用于RuntimeChunked模式",
));
}
chunked::generate_chunk(request)
}
pub fn generate_topology_only(&self, request: GenerationRequest) -> PcgResult<TopologyResult> {
chunked::generate_topology_only(request)
}
pub fn fill_chunk_details(
&self,
topology_result: &TopologyResult,
chunk_id: &str,
) -> PcgResult<ChunkDetailResult> {
chunked::fill_chunk_details(topology_result, chunk_id)
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::config::GenerationConfig;
#[test]
fn test_generate_satisfies_all_invariants_across_seeds() {
let generator = MapGenerator::new();
for seed in [42u64, 12345, 7, 99, 256, 1024] {
let result = generator
.generate(GenerationRequest {
seed: Some(seed),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.unwrap_or_else(|e| panic!("seed {seed} 生成应成功并通过硬校验: {e}"));
let report = crate::validation::run_full_validation(&result, &[], None);
assert!(
report.all_passed,
"seed {seed} 应满足全部不变量,失败项: {:?}",
report
.items()
.iter()
.filter(|i| !i.passed)
.collect::<Vec<_>>()
);
}
}
#[test]
fn test_generate_with_none_seed_is_deterministic() {
let generator = MapGenerator::new();
let make_request = || GenerationRequest {
seed: None,
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
};
let a = generator.generate(make_request()).expect("生成应成功");
let b = generator.generate(make_request()).expect("生成应成功");
let json_a = crate::export::export_json(&a).expect("导出应成功");
let json_b = crate::export::export_json(&b).expect("导出应成功");
assert_eq!(json_a, json_b, "seed:None 应从配置派生确定性结果");
}
#[test]
fn test_generate_returns_non_empty_result() {
let generator = MapGenerator::new();
let config = GenerationConfig::default();
let expected_digest = ConfigDigest::from_config(&config)
.expect("默认配置应可序列化")
.into_string();
let result = generator
.generate(GenerationRequest {
seed: Some(12345),
config,
constraints: vec![],
runtime_context: None,
trace_id: Some("trace-001".to_string()),
})
.expect("最小生成流程应该成功");
assert_eq!(result.metadata.seed, 12345);
assert_eq!(result.metadata.config_digest, expected_digest);
assert_eq!(result.metadata.algorithm_version, env!("CARGO_PKG_VERSION"));
assert_eq!(result.metadata.trace_id.as_deref(), Some("trace-001"));
assert!(!result.rooms.is_empty());
assert!(!result.door_anchors.is_empty());
assert!(!result.corridors.is_empty());
assert!(!result.terrains.is_empty());
assert!(!result.chunks.is_empty());
assert!(result.debug.is_none());
}
#[test]
fn test_generate_includes_debug_bundle_when_enabled() {
let mut generator = MapGenerator::new();
generator.set_debug(true);
let result = generator
.generate(GenerationRequest {
seed: Some(7),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.expect("启用调试不应影响最小生成流程");
assert!(generator.debug_enabled());
assert!(result.debug.is_some());
assert!(!result.rooms.is_empty());
}
#[test]
fn test_generate_debug_records_stage_durations() {
let mut generator = MapGenerator::new();
generator.set_debug(true);
let result = generator
.generate(GenerationRequest {
seed: Some(42),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.expect("调试模式生成应成功");
let debug = result.debug.expect("调试模式应包含 DebugBundle");
let stats = &debug.stage_stats;
assert_eq!(stats.len(), 5);
assert_eq!(stats[0].stage_name, "topology");
assert_eq!(stats[1].stage_name, "layout");
assert_eq!(stats[2].stage_name, "terrain");
assert_eq!(stats[3].stage_name, "spawn_items");
assert_eq!(stats[4].stage_name, "spawn_enemies");
assert!(stats[0].produced_count > 0, "拓扑阶段应有产出");
assert!(stats[1].produced_count > 0, "布局阶段应有产出");
assert!(stats[2].produced_count > 0, "地形阶段应有产出");
let total_ms: u64 = stats.iter().map(|s| s.duration_ms).sum();
assert!(total_ms < 60_000, "总耗时应在合理范围内");
}
#[test]
fn test_generate_no_debug_has_zero_overhead() {
let generator = MapGenerator::new();
let result = generator
.generate(GenerationRequest {
seed: Some(99),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.expect("非调试模式生成应成功");
assert!(result.debug.is_none(), "非调试模式不应包含 DebugBundle");
}
#[test]
fn test_generate_debug_channels_populated() {
let mut generator = MapGenerator::new();
generator.set_debug(true);
let result = generator
.generate(GenerationRequest {
seed: Some(42),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.expect("调试模式生成应成功");
let debug = result.debug.expect("调试模式应包含 DebugBundle");
let channels = debug.debug_channels.expect("调试模式应包含 debug_channels");
assert!(
!channels.critical_path_nodes.is_empty(),
"关键路径节点不应为空"
);
assert!(
!channels.door_anchor_positions.is_empty(),
"门锚点坐标不应为空"
);
assert!(
!channels.corridor_centerlines.is_empty(),
"走廊中心线不应为空"
);
for (i, centerline) in channels.corridor_centerlines.iter().enumerate() {
assert!(
centerline.len() >= 2,
"走廊 {} 的中心线应至少有 2 个点,实际有 {} 个",
i,
centerline.len()
);
}
assert_eq!(
channels.critical_path_nodes, result.topology.critical_path,
"调试通道的关键路径应与拓扑结果一致"
);
assert_eq!(
channels.door_anchor_positions.len(),
result.door_anchors.len(),
"调试通道的门锚点数量应与实际结果一致"
);
assert_eq!(
channels.corridor_centerlines.len(),
result.corridors.len(),
"调试通道的走廊中心线数量应与实际结果一致"
);
}
#[test]
fn test_generate_debug_spawn_debug_info_populated() {
let mut generator = MapGenerator::new();
generator.set_debug(true);
let result = generator
.generate(GenerationRequest {
seed: Some(42),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.expect("调试模式生成应成功");
let debug = result.debug.expect("调试模式应包含 DebugBundle");
let channels = debug.debug_channels.expect("调试模式应包含 debug_channels");
let spawn_debug = channels.spawn_debug.expect("调试模式应包含 spawn_debug");
assert!(
spawn_debug.candidate_count > 0,
"候选点位数应大于 0,实际为 {}",
spawn_debug.candidate_count
);
assert!(
spawn_debug.accepted_count > 0,
"接受点位数应大于 0,实际为 {}",
spawn_debug.accepted_count
);
assert!(
spawn_debug.accepted_count + spawn_debug.rejected_count <= spawn_debug.candidate_count,
"接受数({}) + 拒绝数({}) 应不超过候选数({})",
spawn_debug.accepted_count,
spawn_debug.rejected_count,
spawn_debug.candidate_count
);
assert_eq!(
spawn_debug.rejection_reasons.len(),
spawn_debug.rejected_count,
"拒绝原因列表长度应与拒绝数一致"
);
for reason in &spawn_debug.rejection_reasons {
assert!(!reason.reason.is_empty(), "拒绝原因描述不应为空");
}
let total_spawns = result.item_spawns.len() + result.enemy_spawns.len();
assert_eq!(
spawn_debug.accepted_count, total_spawns,
"接受数({}) 应与实际点位数({}) 一致",
spawn_debug.accepted_count, total_spawns
);
}
#[test]
fn test_generate_no_debug_has_no_spawn_debug() {
let generator = MapGenerator::new();
let result = generator
.generate(GenerationRequest {
seed: Some(99),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.expect("非调试模式生成应成功");
assert!(result.debug.is_none(), "非调试模式不应包含 DebugBundle");
}
#[test]
fn test_trace_id_propagation_through_pipeline() {
let trace = "trace-propagation-test-001".to_string();
let mut generator = MapGenerator::new();
generator.set_debug(true);
let result = generator
.generate(GenerationRequest {
seed: Some(42),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: Some(trace.clone()),
})
.expect("生成应成功");
assert_eq!(
result.metadata.trace_id.as_deref(),
Some(trace.as_str()),
"trace_id 应传播到结果元数据"
);
let debug = result.debug.as_ref().expect("调试模式应包含 DebugBundle");
assert_eq!(
debug.trace_id.as_deref(),
Some(trace.as_str()),
"trace_id 应传播到 DebugBundle"
);
let channels = crate::ue::adapter::export_named_channels(&result).expect("导出应成功");
for channel in &channels {
let channel_trace = channel.metadata.get("trace_id");
assert_eq!(
channel_trace,
Some(&crate::ue::points::PropertyValue::String(trace.clone())),
"通道 '{}' 的元数据应包含 trace_id",
channel.name
);
}
}
#[test]
fn test_trace_id_none_does_not_pollute_export() {
let generator = MapGenerator::new();
let result = generator
.generate(GenerationRequest {
seed: Some(42),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.expect("生成应成功");
assert!(result.metadata.trace_id.is_none());
let channels = crate::ue::adapter::export_named_channels(&result).expect("导出应成功");
for channel in &channels {
assert!(
!channel.metadata.contains_key("trace_id"),
"通道 '{}' 在 trace_id 为 None 时不应包含 trace_id 元数据",
channel.name
);
}
}
#[test]
fn test_generate_debug_validation_report_populated() {
let mut generator = MapGenerator::new();
generator.set_debug(true);
let result = generator
.generate(GenerationRequest {
seed: Some(42),
config: GenerationConfig::default(),
constraints: vec![],
runtime_context: None,
trace_id: None,
})
.expect("调试模式生成应成功");
let debug = result.debug.expect("调试模式应包含 DebugBundle");
let report = debug.validation_report.expect("调试模式应包含约束验证报告");
assert!(
!report.items().is_empty(),
"约束验证报告应包含至少一个验证项"
);
assert_eq!(
report.passed_count + report.failed_count,
report.items().len(),
"通过数 + 失败数应等于总验证项数"
);
}
}