Skip to content

Commit

Permalink
Merge pull request #313 from crashkonijn/feature/doc-comments
Browse files Browse the repository at this point in the history 
Added xml comments to various classes. #169
  • Loading branch information
@crashkonijn
crashkonijn authored Dec 5, 2024
2 parents fb9566d + 0b47bd3 commit 6204afc
Show file tree
Hide file tree
Showing 18 changed files with 647 additions and 121 deletions.
112 changes: 102 additions & 10 deletions Package/Runtime/CrashKonijn.Agent.Runtime/ActionBase.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,39 +8,64 @@ public abstract class AgentActionBase<TActionData, TActionProperties>
{
private IActionDisabler disabler;

/// <summary>
/// Gets the action data.
/// </summary>
/// <returns>The action data.</returns>
public IActionData GetData()
{
return this.CreateData();
}

/// <summary>
/// Creates a new instance of action data.
/// </summary>
/// <returns>The created action data.</returns>
public virtual TActionData CreateData()
{
return new TActionData();
}

/// <summary>
/// Gets the action properties.
/// </summary>
public abstract TActionProperties Properties { get; }

/// <summary>
/// Called when the action is created.
/// </summary>
public virtual void Created() { }

/// <summary>
/// Called when the action is started (when it is assigned to an agent).
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public void Start(IMonoAgent agent, IActionData data) => this.Start(agent, (TActionData) data);

/// <summary>
/// Called when the action is started (when it is assigned to an agent).
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public virtual void Start(IMonoAgent agent, TActionData data) { }

/// <summary>
/// Determines whether the action is enabled. This is used by the planner.
/// </summary>
/// <param name="agent">The action receiver.</param>
/// <returns>True if the action is enabled, otherwise false.</returns>
public bool IsEnabled(IActionReceiver agent)
{
return this.IsEnabled(agent, agent.Injector);
}

public void Enable()
{
this.disabler = null;
}

public void Disable(IActionDisabler disabler)
{
this.disabler = disabler;
}

/// <summary>
/// Determines whether the action is enabled. This is used by the planner.
/// </summary>
/// <param name="receiver">The action receiver.</param>
/// <param name="references">The component references.</param>
/// <returns>True if the action is enabled, otherwise false.</returns>
public virtual bool IsEnabled(IActionReceiver receiver, IComponentReference references)
{
if (this.disabler == null)
Expand All @@ -56,30 +81,97 @@ public virtual bool IsEnabled(IActionReceiver receiver, IComponentReference refe
return true;
}

/// <summary>
/// Enables the action.
/// </summary>
public void Enable()
{
this.disabler = null;
}

/// <summary>
/// Disables the action.
/// </summary>
/// <param name="disabler">The action disabler.</param>
public void Disable(IActionDisabler disabler)
{
this.disabler = disabler;
}

/// <summary>
/// Called once before performing the action. Don't override this method, override the other BeforePerform method
/// instead.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public void BeforePerform(IMonoAgent agent, IActionData data) => this.BeforePerform(agent, (TActionData) data);

/// <summary>
/// Called once before performing the action. Override this method to implement custom logic.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public virtual void BeforePerform(IMonoAgent agent, TActionData data) { }

/// <summary>
/// Performs the action. Don't override this method, override the other Perform method instead.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
/// <param name="context">The action context.</param>
/// <returns>The action run state.</returns>
public IActionRunState Perform(IMonoAgent agent, IActionData data, IActionContext context) => this.Perform(agent, (TActionData) data, context);

/// <summary>
/// Performs the action with the specified action data. Use this method to implement custom logic.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
/// <param name="context">The action context.</param>
/// <returns>The action run state.</returns>
public abstract IActionRunState Perform(IMonoAgent agent, TActionData data, IActionContext context);

/// <summary>
/// Called when the action ends. This is called after the action is completed or stopped.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public virtual void End(IMonoAgent agent, TActionData data) { }

/// <summary>
/// Called when the action is stopped. Don't override this method, override the other Stop method instead.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public void Stop(IMonoAgent agent, IActionData data)
{
this.Stop(agent, (TActionData) data);
this.End(agent, (TActionData) data);
}

/// <summary>
/// Called when the action is stopped. Use this method to implement custom logic.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public virtual void Stop(IMonoAgent agent, TActionData data) { }

/// <summary>
/// Called when the action is completed. Don't override this method, override the other Complete method instead.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public void Complete(IMonoAgent agent, IActionData data)
{
this.Complete(agent, (TActionData) data);
this.End(agent, (TActionData) data);
}

/// <summary>
/// Called when the action is completed. Use this method to implement custom logic.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="data">The action data.</param>
public virtual void Complete(IMonoAgent agent, TActionData data) { }
}
}
20 changes: 20 additions & 0 deletions Package/Runtime/CrashKonijn.Agent.Runtime/AgentBehaviour.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,9 @@ private void Update()
this.Run();
}

/// <summary>
/// Runs the current action. This is called in the Update method.
/// </summary>
public void Run()
{
if (this.ActionState.Action == null)
Expand Down Expand Up @@ -165,6 +168,12 @@ private bool IsInRange()
return this.ActionState.Action.IsInRange(this, distance, this.ActionState.Data, this.Injector);
}

/// <summary>
/// Sets the action for the agent. This is mostly used by the action provider.
/// </summary>
/// <param name="actionProvider">The action provider.</param>
/// <param name="action">The action to set.</param>
/// <param name="target">The target of the action.</param>
public void SetAction(IActionProvider actionProvider, IAction action, ITarget target)
{
this.ActionProvider = actionProvider;
Expand All @@ -188,6 +197,10 @@ public void SetAction(IActionProvider actionProvider, IAction action, ITarget ta
this.Events.ActionStart(action);
}

/// <summary>
/// Stops the current action.
/// </summary>
/// <param name="resolveAction">Whether to resolve for a new action after stopping.</param>
public void StopAction(bool resolveAction = true)
{
var action = this.ActionState.Action;
Expand All @@ -201,6 +214,10 @@ public void StopAction(bool resolveAction = true)
this.ResolveAction();
}

/// <summary>
/// Completes the current action.
/// </summary>
/// <param name="resolveAction">Whether to resolve for a new action after completing.</param>
public void CompleteAction(bool resolveAction = true)
{
var action = this.ActionState.Action;
Expand All @@ -214,6 +231,9 @@ public void CompleteAction(bool resolveAction = true)
this.ResolveAction();
}

/// <summary>
/// Will trigger try and resolve a new action from the action provider.
/// </summary>
public void ResolveAction()
{
if (this.ActionProvider == null)
Expand Down
48 changes: 48 additions & 0 deletions Package/Runtime/CrashKonijn.Goap.Runtime/Behaviours/GoapActionBase.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ public abstract class GoapActionBase<TActionData, TActionProperties> : AgentActi

public override TActionProperties Properties => this.Config.Properties as TActionProperties;

/// <summary>
/// Sets the configuration for the action.
/// </summary>
/// <param name="config">The action configuration.</param>
public void SetConfig(IActionConfig config)
{
this.Config = config;
Expand All @@ -33,26 +37,57 @@ public virtual float GetCost(IActionReceiver agent, IComponentReference referenc
return this.Config.BaseCost;
}

/// <summary>
/// Returns the cost of the action.
/// </summary>
/// <param name="agent">The action receiver.</param>
/// <param name="references">The component references.</param>
/// <param name="target">The target of the action.</param>
/// <returns>The cost of the action.</returns>
public virtual float GetCost(IActionReceiver agent, IComponentReference references, ITarget target)
{
return this.Config.BaseCost;
}

/// <summary>
/// Gets the move mode for the action.
/// </summary>
/// <param name="agent">The agent.</param>
/// <returns>The move mode for the action.</returns>
public ActionMoveMode GetMoveMode(IMonoAgent agent)
{
return this.Config.MoveMode;
}

/// <summary>
/// Gets the stopping distance for the action.
/// </summary>
/// <returns>The stopping distance for the action.</returns>
public virtual float GetStoppingDistance()
{
return this.Config.StoppingDistance;
}

/// <summary>
/// Determines whether the agent is in range for the action.
/// </summary>
/// <param name="agent">The agent.</param>
/// <param name="distance">The distance to the target.</param>
/// <param name="data">The action data.</param>
/// <param name="references">The component references.</param>
/// <returns>True if the agent is in range, otherwise false.</returns>
public virtual bool IsInRange(IMonoAgent agent, float distance, IActionData data, IComponentReference references)
{
return distance <= this.GetStoppingDistance();
}

/// <summary>
/// Determines whether the action is valid. Don't override this method, use IsValid(IActionReceiver agent, TActionData
/// data) instead.
/// </summary>
/// <param name="agent">The action receiver.</param>
/// <param name="data">The action data.</param>
/// <returns>True if the action is valid, otherwise false.</returns>
public bool IsValid(IActionReceiver agent, IActionData data)
{
if (agent.ActionProvider is not GoapActionProvider goapAgent)
Expand Down Expand Up @@ -82,11 +117,24 @@ public bool IsValid(IActionReceiver agent, IActionData data)
return this.IsValid(agent, (TActionData) data);
}

/// <summary>
/// Determines whether the action is valid with the specified action data. This is the method you should overwrite (in
/// most instances).
/// </summary>
/// <param name="agent">The action receiver.</param>
/// <param name="data">The action data.</param>
/// <returns>True if the action is valid, otherwise false.</returns>
public virtual bool IsValid(IActionReceiver agent, TActionData data)
{
return true;
}

/// <summary>
/// Determines whether the action is executable.
/// </summary>
/// <param name="agent">The action receiver.</param>
/// <param name="conditionsMet">Whether the conditions are met.</param>
/// <returns>True if the action is executable, otherwise false.</returns>
public bool IsExecutable(IActionReceiver agent, bool conditionsMet)
{
var goapAgent = agent.Injector.GetCachedComponent<GoapActionProvider>();
Expand Down
Loading

0 comments on commit 6204afc

Please sign in to comment.