generated from cncf/hugo-netlify-starter
-
Notifications
You must be signed in to change notification settings - Fork 165
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Adds documentation for script-only mode and templates (#2536)
* Adds documentation for script-only mode and templates * The welcome guide now links to the new page about templates, which is a list of which templates are available and what they do. * The new templates page includes instructions on how to use non-project templates. * The new script-only 'Quick Start' page explains what a script-only project is, how to create one, and how to use them, as well as includes technical details about how the system works. * Fixed a capitalization and plural typo Signed-off-by: Nicholas Lawson <[email protected]>
- Loading branch information
1 parent
7efd373
commit 2b7cd65
Showing
4 changed files
with
157 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| --- | ||
| linktitle: Script-Only 'Quick Start' Projects | ||
| title: Script-only 'Quick Start' Projects | ||
| description: Describes how Script-only 'Quick Start' projects work in O3DE | ||
| weight: 100 | ||
| toc: true | ||
| --- | ||
|
|
||
| Projects in O3DE can be created in a mode which disables all C++ compiling and linking, including the downloading of any libraries that would otherwise be used by those linkers. In this 'Script-only' mode, the project can only make use of pre-compiled gems and components, from shared libraries, but can still otherwise use Lua and Script Canvas to create game logic, and Python to create editor tooling. | ||
|
|
||
| Script-only mode is also known as "Quick Start" mode, because the lack of need to compile anything using C++ or link anything means that the 'build time' for the project is very quick (seconds), and iteration can be much faster. | ||
|
|
||
| The down-side of Script-only mode is that no C++ components can be created and used by the game project itself, unless they are pre-built by other means and injected by some other build system, and all existing libraries used must also be pre-built, such as the ones that are included using the installer layout of the engine. | ||
|
|
||
| Third party gems and plugins can only be used if they are also pre-built. | ||
|
|
||
| Despite these limitations it is a way to quickly get into the editor and start creating immediately, without downloading a compiler and without downloading any additional c++ development libraries such as the Qt SDK. | ||
|
|
||
| ## Creating a Script-only Project | ||
| You can create a new Script-only project by using the ScriptOnlyProject [template](/docs/user-guide/build/templates.md), see the [Creating Projects](/docs/welcome-guide/create) document for more information. | ||
|
|
||
| You can also convert an existing project into a Script-only project by modifying the `project.json` file in the root. The flag that determines whether a project is script-only is the following tag at the root of a `project.json`: | ||
| ```json | ||
| "script_only": true, | ||
| ``` | ||
|
|
||
| The default value is false, so projects without this tag are not script-only. | ||
| If you do convert an existing project to script only, you may need to remove any C++ modules that already exist in it, or disable them from the build system, or encounter errors. | ||
|
|
||
| You may also have to copy the `EngineFinder.cmake` file from an existing script-only project (or the script-only project template in the `templates` folder) into the project's cmake subfolder. | ||
|
|
||
| ## Converting a Script-only project to a compiled project | ||
|
|
||
| To switch back to a 'normal' project, flip the same above flag to false, or remove it from the `project.json`. | ||
| You can then start adding C++ components to your project or use the [template](/docs/user-guide/build/templates.md) system to instantiate new c++ components. You may need to modify the CMake build files to include new subdirectories containing code, just like any project. | ||
|
|
||
| ## Shipping a Script-only project | ||
| Script-only projects do include a script at the root to export the project into a standalone project. See the [Project Export](content/docs/user-guide/packaging/project-export) documentation for details on how project export functions, as it is the same export system used as regular projects. | ||
|
|
||
| ## Trade-offs to be aware of | ||
|
|
||
| ### There is no monolithic build | ||
| Because no C++ compiler or linker is involved and no 3rd party libraries are downloaded, packaging and releasing a script-only mode project will ship as a generic dynamically linked game launcher, as opposed to a final release monolithic executable. This means the final package will be larger and contain Shared Libraries (DLLs on Windows) instead of one giant monolithic executable. | ||
|
|
||
| Making such an executable would require a compiler and linker. You can always switch it to a regular project or even modify the package script to temporarily do so before building it, by automating the modification of `project.json` by your build pipeline as it calls the export script, if you want to still make use of monolithic builds but leave it as a script-only project. | ||
|
|
||
| ### All modules and gems you use must already be compiled | ||
| Because there is no compiler or linker involved, all gems you activate and all other 3rd party content you need to use must be in a form that lets CMake use them without having to compile them (For example, pre-compiled dll files, as opposed to static libraries with headers). When using the pre-built engine from an installer (or making your own) this is the case for all gems included with the engine. Some 3rd Party gems downloaded from other websites may only contain source code, or stub of source that is compiled and linked into the game. These gems will not function in Script-only mode unless the developer of those gems creates and ships special pre-compiled versions of them, perhaps using the pre-built gem [Template](/docs/user-guide/build/templates.md). | ||
|
|
||
| ## How it works (Technical description) | ||
| When CMake configures O3DE, one of the scripts in the project (`EngineFinder.cmake`) sets a global CMake property `O3DE_SCRIPT_ONLY` to `TRUE`. This happens before the CMake project command, and thus before CMake auto-selects a compiler. When this is `TRUE`, the CMake scripts from O3DE which would normally configure compilers, linkers, and other build tools will instead set a null compiler, which is a simple program that always returns success. | ||
|
|
||
| CMake is still invoked just like a 'real' project, but all compiling and linking operations are essentially instantaneous and always succeed (without actually emitting any binaries). But because all binaries are pre-built in an installer (and the Script-Only project contains no custom binaries), this is enough to build and run the editor and game. | ||
|
|
||
| Third Party packages are also skipped downloading during CMake configure and instead, the Third Party libraries that would normally be fetched are synthesized just from their shared libraries and other files. The list of shared libraries and the dynamic linkage information in the dependency tree is gathered when CMake is configuring and building the installer image. During that process, a script located in `cmake/3rdParty/script-only-mode/PostProcessScriptOnlyMappings.cmake` runs during build time based on information emitted about third party libraries (such as their required extra files or shared libraries) at configure time. This script essentially generates a CMake file containing fake 'imported' 3rd Party targets to supply the necessary shared libraries and other files that would otherwise come from 3rd Party packages, and points them at their counterparts that ship as part of the installer instead. | ||
|
|
||
| Finally, a 'fake' game launcher for the project is declared to CMake which depends on a pre-built generic game launcher executable. This generic game launcher is built as part of the install image build, and will read project.json to determine the project name and other information instead of relying on data burned into the binary. | ||
|
|
||
| Because the compiler and linker are fake, CMake will not actually compile or link this 'fake' target, but will still consider it to have succeeded, and copy the things it depends on (recursively) to the binaries folder, which is how the generic game launcher and all its dependencies end up in the binaries folder. | ||
|
|
||
| This means that developers wishing to support Script-only mode for their modules can do so, but would need to ship with pre-built shared libraries which are exposed as `add_library(name SHARED IMPORTED GLOBAL)` in cmake and list their runtime dependencies in that declaration using normal cmake conventions. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| --- | ||
| linktitle: Project and Gem Templates | ||
| title: Project and Gem Templates | ||
| description: Learn about the project and gem templates available in O3DE | ||
| weight: 100 | ||
| toc: true | ||
| --- | ||
|
|
||
| O3DE includes a template system, which you can use to create new projects, new gems, or new snippets of code for the engine based on those templates. The default engine from installer or github includes a few basic templates, but more can be downloaded as part of gems or repositories and added to the engine. | ||
|
|
||
| You can find all the existing templates in the root of the engine in the `templates` sub-folder. They operate by copying their template files into a folder of the user's choosing and replacing certain placeholder text in those files, such as project name, with the actual name given by the user. | ||
|
|
||
| ## Project templates included with the engine | ||
| These templates are for entire projects, which can be created using the Project Manager and then opened to work on in the Editor. | ||
| For a guide on how to create projects from template, see [Creating Projects Using Project Manager](/docs/welcome-guide/create/creating-projects-using-project-manager). | ||
|
|
||
| ### DefaultProject | ||
| This is a good all-round starting point for a game project using O3DE. It comes with a script to export the project into a shippable standalone package. It has a number of gems active by default, including ones for UI, basic prototyping, Script Canvas and Animation, among others. Using this template requires a C++ compiler installed and it includes a basic c++ game module that can be used to write core game logic and components. | ||
|
|
||
| ### ScriptOnlyProject | ||
| This has an identical gem selection to DefaultProject, but disables all C++ compiling and linking. The project is still able to use the Lua and Script Canvas capabilities of the engine, but cannot have custom c++ code embedded or use other gems or modules that are not pre-compiled. It can be used to get a quick look at the engine and editor without having to compile a project, download 3rd party libraries, or install a compiler or linker. You can convert a Script Only project to a regular project at a later time. | ||
|
|
||
| See the [Script-only 'Quick Start' Projects](/docs/user-guide/build/script-only-projects.md) documentation for more information about this feature. | ||
|
|
||
| ### MinimalProject | ||
| This has as few gems active as possible, and is a bare-bones starting point. It is not recommended to use this template as-is, but rather start with it and then activate what gems you might need for your project. Because it activates as little as possible, and includes as few other gems as possible, it has the quickest startup time and asset compilation time. | ||
|
|
||
| ## Notable Gem templates included with the engine | ||
| These templates are for making your own custom gems that can be used to extend the engine and reused across projects. | ||
| To create gems and other components from template, the command line utility must be used, similar to how projects are created using the CLI in [Creating Projects using CLI](/docs/welcome-guide/create/creating-projects-using-cli), but with a different command (`create-gem`) and different argument (`--gem-path`) to supply the output folder. | ||
|
|
||
| linux example: | ||
| ```shell | ||
| scripts/o3de.sh create-gem --help | ||
| scripts/o3de.sh create-gem --gem-path $HOME/O3DE/Projects/MyProject/Gem/MyGem -tn AssetGem | ||
| ``` | ||
|
|
||
| windows example: | ||
| ```cmd | ||
| scripts\o3de create-gem --help | ||
| scripts\o3de create-gem --gem-path %USERPROFILE%\O3DE\Projects\MyProject\Gem\MyGem -tn AssetGem | ||
| ``` | ||
|
|
||
| ### AssetGem | ||
| This template can be used to create a gem that contains only assets, no code, and does not require C++ compilation to use. Ideal for creating buckets of assets you would like to reuse between projects or package and ship without any code attached. It can still contain Lua scripts, as well as Script Canvas, or Python for tooling. | ||
|
|
||
| ### CppToolGem | ||
| This template can be used to create new C++ tools for the Editor. It contains a scaffold of C++ code that will cause a component to be registered with the Editor and has place for you to start adding your custom Tool code. | ||
|
|
||
| ### PythonToolGem | ||
| This template can be used to create new tools for the editor written in Python. Python can be used to access the Engine and Editor APIs, and it can also use Qt For Python to create new panels and UI elements. It contains a bootstrap script which will automatically be called on startup if the gem is active, as well as an example Qt Dialog written in Python that it registers with the View Pane system of the Editor. | ||
|
|
||
| ### DefaultGem | ||
| This template is meant for use when developing a more comprehensive gem that contains code that runs in the engine in standalone mode, as well as code that runs in the Editor and tooling side. It contains those two modules, as well as the boilerplate used to register and activate those two modules in the appropriate location. | ||
|
|
||
| ### GraphicsGem | ||
| This template is meant for use when creating a gem which Atom rendering APIs. Most suitable when adding a new rendering feature to the engine. It includes a module which registers itself with the engine and a Feature Processor which hooks into Atom, letting you start writing your rendering feature immediately. | ||
|
|
||
| ### UnifiedMultiplayerGem | ||
| This template contains the scaffolding of a Gem that will plug into the multiplayer system of the engine and support differing behavior between the client and server (including a Unified launcher that has both behaviors). It includes a Tool-side module as well as an Engine-side module and component. See the [Multiplayer Documentation](/docs/user-guide/networking/multiplayer) for more information. | ||
|
|
||
| ### PrebuiltGem | ||
| This template contains instructions and a starting layout for a gem that can be shipped as a pre-built library (with only header files, no source code). It shows how to hook into existing static or shared libraries instead of shipping the source, as well as how you might structure the shippable tree of a Gem if you want it to work without compiling on the user's side. Pre-built gems are the only way to ship gems that work with Script Only Mode. | ||
|
|
||
| ## Other templates included with the engine | ||
| These templates can be used to save time with boilerplate code, and are used by telling the CLI to inject them into existing projects or gems, as they contain a fragment of code or assets and are not functional standalone. The CLI command `create-from-template` should be used to instantiate the template, with the `-dp` destination path supplied where to put the instantiated template and the `-tn` argument being the name of the template. | ||
|
|
||
| linux example: | ||
| ```shell | ||
| scripts/o3de.sh create-from-template --help | ||
| scripts/o3de.sh create-from-template -dp $HOME/O3DE/Projects/MyProject/Gem/MyGem/MyComponent -tn DefaultComponent | ||
| ``` | ||
|
|
||
| windows example: | ||
| ```cmd | ||
| scripts\o3de create-from-template --help | ||
| scripts\o3de create-from-template --gem-path %USERPROFILE%\O3DE\Projects\MyProject\Gem\MyComponent -tn DefaultComponent | ||
| ``` | ||
|
|
||
| ### DefaultComponent | ||
| This template contains a simple component that can be injected into an existing gem or project. This saves you boilerplate typing when adding new components to an existing code-base. It includes an interface header that allows you to immediately start adding EBus messages to talk to the component. | ||
|
|
||
| ### GemRepo | ||
| This template contains the scaffold of a Gem Repository. Users can add the URL of a Gem Repository to their Project Manager and the Gems inside that repository will become available for use. See the [Gem Repository Overview](/docs/user-guide/gems/repositories/overview) for more information. | ||
|
|
||
| ### RemoteRepo | ||
| This template contains the scaffold of a Remote Repository. See the [Remote Repository](/docs/learning-guide/tutorials/remote-repositories/create-remote-repository) documentation for more information. | ||
|
|
||
| ### ScriptCanvasNode | ||
| This template contains the scaffold of a Script Canvas Node which can be added to an existing codebase to supply new Script Canvas nodes to the engine and editor. Instantiating this template will result in the XML files as well as code, header, and CMake files required to hook into the Script Canvas system. See the [Script Canvas Custom Nodes](/docs/user-guide/scripting/script-canvas/programmer-guide/custom-nodes/_index.md) documentation for more information. | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters