Object API#

All object commands return the structured JSON envelope. Positions are in centimeters (left-handed, Z-up). Rotations are in degrees [pitch, yaw, roll].

Listing Objects#

lych obj list#

List all objects in the scene.

Returns: A JSON envelope with status, error, and outputs, which is a flat list of object ID strings.

Field	Description
outputs : array[str]	Object ID strings for every actor in the scene.

Getting Object Information#

All batch queries accept one or more positional object IDs, or the -all flag to query every object. Each entry in outputs contains object_id and status ("ok" or "not_found"), plus the fields listed below when the object was found.

lych obj get_loc#

Get world-space locations of one or more objects.

Examples:

lych obj get_loc Table_0 Chair_1
lych obj get_loc -all

Parameters:

obj_id… : str	One or more object IDs.
-all	Query every object in the scene.

Returns: A JSON envelope with status, error, and outputs, which is a list of dicts each with the following fields:

Field	Description
object_id : str	The requested object ID.
status : str	`"ok"` or `"not_found"`.
location : [x, y, z]	World-space position in centimeters. Omitted when `status` is `"not_found"`.

lych obj get_rot#

Get world-space rotations of one or more objects.

Examples:

lych obj get_rot Table_0
lych obj get_rot -all

Parameters: Same as get_loc.

Returns: A JSON envelope with status, error, and outputs, which is a list of dicts each with the following fields:

Field	Description
object_id : str	The requested object ID.
status : str	`"ok"` or `"not_found"`.
rotation : [pitch, yaw, roll]	World-space rotation in degrees. Omitted when `status` is `"not_found"`.

Warning

The returned order is [pitch, yaw, roll], which differs from the [roll, pitch, yaw] order shown in the UE5 editor’s axis-aligned transform panel.

lych obj get_aabb#

Get the axis-aligned bounding box of one or more objects. Uses the root/collision component bounds (FActorController::GetAxisAlignedBoundingBox).

Examples:

lych obj get_aabb Table_0
lych obj get_aabb -all

Returns: A JSON envelope with status, error, and outputs, which is a list of dicts each with the following fields:

Field	Description
object_id : str	The requested object ID.
status : str	`"ok"` or `"not_found"`.
center : [x, y, z]	AABB center in centimeters.
extent : [x, y, z]	AABB half-extents in centimeters.

lych obj get_obb#

Get the oriented bounding box of a single object. Uses Actor->GetActorBounds(false) which aggregates all visual mesh components.

Examples:

lych obj get_obb Table_0

Returns: A JSON envelope with status, error, and outputs, which is a list of dicts each with the following fields:

Field	Description
object_id : str	The requested object ID.
status : str	`"ok"` or `"not_found"`.
center : [x, y, z]	OBB center in centimeters.
extent : [x, y, z]	OBB half-extents in centimeters.
rotation : [pitch, yaw, roll]	Actor rotation in degrees.

lych obj get_mesh_extent#

Get the 3D mesh extents of one or more assets by their Unreal asset path. Useful for computing spawn offsets before placing objects.

Examples:

lych obj get_mesh_extent /Game/Assets/Mesh/SM_Table

Returns: A JSON envelope with status, error, and outputs, which is a list of dicts each with the following fields:

Field	Description
mesh_path : str	The requested asset path.
status : str	`"ok"` or `"not_found"`.
extent : [x, y, z]	Full mesh bounding box dimensions (width, depth, height) in centimeters.

lych obj get_color#

Get the annotation color (RGBA) of one or more objects.

Examples:

lych obj get_color Table_0
lych obj get_color -all

Returns: A JSON envelope with status, error, and outputs, which is a list of dicts each with the following fields:

Field	Description
object_id : str	The requested object ID.
status : str	`"ok"` or `"not_found"`.
color : [r, g, b, a]	Annotation color (0–255 per channel).

lych obj get_annots#

Get full annotations for one or more objects.

Examples:

lych obj get_annots Table_0
lych obj get_annots -all

Returns: A JSON envelope with status, error, and outputs, which is a list of dicts each with the following fields:

Field	Description
object_id : str	The requested object ID.
status : str	`"ok"` or `"not_found"`.
guid : str	Actor GUID (editor builds only; `"NO_GUID"` otherwise).
aabb : {center, extent}	Axis-aligned bounding box from `GetAxisAlignedBoundingBox`.
obb : {center, extent, rotation}	Oriented bounding box from `GetActorBounds(false)`.
bounds : {center, extent}	Visual bounds from `GetActorBounds(false)` (all components).
bounds_tight : {center, extent}	Tight bounds from `GetActorBounds(true)` (colliding components only).
location : [x, y, z]	World-space position in centimeters.
rotation : [pitch, yaw, roll]	World-space rotation in degrees.
scale : [x, y, z]	Actor scale.
color : [r, g, b, a]	Annotation color (0–255 per channel).
asset_path : str	Unreal asset path.

Modifying Objects#

Single-target mutations return {"status": "ok", "outputs": []} on success, or {"status": "error", "error": "<message>", "outputs": []} on failure.

lych obj set_loc#

Set the world-space position of an object.

Examples:

lych obj set_loc Table_0 120.0 -50.0 90.0

Parameters:

obj_id : str	Object ID.
x y z : float	New position in centimeters.

lych obj set_rot#

Set the world-space rotation of an object.

Examples:

lych obj set_rot Table_0 0.0 90.0 0.0

Parameters:

obj_id : str	Object ID.
pitch yaw roll : float	New rotation in degrees.

lych obj update#

Move and/or rotate an object in a single command using keyword arguments.

Examples:

lych obj update Table_0 --loc=120.0,50.0,90.0
lych obj update Table_0 --rot=0.0,90.0,0.0
lych obj update Table_0 --loc=120.0,50.0,90.0 --rot=0.0,90.0,0.0

Parameters:

obj_id : str	Object ID.
–loc : str	New position as `x,y,z` (comma-separated). Optional.
–rot : str	New rotation as `pitch,yaw,roll` (comma-separated). Optional.

At least one of --loc or --rot must be provided.

lych obj add#

Spawn a new object into the scene.

Examples:

lych obj add MyTable /Game/Assets/Mesh/SM_Table
lych obj add MyTable /Game/Assets/Mesh/SM_Table 100 200 0
lych obj add MyTable /Game/Assets/Mesh/SM_Table 100 200 0 0 90 0
lych obj add MyTable /Game/Assets/Mesh/SM_Table 100 200 0 0 90 0 1.5

Parameters:

obj_name : str	Unique name for the new object.
obj_path : str	Unreal asset path for the mesh or blueprint.
x y z : float	Spawn position (default: 0 0 0).
pitch yaw roll : float	Spawn rotation in degrees (default: 0 0 0).
scale : float	Uniform scale factor (default: 1.0).

Flags:

-skipIfColliding — do not spawn if location overlaps existing geometry.
-adjustIfPossible — try to nudge to a free spot, fail if none found.
-lockRotation — lock the actor’s rotation after spawning.

lych obj del#

Remove an object from the scene.

Examples:

lych obj del Table_0

lych obj set_mtl#

Set the material of an object’s mesh component.

Examples:

lych obj set_mtl Table_0 /Game/Materials/M_Wood 0

Parameters:

obj_name : str	Object ID.
material_path : str	Unreal asset path for the material.
element_idx : int	Material element index on the mesh.

Editor Utilities#

lych obj list_selected#

Get the object IDs and GUIDs of the currently selected actors in the Unreal Editor. Editor-only; returns an error in non-editor builds.

Returns: A JSON envelope with status, error, and outputs, which is a list of dicts each with the following fields:

Field	Description
object_id : str	Actor name.
guid : str	Actor GUID (or `"NO_GUID"`).

lych obj adjust_light#

Adjust properties of a directional light.

Examples:

lych obj adjust_light DirectionalLight_0 --intensity=5.0
lych obj adjust_light DirectionalLight_0 --rot=0.0,-45.0,0.0
lych obj adjust_light DirectionalLight_0 --color=1.0,0.9,0.8
lych obj adjust_light DirectionalLight_0 --temp=6500

Parameters:

light_id : str	Name of the directional light actor.
–intensity : float	Light intensity (lux).
–rot : str	Rotation as `pitch,yaw,roll` (comma-separated degrees).
–color : str	Linear color as `r,g,b` (comma-separated, 0.0–1.0).
–temp : int	Color temperature in Kelvin.