Match Official API

[hammy275]

Important!

See #14 (comment) for deprecation plans for MC VR API

Original Comment

NOTE: This is the ONLY other planned major version bump.

The Vivecraft developers plan to release an official API at some point. Once it releases, this API should be updated to match it as closely as possible. There isn't a need to have all the features from the official one, however all of the functions we implement should be named and sorted the same way as the official API.

Until the official API releases, this issue won't be closed

[hammy275]

It may be worth considering adding the official API on top of the unofficial one, rather than retooling it. Aka you'd have the IVRAPI instance and a new IVivecraftAPI instance or something, with the former containing the 1.x API and the new one containing the 2.x API.

[hammy275]

To clarify, the main goal of doing this is mainly to allow one codebase to easily work with versions both before and after the official API. I may end up even replicating the classpaths as a result, so imports can even remain.

Note that I will likely only be implementing features that have an equivalent already in MC VR API as a result.

[hammy275]

Here's exactly how I plan for the transition to the official API to happen, documented here. If people have feedback or questions on it, please feel free to send it my way, either here or somewhere else.

Transition Plans

Upon the merge of the official API, it will be backported to MC VR API*. The backport will not replace MC VR API's interfaces, and as a result, will cause a minor version bump (3.1.x) instead of a major version bump (4.x.y) so as to not break semantic versioning. This backport will be supported back to Minecraft 1.18.2, and will be supported on all Vivecraft versions already supported by MC VR API (installer and mixin).

*: The backport will have the interfaces in different packages. This will make import statements different, but it will otherwise be functionally identical.

Simultaneously, MC VR API as a whole will cease feature development. Since the next Minecraft version after the merge will only have Vivecraft versions with an official API, MC VR API becomes unnecessary to maintain/improve outside of bugfixes. MC VR API will continue to be maintained for some unknown amount of time, but will not make its way to these newer versions, one is expected to use the official API on these versions.

The intention behind the handling of this transition is:

• The official API being backported and the time before deprecation is done to give mod developers relying on MC VR API time to move to the official API.
• The official API being backported is done to give mod developers who wish to use the new API the ability to use it independent of a user's Vivecraft version.
• The official API being backported is done to allow mod developers who have mods on multiple Minecraft versions (such as ImmersiveMC) to have one, consistent way to interact with Vivecraft.

Why?

MC VR API was originally created as a stopgap until Vivecraft got an official API so I could add features to a private mod. An official API was planned at the time of MC VR API's creation, but that did not come to fruition. Although the features to the aforementioned private mod were never added, I developed MC VR Playground to demonstrate what the API could do, which then got spun off into ImmersiveMC. After a while however, I decided to sit down and finally write a better API for Vivecraft itself, as Vivecraft and MC VR API being separate mods didn't make much sense. Since the API will now be built into Vivecraft, there is no purpose to MC VR API, hence its deprecation.