Better ParentTask documentation?

[timconkling]

Hi there,

I'm finding ParentTask to be tricky to understand - specifically, the circumstances in which certain functions are called.

• What's the difference between "Decorate(TaskStatus)", "OverrideStatus(TaskStatus)" and "OverrideStatus()"? They all seem to be capable of modifying the result of a child task.
• What's the difference between OnChildStarted() and OnChildStarted(childIndex)? Is it just that the latter will only be called for tasks with parallel tasks? Why is the distinction useful (that is, why not pass childIndex in both circumstances)?
• Similarly, what's the difference between the two forms of OnChildExecuted()?
• Where does the TaskStatus passed to OnReevaluationEnded() come from?
• Is it true that OnChildExecuted() is only called when a child task has ended (or become disabled)? The name is a bit confusing, especially since "CanExecute" is called to determine - I believe! - whether a child can _start_ running.
• What are the circumstances that a ParentTask's Update function will be called? It seems that the parent task needs to return true from CanReevaluate, and also not be marked as Instant?
• What does the result of a ParentTask's OnUpdate mean? (It seems like returning Failure from a ParentTask's Update is meaningful, but all the other task statuses essentially mean the same thing?)
• OnReevaluationStarted/Ended say that they "notify the parent task that a reevaluation has been requested". Is this called when a reevaluation is requested by an immediate child? Any descendent?

I'd _love_ if each of these functions had detailed docs saying "this will be called when X happens, if Y is true", or whatever. (I'd be happy to help in this effort as well, if it makes a difference! I just need to get un-confused on some of these details first.)

Thanks!
Tim

 

[Justin]

I definitely agree that the parent task documentation can be improved. I think most people just start with an existing parent task and modify from there rather than starting from scratch but I'll try to get something together that answers your questions. If you also search for the particular method within the BehaviorManager and set breakpoints it'll also show exactly when that method is called.

 

[timconkling]

Confusingly, OnReevaluationStarted/OnReevaluationEnded are only ever called on Composite tasks, despite being defined on ParentTask. (These functions can simply be moved to Composite without breaking any code, aside from an easily-changed cast in BehaviorManager.ReevaluateParentTasks, to avoid confusion).

It was also unclear to me (until I stepped through the code) that CanReevaluate() is called only immediately after Task.Start(); it's essentially an immutable property of a running task, rather than something called every tick, and OnReevaluationStarted is the place to short-circuit that re-evaluation.

It also _seems_ like - based on the framework's existing tasks - OnReevaluationEnded() is the "safe" place to interrupt a child task via BehaviorManager.instance.Interrupt. Is that the case, or is it ok to call this from other places as well?

 

[Justin]

Confusingly, OnReevaluationStarted/OnReevaluationEnded are only ever called on Composite tasks, despite being defined on ParentTask. (These functions can simply be moved to Composite without breaking any code, aside from an easily-changed cast in BehaviorManager.ReevaluateParentTasks, to avoid confusion).

That's a good point, and I'll move those methods. OnReevaluation* relates to conditional aborts so they will only ever be called on the composite task.

It also _seems_ like - based on the framework's existing tasks - OnReevaluationEnded() is the "safe" place to interrupt a child task via BehaviorManager.instance.Interrupt. Is that the case, or is it ok to call this from other places as well?

That's one location, or you can do the interruption within OnUpdate such as the interrupt task does.