Built-in Commands

Note:

This is the reference for each individual built-in command. For how the command system works as a whole – discovery, execution order, and the plugin architecture – see Command System.

Registration Commands

Registration commands only run when the --automatic-register flag is set (or the GUI checkbox is enabled). They modify CMake and module files to integrate the new class into the build.

register_file_list

Adds the generated .h and .cpp files to the gem’s CMake build target.

Behavior: Resolves the file’s actual header and source paths from ctx.copy_files – the real paths the template staged, not an assumed Source/{component_name}.h/.cpp. Falls back to Source/{component_name}.h/.cpp only if no matching entry exists. If the file’s isEditor flag is set, searches for an editor-specific CMake target (Code/, Source/Tools/, or a detected editor target name) instead of the runtime build target, falling back to the runtime target if none is found. Locates the resolved target’s FILES_CMAKE list file and inserts the header and source into the set(FILES ...) block. If the target uses inline sources instead of a cmake list file, appends a target_sources(...) block to CMakeLists.txt.

register_module_descriptor

Adds a CreateDescriptor() call to the gem’s module file so the component is instantiated at startup.

Behavior: Adds #include "{component_name}.h" and inserts {component_name}::CreateDescriptor() into the m_descriptors.insert(...) block.

register_system_component

Adds the component to the GetRequiredSystemComponents() list so it activates automatically.

Behavior: Adds #include and inserts azrtti_typeid<Namespace::ComponentName>() into the return AZ::ComponentTypeList{ ... } block.

register_interface_header

Registers an interface header (e.g. PlayerHealthInterface.h) in the gem’s INTERFACE or API build target.

Behavior: Locates the interface header under Include/{Namespace}/. Scans CMake targets to find an INTERFACE or API target. Adds the header to that target’s file list.

General Commands

These commands run regardless of the --automatic-register setting.

add_gem_dependency

Adds a gem dependency to the current build target’s BUILD_DEPENDENCIES block in CMake.

Behavior: Finds the o3de_add_target / ly_add_target block for the current build target. Inserts the dependency under BUILD_DEPENDENCIES > PRIVATE if not already present. Includes a self-dependency guard – if the dependency resolves to the same gem as the current namespace, the command is skipped.

copy_file

Copies a file from one location to another within ctx.dest_root.

copy_setreg

Ensures the Registry/ directory exists for setreg file placement.

Behavior: Determines the correct Registry/ directory based on the gem’s directory structure (Gem/, Code/, or root-level).

register_asset_setreg

Configures the O3DE Asset Processor to recognize a custom data asset file extension.

Behavior: Reads the asset class UUID from its C++ header (via AZ_RTTI / AZ_TYPE_INFO macros). Writes an RC entry into the gem’s .setreg JSON under Amazon > AssetProcessor > Settings, mapping the file extension to the asset type GUID.

register_generic_asset

Registers a GenericAssetHandler in the gem’s DataAssetSystemComponent.

Behavior: Adds #include for the asset header, inserts a GenericAssetHandler registration block into Activate(), and adds a ::Reflect(context) call in Reflect().

replace_text

Performs find-and-replace on a generated source file. Useful for injecting variable values into template placeholders that are not standard O3DE template variables.

Example – replacing a channel placeholder with a user-provided value:

{
    "command": "replace_text",
    "args": {
        "component_name": "${Name}_Reactor.h",
        "text_to_replace": "${PulseChannel}",
        "replacement_var": "pulse_channel"
    }
}

copy_file_to

General-purpose “copy one staged file to any destination” command. This is the single primitive intended to replace the older copy_file / copy_setreg / copy_asset_files / copy_variant_files family in new templates. Those commands remain registered for templates already using them.

Behavior: Copies a single file from the staging directory to a destination resolved against one of five named anchors – the build target’s source tree (dest_root), the gem root, <gem>/Assets/, <gem>/Registry/, or the engine root.

copy_glob_to

Glob-based companion to copy_file_to – copies every staged file matching a pattern into a destination directory, preserving relative structure.

Behavior: Use this when an entire subtree of staged files shares one destination anchor and subdirectory. For one-off copies use copy_file_to directly.

copy_asset_files

Copies a template’s asset subtree (shaders, .pass, .azasset, materials, textures) directly into <gem>/Assets/, bypassing the normal o3de create-from-template staging path.

Behavior: Asset files belong at <gem>/Assets/..., not under the C++ build tree that normal staging writes to. This command reads directly from a sibling TemplateAssets/ folder, which staging never touches. It copies that folder into the gem’s Assets/ tree, applying ${Name}/${GemName} substitution to both paths and contents.

copy_variant_files

Copies one of several parallel variant subtrees into the gem’s source tree, selected by an input variable’s value. Used when a template offers multiple integration modes that all target the same final file paths (see Scoped Commands).

Behavior: Reads the variant variable’s value, copies only the matching <template>/Variants/<value>/ subtree, and skips the others. This lets multiple mutually-exclusive file sets (e.g. different RenderingSystemComponent shapes) share the same destination paths.

add_pass_creator_call

Wires a custom Atom RPI pass class into a gem’s RenderingSystemComponent so Atom’s PassSystem knows how to instantiate it from a .pass template.

Behavior: Injects matching AddPassCreator/RemovePassCreator calls into Activate()/Deactivate(), adding the necessary #includes. Idempotent – re-running with the same pass name is a no-op rather than duplicating the registration.

add_feature_processor_registration

Wires an Atom RPI FeatureProcessor into a gem’s RenderingSystemComponent. Mirrors add_pass_creator_call for the FeatureProcessorFactory API surface.

Behavior: Injects matching RegisterFeatureProcessor/UnregisterFeatureProcessor calls into Activate()/Deactivate(), adding the necessary #includes. Idempotent, same as add_pass_creator_call.

Command Summary Table