Feature request: Feature Add single page 'TLDR' style folder structure of project

[OBWANDO]

Preface:

Community member wrote: I guess what I'm mostly confused about is the way the project is structured and where we are expected to put the project code in. I'm very new to O3DE and Lumberyard, having only really worked with UE4 before so I'll keep playing with it before I come asking questions.

Feature

Add a simple page that shows the folder structure of O3DE and where files go (code, assets, gems / etc) If the path is fluid, provide a best practices approach.

What is the relevance of this feature?

This will help users accelerate adoption by gaining a clear understanding of where things should be and create consistency.

What are the advantages of the feature?

Speed and clarity

What are the disadvantages of the feature?

Maintenance if core folder locations change

Feature design description

Create a simple page that may show each folder path, the type of files that belong in there, and a link to the corresponding area where they can learn more about that type of object in our docs..

[lemonade-dm]

The project structure can be seen when a new project is created via the scripts\o3de.py create-project command or by the Project Manager. The Default Project template contains the layout of a new project

<Project Root>/.
    Assets/.
    build/.
    Cache/.
    Code/.
    Platform/.
    Registry/.
    Resources/.
    ShaderLib/.
    Shaders/.
    user/.
    CMakeLists.txt
    EngineFinder.cmake
    project.json
    README.md

[OBWANDO]

Where should someone put Meshes? Textures? Animations? Sounds? Script Canvas Scripts? project config files? Are there places where they should look first as a best practices that might match how the current gems were made?

And speaking of gems... What about gems? How should they be structures? Do they belong in the project?

[lemonade-dm]

Meshes, Animations, Sounds, Script Canvas Scripts are all assets that should be placed with the Assets directory. Project Config files would be Settings Registry files that are placed with the Registry directory.

Gems that should be(and can be) distributed with the project can live within the Code directory.

External Gems that are distributed separately from a project or can't be distributed with a project due to licensing reasons can live in a standalone location where it gets registered with the project via the O3DE registration system.

The mechanism for how Gems are treated by O3DE as follows. Definition: External Subdirectory- A directory with a CMakeLists.txt. Can be used to hook any user directory into the CMake build generator. Definition: Gem - An External Subdirectory with an additional file, which is the gem.json. A valid gem.json is only required to that contain a "gem_name" field in it. That is it, no other requirements for a gem exist.

Registration: Gem's are registered in one of three locations.

1. ~/.o3de/o3de_manifest.json - The user's global manifest file - Specific to that user's machine A gem that is registered in the o3de_manifest.json will be available for selection within the Project Manager. This does not affect whether a Gem appears within a build solution
2. The project's project.json - The project's manifest file - Distributed with the project be that via downloading or source control. Any registered gems here, will be added to any build solution generated when that Project is in configured. By "configured", what is meant is that if a project-centric workflow is used, CMake is run from the project root directory. If an engine-centric workflow is used, CMake is run from the engine root directory, but the path to the project is supplied via the LY_PROJECTS option
3. The engine's engine.json - The engine's manifest file - Distributed with the engine, be that via downloading the engine or syncing it through source control. Registered gems in the engine.json can be seen as official gems that come with O3DE. ALL gems in the engine are registered in the engine.json. This means Atom, EMotionFX, ScriptCanvas, etc... If a gem isn't in the engine.json isn't added to any build solutions when the engine is configured. In this case what "configured" means, is that when using the Engine in an engine-centric workflow(via running CMake from the engine root directory) or using a project-centric workflow with a source code engine(as opposed to an pre-built SDK) engine

So to sum up the 3 states of registration the following can be studied

User Global - o3de_manifest.json - 1. Gem will appear in Project Manager and be select-able Project Specific - project.json - 1. Gem will appear in Project Manager and be select-able. 2. Project will add gem to build solution when the project is configured through CMake. Engine Specific - engine.json - 1. Gem will appear in Project Manager and be select-able. 2. Engine will add gem to build solution when the engine is configured via CMake. A project is not required to have the gem appear in the build solution

Enabling a Gem: An enabled gem is the state of having a project's "main" applications(GameLauncher, Editor, AssetProcessor) depend on that gem.

1. A gem must be either registered with the project.json or engine.json in order to enable it. The reason for this is that it must be part of the build for the project or engine in order for the build system to add it as a dependency.

The Best Practice for place to look an example gem, is for users to create a gem using the default gem template. The O3DE scripts of scripts\o3de.py that comes with the engine can create a gem with the proper layout in files and should be what the user endeavors to use. Currently the method for creating a gem is using the command line: scripts\o3de.bat create-gem <path-to-new-gem>

[sptramer]

This isn't an RFC, this is just a feature request. Moving to the o3de.org repo as such.