Class BotBrain<TState, TBot, TAction>

A basic bot brain.

Inheritance

object

UrgeBase<TState, TBot, TAction>

UrgeList<TState, TBot, TAction>

BotBrain<TState, TBot, TAction>

OvermindBrain

TestBotBrain

TestBotBrain

FakeBrain

Implements

IBotBrain<TState, TBot, TAction>

IUrgeList<TState, TBot, TAction>

IUrge<TState, TBot, TAction>

IBotBrain

IBasedOn<IBotBrain>

IBasedOn

IEquatable<IBotBrain>

IUrgeList

IUrge

IEquatable<IUrge>

IHasParameters

Inherited Members

UrgeList<TState, TBot, TAction>.Urges

UrgeList<TState, TBot, TAction>.ExclusiveUrges

UrgeList<TState, TBot, TAction>.ParallelUrges

UrgeList<TState, TBot, TAction>.Equals(IUrge)

UrgeList<TState, TBot, TAction>.Run(TState, TBot)

UrgeList<TState, TBot, TAction>.AddUrge(IUrge)

UrgeList<TState, TBot, TAction>.RemoveUrge(IUrge)

UrgeList<TState, TBot, TAction>.ExclusiveUrgesFor(TBot, TState)

UrgeList<TState, TBot, TAction>.ParallelUrgesFor(TBot, TState)

UrgeList<TState, TBot, TAction>.RunUrges(TState, TBot)

UrgeList<TState, TBot, TAction>.RunUrge(TState, TBot, IUrge<TState, TBot, TAction>)

UrgeList<TState, TBot, TAction>.HandleUrgeException(IUrge<TState, TBot, TAction>, TBot, Exception)

UrgeBase<TState, TBot, TAction>.NoUrgeName

UrgeBase<TState, TBot, TAction>.Logger

UrgeBase<TState, TBot, TAction>.Name

UrgeBase<TState, TBot, TAction>.Type

UrgeBase<TState, TBot, TAction>.IsExclusive

UrgeBase<TState, TBot, TAction>.ToString()

UrgeBase<TState, TBot, TAction>.Equals(IUrge)

UrgeBase<TState, TBot, TAction>.Equals(object)

UrgeBase<TState, TBot, TAction>.GetHashCode()

UrgeBase<TState, TBot, TAction>.Run(TState, TBot)

UrgeBase<TState, TBot, TAction>.GetParameter<T>(TBot, string)

UrgeBase<TState, TBot, TAction>.GetParameter<T>(TBot, IEnumerable<string>)

UrgeBase<TState, TBot, TAction>.TryGetParameter<T>(TBot, IEnumerable<string>, out T)

UrgeBase<TState, TBot, TAction>.TryGetParameter<T>(TBot, string, out T)

UrgeBase<TState, TBot, TAction>.GetParameterNames(string)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Microsoft.XboxStudios.BotBrain

Assembly: BotBrain.Core.dll

Syntax

public class BotBrain<TState, TBot, TAction> : UrgeList<TState, TBot, TAction>, IBotBrain<TState, TBot, TAction>, IUrgeList<TState, TBot, TAction>, IUrge<TState, TBot, TAction>, IBotBrain, IBasedOn<IBotBrain>, IBasedOn, IEquatable<IBotBrain?>, IUrgeList, IUrge, IEquatable<IUrge?>, IHasParameters where TBot : IAutomatedBot<TAction>

Type Parameters

Name	Description
TState	A title-specific state object.
TBot	A title-specific bot object that implements IAutomatedBot<TAction>.
TAction	The title-specific bot action that implements IEquatable<T>.

Remarks

Initializes a new instance of the BotBrain<TState, TBot, TAction> class.

Constructors

BotBrain(ILogger<BotBrain<TState, TBot, TAction>>)

A basic bot brain.

Declaration

public BotBrain(ILogger<BotBrain<TState, TBot, TAction>> logger)

Parameters

Type	Name	Description
ILogger<BotBrain<TState, TBot, TAction>>	logger	The logger to use.

Remarks

Initializes a new instance of the BotBrain<TState, TBot, TAction> class.

Properties

BasedOn

Gets the name of the template this object is based on.

Declaration

[DataMember]
public string? BasedOn { get; set; }

Property Value

Type	Description
string

BasedOnObject

Gets or sets the template this object is based on.

Declaration

public IBotBrain? BasedOnObject { get; set; }

Property Value

Type	Description
IBotBrain

Bots

Gets the collection of bots controlled by the brain.

Declaration

[IgnoreDataMember]
public IReadOnlyCollection<TBot> Bots { get; }

Property Value

Type	Description
IReadOnlyCollection<TBot>

Considerations

Gets the considerations for the brain.

Declaration

[JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
public ICollection<IConsideration<TState, TBot, TAction>> Considerations { get; }

Property Value

Type	Description
ICollection<IConsideration<TState, TBot, TAction>>

Parameters

Gets or sets the parameters for the brain.

Declaration

[JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
public IParameterManager Parameters { get; set; }

Property Value

Type	Description
IParameterManager

Methods

AddConsideration(IConsideration)

Adds a consideration to the list.

Declaration

public void AddConsideration(IConsideration consideration)

Parameters

Type	Name	Description
IConsideration	consideration	The consideration.

ApplyAction(TBot, TAction)

Applies an action to the bot.

Declaration

protected virtual Task<bool> ApplyAction(TBot bot, TAction action)

Parameters

Type	Name	Description
TBot	bot	The bot.
TAction	action	The action.

Returns

Type	Description
Task<bool>	True if the bot's action changed.

AreEqual(TAction, TAction)

Determines if the two actions are equal.

Declaration

protected bool AreEqual(TAction left, TAction right)

Parameters

Type	Name	Description
TAction	left	The first action to compare.
TAction	right	The second action to compare.

Returns

Type	Description
bool	True if the actions are equal.

Choose(TState, TBot, IReadOnlyList<BotBrainUrgeResult<TState, TBot, TAction>>)

Chooses the best among a weighted set of urge results.

Declaration

protected virtual UrgeResult<TState, TBot, TAction>? Choose(TState state, TBot bot, IReadOnlyList<BotBrainUrgeResult<TState, TBot, TAction>> recommendations)

Parameters

Type	Name	Description
TState	state	The game state.
TBot	bot	The bot.
IReadOnlyList<BotBrainUrgeResult<TState, TBot, TAction>>	recommendations	The recommendations to choose between.

Returns

Type	Description
UrgeResult<TState, TBot, TAction>?	The selected urge result.

CreateBotData(TBot, BrainBotData<TState, TBot, TAction>)

Adds the bot's brain data to collection of the running bots.

Declaration

protected void CreateBotData(TBot bot, BrainBotData<TState, TBot, TAction> data)

Parameters

Type	Name	Description
TBot	bot	The bot.
BrainBotData<TState, TBot, TAction>	data	The brain data.

CreateBotData(TBot, IReadOnlyCollection<TState>, CancellationToken)

Creates the bot's brain data and adds it to collection of the running bots.

Declaration

protected virtual void CreateBotData(TBot bot, IReadOnlyCollection<TState> states, CancellationToken token)

Parameters

Type	Name	Description
TBot	bot	The bot.
IReadOnlyCollection<TState>	states	The states to associate with the bot.
CancellationToken	token	The token for canceling actions.

Remarks

If the bot was already running, the previous cancellation token and states will be merged but no other data is retained.

Equals(IBotBrain?)

Determines whether the specified brain is equal to this one.

Declaration

public virtual bool Equals(IBotBrain? other)

Parameters

Type	Name	Description
IBotBrain	other	The brain to compare to.

Returns

Type	Description
bool	True if the brains are equal.

ExclusiveUrgesFor(TBot, TState)

Gets the urges which are exclusive for the given bot.

Declaration

protected override IEnumerable<IUrge<TState, TBot, TAction>> ExclusiveUrgesFor(TBot bot, TState state)

Parameters

Type	Name	Description
TBot	bot	The bot.
TState	state	The game state.

Returns

Type	Description
IEnumerable<IUrge<TState, TBot, TAction>>	An enumerable of urges.

Overrides

UrgeList<TState, TBot, TAction>.ExclusiveUrgesFor(TBot, TState)

ExecuteUpdate(TState, TBot)

Updates the state and current action of the given bot.

Declaration

protected virtual Task<bool> ExecuteUpdate(TState state, TBot bot)

Parameters

Type	Name	Description
TState	state	The game state.
TBot	bot	The bot to update.

Returns

Type	Description
Task<bool>	A task that returns true if the bot action changed.

GetBotData(TBot)

Gets the bot data for the given bot.

Declaration

public BrainBotData<TState, TBot, TAction>? GetBotData(TBot bot)

Parameters

Type	Name	Description
TBot	bot	The bot.

Returns

Type	Description
BrainBotData<TState, TBot, TAction>	The bot data.

HandleConsiderationException(IConsideration<TState, TBot, TAction>, TBot, Exception)

Handles a consideration exception.

Declaration

protected virtual void HandleConsiderationException(IConsideration<TState, TBot, TAction> consideration, TBot bot, Exception e)

Parameters

Type	Name	Description
IConsideration<TState, TBot, TAction>	consideration	The consideration that threw the exception.
TBot	bot	The corresponding bot.
Exception	e	The exception.

ParallelUrgesFor(TBot, TState)

Gets the urges which are not exclusive for the given bot, and can be evaluated in parallel.

Declaration

protected override IEnumerable<IUrge<TState, TBot, TAction>> ParallelUrgesFor(TBot bot, TState state)

Parameters

Type	Name	Description
TBot	bot	The bot.
TState	state	The game state.

Returns

Type	Description
IEnumerable<IUrge<TState, TBot, TAction>>	An enumerable of urges.

Overrides

UrgeList<TState, TBot, TAction>.ParallelUrgesFor(TBot, TState)

PauseBot(TBot)

Pauses the bot.

Declaration

protected virtual Task PauseBot(TBot bot)

Parameters

Type	Name	Description
TBot	bot	The bot to pause.

Returns

Type	Description
Task	An async task that completes when the bot is stopped.

PostUpdateBot(TState, TBot, TAction, TAction)

Handles all post-update bot logic.

Declaration

protected virtual void PostUpdateBot(TState state, TBot bot, TAction previous, TAction next)

Parameters

Type	Name	Description
TState	state	The state.
TBot	bot	The bot.
TAction	previous	The previous action.
TAction	next	The next action.

PreUpdateBot(TState, TBot)

Handles all pre-update bot logic.

Declaration

protected virtual void PreUpdateBot(TState state, TBot bot)

Parameters

Type	Name	Description
TState	state	The state.
TBot	bot	The bot.

Rank(TState, TBot, IReadOnlyCollection<UrgeResult<TState, TBot, TAction>>)

Ranks each urge result by evaluating considerations into a weighted score and creating a BotBrainUrgeResult<TState, TBot, TAction>.

Declaration

protected virtual IEnumerable<BotBrainUrgeResult<TState, TBot, TAction>> Rank(TState state, TBot bot, IReadOnlyCollection<UrgeResult<TState, TBot, TAction>> results)

Parameters

Type	Name	Description
TState	state	The state.
TBot	bot	The bot being controlled.
IReadOnlyCollection<UrgeResult<TState, TBot, TAction>>	results	The urge results.

Returns

Type	Description
IEnumerable<BotBrainUrgeResult<TState, TBot, TAction>>	An enumerable of weighted bot brain results.

RemoveConsideration(IConsideration)

Removes a consideration from the list.

Declaration

public void RemoveConsideration(IConsideration consideration)

Parameters

Type	Name	Description
IConsideration	consideration	The consideration.

Run(TState, TBot)

Chooses an action and urgency of that action for the given bot and state.

Declaration

public override Task<IEnumerable<IRecommendedAction<TAction>>> Run(TState state, TBot bot)

Parameters

Type	Name	Description
TState	state	The game state.
TBot	bot	The bot to control.

Returns

Type	Description
Task<IEnumerable<IRecommendedAction<TAction>>>	An enumerable of weighted bot actions.

Overrides

UrgeList<TState, TBot, TAction>.Run(TState, TBot)

Start(TBot, IReadOnlyCollection<TState>, CancellationToken)

Starts controlling the bot.

Declaration

protected virtual void Start(TBot bot, IReadOnlyCollection<TState> states, CancellationToken token)

Parameters

Type	Name	Description
TBot	bot	The bot to control.
IReadOnlyCollection<TState>	states	The states used to update the bot.
CancellationToken	token	A cancellation token to end the automation.

Start(TBot, CancellationToken, params TState[])

Starts controlling the bot.

Declaration

public virtual void Start(TBot bot, CancellationToken token = default, params TState[] states)

Parameters

Type	Name	Description
TBot	bot	The bot to control.
CancellationToken	token	A cancellation token to end the automation.
TState[]	states	The states used to update the bot.

Stop(TBot)

Stops controlling the bot.

Declaration

public virtual Task Stop(TBot bot)

Parameters

Type	Name	Description
TBot	bot	The bot to stop controlling.

Returns

Type	Description
Task	A task that returns after stopping the bot.

TryUpdate(TState, TBot)

Attempts to update the bot's action based on the state.

Declaration

protected virtual Task<bool> TryUpdate(TState state, TBot bot)

Parameters

Type	Name	Description
TState	state	The state.
TBot	bot	The bot.

Returns

Type	Description
Task<bool>	True if the bot's action changed.

Update(object, IReadOnlyCollection<IAutomatedBot>?)

Updates the state and current action of the given bots.

Declaration

public Task Update(object state, IReadOnlyCollection<IAutomatedBot>? bots = null)

Parameters

Type	Name	Description
object	state	The game state.
IReadOnlyCollection<IAutomatedBot>	bots	The bots to update. If null, all controlled bots are updated.

Returns

Type	Description
Task	A task that returns after updating each bot.

Update(TState, IReadOnlyCollection<TBot>?)

Updates the state and current action of the given bots.

Declaration

public virtual Task Update(TState state, IReadOnlyCollection<TBot>? bots = null)

Parameters

Type	Name	Description
TState	state	The game state.
IReadOnlyCollection<TBot>	bots	The bots to update. If null, all controlled bots are updated.

Returns

Type	Description
Task	A task that returns after updating each bot.

Events

OnBotPaused

Occurs when the brain pauses a bot.

Declaration

public event EventHandler<TBot>? OnBotPaused

Event Type

Type	Description
EventHandler<TBot>

OnBotStopped

Occurs when the brain stops a bot.

Declaration

public event EventHandler<TBot>? OnBotStopped

Event Type

Type	Description
EventHandler<TBot>

Implements

IBotBrain<TState, TBot, TAction>

IUrgeList<TState, TBot, TAction>

IUrge<TState, TBot, TAction>

IBotBrain

IBasedOn<T>

IBasedOn

IEquatable<T>

IUrgeList

IUrge

IEquatable<T>

IHasParameters