exampleHumanArtPartActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
*******************************************************************************/
 
//! \file exampleHumanArtPartActuator.h
//! \brief Actuator component demonstrating control of DI-Guy human character joints
//!
//! DtExampleHumanArtPartActuator shows how to manipulate articulated parts (joints)
//! on human characters in VR-Forces. This example animates the left shoulder joint
//! of a DI-Guy character, demonstrating the complete pattern for controlling human
//! skeleton articulation from simulation logic.
//!
//! Key Patterns Demonstrated:
//! - VR-Forces actuator component lifecycle (init, tick)
//! - DI-Guy articulated part lookup and manipulation
//! - Smooth joint animation using sinusoidal interpolation
//! - Pause-aware animation (handling simulation pause/resume)
//! - Platform-specific component access via DtPlatformLocalObjectFacade
//!
//! Use Cases:
//! This pattern enables:
//! - Procedural character animation (waving, gesturing, pointing)
//! - Injury modeling (limping, holding injured limbs)
//! - Equipment interaction (carrying objects, operating controls)
//! - Behavioral animation (soldier hand signals, crew actions)
//! - Motion capture playback (replaying recorded joint angles)
 
#pragma once
 
#include <vrfobjcore/actuatorComponent.h>
#include <vrfobjcore/platformLocalObjectFacade.h>
 
namespace makVre
{
//! Type identifier string for human articulated part actuator component
constexpr char DtExampleHumanArtPartActuatorType[] = "vre-example-human-art-part-actuator";
 
//! \brief Actuator component that animates DI-Guy human character joints
//!
//! PATTERN: VR-Forces Actuator Components
//! Actuator components execute simulation-side logic on entities, controlling their
//! behavior, appearance, and state. They are the simulation engine counterpart to
//! player station components (DtPlayerComponent).
//!
//! Common Actuator Component Types:
//! - Motion actuators: Control entity movement and navigation
//! - Weapon actuators: Manage firing, reloading, aiming
//! - Sensor actuators: Simulate detection and tracking
//! - Animation actuators: Control visual appearance and articulation (this example)
//! - Communication actuators: Handle radio and data link simulation
//!
//! Actuator Lifecycle:
//! 1. Construction with entity owner and simulation services
//! 2. init() called once after construction for initialization
//! 3. tick() called every simulation frame to update state
//! 4. Destruction when entity is removed or component detached
//!
//! DI-Guy Articulated Parts:
//! DI-Guy human characters use a skeletal system with named joints (articulated parts).
//! Each joint can be controlled via:
//! - Azimuth: Rotation around vertical axis (yaw)
//! - Elevation: Rotation around lateral axis (pitch)
//! - Rotation: Rotation around forward axis (roll)
//! - Angular rates: Velocities for smooth interpolation
//!
//! This Example:
//! Animates the left shoulder joint with a sinusoidal motion, demonstrating:
//! - Articulated part lookup by DI-Guy joint identifier
//! - Setting joint angles and angular rates for smooth motion
//! - Pause-aware animation (stops during simulation pause)
//! - Continuous cyclical animation using time accumulation
//!
//! REUSABLE: This class structure applies to any actuator that needs to control
//! human character articulation. Replace the joint identifier and animation logic
//! to control different joints or implement different motion patterns.
//!
class DtExampleHumanArtPartActuator : public DtActuatorComponent
{
public:
   //! \brief Constructor - Initialize actuator component for an entity
   //!
   //! PATTERN: VR-Forces Component Construction
   //! VR-Forces components are constructed with references to:
   //! - name: Component instance identifier (for debugging and logging)
   //! - owner: The entity (DtLocalObject) this component belongs to
   //! - simManager: Access to simulation services (time, messaging, etc.)
   //! - desc: Component descriptor from entity definition (configuration)
   //! - parentRegistry: Reader-writer registry for parameter serialization
   //!
   //! The owner provides access to entity state and other components. The
   //! DtPlatformLocalObjectFacade helper class simplifies access to platform-specific
   //! features like articulated parts.
   //!
   //! \param name Component instance name
   //! \param owner Owning entity
   //! \param simManager Simulation services access
   //! \param desc Component descriptor with configuration parameters
   //! \param parentRegistry Parent registry for parameter serialization
   //!
   DtExampleHumanArtPartActuator(const DtString& name,
      DtLocalObject* owner,
      DtSimulationServices* simManager,
      DtComponentDescriptor* desc = nullptr,
      DtReaderWriterRegistry* parentRegistry = nullptr);
 
   //! Default constructor - deleted (components require owner and services)
   DtExampleHumanArtPartActuator() = delete;
 
   //! Copy constructor - deleted (components are not copyable)
   DtExampleHumanArtPartActuator(const DtExampleHumanArtPartActuator& orig) = delete;
 
   //! Assignment operator - deleted (components are not assignable)
   const DtExampleHumanArtPartActuator& operator=(const DtExampleHumanArtPartActuator& orig) = delete;
 
   //! Destructor - cleanup component resources
   virtual ~DtExampleHumanArtPartActuator() override;
 
public:
   //! \brief Initialize component after construction
   //!
   //! PATTERN: VR-Forces Component Initialization
   //! The init() method is called once after construction to perform initialization
   //! that may depend on other components or simulation state. Always call the
   //! base class init() first to ensure proper initialization order.
   //!
   //! This Example:
   //! Performs only base class initialization. Articulated part lookup is deferred
   //! to the first tick() call to ensure the entity's articulated part system is
   //! fully initialized.
   //!
   //! \return true if initialization succeeded, false on failure
   //!
   virtual bool init() override;
 
   //! \brief Return component type identifier string
   //!
   //! Used by VR-Forces factory system to identify component type for instantiation
   //! and serialization. Must match the type string used in component registration.
   //!
   //! \return DtExampleHumanArtPartActuatorType constant
   //!
   virtual const char* type() const override;
 
   //! \brief Update component state for one simulation frame
   //!
   //! PATTERN: Articulated Part Animation
   //! This method demonstrates the complete pattern for animating DI-Guy joints:
   //!
   //! 1. Check for simulation pause (dT() == 0) and stop motion if paused
   //! 2. Lazy lookup articulated part on first tick (ensures entity is initialized)
   //! 3. Calculate desired joint angle and rate based on animation time
   //! 4. Set joint angles (azimuth, elevation, rotation) and rates
   //!
   //! Smooth Animation:
   //! Setting both the target angle and the angular rate produces smooth interpolated
   //! motion. VR-Forces/DI-Guy interpolates between the current and target angles
   //! using the provided rate.
   //!
   //! Animation Pattern Used:
   //! Sinusoidal motion from 0 to π/2 radians over myAnimationInterval seconds:
   //! - angle = maxAngle * sin(theta)
   //! - rate = derivative of angle with respect to time
   //!
   //! REUSABLE: This animation pattern can be adapted for:
   //! - Different joints (change DiGuyDisArtPartShoulderLeft to other joint IDs)
   //! - Different motion types (linear, ease-in/out, keyframed)
   //! - Multiple simultaneous joint animations (lookup and animate multiple parts)
   //! - Triggered animations (respond to events rather than continuous cycles)
   //!
   virtual void tick() override;
 
   //! \brief Static factory creator method for component instantiation
   //!
   //! PATTERN: VR-Forces Component Factory
   //! VR-Forces uses factory methods to instantiate components from entity definitions.
   //! This static method must match the signature expected by the component factory
   //! and return a new instance of this component class.
   //!
   //! Registered in plugin initialization:
   //!   componentFactory()->addCreatorFcn(DtExampleHumanArtPartActuatorType,
   //!      &DtExampleHumanArtPartActuator::creator);
   //!
   //! REUSABLE: This exact signature is required for all VR-Forces components.
   //!
   //! \param name Component instance name
   //! \param owner Owning entity
   //! \param simManager Simulation services access
   //! \param desc Component descriptor with configuration
   //! \param parentRegistry Parent registry for parameters
   //! \return New component instance
   //!
   static DtSimComponent* creator(const DtString& name,
      DtLocalObject* owner,
      DtSimulationServices* simManager,
      DtComponentDescriptor* desc = nullptr,
      DtReaderWriterRegistry* parentRegistry = nullptr);
 
protected:
   //! Facade providing convenient access to platform-specific entity features
   //! Simplifies access to articulated parts, sensors, weapons, and other
   //! platform subsystems
   DtPlatformLocalObjectFacade myPlatformLocalObjectFacade;
 
   //! Pointer to the left shoulder articulated part state
   //! Null until first tick() call, then cached for efficient subsequent access
   makVrf::DtArticulatedPartStateRepository* myLeftShoulder;
 
   //! Animation cycle duration in seconds
   //! The joint will complete one full motion cycle (0 to max angle and back) in this time
   double myAnimationInterval;
 
   //! Current time within the animation cycle (0 to myAnimationInterval)
   //! Accumulated each tick to calculate the current phase of the animation
   double myTimeInInterval;
};
} // namespace makVre