RFC: EditorEntityComponentBehaviors Libraries

[FuzzyCarter]

Summary:

A set of libraries that allow for Editor Entity Components to be interacted with through common user interactions that come packed with behavior validators (need to break validators out into their own RFC).

For a prototype please see Gem/PythonTests/EditorPythonTestTools/editor_python_test_tools/editor_component

What is the motivation for this suggestion?

Why is this important?

• As we continue to stabilize the automation, looking into ways to provide standard behaviors for interactions with the AzLmbr API will allow us to write cleaner, more maintainable, and stable tests that we trust.
• Abstracting the complexity of AzLmbr interactions provides an easy to use interface.
  • Lowers the barrier of entry for writing automation.
  • Prevents interacting with abstracted behaviors in a way that's been proven to be error prone or flaky.

What are the use cases for this suggestion?

• Easily adds a component to an entity.
• Easily allows a user to interact with a component entity.

    phsyx_collider_entity = EditorEntity.create_editor_entity("TestEntity")
    physx_collider = PhysxCollider(phsyx_collider_entity)
    physx_collider.shape.set(physics.ShapeType_Box)
    physx_collider.shape.box.height.set(value)
    var = physx_collider.box_shape.height.get()

What should the outcome be if this suggestion is implemented?

• A library of editor entity component property types.
• A Library of Entity Component behavior classes.

Suggestion design description:

On-Build Auto-generation of the following:

• A library of editor entity component property types.
  • A base class for a property and it's default expected behaviors to be overridden.
  • A series of classes that define the behavior of those property types.
    • EG: A float property would inherit the base property class and would define the common behaviors for a float property.
• A Library of Entity Component behavior classes.
  • A base class that defines the standard behaviors for an entity component.
  • A series of classes for each entity component that inherits the base entity component class that then registers a property class for each property supported by the entity component.

What are the advantages of the suggestion?

• Libraries are always up to date
• Property Classes could later be extended for other Entity/Component models throughout the engine (such as in the Character Editor's Inspector).

What are the disadvantages of the suggestion?

• Effort required for writing the auto-gen system.
• Effort required to define one-off entity component/property behaviors.
  • Built-In Bus Calls such as Reflection Probe in Atom.
  • Special handling for Properties that use built-in Enums.
  • Special handling properties that are containers.

How will this be work within the O3DE project?

• It could be generated every build and could be placed in a parallel folder to user\python_symbols\azlmbr called user\python_symbols\editor_tools\

Are there any alternatives to this suggestion?

Same implementation as above but not using auto-generation.

What is the strategy for adoption?

• Explain how new and existing users will adopt this suggestion.
  • TBD
• Point out any efforts needed if it requires coordination with multiple SIGs or other projects.
  • TBD
• Explain how it would be taught to new and existing O3DE users.
  • TBD

[lmbr-pip]

@FuzzyCarterAWS - These RFCs should be created in SIG/Testing (or other relevant SIG or TSC github) ie https://github.com/o3de/sig-testing/issues

You should work with a maintainer to migrate issue (need maintainer with permissions on SIG repository).

[Kadino]

Unclear ownership as this falls in the grey area between SIGs. @o3de/sig-testing can iterate on this to clarify.

[hultonha]

I'm not totally clear on what this is adding and/or solving. Could you maybe include some examples of before/after to help show how this improves consistency and makes things easier/clearer? Thanks!

[smurly]

currently accessing behavior context properties requires a property path string using a bus call that takes python type any for the value. I believe the intention of this is to create a hardened interface on the python side for setting, getting and validating function for each component property.
in python the bus call to set a property looks something like
editor.EditorComponentAPIBus(bus.Broadcast, "SetComponentProperty", self.id, component_property_path, value)
which is available wrapped in editor_entity_utils.py as a method set_component_property_value
the component itself also has a string name used for interacting with it via bus calls. component names and property paths represent a collection of static strings which are subject to change on the C++ side of behavior context which has on occasion resulted in automation breaks on the python side.
Atom automation addressed this issue through the use of constants dictionaries in AutomatedTesting/Gem/PythonTests/Atom/atom_utils/atom_constants.py where each component has a dictionary collection including component name string and property path strings which can be used with editor_entity_utils.py calls to set/get property values like the following:
mesh_component.set_component_property_value(AtomComponentProperties.mesh('Model Asset'), model.id)

this RFC proposes a way to encapsulate these property path and component name strings in python so that they are centralized with get/set/validate methods for each property as a component specific object.
adding an instance of a component to an entity would be an initialize python component class providing the entity as an argument.
setting a component property would be done by calling the set method on the component objects property

Generating python component classes could be helpful in writing automation against the components. autogenerating might break automation though since the python classes if changed by this generation might not be reflected in automation python code using it; autogenerating could introduce breaking changes.
some sort of generation tooling to make the component classes could be used to initially populate the python classes.