Open 3D Engine Versioning and Release Terminology

Open 3D Engine (O3DE) Version Numbering

O3DE uses MAJOR.MINOR.PATCH semantic versioning for all the version fields in engine.json, gem.json and project.json files to indicate API and other important changes.

• MAJOR is for API-breaking changes
• MINOR is for non-API-breaking changes that add new APIs or change them in a non-breaking way
• PATCH is for all other non-API-breaking changes, usually important fixes

The engine display version uses YY.MM.PATCH and is only used in the O3DE SDK. By using a date-oriented scheme for the SDK display version users can easily tell how recently an engine SDK was released, but it does not provide any information about compatibility or the kinds of changes made.

O3DE Release Terminology

• Stable: This feature is ready for users to actively develop using it. APIs and functionality can be considered stable and any significant new work will be captured in an RFC before changes are made.
• Preview: This feature is almost done and is stable. May still go through small changes.
• Experimental: This feature is a work-in-progress. Don’t depend on it yet; it may go through significant changes.

Engine Version Information In engine.json

O3DE engine version information is stored inside the engine.json file at the root of the engine.

Example:

A developer may use the compatible_engines field in their gem.json to indicate that their gem is known to be compatible with any engine in development named o3de version 2.0.0 or higher or an SDK engine named o3de-sdk that is exactly version 1.2.0.

{
    "gem_name":"CustomGem",
    "compatible_engines": [
        "o3de>=2.0.0",
        "o3de-sdk==1.2.0"
    ]
}

Engine APIs

The API versions specified in the api_versions field in engine.json are currently based on the content inside the engine’s Code folder and are provided as simple but useful way for developers to indicate compatibility when they expect their gem or tool to be compatible with multiple engine versions unless breaking changes are made to APIs inside the engine’s Code folder.

Example:

A developer that creates a gem that includes an Editor tool, may update their gem.json file to indicate the gem is known to be compatible with any non-breaking version of the Editor APIs.

{
    "gem_name":"EditorToolGem",
    "engine_api_dependencies": [
        "editor~=1.0.0"
    ]
}