Version:

Gem Manifest File (gem.json)

The gem.json manifest provides data about a Gem. Each Gem must have a gem.json file at the root folder of that Gem.

gem.json Manifest Contents

FieldRequiredDescription
gem_nameRequiredThe name of this gem. This name must be fewer than 64 characters and contain only alphanumeric, ‘_’ or ‘-’ characters, and start with a letter.
display_nameRequiredThe user-friendly display name for this gem. This name will be displayed in user interfaces and can contain characters not allowed in the gem_name field.
canonical_tagsRequiredA list of pre-defined tags used to differentiate types of manifests which can be Project, Template or Gem. For Gems this field should always be Gem.
compatible_enginesOptionalA list of engine names and optional version specifiers that this gem is known to be compatible with: i.e. o3de>=2.0.0, o3de-sdk==1.2.0, o3de-custom etc. If empty, the gem is assumed compatible with all engines if they meet all the requirements in the engine_api_dependencies and dependencies fields. See Gem Versioning for details.
dependenciesOptionalThe names of any other Gems, your Gem directly depends on with optional version specifiers: i.e. Atom>=1.0.0, PhysX==2.0.0, ScriptCanvas etc. See Gem Versioning for details.
documentation_urlOptionalThe URL of the documentation for your gem: i.e. https://www.mydomain.com/docs .
download_source_uriOptionalThe URI of the .zip file containing the Gem archive. This is a direct download to the Gem’s .zip archive: i.e. https://github.com/o3de/o3de-extras/releases/download/1.0/Example-2.0.zip
engine_api_dependenciesOptionalA list of engine API dependencies. If empty, the Gem is assumed compatible with all versions of any engine APIs. See Gem Versioning for details.
icon_pathOptionalThe relative path to the filename of the icon image file, usually preview.png.
last_updatedOptionalThe date this file or Gem was last updated in YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, or YYYY-MM-DDTHH:MM:SS format.
licenseRequiredThe license this Gem uses: i.e. Apache-2.0 or MIT.
license_urlRequiredThe URL for the license website: i.e. https://opensource.org/licenses/Apache-2.0 Or https://opensource.org/licenses/MIT .
originRequiredThe name of the originator for this Gem: i.e. XYZ Inc.
origin_uriOptionalDeprecated and replaced by download_source_uri.
origin_urlOptionalThe URL of the originator for this gem: i.e. https://www.mydomain.com .
platformsOptionalA list of platforms this Gem is known compatible with: i.e. “Windows”,“Linux”,“Android”,“iOS”,“MacOS” etc.
repo_uriOptionalThe URI for the Gem repository containing this Gem.
requirementsOptionalNotice of any requirements your Gem has: i.e. This Gem requires you install X from https://www.mydomain.com .
sha256OptionalThe SHA-256 digest of the .zip archive that the origin_uri field points to. You can omit this field for testing, but we highly recommend including it.
source_control_refOptionalThe source control reference for this Gem version. This can be a tag, commit hash or branch: i.e. release-1.0.0, 0462139, development etc.
source_control_uriOptionalThe URI of the source repository for this Gem: i.e. https://github.com/o3de/o3de-extras .
summaryRequiredA short description of your Gem.
typeRequiredThe type of gem which can be Code, Asset or Tool. This field is used as a filter in the Project Manager.
user_tagsOptionalA list of user-defined tags used to categorize Gems. This list should always include the name of your Gem, and any other common tags that might help a user discover your gem: i.e. Network, Rendering, Utility, Scripting etc.
versionOptionalThe MAJOR.MINOR.PATCH semantic version that is updated as changes are made to the gem. Developers may use the dependencies field in gem.json to indicate other gem dependencies and the version ranges they are compatible with. See Gem Versioning for details.

gem.json Manifest Examples

ScriptCanvas Tool Gem gem.json Manifest

ScriptCanvas is a Tool type gem that comes with the engine and provides Editor and game functionality.

{
    "gem_name": "ScriptCanvas",
    "display_name": "Script Canvas",
    "version": "1.0.0",
    "license": "Apache-2.0 Or MIT",
    "license_url": "https://github.com/o3de/o3de/blob/development/LICENSE.txt",
    "origin": "Open 3D Engine - o3de.org",
    "origin_url": "https://github.com/o3de/o3de",
    "type": "Tool",
    "summary": "The Script Canvas Gem provides Open 3D Engine's visual scripting environment, Script Canvas.",
    "canonical_tags": [
        "Gem"
    ],
    "user_tags": [
        "Scripting",
        "Tools",
        "Utility"
    ],
    "icon_path": "preview.png",
    "requirements": "",
    "documentation_url": "https://o3de.org/docs/user-guide/gems/reference/script/script-canvas/",
    "dependencies": [
        "ScriptEvents",
        "ExpressionEvaluation",
        "GraphCanvas"
    ],
    "compatible_engines":[],
    "engine_api_dependencies":[]
}

AudioEngineWwise Code Gem gem.json Manifest

AudioEngineWwise is a Code type gem that comes with the engine that requires an external application be installed in order to use it.

{
    "gem_name": "AudioEngineWwise",
    "display_name": "Wwise Audio Engine",
    "version": "1.0.0",
    "license": "Apache-2.0 Or MIT",
    "license_url": "https://github.com/o3de/o3de/blob/development/LICENSE.txt",
    "origin": "Open 3D Engine - o3de.org",
    "origin_url": "https://github.com/o3de/o3de",
    "type": "Code",
    "summary": "The Wwise Audio Engine Gem provides support for Audiokinetic Wave Works Interactive Sound Engine (Wwise).",
    "canonical_tags": [
        "Gem"
    ],
    "user_tags": [
        "Audio",
        "Utility",
        "Tools"
    ],
    "icon_path": "preview.png",
    "requirements": "Users will need to download Wwise from the <a href='https://www.audiokinetic.com/download/'>Audiokinetic Web Site</a>.",
    "documentation_url": "https://o3de.org/docs/user-guide/gems/reference/audio/wwise/audio-engine-wwise/",
    "dependencies": [
        "AudioSystem"
    ],
    "compatible_engines":[],
    "engine_api_dependencies":[]
}

DevTextures Asset Gem gem.json Manifest

DevTextures is an Asset type gem that comes with the engine and provides general purpose texture assets useful for prototypes and preproduction.

{
    "gem_name": "DevTextures",
    "display_name": "Dev Textures",
    "version": "1.0.0",
    "license": "Apache-2.0 Or MIT",
    "license_url": "https://github.com/o3de/o3de/blob/development/LICENSE.txt",
    "origin": "Open 3D Engine - o3de.org",
    "origin_url": "https://github.com/o3de/o3de",
    "type": "Asset",
    "summary": "The Dev Textures Gem provides a collection of general purpose texture assets useful for prototypes and preproduction.",
    "canonical_tags": [
        "Gem"
    ],
    "user_tags": [
        "Assets",
        "Debug",
        "Utility"
    ],
    "icon_path": "preview.png",
    "requirements": "",
    "documentation_url": "https://o3de.org/docs/user-guide/gems/reference/assets/dev-textures/",
    "dependencies": [],
    "compatible_engines":[],
    "engine_api_dependencies":[]
}