Add a node to an anim graph.

Returns the new node object exactly as get_anim_graph emits it. An unknown node_type is refused with the list of known types.

Args: anim_graph_id: Graph id (number or digit string). node_type: RTTI or palette name, case-insensitive (for example AnimGraphMotionNode, AnimGraphStateMachine, BlendTree, BlendTreeBlend2Node). parent_id: Parent node id (a state machine or blend tree). Defaults to the root state machine. name: Node name. The engine generates one when omitted. position: [x, y] graph-canvas position in integer pixels.

Add a value parameter to an anim graph.

Returns the parameter object as get_anim_graph emits it. The gem checks each value against the type; min and max are only valid for ranged types (Float, Int, Vector2/3/4, Color, Rotation).

Args: anim_graph_id: Graph id (number or digit string). name: Parameter name. parameter_type: Float (a FloatSlider), FloatSpinner, Int (an IntSlider), IntSpinner, Bool, String, Tag, Vector2, Vector3, Vector3Gizmo, Vector4, Color, Rotation, or the full class name. default: Default value: a number, bool, string, or a list of numbers for vector, color and rotation types. min: Range minimum (ranged types only). max: Range maximum (ranged types only). description: Optional description. group: Group to put the parameter in; created when missing.

Add a state-machine transition, optionally with conditions.

Returns the transition object as get_anim_graph emits it. Source and target must share a state-machine parent; an exit node cannot be a source. All conditions are added as one Animation Editor undo step.

Args: anim_graph_id: Graph id (number or digit string). target_node_id: The state to transition to. source_node_id: The state to transition from. Required unless wildcard is true. wildcard: True for a wildcard transition (from any state). Then omit source_node_id. blend_time: Blend time in seconds, 0 or more. priority: Higher wins when several transitions are ready (0 to 2**32-1). disabled: Create the transition disabled. sync_mode: 0 disabled, 1 track based, 2 clip based. interpolation: 0 linear, 1 ease curve. conditions: List of {"condition_type": ..., "attributes": {...}}. Types: ParameterCondition, TimeCondition, PlayTimeCondition, MotionCondition, StateCondition, TagCondition, Vector2Condition (or the RTTI name). For example {"condition_type": "ParameterCondition", "attributes": {"parameterName": "Speed", "function": "GREATER", "testValue": 0.1}}. Enum attributes take the integer or the name; an unsupported attribute is refused with the supported list.

Add a component to an entity.

Args: entity_id: The entity ID to add the component to. component_type: Component type name (e.g. 'Mesh', 'PhysX Dynamic Rigid Body').

Add a node to a Track View sequence.

Add a Director node first; most other node types need a Director present.

Args: name: Sequence name. node_type: One of Director, Event, AzEntity, Component, CVar, Material, Group, Layer, Comment. node_name: Name for the new node.

Assign an asset to a component property by resolving the asset path.

asset_path is the product path in the asset catalog (for example objects/thing.fbx.azmodel). The property is read back after setting, and only an assignment that holds is reported as done; an unknown asset, component or property, or a value that does not stick, is returned as an error.

Begin a persistent Python session in the O3DE editor.

Build an O3DE project using CMake.

This runs CMake configure followed by CMake build. Timeouts are configurable via O3DE_CONFIGURE_TIMEOUT and O3DE_BUILD_TIMEOUT environment variables.

Args: project_path: Path to the O3DE project. config: Build configuration -- profile, debug, or release (default: profile).

Trigger a RenderDoc frame capture in the O3DE editor.

Attempts to trigger a RenderDoc capture via GraphicsProfilerBus. That bus is not exposed to editor Python on O3DE 26.10.0, so there the tool returns manual_required with the manual alternatives (F12 in RenderDoc, or the editor's GPU capture menu).

Returns: JSON with status ok if the capture was triggered, error on failure, or manual_required if the Python API cannot trigger the capture and manual action is needed.

Capture a screenshot of the editor viewport.

Captures the rendered frame with Atom's FrameCaptureRequestBus.CaptureScreenshot, then waits on the client for a new, fully written file (O3DE_CAPTURE_WAIT, default 15 s). A level must be open: without one the engine accepts the capture and never writes a file, which is reported as capture_not_written. A PySide6 widget grab is tried first, but it cannot run in the editor's embedded interpreter on O3DE 26.10.0 (QApplication.instance() is None).

Args: output_path: File path for the screenshot (.png, .jpg, .jpeg, .bmp, or .tga). width: Scale width for the PySide6 grab only; ignored by the Atom capture, so it has no effect on 26.10.0. height: Scale height for the PySide6 grab only; ignored like width.

Connect an output port to an input port (blend trees).

Returns the target node's input port object. Refused: a target inside a state machine (use add_anim_graph_transition), incompatible port types, an occupied input, a duplicate, and a cycle. An unknown port name is refused with the node's ports listed as "name" (index).

Args: anim_graph_id: Graph id (number or digit string). source_node_id: Node whose output to connect. source_port: Output port index or name. target_node_id: Node whose input to connect. target_port: Input port index or name.

Create a new, empty, in-memory EMotion FX anim graph to author.

Returns {"id": <graph id>, "file_name": ""}. The graph starts with only its root state machine. Save it with save_anim_graph; remove it with remove_anim_graph.

Create a new entity in the current O3DE level.

Tries the AiCompanion gem's native create_entity request first (gem 0.5.0 or later, works in the gem's secure mode) and returns its JSON verbatim: {"entity_id": ..., "name": ..., "position": [...]}. The name is checked here with the gem's own rule (a letter first, then letters, digits, _ or -, at most 128 characters) before either path, and the gem validates the parent; a refusal is returned as an error. Older gems and the legacy transport fall back to editor Python, which prints Created entity [<id>].

Args: name: Name for the new entity. parent_id: Optional entity ID of the parent. Omit (or pass null) for root-level.

Create a new O3DE gem.

Args: name: Gem name (alphanumeric, hyphens, underscores). path: Directory where the gem will be created. template: Gem template to use (default: DefaultGem).

Create a new level in the current O3DE project and open it in the editor.

Args: name: Level name (alphanumeric, hyphens or underscores, starting with a letter). The level is written to <project>/Levels/<name>/. template: Level template prefab, as a path relative to an asset scan folder. Defaults to the editor's own New Level default, Prefabs/Default_Level.prefab (camera, sun, grid). Pass an empty string for a bare level with no entities.

Write a prefab file to disk from an existing entity.

The path is relative to the project root. The level is not modified; use instantiate_prefab afterwards to place the saved prefab.

Create a new O3DE project.

Args: name: Project name (alphanumeric, hyphens, underscores). path: Directory where the project will be created. template: Project template to use (default: DefaultProject).

Create a new Track View cinematic sequence in the current level.

Creates a modern Sequence Component sequence (on its own entity). A new sequence has no nodes; add a Director node with add_sequence_node before adding other nodes. An existing name is reported as an error.

Args: name: Sequence name.

Delete an entity from the current O3DE level.

Tries the gem's native delete_entity request first (gem 0.5.0 or later, works in secure mode) and returns its JSON verbatim: {"deleted": <id>}. A missing entity or the level's root entity is refused by the gem and returned as an error. Older gems and the legacy transport fall back to editor Python, which prints Deleted entity [<id>].

Args: entity_id: The entity ID to delete.

Delete a Track View cinematic sequence from the current level.

Args: name: Sequence name.

Disable a gem in an O3DE project.

Args: gem_name: Name of the gem to disable. project_path: Path to the project.

Remove the connection feeding an input port.

Returns {"removed": "<connection id>"}; a free port is not_found.

Args: anim_graph_id: Graph id (number or digit string). target_node_id: Node whose input to free. target_port: Input port index or name.

Duplicate an entity (and its children) in the current O3DE level.

Args: entity_id: The entity ID to duplicate.

Edit properties of an existing O3DE project.

Args: project_path: Path to the project. project_name: New name for the project (optional). origin: New origin URL or description (optional).

Enable a gem in an O3DE project.

Args: gem_name: Name of the gem to enable. project_path: Path to the project.

End a persistent Python session and clean up its namespace.

Enter game mode (play-in-editor) in the O3DE Editor.

Execute Python code in a persistent session.

Exit game mode and return to edit mode.

Export an O3DE project for distribution.

This is a long-running operation. Timeout is configurable via the O3DE_EXPORT_TIMEOUT environment variable (default: 3600s).

Args: project_path: Path to the O3DE project to export. output_path: Directory where the exported project will be written. config: Build configuration -- profile, debug, or release (default: profile).

Focus the viewport camera on an entity.

Describe one EMotion FX anim graph in full.

Returns the gem's JSON: nodes (with type, parent, position, ports and connections; state machines also carry entry_state_id), transitions (with blend time and conditions), parameters, node_groups and the root_state_machine_id. Pass exactly one selector. An unknown graph is returned as an error. Needs the AiCompanion gem's native request (gem 0.6.0+) and the EMotionFX gem.

Args: anim_graph_id: Graph id from list_anim_graphs (number or digit string). file_name: Graph file name, matched exactly first, then by its tail case-insensitively (for example Character.animgraph).

List the Asset Processor jobs for one source file, with failure logs.

Returns {"source_path", "jobs": [{"job_key", "platform", "builder", "status", "error_count", "warning_count", "job_run_key", "source_file", "watch_folder", "log"?, "truncated"?}]} with status one of queued, in_progress, failed, completed or missing. A source the Asset Processor has not registered answers the error code engine_error. Needs the AiCompanion gem 0.6.0+; works in secure mode.

Args: source_path: The source file, relative to the project or a full path. escalate: Move the file's queued jobs to the front of the queue. include_logs: Attach each failed job's log (cut at 64 KB).

Report whether the editor is connected to the Asset Processor.

Returns {"connected", "ping_ms"}. Unlike get_asset_processor_status, which checks for the process on this machine without the editor, this asks the editor itself. Needs the AiCompanion gem 0.6.0+.

Check whether the O3DE Asset Processor is running.

Ask the Asset Processor, through the editor, for one asset's build status.

Returns {"path", "status", "connected"} with status one of unknown, missing, queued, compiling, compiled or failed (plus query_path when the gem rewrote the path). The query also escalates the asset in the build queue. A source whose build failed has no products and answers missing; use get_asset_jobs or wait_for_asset to tell that apart from a file not registered yet. Needs the AiCompanion gem 0.6.0+; works in secure mode.

Args: path: A source or product path, relative to the project, or a full path. flush_io: Flush the file monitor first. Use right after writing the file.

Check the status of a background build.

Args: build_id: Build ID returned by start_build.

Discover the scripting API of any O3DE gem's reflected EBuses.

Query the running editor's BehaviorContext for a bus schema.

Tries the AiCompanion gem's native get_bus_schema request first (gem 0.4.0 or later): it reads the live C++ reflection and includes each event's argument names and tooltips, which the Python bindings do not expose, and it works in the gem's secure mode. Older gems, the legacy RemoteConsole transport, or an unknown bus fall through to the editor-Python query, and that in turn falls back to the stub files.

Check what O3DE MCP capabilities are currently available.

Call this first to determine whether the editor is connected (for editor tools) and whether the O3DE CLI is available (for project tools). This avoids wasting tokens on tools that will fail.

Tool categories are discovered dynamically — any new tools added to the server will automatically appear in the response.

Returns: JSON object with editor, cli, and tool_categories sections describing current availability and configuration.

Get a property value from a component on an entity.

Args: entity_id: The entity ID. component_type: Component type name (e.g. 'Transform'). property_path: Property path using '|' separator (e.g. 'Controller|Configuration|Model Asset').

Get the value of an O3DE console variable (CVAR).

Get information about the local O3DE engine installation.

Returns: JSON object with engine metadata, or an error message if no engine is found.

Return one entity's name, transform, parent and component list as JSON.

Served natively by the AiCompanion gem's C++ (get_entity request type, gem 0.4.0 or later) with no editor Python, so it is the cheapest way to look at a single entity and works in the gem's secure mode. On gem 0.6.0 the reply also carries non_uniform_scale and effective_scale, and ids are decimal strings. An unknown id is the error not_found (gem 0.5.0 and earlier answered with the gem's own {"entity_id": ..., "error": ...} object instead).

List all components attached to an entity.

Args: entity_id: The entity ID to inspect.

Returns: JSON array of objects with 'component_id' and 'type' fields.

Return the entity hierarchy as a nested JSON tree.

Served natively by the AiCompanion gem, without editor Python.

Get information about the currently loaded level.

Returns: JSON object with 'level_name' and 'level_path' fields.

Extract error lines from an O3DE log file.

Return the full scene state as JSON, served natively by the AiCompanion gem.

Entities, components, transforms and hierarchy in one call, produced by the gem's C++ SceneSnapshotProvider rather than an editor Python script. Cheaper than list_entities plus per-entity queries, and it still works when the AgentServer runs in secure mode.

Describe one Track View sequence: its time range and its nodes.

Returns JSON with the time range and the node names at the sequence root. A sequence with no Director node yet reports an empty node list.

Args: name: Sequence name.

List the variable names in a persistent Python session.

Get the world transform of an entity.

Returns position, rotation (an [x, y, z, w] quaternion) and scale, the effective [x, y, z] scale: the Transform's uniform scale times the entity's Non-uniform Scale component, if it has one. uniform_scale and non_uniform_scale (null without the component) give the two parts.

Get the position and rotation of the active editor viewport camera.

Returns JSON with position (3 floats) and rotation (3 Euler angles in degrees). FOV is not available via the Python bindings.

Instantiate a prefab in the current level.

List every EMotion FX anim graph the engine holds.

Returns the gem's JSON: editor_mode and an anim_graphs array with each graph's id, file_name, ownership and dirty flags, node and parameter counts, and the actor instances using it. Needs the AiCompanion gem's native request (gem 0.6.0+) and the EMotionFX gem.

List all entities in the currently open O3DE level.

Returns a JSON array of objects with 'id' and 'name' fields.

List all external gems registered on this machine.

Returns: JSON array of gem objects, or the error no_gems if none are registered.

List all levels available in an O3DE project.

List gems enabled in a specific O3DE project.

Args: project_path: Path to the O3DE project.

List all O3DE projects registered on this machine.

Returns: JSON array of project objects, or the error no_projects if none are registered.

List the Track View cinematic sequences in the current level.

Returns {"sequences": [{"name", "start", "end"}, ...], "count": N}, with each sequence's time range in seconds.

List available O3DE project and gem templates.

Scans the engine's Templates directory for template definitions.

Returns: JSON array of template objects with name, summary, and path.

Load an .animgraph file into the engine so it can be authored.

Returns {"id", "file_name"}. Loading a file that is already loaded this way returns the existing graph's id.

Args: file_name: Absolute path, an @alias@ path, or a path relative to the project.

Open a level in the O3DE Editor.

Args: level_path: Path to the level relative to the project (e.g. 'Levels/MyLevel').

Start playing a Track View sequence in the editor.

Args: name: Sequence name.

Redo the last undone editor action.

Trigger an Asset Processor rescan for a project.

Register an O3DE engine installation with the O3DE manifest.

Args: engine_path: Path to the engine root directory (must contain engine.json).

Register an external gem with an O3DE project.

Args: gem_path: Path to the gem directory. project_path: Path to the project to add the gem to.

Remove an anim graph from the engine (not its file on disk).

Returns {"removed": <graph id>}.

Args: anim_graph_id: Graph id (number or digit string).

Remove a node (and its children) from an anim graph. The root is refused.

Returns {"removed": "<node id>"}.

Args: anim_graph_id: Graph id (number or digit string). node_id: Node id from get_anim_graph.

Remove a value parameter from an anim graph. Groups are refused.

Returns {"removed": "<name>"}.

Args: anim_graph_id: Graph id (number or digit string). name: The parameter's name.

Remove a transition (and its conditions).

Returns {"removed": "<transition id>"}.

Args: anim_graph_id: Graph id (number or digit string). transition_id: Transition id from get_anim_graph.

Remove a component from an entity.

Execute an O3DE console command in the running editor.

Execute a Python script inside the running O3DE Editor.

The script runs in the editor's embedded Python interpreter and has access to the full azlmbr (EditorPythonBindings) API. Use this for custom editor automation that isn't covered by other tools.

Args: script: Python code to execute. Has access to azlmbr modules. timeout: Optional per-call execution timeout in seconds. The editor runs the script synchronously and does not reply until it finishes, so raise this for known-heavy operations. Omit to use the O3DE_EDITOR_TIMEOUT default (600s).

Save an anim graph to disk. Not undoable.

Returns {"id", "file_name"}. The file must land inside the project root; the gem refuses any other path.

Args: anim_graph_id: Graph id (number or digit string). file_name: Where to save. Omit to save to the graph's current file.

Save the currently open level.

Report where a prefab instance came from.

Propagating live entity edits back to a .prefab file is not reachable from the editor's Python API: PrefabPublicRequestBus reflects no save event, and the only serialiser, SaveTemplateToString, is keyed by template id with nothing exposed to map an entity to one. This returns the owning prefab path and says so, rather than reporting a success that never happened. To get a prefab onto disk, use create_prefab_from_entity.

Set the active O3DE engine by name (in-process, not persistent).

Args: name: Name of the registered engine to activate.

Make a node the entry state of the state machine that contains it.

Returns {"entry_state_id": "<node id>"}.

Args: anim_graph_id: Graph id (number or digit string). node_id: The node to enter first; it must be able to act as a state.

Edit a node: rename, move, enable/disable, or set reflected fields.

Returns the node object as get_anim_graph emits it. Pass at least one change. An unknown attribute is refused with the settable fields listed.

Args: anim_graph_id: Graph id (number or digit string). node_id: Node id from get_anim_graph. name: New node name. position: [x, y] graph-canvas position in integer pixels. enabled: Enable or disable the node. attributes: Reflected fields to set, for example a motion node's {"motionIds": ["<motion id>", ...]} (read back as the node's motion_ids).

Change a transition's settings. Pass at least one setting.

Returns the transition object as get_anim_graph emits it.

Args: anim_graph_id: Graph id (number or digit string). transition_id: Transition id from get_anim_graph. blend_time: Blend time in seconds, 0 or more. priority: Higher wins when several transitions are ready. disabled: Disable or re-enable the transition. sync_mode: 0 disabled, 1 track based, 2 clip based. interpolation: 0 linear, 1 ease curve.

Set a property value on a component.

Args: entity_id: The entity ID. component_type: Component type name (e.g. 'Transform'). property_path: Property path using '|' separator (e.g. 'Controller|Configuration|Model Asset'). value: The value to set (as a string — booleans as 'true'/'false', numbers as their string representation).

Set the value of an O3DE console variable (CVAR).

Set the parent of an entity (reparent in the hierarchy).

Set a Track View sequence's play time range, in seconds.

Args: name: Sequence name. start: Range start in seconds. end: Range end in seconds (must be greater than start).

Set the world transform of an entity (only provided components are changed).

rotation is an [x, y, z, w] quaternion and scale an [x, y, z] vector, the effective scale to end up with (each element in (0, 1000]). The call goes to the AiCompanion gem's native set_transform request (works in secure mode) and returns the updated entity's JSON, the same shape as get_entity. The gem refuses an unknown entity or out-of-bounds values, and that is returned as an error.

On gem API 0.5.0 and later (gem 0.6.0) the quaternion and the scale are sent as is. A non-uniform scale is applied through the engine's Non-uniform Scale component (each element at least 0.01); an O3DE Transform itself holds only a uniform scale. A later uniform scale sets that component back to 1. The reply carries scale (uniform), non_uniform_scale and effective_scale.

On older gems the quaternion is converted to XYZ Euler degrees, a rotation at a gimbal pole (pitch within 0.02 degrees of plus or minus 90) goes through editor Python instead, which prints Transform set for entity [<id>], and a non-uniform scale is refused with non_uniform_scale_unsupported. The legacy transport also uses the editor-Python path. An all-zero quaternion is rejected before any path.

Set the active editor viewport camera transform.

Start a CMake build in the background and return a build ID.

Unlike build_project, this returns immediately with a build ID that can be polled via get_build_status. Output is drained on a background thread to prevent pipe stalls on large builds.

Args: project_path: Path to the O3DE project. config: Build configuration -- profile, debug, or release (default: profile). target: Optional CMake target to build (default: all targets).

Stop the Track View sequence currently playing in the editor.

Read the last N lines of an O3DE log file.

Undo the last editor action.

Run the AiCompanion gem's scene validation and return the report as JSON.

Flags common problems (missing cameras, entities without transforms, physics bodies without colliders, and similar) without executing any editor Python.

Wait until one asset is built, or report why it failed.

Polls get_asset_status. compiled returns {"path", "status": "compiled", "ready": true, "elapsed"}. A failed build returns the error asset_build_failed with the failed jobs and their logs. A source whose build failed answers missing, just like one the Asset Processor has not seen yet, so after a short grace period a missing status is checked against get_asset_jobs. When timeout runs out the result is {"ready": false, "status": <last status>}, not an error. Needs the AiCompanion gem 0.6.0+.

Args: path: The asset to wait for: its source path (best, since the job check needs the source) or a product path. timeout: Seconds to wait (default 120, max 3600). just_written: True right after writing the file, so the first query flushes the file monitor. source_path: The source file to check for failed jobs, when path is a product path. poll_interval: Seconds between polls (0.1 to 10, default 1).

Wait for the Asset Processor process to exit (or until timeout).

This watches for the process to stop, not for it to go idle, so it suits a one-off AssetProcessorBatch run. A GUI Asset Processor running beside the editor stays up while idle, so with one running this waits out the timeout and reports completed: false.

Returns a progress result {"completed": bool, "elapsed": seconds}. completed is True when no Asset Processor process is running, or False when one was still running when timeout elapsed, with a message noting the timeout. A not-yet-finished wait is a result, not a failure, so this tool does not return the error envelope.