{"id":18985072,"url":"https://github.com/o3de/o3de-extras","last_synced_at":"2025-04-04T22:03:03.825Z","repository":{"id":37968357,"uuid":"505912410","full_name":"o3de/o3de-extras","owner":"o3de","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-28T12:33:18.000Z","size":80762,"stargazers_count":67,"open_issues_count":66,"forks_count":68,"subscribers_count":23,"default_branch":"development","last_synced_at":"2025-03-28T13:36:22.761Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/o3de.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-21T16:00:48.000Z","updated_at":"2025-03-28T12:33:22.000Z","dependencies_parsed_at":"2023-09-29T21:48:45.554Z","dependency_job_id":"fd683bd2-e655-4f48-a883-22abf1cac406","html_url":"https://github.com/o3de/o3de-extras","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3de%2Fo3de-extras","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3de%2Fo3de-extras/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3de%2Fo3de-extras/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/o3de%2Fo3de-extras/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/o3de","download_url":"https://codeload.github.com/o3de/o3de-extras/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247256104,"owners_count":20909240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T16:24:31.539Z","updated_at":"2025-04-04T22:03:03.804Z","avatar_url":"https://github.com/o3de.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# o3de-extras\nAs the name implies, o3de-extras repo is for \"Extra\" O3DE objects that are considered \"Canonical\" to O3DE but not \"Core\" to the engine.\n\n## O3DE modularity\nO3DE is highly modular engine and is essentially a collection of O3DE objects.\nO3DE objects are things like projects and gems, discrete objects that can be hierarchical, meaning one object may be the parent or child of another object, some O3DE objects have no children or parents at all.\nIf an O3DE object has no parent, we say it is a \"top level object\".\nO3DE objects can exist anywhere on your local filesystem, so we do have to tell O3DE where they are by registering all top level objects.\nChild objects do not need to be registered as O3DE finds them automatically when the parent is registered.\nThe result of registration is an entry for each top level object in the `\u003cuser\u003e/.o3de/o3de_manifest.json`.\nAs a matter of organization, child objects are always under the root of the parent object.\nFor instance the engine itself is a top level object and a parent object.\nThe engine is the parent of many child objects, such as AutomatedTesting project which lives under its root. \nAutomatedTesting project is the child of the engine object but also is the parent of still other O3DE objects under its root, and has a child gem.\nGems (which are reusable pieces of an o3de project, which other engines might call a plugin) can have other gems as children, and so on. \nSometimes it is better for an object to not be child, such as when its functionality may not always be needed, or is a community object.\n\n## Core, Canonical and Non-Canonical repos and objects\nCanonical means officially supported, tested and part of an official O3DE release.\nNon-Canonical means unofficial, untested and not part of an official O3DE release.\nCore means it's in the o3de/o3de core engine repo.\nRepos, including some o3de.org repos, may or may not be Canonical.\nAnd it follows that any object in a Canonical repo is a Canonical object.\nCanonical objects may not rely on any Non-Canonical objects.\nAny object in a Non-Canonical repo is considered a Non-Canonical object.\nCurrently, the core engine (o3de/o3de) and the extras (o3de/o3de-extras) are Canonical repos, and therefore all the object contained within are Canonical.\nCanonical repos/objects must meet a few O3DE requirements:\n\n1. They are owned by the O3DE.org/Linux Foundation.\n2. They are held to the O3DE coding standard.\n3. Their content is managed by a O3DE Special Interest Group (SIG).\nThat SIG controls that Canonical object and has passes judgement on what is and is not included by that object. \n4. All additions, changes to existing Canonical objects must pass an automated review (AR) in which multiple maintainers code review and approve the change.\nThe AR system pulls all Canonical repos, registers all Canonical objects, enable all Canonical gems for the AutomatedTesting project, configures, builds and executes all tests.\nEverything must pass before it can be accepted into a Canonical repo.\n5. All Canonical repos are by definition part of an O3DE release and so must maintain at least 2 branches, a main branch and a development branch.\nThe main branch is the stable release which is tagged.\nThe development branch is the cutting edge and is branched for stabilization for a release.\nOnce stabilized, the stabilization branch is merged into main and tagged for the release.\nAll changes to stabilization changes are also merged back into development branch.\n\n## Core engine objects (i.e. the objects in o3de/o3de) have an additional requirement:\nAnything included in the core must build and not rely on anything outside the core.\nSo with just the o3de/o3de core repo, the engine and AutomatedTesting project must build.\nSo if an object is needed or the engine will fail to build, then it is by definition a core object and MUST be in the o3de/o3de core engine repo. \nWhat we don't want is to have too many core objects.\nWe want the core to be as small as possible, so that it can run on the widest range of devices possible.\nSo consideration of the object size and purpose/usefulness should go into the decision on whether the object belongs in the core, extras or another repo.\nWhat objects are excepted into the core should be held to a higher bar than objects in the extras.\nSome objects may not be needed to build the engine or AutomatedTesting project but may be considered so useful or \"core\" to the engine we decide to just include it in the core.\nThe objects in the core should represent core functionality and should be useful to nearly anyone using O3DE.\n\n## Core or Extras or somewhere else?\nHow do we know where to put a new object? \nIf an object's functionality is optional, this is a good indication it may not be suitable for the core and more likely should be in the extras or another repo.\nIf the object is large, such as a large project which can be many gigabytes in size, this definitely not in the core, most likely not in the extras, and should probably be in its own repo.\nExtras should be the default place for new development.\nNew core objects should be a red flag and there should be debate and justification on why this new object is core.\nWe can always promote an extras object in to the core if we want, and we can always demote a core object into the extras.\nOnce an object has outlived its usefulness it should be demoted into another Non-Canonical deprecation repo.\n\n## New Canonical repos\nWhen we add a new Canonical repo all SIG's must update their processes to include checking those repos for issues just as they do for the core engine repo.\nSo caution should be taken in how many repos we consider Canonical, as this increases load on the SIGs.\n\n## Testing\nAll Canonical repos like o3de/o3de-extras and o3de/o3de, use O3DE's automated review (AR) system to gate pull requests (PR's).\nSo o3de-extras objects are tested with the engine and follow the same coding standards and thus should be thought of as part of the engine.\nWhen AR is performed on a PR to the core engine, o3de-extras development branch is also pulled, registered and gems enabled for the AutomatedTesting project by referencing them in the .automatedtesting.json.\nSimilarly, when AR is performed on a PR to the extras, the core engine development is pulled, registered and gems enabled for the AutomatedTesting project by referencing them in the .automatedtesting.json.\nEverything must build and all tests must pass, with multiple maintainers approving code reviews in order to accept the PR.\n\n## Branches\nJust like the core engine, the main branch is the stable release branch and is tagged for release, while the development branch is the cutting edge.\nWhen working on the code make a branch of development, make your changes, create your PR, run and pass AR, merge into development.\n\n## Contribute\nFor more information about contributing to O3DE, visit [https://o3de.org/docs/contributing/](https://o3de.org/docs/contributing/).\n\n## Download and Register o3de-extras\n\n### Clone the repository \n\n```shell\ngit clone https://github.com/o3de/o3de-extras\n```\n\nFor more details on setting up the engine, refer to [Setting up O3DE from GitHub](https://o3de.org/docs/welcome-guide/setup/setup-from-github/) in the documentation.\n\n### Setting up o3de-extras\n\nSince the o3de-extras repo can be cloned anywhere on your local computer, we just need to tell O3DE where to find the extra objects in this repo by registering them.\nFrom the O3DE repo folder, you can register some or all extra objects using the `o3de register` command.\nSince these are all optional objects, we may not need or want all the objects.\nIf we want to register a particular object such as a single gem we would issue the following command:\n```\nscripts\\o3de.bat register --gem-path \u003co3de-extras\u003e/Gems/\u003cgem name\u003e\n```\nOr you may want to register all the Gems.\nSince this repo follows the [standard O3DE compound repo format](https://github.com/o3de/o3de/wiki/O3DE-Standard-repo-formats) all the o3de-extras gems will be in the `\u003co3de-extras\u003e/Gems` path.\nWe can therefore register all the gems in the extras gems path with one command:\n```\nscripts\\o3de.bat register --all-gems-path \u003co3de-extras\u003e/Gems\n```\nThis can be repeated for any object type (if they exist):\n```\nscripts\\o3de.bat register --all-engines-path \u003co3de-extras\u003e/Engines\nscripts\\o3de.bat register --all-projects-path \u003co3de-extras\u003e/Projects\nscripts\\o3de.bat register --all-gems-path \u003co3de-extras\u003e/Gems\nscripts\\o3de.bat register --all-templates-path \u003co3de-extras\u003e/Templates\nscripts\\o3de.bat register --all-restricted-path \u003co3de-extras\u003e/Restricted\n```\nIf we registered a gem, which is a piece of a project like a plugin, and we want to use that gem in our project we would only have to tell O3DE to enable that gem for our project by using the `o3de enable-gem` command:\n```\nscripts\\o3de.bat enable-gem --gem-name \u003cgem name\u003e --project-name \u003cproject name\u003e\n```\n\nFor a complete tutorial on project configuration, see [Creating Projects Using the Command Line Interface](https://o3de.org/docs/welcome-guide/create/creating-projects-using-cli/) in the documentation.\n\n## License\n\nFor terms please see the LICENSE*.TXT files at the root of this distribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo3de%2Fo3de-extras","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fo3de%2Fo3de-extras","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo3de%2Fo3de-extras/lists"}