Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Map Format Rework #579

Merged
merged 14 commits into from
Mar 10, 2024
Merged

Map Format Rework #579

merged 14 commits into from
Mar 10, 2024

Conversation

officialMECH
Copy link
Contributor

This PR overhauls the entire Map Format section of the wiki, providing a new structure and better organizational flow for content. The motivation is to make it easier for future maintainers to accommodate future changes to the schema and allow developers to better understand the semantics and relationships between versions.

Early documentation is also available for the v4 schema as introduced in 1.34.5, based on current knowledge from internal testing and clarifications from community members and official developers.

A preview deployment is available below if you'd like to preview all changes in action:
https://officialmech.github.io/wiki/mapping/map-format.html

I've summarized the main changes below, but if you have any additional questions or amendments that are necessary before merging feel free to let me know or request changes if necessary.

Summary

  • The "Overview" page has been expanded with information covering the more broad aspects of the map format:
    • Brief summaries of all historical schemas, including their mental models and any special behaviors associated with them.
    • Serialization behaviors that are version-independent (defaulted properties, file compression, etc.). This allows supports to be able to link to dedicated sections describing these behaviors and potential fixes/accommodations.
    • An expanded section on how custom data is modeled in each schema and links to documentation provided by mods or services that support custom data properties.
    • A new section where developers can link to scripting tools and frameworks that assist with or automate serialization.
  • Each map file has one dedicated page, where documentation of its contents are organized by scope rather than by field. This reduces the need to write the same content on multiple pages and establishes better semantics for how to describe the properties across schemas (since some fields end up being renamed in future schemas anyways).
  • Code groups (as provided by vitepress) are used to visually illustrate the changes between schemas. The intent is for the developer to be able to better identify the relationships between the different schemas, such that each snippet would ideally produce the same result when building wrappers or compatibility layers.
  • Sample files are included for every historical schema change, isolated from the markdown. This is mainly used as a broad reference for users to understand where the object groups are located in each file, but also allows developers to fetch these files directly from the repo if they'd like to use them for unit tests.
  • Many sections were updated or rewritten to fill out missing content, which means as of now the schema should be up-to-date with all features and capabilities introduced since 1.34.5.

Warning

There will most certainly be dead links in this PR that will need to be updated in external services, so if needed you can use the following conversions to handle redirects if necessary:

  • /mapping/infodat-format -> /mapping/map-format/info
  • /mapping/difficulty-format-v2 -> /mapping/map-format/beatmap
  • /mapping/difficulty-format-v3 -> /mapping/map-format/beatmap

Other Changes

  • vitepress-plugin-tabs was added as a dependency and configured for the project. The plugin allows you to define tabs for sectioned content without needing to wrap the content in a code group.

Copy link
Contributor

@XAce1337manX XAce1337manX left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Content looks good. Just a few typos and a note.

@bloodcloak bloodcloak merged commit fc145f0 into bsmg:master Mar 10, 2024
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants