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.
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:
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.
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
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.Other Changes
vitepress-plugin-tabswas 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.