Let's just continue with our above begun example. The good old Ebon Dragon is on the stack. Stack is passed by all players so the old brute can be summoned.
Like explained above the script being called has a key CARD PLAYED KEY.
For the sake of the example here once the complete code with line numbers for reference:
01: / / Ebon Dragon played start
02: int debugLevel = 3;
02: D.addLog("4219: Played card start: "+card,debugLevel);
03: bRet = false;
04:
05: if (match.getHand(opponent).size()==0)
06: {
07: D.addLog("4219: No card on hand, nothing to put
away...",debugLevel);
08: D.addLog("4219: Played card end. ", debugLevel);
09: bRet=true;
10: return;
11: }
12:
13: if (targetCard == null)
14: {
15: if
16: {
17: D.addLog("4219: Decided YES/NO", debugLevel);
18: match.askYesNo(player, card, ev);
19: reason="Decide yes/no";
20: return;
21: }
22: if (selectNo==true)
23: {
24: D.addLog("4219: Decided not to take Ebon dragons ability",debugLevel);
25: D.addLog("4219: Played card end. ", debugLevel);
26: bRet=true;
27: return;
28: }
29: D.addLog("4219: Decided to take Ebon dragons ability",debugLevel);
30: D.addLog("4219: Asking opponent to select a card.",debugLevel);
31: match.askSelectCardFromHand(opponent, card, ev);
32: match.setPlayerCardMessage(opponent, ""+card+" played, you must select a card from your hand to dispose to the graveyard.");
33: return;
34: }
35: D.addLog("4219: Opponent selected a card to drop: "+targetCard,debugLevel);
36: L.addLog("Ebon Dragon forced "+opponent+" to drop a card: "+targetCard);
37: match.moveCardFromHandToGraveyard(opponent, targetCard);
38: bRet = true;
39: D.addLog("4219: Played card end. ", debugLevel);
40: / / Ebon Dragon played end
First things I allways do is define a debugLevel, with that I control the output to the Loging instance. Usually I log as much as possible to be able to debug the code. Debugging interpreted code is somewhat - well - not nice. I will ommit debuging calls from further explanation, they should be more or less self explaining.
From line 05 I first check, whether the opponent has any cards left on his hand, if not, why bother asking him to drop one... If he has no card left, I just exit with bRet=true; and already I'm finished.
From line 13 I check whether a successfull communication returned a targetCard already, if that is the case I can continue at line 35. But since we enter the first time, there is as yet no target end we enter the if-clause to line 15.
The Ebon Dragon has that dreadful word "may" in his text, so the player playing it out can chose if he wants to activate the dragons ability. There are several possible ways to implement such. Here I chose to actually ask the player whether he wants to activate the ability. If a communication about asking was already successfull either or both "selectYes" and/or "selectNo" will be set to something different than null. Since again we are at our first "round", everything is null and we go to line 17.
Line 18 actually initiates the communication with the player:
18: match.askYesNo(player, card, ev);
Means:
The script wishes to communicate with player "player" (which is the owner of the card)
The card responsible for communication is "card" (which is the Ebon Dragon)
The result of the communication should be put in "our" Script environment which is "ev"
The communication we want is a decision, about Yes or No
bRet is already set to false (line 03), so we exit the script here.
... Comunication going on...
When the communication is finished, match will call this script again. The result of the communication is available in ev (which is mapped to the above listed variables), you should use the above listed variables, which are set correspondingly.
So the script is entered again, opponents hand didn't change, targetCard is still null so we are at line 15 and oh wonder, the player probably selected YES. So we neither enter the if clause at line 15 again, nor the if clause at line 22, but we rather continue at line 29.
31: match.askSelectCardFromHand(opponent, card, ev);
At line 31 we again initiate another communication with a player, this time with our opponent. We kindly ask him, to please select a card from his hand (which we will DESTROY later HAR HAR HAR!). bRet is still set to false so we quietly leave at line 33 and await another calling after the opponent selected a card.
Here we go again.
So the script is entered again, opponents hand didn't change, but targetCard is not null so we go to line 35.
37: match.moveCardFromHandToGraveyard(opponent, targetCard);
In line 37 we tell (not ask!) the match to move the opponent players card (which is held in variable "targetCard" to the graveyard.
This is done directly, the call is synchronous. A hell of a lot can happen in that simple call.
(not with the Ebon Dragon, but imagine if we played another card, which had destroyed a creature in the battlefield, rather than from hand. If for example a "Fire Snake" was destroyed, a lot of communication would be startet about which land was to be destroyed etc... but - all that going on doesn't interfere with the current stack or the current communication, so calling synchronously is ok)
we set bRet=true; and are finally done with playering out the Ebon Dragon, in just three "rounds".