feat: add worldgen climate snapshots

[MichaelFisher1997]

Summary

• Add deterministic worldgen climate snapshots covering temperature, humidity, continentalness, erosion, ruggedness, river/ridge masks, elevation, biome, and ocean state.
• Add a worldgen-climate-snapshot build step that writes JSON snapshots or PPM heatmaps for reproducible tuning review.
• Document snapshot and heatmap commands in the README.

Verification

• nix develop --command zig build worldgen-climate-snapshot -- --width 2 --depth 2 --output /tmp/opencode/climate-snapshot-test.json
• nix develop --command zig build worldgen-climate-snapshot -- --width 2 --depth 2 --format ppm --field humidity --output /tmp/opencode/climate-snapshot-test.ppm
• nix develop --command zig build test -- --test-filter ClimateSnapshot
• nix develop --command zig build test

Fixes #660

[github-actions]

📋 Summary

Linked Issue: Fixes #660 - "Worldgen Phase 3: add visual and debug snapshots for worldgen tuning"

The PR fully addresses issue #660 by adding deterministic climate snapshot capture for worldgen tuning. It introduces a new climate_snapshot.zig module with JSON and PPM heatmap output, a CLI build step worldgen-climate-snapshot, documentation in the README, and unit tests verifying determinism and value normalization. The workflow is entirely headless (no game window required) and outputs are written to configurable paths outside source control.

Overall Quality: Clean, well-structured implementation following existing codebase patterns with proper memory management, tests, and documentation.

---

📌 Review Metadata

• Reviewed Commit SHA: 08d755faa273518d63256aba127a7b0bf8c7ffc8
• Reviewed PR: feat: add worldgen climate snapshots #677
• Linked Issue: Worldgen Phase 3: add visual and debug snapshots for worldgen tuning #660 (fully addressed)

---

🔴 Critical Issues (Must Fix - Blocks Merge)

None identified.

---

⚠️ High Priority Issues (Should Fix)

None identified.

---

💡 Medium Priority Issues (Nice to Fix)

[MEDIUM] modules/world-worldgen/src/climate_snapshot.zig:22-33 - cave_region missing from Field enum
Confidence: High
Description: The Sample struct includes cave_region: f32 and it is serialized in JSON output, but the Field enum (used for PPM heatmap generation) does not include a .cave_region variant. This makes it impossible to generate a heatmap for cave regions despite the data being collected.
Impact: Incomplete heatmap feature - users cannot visualize cave_region data.
Suggested Fix: Add cave_region to the Field enum and handle it in fieldValue().

---

ℹ️ Low Priority Suggestions (Optional)

[LOW] src/worldgen_climate_snapshot_main.zig:62 - No help text printed for --help
Confidence: High
Description: The CLI parser returns error.HelpRequested when --help is passed, but no usage instructions are printed to stdout/stderr. The program exits with an error code instead of showing helpful information.
Impact: Poor user experience when users try to discover CLI options.
Suggested Fix: Print usage information to stderr before returning from main() when error.HelpRequested is caught, or handle it in parseArgs directly.

---

📊 SOLID Principles Score

Principle	Score	Notes
Single Responsibility	9	climate_snapshot.zig handles capture, serialization, and visualization logic cleanly separated into functions. CLI parsing is isolated in the main file.
Open/Closed	8	Easy to extend with new fields or output formats. The Field enum approach makes adding new heatmap fields straightforward.
Liskov Substitution	N/A	No inheritance hierarchies involved.
Interface Segregation	9	Clean separation between capture API (capture()), JSON writer (writeJson()), and heatmap writer (writeHeatmapPpm()).
Dependency Inversion	8	Uses module imports and allocator injection; no tight coupling to concrete implementations.
Average	8.5

---

🎯 Final Assessment

Overall Confidence Score: 92%

Confidence Breakdown:

• Code Quality: 90% (Clean Zig code, proper memory management, follows conventions)
• Completeness: 95% (Fully addresses issue Worldgen Phase 3: add visual and debug snapshots for worldgen tuning #660 requirements with tests and docs)
• Risk Level: 85% (Low risk - additive feature, no changes to existing systems)
• Test Coverage: 95% (Includes determinism and normalization tests, integrated into test suite)

Merge Readiness:

• All critical issues resolved
• SOLID average score >= 6.0
• Overall confidence >= 60%
• No security concerns
• Tests present and passing

Verdict:

MERGE WITH FIXES - One minor cave_region field omission in the heatmap enum should be addressed either in this PR or as a fast-follow.

---

{
  "reviewed_sha": "08d755faa273518d63256aba127a7b0bf8c7ffc8",
  "critical_issues": 0,
  "high_priority_issues": 0,
  "medium_priority_issues": 1,
  "overall_confidence_score": 92,
  "recommendation": "MERGE"
}

opencode session  |  github run

[github-actions]

📋 Summary

Linked Issue: Fixes #660 - "Worldgen Phase 3: add visual and debug snapshots for worldgen tuning"

The PR fully addresses issue #660 by adding deterministic climate snapshot capture for worldgen tuning. It introduces a new climate_snapshot.zig module with JSON and PPM heatmap output, a CLI build step worldgen-climate-snapshot, documentation in the README, and unit tests verifying determinism and value normalization. The workflow is entirely headless (no game window required) and outputs are written to configurable paths outside source control.

Overall Quality: Clean, well-structured implementation following existing codebase patterns with proper memory management, tests, and documentation.

---

📌 Review Metadata

• Reviewed Commit SHA: bc891c6d74ac5f778e026c370e7d6974a3b07489
• Reviewed PR: feat: add worldgen climate snapshots #677
• Linked Issue: Worldgen Phase 3: add visual and debug snapshots for worldgen tuning #660 (fully addressed)

---

🔴 Critical Issues (Must Fix - Blocks Merge)

None identified.

---

⚠️ High Priority Issues (Should Fix)

None identified.

---

💡 Medium Priority Issues (Nice to Fix)

None identified.

---

ℹ️ Low Priority Suggestions (Optional)

[LOW] modules/world-worldgen/src/climate_snapshot.zig:199-208 - cave_region normalization not tested
Confidence: Medium
Description: The cave_region field was added to the Field enum (addressing the previous review), but the normalization test "ClimateSnapshot values are normalized for heatmap fields" does not assert that sample.cave_region is within [0, 1]. Since fieldRange() returns {0.0, 1.0} for all non-height fields (including cave_region), the test coverage is incomplete.
Impact: Minor gap in test coverage; if cave_region ever produces values outside [0, 1], heatmap normalization will clamp them silently.
Suggested Fix: Add try std.testing.expect(sample.cave_region >= 0.0 and sample.cave_region <= 1.0); to the normalization test.

---

📊 SOLID Principles Score

Principle	Score	Notes
Single Responsibility	9	climate_snapshot.zig cleanly separates capture, serialization, and visualization. CLI parsing is isolated in the main file.
Open/Closed	8	Easy to extend with new fields or output formats via the Field enum.
Liskov Substitution	N/A	No inheritance hierarchies involved.
Interface Segregation	9	Clean separation between capture API (capture()), JSON writer (writeJson()), and heatmap writer (writeHeatmapPpm()).
Dependency Inversion	8	Uses module imports and allocator injection; no tight coupling to concrete implementations.
Average	8.5

---

🎯 Final Assessment

Overall Confidence Score: 95%

Confidence Breakdown:

• Code Quality: 92% (Clean Zig code, proper memory management with defer/errdefer, follows conventions)
• Completeness: 98% (Fully addresses issue Worldgen Phase 3: add visual and debug snapshots for worldgen tuning #660; previous review issues fixed)
• Risk Level: 90% (Low risk - purely additive feature, no changes to existing game systems)
• Test Coverage: 92% (Includes determinism and normalization tests; minor gap with cave_region)

Merge Readiness:

• All critical issues resolved
• SOLID average score >= 6.0
• Overall confidence >= 60%
• No security concerns
• Tests present and passing (if applicable)

Verdict:

MERGE - All previously reported issues have been resolved. The implementation is clean, well-tested, and fully satisfies the requirements of #660.

---

{
  "reviewed_sha": "bc891c6d74ac5f778e026c370e7d6974a3b07489",
  "critical_issues": 0,
  "high_priority_issues": 0,
  "medium_priority_issues": 0,
  "overall_confidence_score": 95,
  "recommendation": "MERGE"
}

opencode session  |  github run