Implementing new Ability Factories and Card Support Code

[Agetian]

As of right now, I've done all I could with the targeting overlay codebase and I can conclude that it's usable at its basic functional level at the moment (I'll return to it once I improve my Java2D skills), so I'm moving on to my next developer target - figuring out how the ability factories work and potentially implementing some new card-related code (most likely in the AF department) to support some of the legacy cards that are currently not yet supported.

This is a very difficult issue for me because, as I've said before, I'm not a great expert on rule interactions and I've never touched the ability factory code before.

As I was looking through the AFs that are getting refactored at the moment by Max Mtg, I've noticed several recurring methods that each ability factory has (or at least can have). I think I figured out what some of them do but the others remain a mystery for me. I'd be grateful if someone who is good with the AF code can clarify some key points of the ability factory implementation for me:

1) in forge.card.abilityfactory:
Am I correct that each new ability factory should now be registered in ApiType.java, in the ApiType enumeration? That, apparently, is where this code goes, but I'd like to make sure. Also, is anything else necessary to be done in the global Ability Factory code to add support for a new ability factory, or is registering it in ApiType enough?

2) in forge.card.abilityfactory.effects:
As far as I understand, the abilityfactory.effects package contains the implementation of the ability effects as such, regardless of how AI is able to interact with the ability etc. I believe that:
getStackDescription is used to build a string description of the ability as it appears in the stack window.
resolve is the implementation of the effect as such which defines what effect the ability has on the cards on the playfield (e.g. on its target etc.)

I noticed that some parameters are usually passed to various ability factory methods via a java.util.Map<String, String> - is there a list of possible parameters anywhere? Some of them have rather unintuitive names - some of them seem like they should make sense immediately, but after some thinking, for instance, I realize I have no idea what AllType or AllValid could be used for when passed to a resolve method of an AF. Also, where do the parameters come from? Are they defined in card scripts or something like that?

Also, I believe that the above-mentioned two methods (getStackDescription and resolve) are the only ones that are essential to be implemented for the AF effect, everything else that might be there are just support methods, right?

3) in forge.card.abilityfactory.ai:
There are several methods that need to be implemented here, some of which make sense to me and some of which are a mystery:
canPlayAI - used to test whether the AI can play the ability at the given moment and should return 'true' in situations when it can, right?
chkAIDrawback - no idea, honestly... I'd need some help on this one.
doTriggerAINoCost - I *think* this defines how the AI plays the effect (e.g. what it chooses as target etc.), but I'm not sure; moreover, the words "No Cost" in the method name baffle me, I'm not sure why it says "NoCost" and whether there's also a version "with cost".

What's even more puzzling is that chkAIDrawback sometimes just calls doTriggerAINoCost and doTriggerAINoCost sometimes just calls CanPlayAI, which is a bit confusing... not sure why that is.

Also, are there any other methods out there that I haven't yet noticed in the AI department and that may be implemented for the ability factory-related AI?

4) in ability factory code in general:
In parameter names and field names, I think "sa" refers to SpellAbility and "ab" refers to Ability, though sometimes the difference eludes me (does it mean that "ab" is for non-spell abilities only?..).

I'd welcome any help that any of you will be able to provide for me regarding the problems I've outlined above. I hope I'll be able to help out with AFs once I figure out how they work and what would be necessary to code them.
Thanks a lot in advance for your help!
- Agetian

[Max mtg]

I'm quite a newbie to these AFs, yet had to refactor them because it was way too hard to understand how to make an online play out of that. So these are my comments, I guess some more experienced folks have a lot to add to my answers.

1. These are operation codes not ability factories. Yes, once you add an enum member and give references to its effect and ai classes, you may add it to card scripts.

2.
a) Correct. Sometimes an effect class has to reference ai class =( It's a flaw - I think - there should be no such references. Yet, I cannot find a better solution for now. Look for a check player.isHuman() in resolve(). The recently made CharmEffect is also a good example.

b) A list of possible map keys and values varies from one operation to another. I guess there is no such list described anywhere (there actually were a few documenting comments in old AF files). Parameters do come from card scripts, yes.

c) resolve is the only essential method. stack description is optional.

3.
a) This is a very dark and mystrious arts for me. Yet, as I have seen, the "withcost" version of dotrigger does only

Code: Select all

        if (!ComputerUtil.canPayCost(sa, aiPlayer) && !mandatory) {
            // payment is usually not mandatory
            return false;
        }


and returns doTriggerNoCost result. See forge.card.abilityfactory.SpellAiLogic for a common 'withcost' version of dotrigger.

b) What chkAIDrawback calls each time is also a puzzle to me. Those implementations are not mine, I just moved them to a better place.

c) canPlay is essential. The rest is defined based on that, unless you override them.

4. No idea at all, why there are so many subclasses for ability.

[Agetian]

Thanks for your clarifications and comments, Max! Hopefully, someone else will be able to shed some light on the remaining mysteries, in the meantime, I'll dig a bit through the code.

- Agetian

[Sloth]

1) in forge.card.abilityfactory:
Am I correct that each new ability factory should now be registered in ApiType.java, in the ApiType enumeration? That, apparently, is where this code goes, but I'd like to make sure. Also, is anything else necessary to be done in the global Ability Factory code to add support for a new ability factory, or is registering it in ApiType enough?

Correct and there's nothing to do in AbilityFactory other than adding a block like this:

2) in forge.card.abilityfactory.effects:
As far as I understand, the abilityfactory.effects package contains the implementation of the ability effects as such, regardless of how AI is able to interact with the ability etc. I believe that:
getStackDescription is used to build a string description of the ability as it appears in the stack window.
resolve is the implementation of the effect as such which defines what effect the ability has on the cards on the playfield (e.g. on its target etc.)

Correct. Resolve can hold some AI stuff though (when decissions have to be made at resolution of the spell/ability).

I noticed that some parameters are usually passed to various ability factory methods via a java.util.Map<String, String> - is there a list of possible parameters anywhere? Some of them have rather unintuitive names - some of them seem like they should make sense immediately, but after some thinking, for instance, I realize I have no idea what AllType or AllValid could be used for when passed to a resolve method of an AF. Also, where do the parameters come from? Are they defined in card scripts or something like that?

Some parameters are general, but some are specific to certain AF's. The card scripts are all about these parameters:

Code: Select all

| PARAMETERNAME$ PARAMETERVALUE |

in forge.card.abilityfactory.ai:
There are several methods that need to be implemented here, some of which make sense to me and some of which are a mystery:
canPlayAI - used to test whether the AI can play the ability at the given moment and should return 'true' in situations when it can, right?

No, canPlayAI returns true, when it's a rather good idea to cast the spell / activate the ability now (what you describe is handled with canPlay).

chkAIDrawback is for secondary effects (subabilities). It only returns false when the effect is very harmful for the AI (For example casting Crush with an empty library). The first ability will run through canPlayAI the subabilities through chkAIDrawback.

doTriggerAI returns true whether a triggered ability should be used or not. doTriggerAINoCost is used for some other stuff like Cascade.

[Max mtg]

1) in forge.card.abilityfactory:

Correct and there's nothing to do in AbilityFactory other than adding a block like this:

Code: Select all

        else if (this.api.equals("Tap")) {
            ai = new TapAi();
            se = new TapEffect();
        }

THIS IS OUTDATED!

[Agetian]

Thanks a lot for clarifications, Sloth! I have some new questions though:

- In ability factory implementations, I haven't seen an implementation of the canPlay method - in what cases should that be overridden in an ability factory? (most ability factories implement getStackDescription and resolve, but do not implement canPlay).
- Is it safe to assume then, that if no subabilities are harmful for the AI, it's OK to just return the same value from chkAIDrawback as from canPlayAI?
- When you said that doTriggerAINoCost is used for some other stuff, what is the criterion to decide if it's "other stuff" or not? Most ability factories I've seen implement doTriggerAINoCost and do not implement doTriggerAI, I wonder how I should decide which one to stick to.
- Am I correct in assumption that doTriggerAI should return false if the triggered ability shouldn't be used (even if it technically can be)?

EDIT: Also, in the context of specific card implementation goals I have in mind, I'd like to ask:
- What is the current difficulty in implementing the double cards, such as Day/Night in Apocalypse? I'm pretty sure I've seen implementations of cards that change their effect depending on what cost was paid, not sure what adaptation exactly would be necessary in order to allow cards such as the one I mentioned.
- What might be a good enough strategy to implement damage prevention from a source (e.g. Circles of Protection)? I can see the basic damage prevention AF implemented, but my guess would be that it's currently not possible to confine the choice to the specific card type or color (e.g. CoP Artifacts, CoP Red). I wonder if this warrants an implementation of a separate subtype of the damage prevention AF or just a separate subtype of the card choice AF.

If you have any advice regarding the above two, please let me know as well.
Thanks in advance for your answers!
- Agetian

[Max mtg]

- canPlay is not supposed to be in Effects classes. Only resolve method should be there, preconditions are checked elsewhere.
- see the base class spellailogic for a doTriggerAI implementation common for all ai logics

[Hellfish]

Re:Split cards.

Basically, Card.hasProperty() would have to work differently.We could store the alternate side as an alternate characteristic-set but we can't do it the way you describe because split cards should have only the characteristics of it's cast side on the stack but sort of a combination of it's two sides elsewhere.See rule 708.2 and 708.5

[Sloth]

- Is it safe to assume then, that if no subabilities are harmful for the AI, it's OK to just return the same value from chkAIDrawback as from canPlayAI?

Most chkAIDrawback functions can always return true (because they can't harm in any way), BUT if there is a script that has a subability of this type that targets, some basic targeting should be present or the AI will make illegal plays.

- When you said that doTriggerAINoCost is used for some other stuff, what is the criterion to decide if it's "other stuff" or not?

Other stuff is mainly canPlayFromEffectAI, which is mostly used whenever a card can be used instantly (and not until end of turn or whenever). Cascade, Ripple, Rebound etc.

Most ability factories I've seen implement doTriggerAINoCost and do not implement doTriggerAI, I wonder how I should decide which one to stick to.

The default doTriggerAI in SpellAiLogic redirects to doTriggerAINoCost, so doTriggerAINoCost is the important one.

- Am I correct in assumption that doTriggerAI should return false if the triggered ability shouldn't be used (even if it technically can be)?

Yes.

- What is the current difficulty in implementing the double cards, such as Day/Night in Apocalypse? I'm pretty sure I've seen implementations of cards that change their effect depending on what cost was paid, not sure what adaptation exactly would be necessary in order to allow cards such as the one I mentioned.

The problem is that:
A. these cards have two names. Pithing Needle can only name one half.
B: these cards have two mana costs. Dark Confidant must take the combined cost, Chalice of the Void only the half that was cast.
C: these cards have two colors...
A+B+C also make changes in the deckeditor necessary.

- What might be a good enough strategy to implement damage prevention from a source (e.g. Circles of Protection)? I can see the basic damage prevention AF implemented, but my guess would be that it's currently not possible to confine the choice to the specific card type or color (e.g. CoP Artifacts, CoP Red). I wonder if this warrants an implementation of a separate subtype of the damage prevention AF or just a separate subtype of the card choice AF.

There are two problems:
A. The CoP's target a "Source" which is a messy game term (look it up in the comprehensive rules).
B. "The next time" hasn't been implemented in AF Prevent yet (but that's not such a big problem).

[Agetian]

Ok, thanks for the input, guys! Will see what I can do! Will probably need some cooperation on some of these, will keep you posted. Please let me know if anyone may be willing to tackle these (or other) types of cards in the future in cooperation with me.

- Agetian

[friarsol]

I don't think anyone has mentioned it yet, but the Wiki has a tons of relatively up to date information, including Parameter lists for each AF and what they generally mean.

http://www.slightlymagic.net/wiki/Forge_API

[Agetian]

That's great! Yeah, I started reading that set of documentation as well.
By the way, since the changes needed to implement these cards (and potentially other as well that do not yet have support in the code base) are extensive enough and are likely to temporarily break many things and require experimentation, is there any way for me to set up a copy of the local repository which I could use exactly for experiments with cards and card-related code? I want it to be independent from my main copy of the SVN repo which I can use to submit some smaller changes that do not require weeks/months of experimentation and faulty code - so basically, I want to set up something like a local "branch" on my PC (not really a branch though since I won't submit it as a branch to the SVN repository), or rather a local copy so that I have two independent copies of the SVN trunk both of which I can synchronize with the main repo when necessary - however, one of them will be used for the standard checkout/commit routine with smaller scale changes, and the other will be used for my large-scale experiments with the card code that is likely to be the cause of faults, crashes, and other stuff that I won't actually commit to the SVN until (and if ever) I have a working model of the code set up.
- Agetian

[friarsol]

That's great! Yeah, I started reading that set of documentation as well.
By the way, since the changes needed to implement these cards (and potentially other as well that do not yet have support in the code base) are extensive enough and are likely to temporarily break many things and require experimentation, is there any way for me to set up a copy of the local repository which I could use exactly for experiments with cards and card-related code? I want it to be independent from my main copy of the SVN repo which I can use to submit some smaller changes that do not require weeks/months of experimentation and faulty code - so basically, I want to set up something like a local "branch" on my PC (not really a branch though since I won't submit it as a branch to the SVN repository), or rather a local copy so that I have two independent copies of the SVN trunk both of which I can synchronize with the main repo when necessary - however, one of them will be used for the standard checkout/commit routine with smaller scale changes, and the other will be used for my large-scale experiments with the card code that is likely to be the cause of faults, crashes, and other stuff that I won't actually commit to the SVN until (and if ever) I have a working model of the code set up.
- Agetian

Just do an additional checkout to a new folder on your machine. I have this setup so I always have a "clean" version of the svn, so when I'm doing experimentation, I have a stable codebase to come back to. Additionally, I have my "pics" folder on the same level as these two folders and just point my main.properties there instead of relatively, so I share the pics for both repos

[Agetian]

Just do an additional checkout to a new folder on your machine. I have this setup so I always have a "clean" version of the svn, so when I'm doing experimentation, I have a stable codebase to come back to. Additionally, I have my "pics" folder on the same level as these two folders and just point my main.properties there instead of relatively, so I share the pics for both repos

Oh, nice, thanks for the advice!
- Agetian

[Agetian]

I'm working on an experimental version of the code which may later become a part of a new AF that deals with choosing a source (for Circles of Protection and whatever other cards may refer to "source"). I need a little consultation in this regard. Currently my mockup version of a source chooser does the following:

1) If there are any effects on the stack, it adds the cards that were the sources of those effects into the list, marking them with "(From stack)".
2) To the list of effects on the stack, it adds all the permanents currently in play.

It lists all of that and lets the user pick one.
I have a question: does the above cover all the possible scenarios of a "source"? I just can't possibly imagine what else there could be - if it's neither visible on the stack nor in play as a permanent, what else can it be?

Also, another question is: is there any implementation of "Prevent damage from <...>" currently in Forge? I looked at the damage prevention facilities in the current ability factory but could only find code related to preventing damage *to* a card, not coming *from* a card - if there is any code like that, I'd like to take a look at it, can you please tell me where I can find it? If there's no such implementation yet, can you please tell me what would be the easiest way to detect if a card has any damage-dealing effects (which includes combat damage and spell abilities and whatnot)?

Thanks in advance.
- Agetian