Below is a summary of the changes in progress. (The current git MR is here: https://git.net-core.org/tome/t-engine4 ... quests/463 )
There's a lot of material here, but everything works pretty much the same way it always has (or was intended to).
The best way to digest this is probably to first skim over the changes summary below. (Most talent developers will not need to be very familiar with the more technical changes.)
Then, to understand how the new tactical AI works, review the following posts, containing the lua code documentation covering the tactical AI and tactical tables, together, which contain a number of examples.
Testing Instructions:
This development contains some testing code and is intended to be run in ToME's development mode. It contains the following soft switches which can be changed “on the fly” in the lua console as required:
config.settings.ai_transition:
Set true to automatically call the new talented and tactical AIs in place of their older (but updated) counterparts. This should be set true for the current testing, but can be turned off to (mostly) revert to old AI behavior.
config.settings.tactical_cache_test (Performance penalty):
Set true to force cache testing of new tactical tables. Should not be needed at this point.
config.settings.log_detail_ai (Performance penalty):
Set from 0 to 4 to control the level of detail output to the log file by various AIs and associated functions. This should probably be set to at least level 1 during testing to provide general information on what the AI is doing. Level 4 is VERY verbose (but very useful for debugging tactical tables, etc.)
The normal operating mode will be with config.settings{ai_transition=true, tactical_cache_test=false, log_detail_ai=0}.
The main things to look out for when testing are:
1) Lua errors (obviously)
2) Any talents that completely confound the AI (so that it keeps trying and failing to use it over and over, for example)
3) Any situations where the new tactical AI does something obviously stupid (an action that could NEVER be the right one)
Comments are welcome!
SUMMARY OF CHANGES:
Code: Select all
This update has 3 main parts:
A) Upgrading AI primitives (“infrastructure”) in the engine to make designing new and more capable AIs easier.
B) Rewriting the Talented and Tactical AIs, plus adding some supporting AIs, so that NPCs in ToME using them behave more intelligently.
C) Correcting and updating tactical tables and associated code for a number of (but not all) talents that are currently not being used effectively by NPCs.
HIGHLIGHTS:
Major rewrite of many AI definitions and functions, including new functions to make writing new AIs simpler.
Completely new talented and tactical AIs (for ToME) that allow NPCs to act without contact with the player, actively manage all standard resources, and more consistently comply with their AI specifications. This includes provisions for all NPCs to avoid drowning/grid damage, better coordinate movement and talent use, and invoke other AIs.
NPCs can both activate and deactivate all sustain talents intelligently (particularly for the tactical AI) with or without player contact, according to the tactical situation.
The new AIs are designed to work concurrently with their existing counterparts to allow for them to be phased in.
Main Game Play Effects (for NPCs using the new AIs):
NPCs do not require contact with the player to act.
NPCs will actively manage all standard resources, including their health.
NPCs can both activate and deactivate sustained talents as appropriate.
NPCs will move away from harmful (damaging, suffocating) terrain, and will do a better job at maintaining appropriate distance from the player while in combat (new tactical AI).
If using a talent fails, the NPC will immediately attempt to use another (next best for the tactical AI) talent.
GAME LOG DETAIL CONTROL:
The amount of detail printed in the game log by most engine/ToME ai functions can be controlled by setting the variable:
config.settings.log_level_ai = X
Where X is a number from 0 (no extra output) to 4 (very verbose output) specifiying how much detail to output to the game log.
NEW/UPDATED AI’s included:
“dumb_talented” (engine) – updated to add support for t.onAIGetTarget.
“improved_talented” (engine) - Simplified version of “dumb_talented” using the new talent filter system. Designed as a drop-in replacement for the dumb_talented AI using the new AI functions.
“improved_talented_simple” (ToME) – designed as an overload for the dumb_talented_simple AI
“improved_tactical” (ToME) – designed as a drop-in replacement for the tactical AI (details below)
“maintenance” (ToME) – manages health and resources, triggering other appropriate talents and AIs, (mostly for simple AIs out of combat)
“move_safe_grid” (ToME) – moves from harmful to safe terrain
“flee_dmap_keep_los” (ToME) – migrated from ai.tactical.lua, flees from current target while maintaining LOS to it
“target_simple” (engine) – will only maintain targeting on hostiles
"target_simple" (ToME) – has an increased chance to clear friendly targets, always clears self
“tactical” --The existing tactical AI has been partially updated to be compatible with most of the new tactical table functionality, with minimal changes. (It lacks most of the additional features of the new tactical AI in order to work as before as much as possible.) Better log file output.
NEW TACTICAL AI:
This is an almost complete rewrite of the current tactical AI that is compatible with existing NPC specifications and data.
Interprets existing tactical tables as before, but supports additional information allowed in the new tactical table format.
The tactical AI weighs all tactical table parameters (not just the best one) when evaluating talents, making it much better at picking the correct talent at the correct time.
Full support for both positive and negative tactical values – this allows the AI to intelligently turn on and off sustained talents, including those with sustain_slots or that drain resources. (For example, an NPC can switch between hymns or vile poison enhancements as the tactical situation develops.)
Automatically manages all standard resources, with support for resource-specific wants.
Does a better job at maintaining an advantageous distance to the target.
(Un-tested) The tactical AI should run significantly faster than before for most NPCs. The new AI is more efficient when evaluating and performing actions, but does more.
Extensive documentation for the changes, including detailed instructions/tutorial for how to construct tactical tables.
Defined key parameters for supported TACTICs in mod.class.interface.ActorAI. This allows new TACTICs to be added easily, including by addons.
EXTENDED TACTICAL TABLE functionality:
Added detailed documentation on how to construct tactical tables and how they are interpreted by the (new) tactical AI.
No changes are required to current tactical tables for them to be interpreted by the new AI functions the same way they were interpreted before. Note, however, that many of the existing tactical tables have significant errors that prevent NPCs from using talents appropriately. (A number of these have been corrected as part of this development.)
Changes:
Tactical functions take the actor affected rather than the NPC's ai target as an argument in order to be consistent with the way DamageType and status resistances are interpreted.
There is an additional (lowest) level of table parsing for status immunities to allow both DamageType resistance and status effects to be accounted for.
For example, Apply Poison’s NATURE-based damage is added to the tactical table as:
tactical = { ATTACK = {NATURE = {poison = 2}}}
which takes both the target’s poison immunity and NATURE resistance into account.
A sub-table SELF = {…} can be specified for tactics that apply only to the talent user. This helps specify tactics for talents that have different effects on the user and on their target(s).
For example, the updated tactical table for lightning runes is now:
tactical = { ATTACK = { LIGHTNING = 1 }, SELF = {defend = 1} }
reflecting the fact that it provides defense to the user (but not the target).
When applying DamageTypes, source damage bonuses and target affinity are accounted for in addition to resistances and penetration.
Alternate tactical tables (t.tactical_imp) are included for some talents during the transitional period.)
AI talent use changes:
Completed support (This was only partially supported before.) for the talent field t.onAIGetTarget for all engine AIs and support functions. ActorAI:getTarget(typ).
Separated ai pre-use talent checks from actor:preUseTalent into new function (ActorAI:aiPreUseTalent) at the engine level. This is needed to allow sustains to be turned on and off properly (to allow ActorTalents:forceUseTalent to turn off sustains (with buff removal effects, for example), when the AI would otherwise NOT turn them off.
For ToME, this permits the function talent.on_pre_use_ai to control both activating and deactivating sustained talents.
SUMMARY of FUNCTIONS:
New Engine Functions:
ActorTalents:filterTalent(t, filter) - checks a talent against a filter
ActorAI:aiTalentTargets(t, aitarget, tg, all_targets, ax, ay) - Generate a list of target entities (Actors) a talent MAY affect if used (This provides engine support for the dummy projection performed in the current tactical AI.)
ActorAI:aiGetAvailableTalents(aitarget, t_filter, t_list) – generates a list of talents available for use
aiPreUseTalent(t, silent, fake) – (stub) determines if the AI should use a talent (separated from preUseTalent to allow sustains to be correctly turned on and off)
ActorAI:getTarget(typ) – supports talent.onAIGetTarget, talents automatically self-targeted, and supports the grid_params argument to locate grids if the targeting table requires it.
ActorAI:getTargetGrid(tg, params) – acquires grids via projection, choosing one to move to based on parameters in the targeting table -making targeting of movement talents for NPCs much simpler.
Updated Engine Functions:
ActorAI:setTarget will automatically check on_acquire_target and on_targeted functions when a new target is set.
ActorAI:runAI will return nil, generating a log message, rather than crashing with an undefined ai
New ToME functions:
ActorAI.aiParseTalent(t) – parses a talent definition, setting some variables for AI use – making talent analysis faster for the AI
ActorAI.AI_InitializeData() – parses all talent definitions, initializes resource tactics, and logs a summary of all tactics detected in talent definitions
ActorAI:aiPreUseTalent(t, silent, fake) – Determines if the AI should use the talent. Checks t.on_pre_use_ai (applies to both activation and deactivation of sustained talents) and caches its results in the self.turn_procs table.
ActorAI:aiCheckSustainedTalent(t) – determines if a sustained talent should be toggled (Allows simple AIs to turn on and off sustained talents correctly. This is primarily concerned with resource drains.)
ActorAI:aiGetResourceTalent(res_def, t_filter, t_list) – finds a talent to replenish a resource
ActorAI:aiResourceAction(res_def, t_filter, t_list) – finds an action (talent or AI) to replenish a resource
ActorAI:aiHealingAction(aitarget, filter, t_list) – finds an action (talent or AI) to heal self
ActorAI:aiGetGridDamage(gx, gy) – computes expected grid damage and air loss for the actor. Updated some grid definitions to allow this function to detect the damage.
ActorAI:aiGridHazard(gx, gy, dam_wt, air_wt) – rates the overall hazard level for grid. May be overloaded for some Actors to allow for special map navigation.
ActorAI:aiFindSafeGrid(radius, want, dist_weight, ignore_los, grid_val) – finds the a nearby grid to escape grid damage and suffocation.
ActorAI:aiCanFleeDmapKeepLos() – moved from tactical ai for general use
ActorAI:aiTacticEffectValues(targets, effect_type, effect_wt, talent, selffire, friendlyfire) – computes the tactical value of specific tactic weight argument vs a list of actors – for concurrent compatibility with the existing tactical AI
ActorAI:aiTalentTactics(t, aitarget, targets, tactic, tg, wt_mod) – fully resolves the tactical table for a talent (including finding targets as needed) – used by the new tactical AI to evaluate talents and by some simple AIs to use tactical tables when choosing talents
Combat:combatGetAffinity(type) – returns damage affinity
Talents.aiLowerTacticals(tactical) – function to convert TACTIC labels to lower case in tactical tables
Player:restStep() - overload of engine.interface.PlayerRest:restStep() that triggers the new callback "callbackOnWait"
Updated ToME Functions:
NPC:act() – NPCs will perform resting activity if they take no other action during a turn. This uses the new callback "callbackOnWait"
NPC:getTarget(typ) – simplified to reflect the changes to ActorAI:getTarget
NPC:seen_by(who) – NPCs will not pass friendly targets to each other unless ai_state._pass_friendly_target is set
NPC:aiCanPass(x, y) – removed (uses engine version), shove pressure folded into ActorAI:moveDirection
MISC RELATED CHANGES:
The level of log file detail output by various AI functions can be specified by setting config.settings.log_detail_ai to a value from 0 (minimal output) to 4 (very verbose output).
Engine:
ActorAI:aiSeeTargetPos(target) – added extra checks to the estimated location to exclude it if another actor is seen there and that the target can actually move there – this significantly reduces the chance to target friends or self
ActorLife:takeHit(value, src, death_note) – death message is not displayed if src is undefined
utils: table.to_strings = function(src, fmt) – converts a table to table of formatted strings, very useful for various debugging outputs
utils: table.equivalence(t1, t2, recurse) – checks if two tables are equivalent, i.e. they are identical or contain the same values assigned to the same keys, can recursively track all of the keys to the first difference found
ToME:
ActorAI:moveDirection(x, y, force) – moved from NPC.lua, incorporates shove algorithm code, fixing a bug that causes shove pressure to almost always fail
Actor:preUseTalent(ab, silent, fake) – updates any missed AI parsing of talents as needed when tested
Resource definitions updated with new AI parameters (equilibrium, paradox, psi, air)
Actor:regenLife(fake) --- returns the life, psi regenerated, updated to take a fake parameter to calculate the amount of life and psi that will be regenerated without applying the values. Eliminated the resting hack for Solipsism: life regeneration is only reduced by the amount of psi regeneration that can be used, none is diverted once psi is replenished.
Updated Actor status immunity functions:
Actor:canBe(what, eid) -- Rewritten to reference a table of status type labels that makes defining new status types (addons) much simpler. Can take an argument for the effect id being applied, which forces checking of general status immunities (negative_status_immune is always checked), and can be used to force checking of status types contained in the effect subtype table. (i. e. self:canBe(nil, “EFF_DAZED”) will check stun_immune.)
Now returns the random result, percent chance to be affected. AIs have been updated to use the chance rather than an individual result, so that tactical weights are consistent across multiple calls.
Actor.newStatusType(what, method) – used to define a new status type. e.g. Actor.newStatusType(“annoy”, true) causes self:canBe(“annoy”) to check the self.annoy_immune field.
Actor:canSeeNoCache(actor, def, def_pct) – updated to always return the correct chance to see the target (regardless of success).
Actor:getTalentSpeed(t) – looks for a t.getEnergy function that returns the amount of game energy needed to use the talent (on the basis of 1 = 100% of normal, stacks with talent type speed).
Combat:combatGetResist(type) -- results are properly bounded between -100% and + 100%.
resolvers.talented_ai_tactic updated to better balance ai_tactic for more tactical flexibility. Fixed an upvalue(!) bug that could cause failure when placing randbosses generated from an earlier save file.
Some ToME TALENT CHANGES:
Note many talent defintions have incorrect tactical tables. A number of the most complex (for the AI) talents have been updates with new tactical information so that NPCs can use them.
Talents can have .ai_level field to specify the (raw) talent level to use for AI purposes (For prodigies and other 1 point talents).
Summoning Talents – Defined new functions in talents.lua (available to all talent definitions) supporting significant tactical changes which allow NPCs to better pick appropriate summoning talents and place summons.
Poisons – use the updated AI changes to allow NPCs to switch between poison effects in combat.
Psionic Projection talents – tactical tables for discharging the talent now take into account the loss of the aura effect
Meditation – enabled for NPCs who will actively toggle this talent to manage their equilibrium.
Spacetime Tuning – enabled for NPCs which will automatically set an appropriate preferred paradox value.
Suncloak – enabled for NPCs (requires LOS to target)
True Grit – enabled for NPCs (since they can now manage their resources)
Nature Touch – NPCs will search for a target (favoring self) that needs healing
Some ToDo Items:
Update the way the Actor.ai_tactics table is used to allow for sustains/status effects to modify tactical priorities in the tactical AI. So wild speed could reduce but not eliminate talent use, Unstoppable would prevent running away while active, etc...
Finish enabling summoning talents for NPCs : Detonate, Rage, Phase Summon
Wards: NPCs must match wards to target attack types
Add a method in data.damage_types.lua to translate compound DamageTypes into the base types (that have resistances)
)