Collectible Card Game Headquarters

Can someone give me a brief description on what the core AI procedures are? If I want to make more cards playable, I'll need to know how the system works and it saves time if I don't have to browse through a hundred files to find it.

Specifically, I'd like to know these

-The procedure the AI uses to calculate the play priority of a spell or ability. The priority the spell itself has, ignoring costs and timing.
-The procedure the AI uses to calculate the timing priority of the same - the one that evaluates if it's the correct time to activate the thing, or it is better to do later.
-The main procedure that decides what to play based on input from the above two, costs, and available resources.
-The procedure the AI uses to decide what to discard from hand
-The procedure the AI uses to decide what to search for in the deck
-It seems the whole thing is operating on the script containing the rules the AI should use specified as $AILogic? Can I have a list of the existing logics and what they are used for and the correct syntax?
An example, if I want to specify "play this during X phase, or in response to the permanent containing the ability being targeted by an enemy spell, but only if above Y life. It's a spell that kills a target permanent, pick the one with the highest current in-play value. Do not use if a spell/ability with the same name is already on the stack under the AI's control.", what do I write there?
I did find https://www.slightlymagic.net/wiki/Forge_API but it tells nothing about AI stuff.
-How do you specify a card is/isn't AI playable? (Assuming I do manage to teach it to use something it couldn't use before, I will need to know this.)

It would be a good start for you to explore the AI code starting with AiController and PlayerControllerAi, which contain the basic "selection" functions that you're referring to (e.g. selecting a SpellAbility to play from what the AI has). Tbh I never fully understood the difference between AiController and PlayerControllerAi, as well as why there was a need for there to be two of them, but I do remember that there was a reason for that.

As for the specific effects, the AI has a mapping between effects and AI classes which you can find in SpellApiToAi. Depending on the API of the effect (e.g. it's a Draw effect, a Discard effect, a Manifest effect, or something else), a particular set of AI routines is chosen (e.g. for a Draw effect, the code in the class DrawAi is executed). Each class has several methods which will help the AI determine if it can play the effect or not, and if it can, then what it should target, choose, etc. The effect AI classes inherit from SpellAbilityAi, which contains the default implementations of all those methods. If a certain method is not overridden in the effect AI class, the default implementation will be called.

There is the "global" effect logic, which applies to all cards with the same effect (e.g. the "default" Draw AI logic, which will be called for all the cards with the Draw effect if no special logic is specified), and there is the more "specific" logic, which is usually specified via AILogic$ <name_of_the_logic>. Those logic names are typically unique to the API and can be figured out from reading the appropriate AI class (e.g. DrawAi for the "Draw" type effect AI). They are mostly consolidated in the method checkAiLogic, if possible, but some are currently scattered elsewhere (especially in the "older style" implementation of effect AI classes which use canPlayAI as a function to determine if the AI can play the effect, and do not contain checkAiLogic at all). There is no comprehensive list of AI logic types, as far as I know, though certain common logics will appear in many, and some even in most of the APIs (such as AILogic$ Never, which makes the AI never use the ability).

Some cards are unique enough to have their own logic (e.g. Necropotence), and then such a logic is at least temporarily relegated to SpecialCardAi until it can be generalized. SpecialCardAi contains all the classes used for unique card logic. Such a logic is generally also deduced from the AILogic parameter, but some may be determined from the name of the original source card (though AILogic is preferred). SpecialCardAi class methods are called from effect AI classes.

Also, there are separate routines for combat (e.g. AiAttackController and AiBlockController define the logic for attacking and blocking), and a number of utility functions that are used from various points in the AI code are available as static methods from ComputerUtil****.

Whether a card is AI-playable or not is determined by the presence of the SVar "RemAIDeck", which generally contains the value "True". So, AI-unplayable cards will contain the following line in their script:
SVar:RemAIDeck:True

This is my understanding of the basics, though I'm sure there is much more to it than that.
Good luck!

- Agetian

Thanks!

I'll dig deeper into this once the quest mode stuff is all done - meanwhile any more information is welcome. 5 smaller patches wait for integration and we discussed at least a few more that could be made optional after that.
After those are done, next up is improving AI - both for cards already in decks or cards I encounter often in drafts, and also for cards needed for new decks/worlds. This is going to be an "endless" work, unlike adding quest options, which is why I want to get those done first
...took me a good two years to make a decent AI for Master of Magic and that game has 214 spells total, with far less interaction between things. Though here I'll have source code instead of a hex editor, that might speed things up a little.