Emerald AI API - Black-Horizon-Studios/Emerald-AI GitHub Wiki

Emerald AI API

Emerald AI has tons of API that can be accessed to allow for added functionality, custom mechanics, and more.

Table of Contents

 

Getting Started with Emerald AI's API

In order for Emerald AI's API to be accessed via code, users must reference their AI’s EmeraldAISystem component. Once this is accessed, users will need to find the EmeraldAIEventsManager that holds all of the AI’s API. It is recommended that you use the EmeraldAI namespace at the top of your scripts to make accessing the Emerald AI scripts easier using:

using EmeraldAI;

Next, you will want a reference to an AI’s events manager script. There is one that is located on each AI. This can be done using the following and should be called on Start:

EventsManager = GetComponent<EmeraldAIEventsManager>();

Now, when using the EventsManager variable, you can access all of an AI’s internal functions that allow you to control a wide variety of functionality. The following API is assumed you used the EventsManager variable name as your reference to the EmeraldAIEventsManager component.

Users can also use the EmeraldAISystem for altering an AI's variables directly.

EmeraldComponent = GetComponent<EmeraldAISystem>();

For users who need a working example, please use the following script to get you started. (This script needs to be attached to your AI in order to work correctly)

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using EmeraldAI;

public class AccessEmeraldAIExample : MonoBehaviour
{
    EmeraldAISystem EmeraldComponent;
    EmeraldAIEventsManager EventsManager;

    //Get the EmeraldAISystem component and EmeraldAIEventsManager and store them as variables.
    void Start ()
    {
        EmeraldComponent = GetComponent<EmeraldAISystem>();
        EventsManager = EmeraldComponent.EmeraldEventsManagerComponent;
    }
    
    //Changes the AI's current behavior to Aggressive when pressing the H key.
    void Update()
    {
        if (Input.GetKeyDown(KeyCode.H))
        {
            EventsManager.ChangeBehavior(EmeraldAISystem.CurrentBehavior.Aggressive);
        }
    }
}

 

Damaging an AI

If you’d like to apply damage to an AI directly, for something like a custom character controller, you can do so with the code below. It is assumed you have a reference to the hit target when doing so.

For a detailed guide on setting up custom damage, please see the Setting up Custom Damage with Emerald AI section.

Damage

Damages an AI with a customizable damage amount, Target Type, Transform to assign as target, and the amount of ragdoll force applied on death.

Damage (int DamageAmount, TargetType AttackersTargetType, Transform YourTargetsTransform, int RagdollForce)

Example:

//Damages an AI to the YourTargetReference object
if (YourTargetReference.GetComponent<EmeraldAI.EmeraldAISystem>() != null)
{
   YourTargetReference.GetComponent<EmeraldAI.EmeraldAISystem>().Damage(YourDamageAmount, EmeraldAI.EmeraldAISystem.TargetType.Player, YourPlayerTransform, 400);
}

 

Emerald AI Events Manager API

Here's all of the usable Emerald AI Events Manager API. Some of these can be used as Animation Events, such as playing an attack sound or playing footstep sounds.

General API

OverrideCombatTarget

Assigns a specified combat target for your AI to attack ignoring any distance limitations. If the target is not within attacking range, the AI will move to the target's position and attack based on its attack distance.

EventsManager.OverrideCombatTarget(Transform Target);

SetIgnoredTarget

Adds the specified ignored target to the static EmeraldAISystem IgnoredTargetsList.

EventsManager.SetIgnoredTarget(Transform TargetTransform)

ClearIgnoredTarget

Removes the specified ignored target from the static EmeraldAISystem IgnoredTargetsList.

EventsManager.ClearIgnoredTarget(Transform TargetTransform)

ClearAllIgnoredTargets

Clears all ignored targets from the static EmeraldAISystem IgnoredTargetsList.

EventsManager.ClearAllIgnoredTargets();

GetAttacker

Returns the transform that last attacked the AI.

EventsManager.GetAttacker();

ChangeDetectionType

Changes the AI's Detection Type.

EventsManager.ChangeDetectionType (EmeraldAISystem.DetectionType DetectionType)

GetCombatTarget

Returns the AI's current target.

EventsManager.GetCombatTarget();

GetFaction

Returns this AI's current Faction as a string. (This is the Faction that is set through the Emerald AI Editor under Faction Options)

EventsManager.GetFaction();

KillAI

Instantly kills the AI.

EventsManager.KillAI();

ResetAI

Resets an AI to its default state. This is useful if an AI is being respawned or reused.

EventsManager.ResetAI();

InstantlyRefillAIHealth

Refills the AI's health to full instantly

EventsManager.InstantlyRefillAIHealth();

ChangeBehavior

Changes the AI's Behavior

EventsManager.ChangeBehavior(EmeraldAISystem.CurrentBehavior NewBehavior)

Example:

//Change the AI's current behavior to Passive
EventsManager.ChangeBehavior(EmeraldAISystem.CurrentBehavior.Passive);

ChangeConfidenceLevel

Changes the AI's current Confidence level

EventsManager.ChangeConfidence(EmeraldAISystem.ConfidenceType NewConfidence)

Example:

//Change the AI's current confidence to Brave
EventsManager.ChangeConfidence(EmeraldAISystem.ConfidenceType.Brave);

ChangeWanderType

Changes the AI's current Wander type

EventsManager.ChangeWanderType(EmeraldAISystem.WanderType NewWanderType)

Example:

//Change the AI's current Wander Type to Stationary
EventsManager.ChangeWanderType(EmeraldAISystem.WanderType.Stationary);

SetFactionLevel

Changes the relation of the given faction. Note: The faction must be available in the AI's faction list.

EventsManager.SetFactionLevel(string Faction, string FactionLevel)

Example:

//Sets the Beast faction relation to Friendly
EventsManager.SetFactionLevel("Beast", "Friendly");

ChangeFaction

Changes the AI's faction. (Note: The FactionName must exists within the Faction Manager's Current Faction list)

EventsManager.ChangeFaction(string FactionName)

Example:

//Changes the AI's Faction to Undead
EventsManager.ChangeFaction("Undead");

AddFactionRelation

Adds the Faction and Faction Relation to the AI's Faction Relations List. Note: The faction must exist within the Faction Manager's Current Faction List.

EventsManager.AddFactionRelation(string Faction, string FactionLevel)

Example:

//Adds the Orc faction and relation as Enemy to an AI's Faction Relation list.
EventsManager.AddFactionRelation("Orc", "Enemy");

GetAIRelation

Returns the relation of the EmeraldTarget with this AI. The EmeraldTarget sent must be another AI's EmeraldAISystem component.

EventsManager.GetAIRelation(EmeraldAISystem EmeraldTarget)

Example:

//Debug logs the AI's relation to the AI's current target, given that it is another AI, to the Unity Console.
Debug.Log(EventsManager.GetAIRelation(EmeraldComponent.TargetEmerald));

SetPlayerRelation

Sets the relation of the player and this AI to Enemy.

EventsManager.SetPlayerRelation(EmeraldAISystem.PlayerFactionClass.RelationType Relation)

Example:

//Sets the relation of the player and this AI to Enemy.
EventsManager.SetPlayerRelation(EmeraldAISystem.PlayerFactionClass.RelationType.Enemy);

GetPlayerRelation

Returns the relation of the EmeraldTarget with this AI.

EventsManager.GetPlayerRelation()

Example:

//Debug logs the AI's relation to the player to the Unity Console.
Debug.Log(EventsManager.GetPlayerRelation());

SetCombatTarget

Assigns a specified combat target for your AI to attack within the AI's Detection Radius. Note: Targets outside of an AI's Detection Radius will be ignored. If you want no distance limitations, use OverrideCombatTarget(Transform Target).

EventsManager.SetCombatTarget(Transform Target)

SetFollowerTarget

Assigns a new follow target for your companion AI to follow.

EventsManager.SetFollowerTarget(Transform Target)

ClearTarget

Clears the AI's target. This is important if you are going to be destroying a target such as a player. An optional bool parameter can also be passed to clear an AI's follower target, if the AI is using the Companion or Pet Behavior Types.

EventsManager.ClearTarget(bool? ClearFollower = false)

Example:

//Clears the AI's target.
EventsManager.ClearTarget();

//Clears the AI's target and its current follower.
EventsManager.ClearTarget(true);

TameAI

Tames the AI to become the Target object’s companion. Note: The tameable AI must have a Cautious Behavior Type and a Brave or Foolhardy Confidence Type. The AI must be tamed before the AI turns Aggressive to be successful.

EventsManager.TameAI(Transform Target)

SearchForClosestTarget

Searches for a new target within the AI's Attacking Range closest to the AI.

EventsManager.SearchForClosestTarget()

SearchForRandomTarget

Searches for a new random target within the AI's Attacking Range.

EventsManager.SearchForRandomTarget()

FleeFromTarget

Makes an AI flee from the specified target by overiding their behavior and confidence levels.

EventsManager.FleeFromTarget(Transform FleeTarget)

UpdateAIMeleeDamage

Updates the AI's Min and Max Melee Damage using the sent Melee Attack Number from the AI's Melee Attack List starting from 1. If the attack is not using randomized damage, the Min Damage will be used.

EventsManager.UpdateAIMeleeDamage(int MeleeAttackNumber, int MinDamage, int MaxDamage)

UpdateAIAttackSpeed

Updates the AI's Minimum and Maximum Attack Speed.

EventsManager.UpdateAIAttackSpeed (int MinAttackSpeed, int MaxAttackSpeed)

CheckForPlayerDetection

Checks to see if the player is currently within the AI's detection radius by returning true or false.

EventsManager.CheckForPlayerDetection();

DebugLogMessage

Debug logs a message to the Unity Console for testing purposes.

EventsManager.DebugLogMessage(string Message);

GetDistanceFromTarget

Returns the current distance between the AI and their current target (Returns -1 if the Current Target is null).

EventsManager.GetDistanceFromTarget();

EnableObject

Enables the passed gameobject.

EventsManager.EnableObject(GameObject Object);

DisableObject

Disables the passed gameobject.

EventsManager.DisableObject(GameObject Object);

 

Movement & Destination API

AddWaypoint

Adds a waypoint to an AI's Waypoint List.

EventsManager.AddWaypoint(Transform Waypoint)

RemoveWaypoint

Removes a waypoint from the AI's Wapoint List according to the specified index.

EventsManager.RemoveWaypoint(int WaypointIndex)

ClearAllWaypoints

Clears all of an AI's current waypoints. Note: When an AI's waypoints are cleared, it will be set to the Stationary wander type to avoid an error. If you want the AI to follow newly created waypoints, you will need to set it's Wander Type back to Waypoint with the ChangeWanderType functio (located within the EmeraldAIEventsManager script).

EventsManager.ClearAllWaypoints();

UpdateDynamicWanderPosition

Update the AI's dynamic wandering position to the AI's current position.

EventsManager.UpdateDynamicWanderPosition();

SetDynamicWanderPosition

Sets the AI's dynamic wandering position to the position of the Destination transform. This is useful for functionality such as custom AI schedules. Note: This will automatically change your AI's Wander Type to Dynamic.

EventsManager.SetDynamicWanderPosition(Transform Destination)

UpdateStartingPosition

Updates the AI's starting position to the AI's current position.

EventsManager.UpdateStartingPosition()

SetDestination

Sets the AI's destination using a transform's position.

EventsManager.SetDestination(Transform Destination)

SetDestinationPosition

Sets the AI's destination using a Vector3 position.

EventsManager.SetDestinationPosition(Vector3 DestinationPosition)

StopMovement

Stops an AI from moving. This is useful for functionality like dialogue.

EventsManager.StopMovement();

ResumeMovement

Resumes an AI's movement after using the StopMovement function.

EventsManager.ResumeMovement();

StopFollowing

Stops a Companion AI from moving.

EventsManager.StopFollowing();

ResumeFollowing

Allows a Companion AI to resume following its follower.

EventsManager.ResumeFollowing();

CompanionGuardPosition

Allows a Companion AI to guard the assigned position.

EventsManager.CompanionGuardPosition(Vector3 PositionToGuard)

RotateAITowardsTarget

Rotates the AI towards the specified target that utilizes the AI's turning animations. The angle in which the AI will stop rotating is based off of an AI's Turning Angle set within the Emerald AI editor. This will also stop the AI's movement for the Duration parameter. If a Duration of -1 is used, the duration period will be indefinite and can be canceled with CancelRotateAITowardsTarget().

EventsManager.RotateAITowardsTarget(Transform Target, int Duration)

CancelRotateAITowardsTarget

Cancels the indefinite rotation towards the target after RotateAITowardsTarget has been called.

EventsManager.CancelRotateAITowardsTarget()

RotateAITowardsPosition

Rotates the AI towards the specified position that utilizes the AI's turning animations. The angle in which the AI will stop rotating is based off of an AI's Turning Angle set within the Emerald AI editor. This will also stop the AI's movement for the Duration parameter. If a Duration of -1 is used, the duration period will be indefinite and can be canceled with CancelRotateAITowardsPosition().

EventsManager.RotateAITowardsPosition(Vector3 TargetPosition, int Duration)

CancelRotateAITowardsPosition

Cancels the indefinite rotation towards the Position after RotateAITowardsPosition has been called.

EventsManager.CancelRotateAITowardsPosition()

RotateAIAwayFromTarget

Rotates the AI away from the specified target that utilizes the AI's turning animations. The angle in which the AI will stop rotating is based off of an AI's Turning Angle set within the Emerald AI editor. This will also stop the AI's movement for the Duration parameter. If a Duration of -1 is used, the duration period will be indefinite and can be canceled with CancelRotateAIAwayFromTarget().

EventsManager.RotateAIAwayFromTarget(Transform Target, int Duration)

CancelRotateAIAwayFromTarget

Cancels the indefinite rotation away from the target after RotateAIAwayFromTarget has been called.

EventsManager.CancelRotateAIAwayFromTarget()

RotateAIAwayFromPosition

Rotates the AI away from the specified position that utilizes the AI's turning animations. The angle in which the AI will stop rotating is based off of an AI's Turning Angle set within the Emerald AI editor. This will also stop the AI's movement for the Duration parameter. If a Duration of -1 is used, the duration period will be indefinite and can be canceled with CancelRotateAIAwayFromPosition().

EventsManager.RotateAIAwayFromPosition(Transform Target, int Duration)

CancelRotateAIAwayFromPosition

Cancels the indefinite rotation away from the position after RotateAIAwayFromPosition has been called.

EventsManager.CancelRotateAIAwayFromPosition()

 

Sound API

PlaySoundClip

Plays a sound clip according to the Clip parameter.

EventsManager.PlaySoundClip(AudioClip Clip)

PlayIdleSound

Plays a random attack sound based on your AI's Attack Sounds list. Can also be called through Animation Events.

EventsManager.PlayIdleSound();

PlayAttackSound

Plays a random attack sound based on your AI's Attack Sounds list. Can also be called through Animation Events.

EventsManager.PlayAttackSound();

PlayWarningSound

Plays a random attack sound based on your AI's Attack Sounds list. Can also be called through Animation Events.

EventsManager.PlayWarningSound();

PlayBlockSound

Plays a random block sound based on your AI's Block Sounds list.

EventsManager.PlayBlockSound();

PlayDeathSound

Plays a random death sound based on your AI's Death Sounds list. Can also be called through Animation Events.

EventsManager.PlayDeathSound();

WalkFootstepSound

Plays a footstep sound from the AI's Footstep Sounds list to use when the AI is walking. This should be setup through an Animation Event.

EventsManager.WalkFootstepSound();

RunFootstepSound

Plays a footstep sound from the AI's Footstep Sounds list to use when the AI is running. This should be setup through an Animation Event.

EventsManager.RunFootstepSound();

PlayRandomSoundEffect

Plays a random sound effect from the AI's General Sounds list.

EventsManager.PlayRandomSoundEffect();

PlaySoundEffect

Plays a sound effect from the AI's General Sounds list using the Sound Effect ID as the parameter. This is useful for creating sounds with Animation Events such an interaction sound.

EventsManager.PlaySoundEffect(int SoundEffectID)

 

Items & Effect API

EnableItem

Enables an item from your AI's Item list using the Item ID.

EventsManager.EnableItem(int ItemID)

DisableItem

Disables an item from your AI's Item list using the Item ID.

EventsManager.DisableItem(int ItemID)

DisableAllItems

Disables all items from your AI's Item list.

EventsManager.DisableAllItems()

EnableWeapon

Enables the AI's weapon object and plays the AI's equip sound effect, if one is applied.

EventsManager.EnableWeapon(string WeaponTypeToEnable)

DisableWeapon

Disables the AI's weapon object and plays the AI's unequip sound effect, if one is applied.

EventsManager.DisableWeapon(string WeaponTypeToDisable)

SpawnAdditionalEffect

Spawns an additional effect object at the position of the AI's Blood Spawn Offset position.

EventsManager.SpawnAdditionalEffect(GameObject EffectObject)

SpawnEffectOnTarget

Spawns an effect object at the position of the AI's target.

EventsManager.SpawnEffectOnTarget(GameObject EffectObject)

SpawnBloodSplatEffect

Spawns a blood splat effect object at the position of the AI's Blood Spawn Offset position. The rotation of this object is then randomized and adjusted based off of your attacker's current location.

EventsManager.SpawnBloodSplatEffect(GameObject BloodSplatObject)

CreateDroppableWeapon

Instantiates an AI's Droppable Weapon Object on death (This should be a prefab object).

EventsManager.CreateDroppableWeapon()

 

Animation API

CancelAttackAnimation

Cancels the AI's current attack animation from playing.

EventsManager.CancelAttackAnimation();

PlayEmoteAnimation

Plays an emote animation according to the Animation Clip parameter. Up to 10 emote animations are supported.

EventsManager.PlayEmoteAnimation(int EmoteAnimationID)

LoopEmoteAnimation

Loops an emote animation according to the Animation Clip parameter until it is called to stop. Up to 10 emote animations are supported.

EventsManager.LoopEmoteAnimation(int EmoteAnimationID)

StopLoopEmoteAnimation

Loops an emote animation according to the Animation Clip parameter until it is called to stop. Note: This function will only work if an AI is not in active combat mode.

EventsManager.StopLoopEmoteAnimation(int EmoteAnimationID)

OverrideIdleAnimation

Manually sets the AI's next Idle animation instead of being generated randomly. This is useful for functionality such as playing a particular idle animation at a certain location such as for an AI's schedule. Note: The animation numbers are from 1 to 6 and must exist in your AI's Idle Animation list. You must call DisableOverrideIdleAnimation() to have idle animations randomly generate again and to disable this feature.

EventsManager.OverrideIdleAnimation(int IdleIndex)

DisableOverrideIdleAnimation

Disables the OverrideIdleAnimation feature.

EventsManager.DisableOverrideIdleAnimation()

 

Utility API

UpdateUIHealthBarColor

Updates the AI's Health Bar color

EventsManager.UpdateUIHealthBarColor(Color NewColor)

UpdateUIHealthBarBackgroundColor

Updates the AI's Health Bar Background color

EventsManager.UpdateUIHealthBarBackgroundColor(Color NewColor)

UpdateUINameColor

Updates the AI's Name color

EventsManager.UpdateUINameColor(Color NewColor)

UpdateUINameText

Updates the AI's Name text

EventsManager.UpdateUINameText(string NewName)

UpdateHealth

Updates the AI's Max Health, Current Health, and health bar if it's enabled.

EventsManager.UpdateHealth(int MaxHealth, int CurrentHealth)