Utilities

1 - Common Enums

Common Enums provides shared enumeration types registered with O3DE’s SerializeContext. They can be used in component properties, asset fields, and ScriptCanvas nodes across any gem in the framework. The two primary enums are CurveType (curve selection for motion and gradient systems) and BooleanConditions (condition evaluation for dialogue and record-keeping systems).

Reflect functions: GS_Core::ReflectCommonEnums(context), GS_Core::ReflectCurveType(context)

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• BooleanConditions
• CurveType
• Using Enums in Components
• See Also

BooleanConditions

Used by condition-evaluation logic in the dialogue and record-keeping systems to compare numeric or string values.

Used by: DialogueCondition, Record_DialogueCondition, RecordKeeperComponent

CurveType

Maps to all easing curve functions in the Curves utility. Used by GS_Motion tracks, blend profiles, gradient markers, and any system that needs designer-selectable easing.

Used by: GS_MotionTrack, UiMotionTrack, FeedbackMotionTrack, gradient markers, GS_PhantomCamBlendProfile

Evaluating a CurveType in C++

#include <GS_Core/Utility/Math/CurvesUtility.h>

// Dispatch to the correct curve function via enum
float result = GS_Core::Curves::EvaluateCurve(GS_Core::CurveType::EaseInOutCubic, t);

Using Enums in Components

Use EnumAttribute on a DataElement with UIHandlers::ComboBox to expose enum selection as an Inspector dropdown.

#include <GS_Core/Utility/Math/CurvesUtility.h>
#include <GS_Core/Utility/CommonEnums.h>

// In your component's Reflect() method:
editContext->Class<MyComponent>("My Component", "Description")
    ->DataElement(AZ::Edit::UIHandlers::ComboBox,
        &MyComponent::m_curveType, "Curve Type",
        "The easing curve applied to this animation.")
        ->EnumAttribute(GS_Core::CurveType::Linear,             "Linear")
        ->EnumAttribute(GS_Core::CurveType::EaseInQuadratic,    "Ease In Quadratic")
        ->EnumAttribute(GS_Core::CurveType::EaseOutQuadratic,   "Ease Out Quadratic")
        ->EnumAttribute(GS_Core::CurveType::EaseInOutQuadratic, "Ease InOut Quadratic")
        ->EnumAttribute(GS_Core::CurveType::EaseInCubic,        "Ease In Cubic")
        ->EnumAttribute(GS_Core::CurveType::EaseOutCubic,       "Ease Out Cubic")
        ->EnumAttribute(GS_Core::CurveType::EaseInOutCubic,     "Ease InOut Cubic")
        // ... continue for all desired variants
    ;

This creates an Inspector dropdown where designers select a curve by name without touching code.

See Also

For related resources:

• Curves Utility
• Core Utilities
• Framework API: GS_Core

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

2 - Serialization Helpers

Three helpers that eliminate serialization boilerplate: a single-include header for common reflection, an extension for asset fields, and a ready-made O3DE asset handler template for any custom AssetData subclass.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• GS_ReflectionIncludes.h
• GS_AssetReflectionIncludes.h
• See Also

GS_ReflectionIncludes.h

A single-include header that brings in all O3DE reflection headers needed for any class with an inline Reflect() method.

Includes:

• AzCore/RTTI/RTTI.h
• AzCore/Memory/SystemAllocator.h
• AzCore/Serialization/SerializeContext.h
• AzCore/Serialization/EditContext.h
• AzCore/std/string/string.h

Use this in any header declaring a reflected struct, class, or enum. Does not handle AZ::Data::Asset<T> fields.

#include <GS_Core/Utility/Reflection/GS_ReflectionIncludes.h>

namespace MyProject
{
    struct MyData
    {
        AZ_TYPE_INFO(MyData, "{YOUR-UUID-HERE}");
        static void Reflect(AZ::ReflectContext* context);

        float m_value = 0.0f;
    };
}

GS_AssetReflectionIncludes.h

Extends GS_ReflectionIncludes.h with asset serialization headers.

Adds:

• AzCore/Asset/AssetCommon.h
• AzCore/Asset/AssetSerializer.h

Use this in any header declaring a class with AZ::Data::Asset<T> fields. Ensures SerializeGenericTypeInfo<Asset<T>> is visible and prevents silent failures in Unity builds.

#include <GS_Core/Utility/Reflection/GS_AssetReflectionIncludes.h>

namespace MyProject
{
    struct MyComponent : public AZ::Component
    {
        AZ_COMPONENT_DECL(MyComponent);
        static void Reflect(AZ::ReflectContext* context);

        AZ::Data::Asset<MyAssetType> m_asset;
    };
}

See Also

For related resources:

• Core Utilities
• Framework API: GS_Core

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

3 - Curves

The Curves namespace (GS_Core::Curves) provides 40+ easing functions for smooth animation and interpolation. All functions take a normalized t value in [0,1] and return a remapped [0,1] value. The dispatch function EvaluateCurve routes to the correct function by CurveType enum value, making curve selection fully data-driven from the Inspector or asset editor.

Used by every GS_Motion track, all gradient evaluate calls, and the blend profile system.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Curve Families
• API Reference
• Usage Examples
• See Also

Curve Families

Variant naming: EaseIn = slow start, EaseOut = slow end, EaseInOut = slow start and end.

API Reference

Dispatch Function

float EvaluateCurve(CurveType curveType, float t);

Dispatches to the correct curve function based on the CurveType enum value. This is the primary call site for all motion and gradient systems. t must be in [0,1].

Individual Functions

One free function per CurveType value, all sharing the signature float <Name>(float t). Examples:

All functions follow the same naming pattern as the CurveType enum values.

Usage Examples

Dispatch via enum (data-driven)

#include <GS_Core/Utility/Math/CurvesUtility.h>

// Evaluate at normalized progress t (0 → 1)
float eased = GS_Core::Curves::EvaluateCurve(GS_Core::CurveType::EaseInOutCubic, t);

// Interpolate between two values
float result = start + (end - start) * GS_Core::Curves::EvaluateCurve(curveType, t);

Direct function call

// Call the function directly for a known curve
float eased = GS_Core::Curves::EaseOutBack(t);

See Also

For related resources:

• Common Enums — CurveType enum for data-driven curve selection
• Springs Utility
• Gradients
• Core Utilities

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

4 - Springs

The Springs namespace (GS_Core::Springs) provides six spring-damper types for physics-based animation and smoothing. Springs produce natural-feeling motion that reacts to velocity — ideal for camera follow, UI motion, and any value that should settle rather than snap.

All springs use a halflife parameter: the number of seconds to cover 50% of the remaining distance to the goal. This is more intuitive than raw stiffness/damping constants. Each spring type is available in float, AZ::Vector2, and AZ::Vector3 overloads where applicable.

Used by: gs_phantomcam (camera smoothing), gs_unit (character movement), gs_juice (feedback motions)

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Spring Types
• SimpleSpringDamperExact
• AccelerationSpringDamper
• DoubleSpringDamper
• TimedSpringDamper
• VelocitySpringDamper
• QuaternionSpringDamper
• Usage Example
• See Also

Spring Types

SimpleSpringDamperExact

A critically-damped spring that moves toward a target position. Fast start, ease-out arrival. Computed exactly (no approximation). The most common spring for follow and snap behaviors.

AccelerationSpringDamper

Tracks a target velocity rather than a position. Adds an acceleration memory term for smoother response to sudden direction changes (e.g. thumbstick flicks). Suited for character movement and camera motion where input can change abruptly.

DoubleSpringDamper

Two springs chained together, producing an S-curve (ease-in AND ease-out). Slower to start and slower to arrive than the simple spring. Gives a more polished feel for UI transitions or cinematic camera cuts.

TimedSpringDamper

Attempts to reach the target by a specific time. Adjusts halflife internally so the spring arrives near the target time rather than asymptotically. Useful for choreographed movements with loose time targets.

VelocitySpringDamper

Tracks a moving target by incorporating the target’s own velocity for predictive lead. The follower anticipates the direction of movement, reducing lag on fast-moving targets. Suited for camera following a character at speed.

QuaternionSpringDamper

Rotation spring that operates on angular velocity. Includes a flip option to reverse the rotation direction.

Note: The rotation output jumps to the goal each frame. Extract angularVelocity and integrate externally if you need a continuously smooth rotation output.

Usage Example

#include <GS_Core/Utility/Math/SpringsUtility.h>

// Member fields — must persist between frames
AZ::Vector3 m_followVelocity = AZ::Vector3::CreateZero();

// In your tick function:
AZ::Vector3 currentPos = GetEntityTranslation();
AZ::Vector3 targetPos  = GetTargetTranslation();

GS_Core::Springs::SimpleSpringDamperExact(
    currentPos,       // in/out: current position (updated in place)
    m_followVelocity, // in/out: velocity (cached between frames)
    targetPos,        // target position
    0.1f,             // halflife: 0.1 seconds to cover half the distance
    deltaTime
);

SetEntityTranslation(currentPos);

See Also

For related resources:

• Curves Utility
• Core Utilities

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

5 - Gradients

The Gradients utility provides three parallel gradient types for interpolating values over a normalized [0,1] range using a sorted list of marker points. All types are fully reflected (SerializeContext + EditContext) and editable in the Inspector with visual marker placement. Gradients are lazily sorted before evaluation.

Used by: FeedbackMaterialTrack (color/float animation), UiImageColorTrack, procedural visual effects, any system needing editable color or value ramps.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• Gradient Types
• Marker Structs
• Gradient Classes
• ColorGradient Channels
• Usage Example
• See Also

Gradient Types

Marker Structs

Each gradient type has a corresponding marker struct that defines a single stop on the gradient.

FloatGradientMarker

Vector2GradientMarker

ColorGradientMarker

Gradient Classes

All three gradient types share the same structure and interface:

ColorGradient

ColorGradient maintains two separate marker lists for independent RGB and alpha control:

ColorGradient Channels

ColorGradient exposes three evaluate methods for flexible sampling:

Usage Example

#include <GS_Core/Utility/Gradients/FloatGradientUtility.h>
#include <GS_Core/Utility/Gradients/ColorGradientUtility.h>

// Sample a float gradient at normalized progress (0 → 1)
float value = myFloatGradient.Evaluate(normalizedProgress);

// Sample full RGBA color
AZ::Color color = myColorGradient.Evaluate(normalizedProgress);

// Sample RGB and alpha independently
AZ::Color rgb   = myColorGradient.EvaluateColor(normalizedProgress);
float alpha     = myColorGradient.EvaluateAlpha(normalizedProgress);

See Also

For related resources:

• Curves Utility — easing functions used by motion tracks that drive gradient evaluation
• Core Utilities
• Framework API: GS_Core

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

6 - Entity Helpers

The EntityUtility namespace provides helper functions for finding entities in the active scene by name. Useful for runtime entity lookup without maintaining manual entity references.

For usage guides and setup examples, see The Basics: GS_Core.

API Reference

Usage Example

#include <GS_Core/Utilities/EntityUtility.h>

// Find an entity by name
AZ::EntityId playerId = GS_Core::EntityUtility::GetEntityIdByName("Player");
if (playerId.IsValid())
{
    // Use the entity
}

See Also

For related resources:

• Core Utilities

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

7 - Angle Helpers

The Orientation namespace (GS_Core::Orientation) provides angle-to-sector mapping for directional gameplay — animation direction selection, facing classification, and compass-style sector queries. It splits a full circle into N equal angular sectors and determines which sector a given angle falls into, with hysteresis to prevent rapid sector-switching at boundaries.

Used by: Paper-facing systems (gs_performer), directional input reactors (gs_unit), targeting systems (gs_interaction)

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• SectionConfig Enum
• RotationDirection Enum
• Pick Struct
• API Reference
• Usage Example
• See Also

SectionConfig Enum

A reflected, editor-friendly enum selecting common sector counts and alignment modes. Two alignment modes exist per count:

• cardinal / sideAligned — sector boundaries fall on the cardinal directions; sectors straddle diagonals
• quarters / forwardAligned — sector boundaries fall on diagonals; sectors straddle cardinals

Register with GS_Core::Orientation::ReflectOrientationEnums(context) to expose these in the Inspector.

RotationDirection Enum

Controls the winding convention used when computing sector angles.

Pick Struct

Returned by all PickByAngle overloads. Contains full sector geometry for the selected sector.

Use GS_Core::Orientation::Changed(pick, prevIndex) to detect when the sector index changes between frames.

API Reference

Sector Mapping

Angle Math

Yaw and Quaternion

Reflection

Usage Example

#include <GS_Core/Utility/Math/SectionByAngle.h>

// Member field — track previous sector to enable hysteresis
int m_prevSectorIndex = -1;

// In your tick / update function:
AZ::Vector3 moveDir = GetMovementDirection();

// Get the yaw from the movement direction (Z-up world)
float yaw = GS_Core::Orientation::YawFromDir(moveDir, GS_Core::Orientation::RotationDirection::CCW);

// Map to an 8-way sector with 5-degree hysteresis
GS_Core::Orientation::Pick pick = GS_Core::Orientation::PickByAngle(
    yaw,
    GS_Core::Orientation::SectionConfig::x8_cardinal,
    m_prevSectorIndex,  // previous index for hysteresis
    5.0f                // hysteresis in degrees
);

if (GS_Core::Orientation::Changed(pick, m_prevSectorIndex))
{
    m_prevSectorIndex = pick.index;
    // React to direction change: play animation, update facing, etc.
}

See Also

For related resources:

• Core Utilities
• Framework API: GS_Core

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

8 - Spline Helpers

The SplineUtility namespace (GS_Core::SplineUtility) provides free functions for querying the closest point on an O3DE spline component attached to an entity. All functions take an entity ID and a position in world or local space.

Used by: PathTo_DialoguePerformance (gs_cinematics), any system that guides an entity along a spline path.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• API Reference
• Usage Example
• See Also

API Reference

Usage Example

#include <GS_Core/Utility/SplineUtility.h>

// Find how far along a path the player is (0 = start, 1 = end)
AZ::Vector3 playerPos = GetPlayerWorldPosition();
float fraction = GS_Core::SplineUtility::FindClosestFraction(splineEntityId, playerPos);

// Get the actual closest world position on the path
AZ::Vector3 closestPoint = GS_Core::SplineUtility::FindClosestWorldPoint(splineEntityId, playerPos);

See Also

For related resources:

• Core Utilities
• Framework API: GS_Core

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

9 - Physics Trigger Volume

The physics trigger system is two classes: PhysicsTriggeringVolume (the non-component base class with all trigger logic) and PhysicsTriggerComponent (the concrete O3DE component that wraps it with game-lifecycle awareness). Inherit from either to create interactive volumes — damage zones, pickup areas, dialogue triggers, environmental hazards — without writing boilerplate physics code.

The base class handles entity tracking (one enter/exit per entity), supports both trigger overlaps and collision contacts, and provides optional hold/persist callbacks for continuous processing.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• PhysicsTriggeringVolume
• PhysicsTriggerComponent
• Extending Physics Trigger Volume
• See Also

PhysicsTriggeringVolume

File: Physics/PhysicsTriggeringVolume.h Namespace: GS_Core Base classes: Physics::RigidBodyNotificationBus::Handler, DebugLoggingHelper

A non-component base class that manages the full lifecycle of a physics trigger or collision volume. Add it alongside your own AZ::Component via multiple inheritance.

Configuration Fields

Lifecycle Methods

Virtual Callbacks

Override these in your subclass to react to trigger and collision events.

Internal State

PhysicsTriggerComponent

File: Physics/PhysicsTriggerComponent.h Namespace: GS_Core Base classes: PhysicsTriggeringVolume, GameManagerNotificationBus::Handler

A concrete O3DE component that wraps PhysicsTriggeringVolume and adds game-lifecycle awareness. Automatically disables the trigger during game standby and re-enables it on exit.

Used by: WorldTriggerComponent (gs_interaction), ColliderTriggerSensorComponent — these subclass PhysicsTriggerComponent to implement game-specific trigger behaviors.

Data Fields

Virtual Methods

Override these to implement game-specific trigger behavior.

Standby Handling

Extending Physics Trigger Volume

Use the PhysicsTriggerComponent ClassWizard template to generate a new trigger component with boilerplate already in place — see GS_Core Templates.

Inherit directly from PhysicsTriggeringVolume alongside AZ::Component for a lightweight custom trigger. Use PhysicsTriggerComponent as your base if you need the built-in standby handling.

Header (.h)

#pragma once
#include <AzCore/Component/Component.h>
#include <GS_Core/Utility/Physics/PhysicsTriggeringVolume.h>

namespace MyProject
{
    class DamageZoneComponent
        : public AZ::Component
        , public virtual GS_Core::PhysicsTriggeringVolume
    {
    public:
        AZ_COMPONENT_DECL(DamageZoneComponent);

        static void Reflect(AZ::ReflectContext* context);

    protected:
        void Activate() override;
        void Deactivate() override;

        // Trigger overrides
        bool TriggerEnter(AZ::EntityId entity) override;
        void TriggerHold(float fixedDeltaTime) override;
        bool TriggerExit(AZ::EntityId entity) override;

    private:
        float m_damagePerSecond = 10.0f;
    };
}

Implementation (.cpp)

#include "DamageZoneComponent.h"
#include <AzCore/Serialization/SerializeContext.h>

namespace MyProject
{
    AZ_COMPONENT_IMPL(DamageZoneComponent, "DamageZoneComponent", "{YOUR-UUID-HERE}");

    void DamageZoneComponent::Reflect(AZ::ReflectContext* context)
    {
        if (auto sc = azrtti_cast<AZ::SerializeContext*>(context))
        {
            sc->Class<DamageZoneComponent, AZ::Component, GS_Core::PhysicsTriggeringVolume>()
                ->Version(0)
                ->Field("DamagePerSecond", &DamageZoneComponent::m_damagePerSecond);

            if (AZ::EditContext* ec = sc->GetEditContext())
            {
                ec->Class<DamageZoneComponent>("Damage Zone", "Deals damage inside the trigger volume")
                    ->ClassElement(AZ::Edit::ClassElements::EditorData, "")
                        ->Attribute(AZ::Edit::Attributes::Category, "MyProject")
                        ->Attribute(AZ::Edit::Attributes::AppearsInAddComponentMenu, AZ_CRC_CE("Game"))
                    ->DataElement(AZ::Edit::UIHandlers::Default,
                        &DamageZoneComponent::m_damagePerSecond,
                        "Damage Per Second", "Damage dealt per second while inside");
            }
        }
    }

    void DamageZoneComponent::Activate()
    {
        EnableTriggerHoldUpdate = true;  // Enable hold callbacks for continuous damage
        GS_Core::PhysicsTriggeringVolume::ConnectTriggering(GetEntityId());
    }

    void DamageZoneComponent::Deactivate()
    {
        GS_Core::PhysicsTriggeringVolume::DisconnectTriggering();
    }

    bool DamageZoneComponent::TriggerEnter(AZ::EntityId entity)
    {
        AZ_TracePrintf("DamageZone", "Entity entered damage zone");
        return true; // Accept the entity
    }

    void DamageZoneComponent::TriggerHold(float fixedDeltaTime)
    {
        // Apply damage to all entities currently inside
        for (const AZ::EntityId& entity : m_entities)
        {
            // Apply m_damagePerSecond * fixedDeltaTime damage to entity...
        }
    }

    bool DamageZoneComponent::TriggerExit(AZ::EntityId entity)
    {
        AZ_TracePrintf("DamageZone", "Entity exited damage zone");
        return true;
    }
}

Setup

1. Create an entity with a PhysX Collider component set as a trigger.
2. Add your custom trigger component (e.g., DamageZoneComponent).
3. Configure the collider shape and component properties.
4. Entities with PhysX rigid bodies that enter the collider will trigger your callbacks.

See Also

For conceptual overviews and usage guides:

• The Basics: Utilities

For related resources:

• Core Utilities
• Framework API: GS_Core

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.

10 - Weighted Random

RandomUtils (GS_Core::RandomUtils) provides a single templated static method for weighted random selection from a map. The caller provides their own AZ::SimpleLcgRandom instance for deterministic control over the random sequence.

Used by: RandomNodeData (dialogue random node), KlattVoiceComponent (phoneme selection), any system needing weighted random draws.

For usage guides and setup examples, see The Basics: GS_Core.

Contents

• API Reference
• Usage Example
• See Also

API Reference

template<typename T>
static T GetRandomWeighted(
    AZ::SimpleLcgRandom* rand,
    const AZStd::unordered_map<T, float>& weightedTable
);

Selects one key from weightedTable with probability proportional to its float weight value. Higher weights mean higher probability of selection.

Returns: The selected key of type T.

Edge cases:

• Falls back to the last entry on floating-point precision edge cases.
• Asserts if weightedTable is empty.

Usage Example

#include <GS_Core/Utility/Random/RandomUtils.h>
#include <AzCore/Math/Random.h>

// Member field — keep the random instance alive across calls
AZ::SimpleLcgRandom m_random;

// Build a weighted table: key = item, value = relative weight
AZStd::unordered_map<AZStd::string, float> lootTable;
lootTable["Common Sword"]    = 50.0f;
lootTable["Rare Shield"]     = 30.0f;
lootTable["Epic Helmet"]     = 15.0f;
lootTable["Legendary Ring"]  =  5.0f;

// Select an item — "Common Sword" is 10x more likely than "Legendary Ring"
AZStd::string selected = GS_Core::RandomUtils::GetRandomWeighted(&m_random, lootTable);

See Also

For related resources:

• Core Utilities
• Framework API: GS_Core

Get GS_Core

GS_Core — Explore this gem on the product page and add it to your project.