=========================
Useful Scripting Commands
=========================

.. codeauthor:: Jeremy Ernst

Below are some examples for scripting aspects of the system. In order to fully understand all the attributes and
methods available, please look at the relevant technical documentation.


Creating a Simple Character
---------------------------

.. code-block:: python

    # Import the necessary modules
    import artv2.components.base_components.rig_asset as rig_asset
    import artv2.components.root as root
    import artv2.components.spine as spine
    import artv2.components.biped_leg as leg
    import artv2.components.arm as arm

    # Build an asset, which is required to hold other components.
    new_asset = rig_asset.RigAsset()

    # Create a root component
    root_inst = root.Root()

    # Create a spine components and set the number of spine joints to 4 and its parent to the root
    spine_inst = spine.Spine()
    spine_inst.parent = "root"
    spine_inst.num_joints = 4

    # Create a leg component for the left leg and set its parent to the pelvis bone created by the spine component.
    l_leg_inst = leg.BipedLeg()
    l_leg_inst.parent = "pelvis"

    # Create a mirror of the left leg
    l_leg_inst.create_mirror(prefix="r", suffix="", parent="pelvis")

    # Set the prefix on the left leg instance
    l_leg_inst.prefix = "l"

    # Create an arm component and set its parent to the last spine joint created by the spine component.
    l_arm_inst = arm.Arm(prefix="l")
    l_arm_inst.parent = "spine_04"

    # Create a mirror of the arm component.
    r_arm_inst = l_arm_inst.create_mirror(prefix="r", suffix="", parent="spine_04")



Accessing Component Data
-------------------------

.. code-block:: python

    # In the example, components already exist in the scene, and we want to access information on the components.
    import artv2.components.base_components.rig_asset as rig_asset
    import artv2.components.biped_leg as leg

    # Assume this code has been run previously, which creates an asset and a leg component.
    asset = rig_asset.RigAsset()
    leg_inst = leg.BipedLeg()

    # Now assume Maya has been closed and re-opened, so the above variables are no longer valid.
    # To get access to a specific component, pass in that component's network node in the scene:
    leg_inst = leg.BipedLeg(network_node="leg_metadata")

    # Now let's gather info about the component
    print(leg_inst.joint_mover.get_movers())
    print(leg_inst.joint_mover.get_created_joints())

    # As in the previous example, we can also change properties of the leg, like the prefix, suffix, parent, etc.
    leg_inst.num_thigh_twists = 2