Enhanced AI Hints (unfinished)

The enhanced hints were implemented for the enhanced AI.

Why were new hints neccessary?

• Because the old ones couldn't handle all I wanted - hopefully the new ones are able to.

• There were no "Restrictions" on the hints - so you couldn't reliably base code on them. You were forced to rely on sensible card designers

What's new, what's the main difference?
Hints can be grouped, and one single card can have more than one group of hints. Each group may belongs to a different kind of situation. So for one card there may be different hints for playing out the card, decide whether attack or block or activate an ability. This was not possible with old hints.
New kind of hints can only be added by changing the code. This places necccessary restrictions on the development of new hint types. They can not grow without control and new hints can be categorized and named "correctly".

The old hints were used for one thing only:
To enable the "allround"-AI to evaluate the cards and react to cards in general terms. The goal was to program a reasonable intelligent AI that could play cards without specializing to single cards, but to use the provided hints to be able to handle cards and make decisions based on a somewhat generalized behaviour pattern discernable by the AI via the hints.

The new hints are also used for above. But another "philosophy" is applied. While the "allround" AI basically did something like:
if health is low,
    find a card that gives me health
else
    find a card that I can damage the opponent with
... (you get my meaning)

The new EAI more or less does:
simulate play card A → see what the result is
simulate play card B → see what the result is
simulate play card C → see what the result is
...
take the best result,
play that result in the real game

The difficult thing in EAI hides in the little word "simulate". The EAI implements a complete standalone "second" match, in which it can play cards (simulated play) and inspect the results. These simulation does not in any way interfere with the current game, it is complete EAI internal. In order for the Virtual Match (so I like to call it) to be able to simulate all cards without using the match - and still be able to generalize - it must have means to interpret all cards correctly. This is what the new hints are also used for. The new hints must be:

• exact

• correct

• complete
  

enough for Virtual Match to simulate all effects covered by all cards. As of now this holds true!

In the gui for each of these hints a small help is provided I will not repeat that here!

Hint Categories
-----------
There are different Categories of hints:

• Time

• Play Restrictions

• Occurrence
  
  

• Target: Target

• Target: Restrictions

• Target: Count

• Target: Type
  
  

• Source: Source

• Source: Restrictions

• Source: Count

• Source: Type
  
  

• Playability

The Target / Source
Hints are basically the same. Some cards refer to two cards, like steal 2 HP from creature A and heal player B by the same amount... In this scenario A is the "Source" and B the "Target".
Note:
Within EAI (VirtualMatch), source hints (if present) are allways evaluated befor target hints! (for no apparent reason, cards with only one "target" usually are implemented using the TARGET-hints)

Playability
is not really used yet. It is supposed to give the AI general hints, which refer more to common sense than to the abilities a card may have.

This basically leaves us with 7 Categories.

• Occurrence

• Type

• Target

• Target-Restrictions

• Target-Count

• Time

• Play-Restrictions
  
  Occurrence
  ---------
  WHEN does the effect the hint refers to takes place.

Definition:
csa.jportal.ai.enhancedHints.HintOccurrence

May be one of:
      HINT OCCURRENCE WHEN PLAYED,
      HINT OCCURRENCE WHEN ATTACKED,
      HINT OCCURRENCE WHEN BLOCKED,
      HINT OCCURRENCE WHEN ATTACKING,
      HINT OCCURRENCE WHEN BLOCKING,
      HINT OCCURRENCE WHEN IN PLAY,
      HINT OCCURRENCE WHEN IN TIMING,
      HINT OCCURRENCE WHEN ACTIVATED,
      HINT OCCURRENCE WHEN DRAW CARD,
      HINT OCCURRENCE WHEN PUT TO GRAVEYARD,
      HINT OCCURRENCE WHEN NOT BLOCKED,



Type
----
WHAT is the effect the hint refers to (this is likely to expand).

Definition:
csa.jportal.ai.enhancedHints.HintSourceTypes
csa.jportal.ai.enhancedHints.HintTargetTypes

May be one of:
      HINT STYPE TOUGHNESS ADD,
      HINT STYPE POWER ADD,
      HINT STYPE ABILITY ADD,
      HINT STYPE COLOR ADD,
      HINT STYPE PROTECTION ADD,
      HINT STYPE TOUGHNESS SUB,
      HINT STYPE POWER SUB,
      HINT STYPE ABILITY SUB,
      HINT STYPE COLOR SUB,
      HINT STYPE PROTECTION SUB,
      HINT STYPE COLOR CHANGE,
      HINT STYPE COLOR CHANGE TEXT,
      HINT STYPE TAP,
      HINT STYPE UNTAP,
      HINT STYPE HEAL,
      HINT STYPE DAMAGE,
      HINT STYPE CONTROL CHANGE,
      HINT STYPE FIELD TO GRAVE,
      HINT STYPE FIELD TO HAND,
      HINT STYPE FIELD TO LIBRARY,
      HINT STYPE FIELD TO EXILE,
      HINT STYPE HAND TO LAND,
      HINT STYPE HAND TO GRAVE,
      HINT STYPE HAND TO FIELD,
      HINT STYPE HAND TO LIBRARY,
      HINT STYPE HAND TO EXILE,
      HINT STYPE LAND TO HAND,
      HINT STYPE LAND TO GRAVE,
      HINT STYPE LAND TO LIBRARY,
      HINT STYPE LAND TO EXILE,
      HINT STYPE LIBRARY TO GRAVE,
      HINT STYPE LIBRARY TO HAND,
      HINT STYPE LIBRARY TO LAND,
      HINT STYPE LIBRARY TO FIELD,
      HINT STYPE LIBRARY TO EXILE,
      HINT STYPE REPLAY TURN,
      HINT STYPE REPLAY PHASE,
      HINT STYPE LIBRARY TOP,
      HINT STYPE GRAVE TO HAND,
      HINT STYPE GRAVE TO FIELD,
      HINT STYPE GRAVE TO LAND,
      HINT STYPE GRAVE TO LIBRARY,
      HINT STYPE GRAVE TO EXILE,
      HINT STYPE ALL BLOCK ONE,
      HINT STYPE ALL MUST ATTACK,
      HINT STYPE ONLY ONE BLOCK ,
      HINT STYPE UNTAP DENIAL,
      HINT STYPE ATTACK DENIAL,
      HINT STYPE HALF LIFE,
      HINT STYPE NOT CREATURE DAMAGEABLE,
      HINT STYPE GENERAL DEBUF,
      HINT STYPE GENERAL BUF,
      HINT STYPE GENERAL BLOCK LIMITATION,
      HINT STYPE GENERAL BLOCKER LIMITATION,
      HINT STYPE GENERAL ATTACK LIMITATION,
      HINT STYPE NOT BLOCKABLE IF SINGLE ATTACKER,
      HINT STYPE CANT BLOCK,
      HINT STYPE CHOSE FROM LIBRARY,
      HINT STYPE NOT BLOCKABLE,
      HINT STYPE SELF DESTRUCT,
      HINT STYPE INHERENT,
      HINT STYPE LIBRARY ROCHADE,
      HINT STYPE AURA,
      HINT STYPE PLAYER AURA,
      HINT STYPE STACK NEGATE STACK CARD,
      HINT STYPE STACK NEGATE ABILITY,
      HINT STYPE STACK NEGATE PLAYER DAMAGE,

Note: The hint HINT STYPE INHERENT indicates, that the target is inherhently "set" by playing the card out. Meaning: no player action is needed to select a target. All other targetting information, like count, where the target is to be taken from etc. must STILL be set with corresponding hints. Otherwise EAI would not be able to play the card correctly (and Virtual Match could not react appropriatly).

Target
-----
WHO/WHAT will be effected.

Definition: csa.jportal.ai.enhancedHints.HintSource / HintTarget
May be one of:
      HINT TARGET FROM FIELD,
      HINT TARGET FROM HAND,
      HINT TARGET FROM LAND,
      HINT TARGET FROM LIBRARY,
      HINT TARGET FROM GRAVE,
      HINT TARGET FROM EXILE,
      HINT TARGET IS PLAYER,
      HINT TARGET IS OPPONNET,
      HINT TARGET OWNER,
      HINT TARGET STACK,
      HINT TARGET SELF,

Note: All targets must be supplied. Meaning if the target can be player or opponent than both hints HINT TARGET IS PLAYER and HINT TARGET IS OPPONNET must be set to true.

Target-Restrictions
--------------
TARGET RESTRICTIONS that may be effected.
Definition:
csa.jportal.ai.enhancedHints.HintSourceRestrictions
csa.jportal.ai.enhancedHints.HintTargetRestrictions

May be one of:
      HINT SR TYPE NEEDED,
      HINT SR SUBTYPE NEEDED,
      HINT SR COLOR NEEDED,
      HINT SR ABILITY NEEDED,
      HINT SR TYPE RESTRICTION,
      HINT SR SUBTYPE RESTRICTION,
      HINT SR COLOR RESTRICTION,
      HINT SR ABILITY RESTRICTION,
      HINT SR TAP NEEDED,
      HINT SR UNTAP NEEDED,
      HINT SR COUNT MIN RESTRICTION,
      HINT SR COUNT MAX RESTRICTION,
      HINT SR POWER MIN RESTRICTION,
      HINT SR POWER MAX RESTRICTION,
      HINT SR TOUGHNESS MIN RESTRICTION,
      HINT SR TOUGHNESS MAX RESTRICTION,
      HINT SR COST MIN RESTRICTION,
      HINT SR COST MAX RESTRICTION,
      HINT SR PLAYER CARDS,
      HINT SR OPPONENT CARDS,
      HINT SR BLOCKER,
      HINT SR ATTACKER,
      HINT SR SELF OK,

Note:
These hints place restrictions on the cards chosen. There are two different types of restrictions:

1. NEEDED (the cards must be of type....)

2. RESTRICTION (the cards must not be of type...)

E.g. The target is "FROM FIELD" than all cards in field are in general possible as a target.
Usually FROM FIELD comes with restriction like:
HINT SR TYPE NEEDED Creature
HINT SR TAP NEEDED true
or the like.

Note 2:
If NEEDED or RESTRICTION is missing in the hint name → the hints type is of type "NEEDED".

Note 3:
"PLAYER CARDS" and "OPPONEN CARDS" are special in the way that despite being formally of type "NEEDED", they can both be set. The result is that the card can by ONE OF the two, meaning can be either a player card OR an opponents card.

Note 4:
Type, Subtype, Color are given as
"Creature" , "Land" ...
"Goblin", "Rat" ...
"B", "W", "U"
(without quotation marks!)
If more than one type is needed (restricted) the values can be comma seperated.

Target-Count
----------
HOW MANY targets are effected, AMOUNT of the effect (heal / damage).
Definition:
csa.jportal.ai.enhancedHints.HintSourceCount
csa.jportal.ai.enhancedHints.HintTargetCount

May be one of:
      HINT TCOUNT SINGLE TARGET,
      HINT TCOUNT MULTI TARGET,
      HINT TCOUNT TARGET MIN,
      HINT TCOUNT TARGET MAX,
      HINT TCOUNT TARGET COUNT,
      HINT TCOUNT AMOUNT COUNT,
      HINT TCOUNT X COUNT,
      HINT TCOUNT ALL TARGETS,
      HINT TCOUNT ALL PLAYERS,
      HINT TCOUNT ONE PLAYER,
      HINT TCOUNT POWER,
      HINT TCOUNT TOUGHNESS,
      HINT TCOUNT SPECIAL,
      HINT TCOUNT OPPONENT MORE DIF,
      HINT TCOUNT HAS AMOUNT MULTIPLYER,
      HINT TCOUNT MULTIPLYER FACTOR,
      HINT TCOUNT MULTIPLYER PLAYER,
      HINT TCOUNT MULTIPLYER OPPONENT,
      HINT TCOUNT MULTIPLYER RESTRICTION TYPE,
      HINT TCOUNT MULTIPLYER RESTRICTION SUBTYPE,
      HINT TCOUNT MULTIPLYER RESTRICTION COLOR,
      HINT TCOUNT MULTIPLYER RESTRICTION TAPPED,
      HINT TCOUNT MULTIPLYER RESTRICTION UNTAPPED,
      HINT TCOUNT MULTIPLYER RESTRICTION HAND,
      HINT TCOUNT MULTIPLYER RESTRICTION LAND,
      HINT TCOUNT MULTIPLYER RESTRICTION FIELD,
      HINT TCOUNT MULTIPLYER RESTRICTION GRAVE,
      HINT TCOUNT MULTIPLYER RESTRICTION ATTACKER,

Note:
Targets are allways counted using the "TARGET COUNT".
Amount of anything (like damage) is allways gotton from "AMOUNT COUNT"

Note 2:
Types of ADD POWER / TOUGHNESS (or SUB) derive their add/sub value from ADD POWER (or similar) NOT from AMOUNT

Time
----
HOW LONG will the effect last.

Definition:
csa.jportal.ai.enhancedHints.HintTime

May be one of:
      HINT TTIME TURN COUNT,
      HINT TTIME PHASE COUNT,
      HINT TTIME TARGET DEATH,
      HINT TTIME SOURCE DEATH,
      HINT TTIME ONCE,

Note:
Here TARGET means the target card of an effect and SOURCE means the card these hints belong to (not another secondary target of any type). Thus for example the enchantement "Flight" is placed on a creature. Than the card "Flight" itself would be the one the hint HINT TTIME SOURCE DEATH would refer to.

Play-Restrictions
------------
RESTRICTION on PLAY, when can the effect be played out.

Definition:
csa.jportal.ai.enhancedHints.HintPlayRestrictions

May be one of:
      HINT PR INSTANT ANY,
      HINT PR INSTANT CARD PLAYED,
      HINT PR INSTANT ATTACKER DECLARED,
      HINT PR INSTANT BLOCKER DECLARED,
      HINT PR INSTANT ATTACKER DECLARED FINAL,
      HINT PR INSTANT BLOCKER DECLARED FINAL,
      HINT PR PLAYER TURN,
      HINT PR OPPONENT TURN,
      HINT PR OPPONENT MORE CARDS,

Examples
-------

Portal: Assassin's Blade
........................

No         Key         Type                           Name                                    Value
1         INSTANT   PLAY RESTRICTION        OPPONENT TURN            true
1         INSTANT   TARGET RESTRICTION   COLOR(s) RESTRICTION B
1         INSTANT   TARGET RESTRICTION   ATTACKER                       true
1         INSTANT   TARGET RESTRICTION   OPPONENT CARDS          true
1         INSTANT   TARGET                           TARGET FROM FIELD     true
1         INSTANT   TARGET EFFECT TYPE    FIELD TO GRAVE            true
1         INSTANT   OCCURRENCE                  WHEN PLAYED                true
1         INSTANT   PLAY RESTRICTION        WHILE ATTACKER DECLARATION true
1         INSTANT   TARGET EFFECT COUNT IS SINGLE TARGET          1
1         INSTANT   TARGET RESTRICTION   TYPE NEEDED                 Creature


Renewing Dawn
.............

No         Key                   Type                                Name                                    Value
1         CARD PLAYED   TARGET EFFECT COUNT     MULTIPLYER LAND               true
1         CARD PLAYED   TARGET EFFECT COUNT     MULTIPLYER OPPONENT      true
1         CARD PLAYED   OCCURRENCE                      WHEN PLAYED                       true
1         CARD PLAYED   TARGET EFFECT COUNT     MULTIPLYER COLOR             R
1         CARD PLAYED   TARGET EFFECT COUNT     HAS AMOUNT MULTIPLYER  true
1         CARD PLAYED   TARGET EFFECT COUNT     MULTIPLYER TYPE                Land
1         CARD PLAYED   TARGET EFFECT COUNT     MULTIPLYER FACTOR           2
1         CARD PLAYED   TARGET EFFECT COUNT     MULTIPLYER SUBTYPE          Mountain
1         CARD PLAYED   TARGET                               TARGET IS PLAYER                true
1         CARD PLAYED   TARGET EFFECT TYPE        HEAL                                       true

Hint

Each hint consists of following entities:

• number - an increasing number for each key

• situation key - for what situation is this hint for (see below)

• type of the hint - of what type is the hint (see below)

• name - name of that specific hint

• value - the value of the hint, most often a boolean

Number

An increasing number for each key.

Situation key

One of the following:

• INSTANT

• ACTIVATION

• CARD PLAYED

• ATTACKING

• BLOCKING

• CARD IS BLOCKED

• DEATH

• TRIGGERED

• INHERENT

These losely describe for what situation a hint is used for.

Type

(See also above) There are different types of hints:

• Time

• Play Restrictions

• Occurrence
  
  

• Target: Target

• Target: Restrictions

• Target: Count

• Target: Type
  
  

• Source: Source

• Source: Restrictions

• Source: Count

• Source: Type
  
  

• Playability

The Target / Source
Hints are basically the same. Some cards refer to two cards, like steal 2 HP from creature A and heal player B by the same amount... In this scenario A is the "Source" and B the "Target".
Note:
Within EAI (VirtualMatch), source hints (if present) are allways evaluated befor target hints! (for no apparent reason, cards with only once "target" usually are implemented using the TARGET-hints)

Name

Each hint has a more or less sensible name. Each named hint also has a small (1-2 sentence) help, that explains what is is used for.

Value

Values mostly are just booleans. But - depending on the hint - can also be of:

• type (Creature, Land, Instant, Sorcery, etc.)

• color (W, B, R, U, G)

• ability (Flight, Horsemanship, etc.)

• a number

See provided hint explaination or examples.

TODO:

Remember:

• INHERENT is only a sign for the player not needing to chose

  • it does not tell in any way that the card inherently knows the targets, and thus does not need more hints!

  • allways! more hints are needed, what target is supposed to be chosen by virtual Match

  • that also means, for all not activly chosen targets (from cards players point of view) INHERENT shoul be set

  • in special that also means if a card is OPPONENT CHOSEN, INHERENT must be set (see e.g.: Diaochan, Artful Beauty)

• if a list or a listed restriction of cards are "inherently" chosen

  • CT ALL CARDS (Target count) must be given

  • these all cards get further restricted by additional hints!

  • it does not mean that ALL cards are chosen

  • but rather that "all" cards are the base of the restrictions

  • OPPONENT CARDS is a restriction, not a base

  • base must allways be ALL Cards