Data-Driven Dungeon (JSON Level Loading) - Json

[222448082Ashen]

Description

This PR implements Data-Driven Dungeon (JSON Level Loading). It provides comprehensive usage examples across C++, C#, and Python, while also fixing a critical build failure in the API documentation generation script caused by incomplete metadata.

Type of change

• Bug fix (fixed TypeError in api-pages-script.cjs due to missing JSON fields)
• New feature (added two new complex integration examples)
• Documentation (updated Physics and Json usage indices)

How Has This Been Tested?

• Local Build: Ran node scripts/api-pages-script.cjs manually to confirm the TypeError is resolved and all MDX files generate successfully.
• Verification Script: Executed node scripts/usage-examples-testing-script.cjs for both celestial_mechanics-1-example and data_driven_dungeon-1-example to verify the 6-file requirement.
• C++ Compilation: Verified C++ logic by compiling on Windows using g++ against the SplashKit SDK.

Testing Checklist

• Tested in latest Chrome
• Tested in latest Firefox
• npm run build
• npm run preview

Checklist

If involving code

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

Folders and Files Added/Modified

• Added:
  • physics (Celestial Mechanics source + metadata)
  • json (Data-Driven Dungeon source + metadata + level_data.json)
• Modified:
  • api.json (Added full schema for new functions to satisfy build scripts)

Additional Notes

The api-pages-script.cjs was failing because it expects parameters and signatures objects for all functions in api.json. These have been explicitly added for the new examples to restore the Netlify build pipeline.

[netlify]

✅ Deploy Preview for splashkit ready!

Name	Link
🔨 Latest commit	2e47efe
🔍 Latest deploy log	https://app.netlify.com/projects/splashkit/deploys/69d0664eaf07d000084175fd
😎 Deploy Preview	https://deploy-preview-713--splashkit.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[jankiluitel]

Well done on putting the Data-Driven Dungeon and Celestial Mechanics concepts into practice; this is a powerful and organised contribution.

• I truly enjoy:The examples are more realistic and scalable due to the usage of data-driven design with JSON.
  Several languages (C++, C#, Python) are included, which is in line with SplashKit's cross-platform objectives.
  Clearly making an attempt to finish the necessary metadata in order to fix the api-pages-script issue

Here are some ideas for enhancements:

• The PR is difficult to review due to its size (more than 300 lines spread across several sections). Future modifications could benefit from being divided into smaller PRs (e.g., examples vs. build fixes).Since the API was altered.json, it would be beneficial to verify that no current API documentation behaviour is inadvertently impacted.
• Adding brief comments or explanation in complex sections (especially physics logic and JSON structure) could improve readability for new learners.

Overall, this is a valuable and advanced contribution. Nice work!

[jankiluitel]

This is a strong and advanced contribution — the data-driven approach using JSON and the inclusion of multiple languages (C++, C#, Python) are very valuable for demonstrating real-world usage.

I especially liked:

• Clear use of JSON for structured level data (spawn points, loot, metadata)
• Consistent implementation across multiple languages
• Inclusion of a visual output (PNG), which improves usability

Some suggestions and potential issues to consider:

1. Path handling inconsistency (C++):
   The C++ example uses:
   json_from_file("public/usage-examples/json/level_data.json");
   and then falls back to "level_data.json".
   This could cause confusion depending on execution context. It might be better to standardise a single relative path consistent with other examples.

2. API consistency across languages:
   Python and C# load JSON using simpler paths, while C++ includes fallback logic. Aligning behaviour across languages would improve consistency for learners.

3. Python refresh function:
   refresh_screen(60) is used, but in SplashKit Python the preferred function is refresh_screen_with_target_fps(). This may cause runtime inconsistencies.

4. api.json modifications:
   Changes to api.json are quite extensive and tightly coupled to build scripts. It would be good to confirm:

• No unintended impact on existing API pages
• All required fields follow the expected schema strictly

5. PR size:
   This PR combines multiple concerns (new examples + api.json fixes + physics examples). Splitting into smaller PRs would improve reviewability and reduce risk.

Overall, this is a high-quality and complex contribution, but addressing the above points would improve maintainability and consistency across the project.

[222448082Ashen]

Thank you so much for the thoughtful and detailed review, and for the encouraging feedback. I really appreciate it.

Your points are very fair, and I agree with the direction:

1. PR scope and reviewability
   I agree this PR became too broad. I will split concerns into smaller PRs so each review is focused and lower risk:

• Data-Driven Dungeon example
• Celestial Mechanics example
• API/build-script related fixes

2. Path handling consistency
   Great callout. I have aligned JSON loading to one consistent relative path style and removed mixed/fallback path behavior so execution context is clearer.

3. Cross-language consistency
   I agree this is important for learners. I am aligning C++, C#, and Python behavior so they follow the same flow:

• load JSON
• parse rooms/loot/enemies
• draw/display output

4. Python refresh API usage
   Also fixed. I updated the Python variant to use refresh_screen_with_target_fps(60) for consistency with SplashKit Python expectations.

5. api.json and build safety
   I have been validating this carefully to avoid regressions:

• checked for unintended API-doc behavior changes
• confirmed generated links/anchors are valid
• reran the full build pipeline and link validation successfully

6. Readability improvements
   Agreed. I am adding short comments in dense sections (JSON structure/parsing, spawning, and movement/physics logic) to improve clarity for new learners.

Thanks again for the high-quality review. It helped improve both maintainability and consistency, and I will keep the next updates smaller and more focused.