Initial progress towards a backwards-compatible API

[Rubydesic]

Background

VS2, in development since 2019, was conceived as a library mod enabling other mods (addons) to utilize its physics code for diverse gameplay experiences beyond steampunk. Over four years, this vision materialized with addons like Eureka, Clockwork, Valkyrien Computers, and Tournament, ushering in a new era for Valkyrien Skies. Despite this, an officially supported, backward-compatible API was absent, until now.

Terminology

• VS2: Valkyrien Skies 2
• API¹: Application Programming Interface
• api: New stable API module

Why

Valkyrien Skies updates can disrupt addons that rely on modified or removed public classes, necessitating updates from the addon developer. Until now, addons have been directly depending on Valkyrien Skies' internals, the API of which is in constant flux. This imposes a burden on developers and users, resulting in unnecessary updates and compatibility issues.

What

This PR introduces api, a new module for addon developers. It contains essential functions from VS2 internals needed for addon development. We commit to maintaining the api module and only making non-backward-compatible changes when absolutely necessary. Addons using elements solely from the api module should not require frequent updates to support new VS2 versions.

Some crucial classes for addon development may still be missing from this PR. Addon developers are encouraged to communicate any additions they'd like to see in api.

Future Plans

Experimental APIs

Certain parts of the API may be labeled with an @Experimental annotation. These may not be maintained in a backward-compatible manner. We will introduce a config flag in VS2 to enable these experimental APIs, ensuring user transparency, a-la Java 17's strong encapsulation.

Blocking Internal Access

To prevent addons from inadvertently relying on internals and causing confusion for users when VS2 updates, we will gradually restrict access to various parts of VS2 internals for addons.

Other changes

For VS2 contributors, this PR significantly changes the structure of the Gradle multiproject build. It uses the Kotlin DSL for Gradle rather than the Groovy one, and it also introduces a second set of subprojects (api:common, api:fabric, api:forge) for api. We also use precompiled script plugins rather than Gradle allprojects/subprojects block for configuration. The old fabric, forge, and common projects are now located in the base directory.

Footnotes

1. For the technical-minded among you, when I say "API", I am also referring to the ABI ↩

[ewoudje]

When the when

[ewoudje]

Some way to access all constraints, id say expose a iterator?
Also we prob also want to store the ID, of the constraint in the constraints themselves.