Add an Assimilate API so the keyword lives in one place

Speculative, and separable from the commit before it: the printed card only
assimilates from a graveyard, and this also handles a permanent already on
the battlefield, which no card asks for yet. Drop this commit and the card
still works through StaticEffect$.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: liamiak1

docs/Card-scripting-API/AbilityFactory.md

@@ -103,6 +103,21 @@ Parameters (all optional):
 - `RemoveAllAbilities$ True` - Remove all Abilities, Triggers, Statics and Replacement effects
 - `sVars` - a comma-delimited list of SVars that should be granted to the animated being
 
+## Assimilate
+Handles the keyword action "assimilate" - the target ends up under your control as a Borg artifact
+creature with a +1/+1 counter, having lost its other creature types but keeping its other card types.
+
+How it gets there depends on where it starts. A card in a graveyard or exile is put onto the
+battlefield, and the type change rides on that zone change (via `StaticEffect$`) so ETB triggers
+already see a Borg artifact creature. A permanent already on the battlefield only changes controller
+and is animated in place.
+
+Parameters:
+- `ValidTgts`/`TgtZone` - as for any targeted effect; `TgtZone$ Graveyard` for the graveyard form
+
+Example (*Borg Queen, Perfection Manifest*):  
+`SVar:TrigAssimilate:DB$ Assimilate | TgtZone$ Graveyard | ValidTgts$ Creature.OppOwn`
+
 ## Attach
 Attaches a permanent to an affected card or player.
 

forge-ai/src/main/java/forge/ai/SpellApiToAi.java

@@ -32,6 +32,7 @@ public enum SpellApiToAi {
             .put(ApiType.Attach, AttachAi.class)
             .put(ApiType.AssembleContraption, AssembleContraptionAi.class)
             .put(ApiType.AssignGroup, AssignGroupAi.class)
+            .put(ApiType.Assimilate, AssimilateAi.class)
             .put(ApiType.Balance, BalanceAi.class)
             .put(ApiType.BecomeMonarch, BecomeMonarchAi.class)
             .put(ApiType.BecomesBlocked, BecomesBlockedAi.class)

forge-ai/src/main/java/forge/ai/ability/AssimilateAi.java

@@ -0,0 +1,57 @@
+package forge.ai.ability;
+
+import java.util.List;
+
+import forge.ai.AiAbilityDecision;
+import forge.ai.AiPlayDecision;
+import forge.ai.ComputerUtilCard;
+import forge.ai.SpellAbilityAi;
+import forge.game.card.Card;
+import forge.game.card.CardCollection;
+import forge.game.player.Player;
+import forge.game.spellability.SpellAbility;
+
+/**
+ * The card ends up under our control either way, so any legal target is a gain; the only decision
+ * is which one.
+ */
+public class AssimilateAi extends SpellAbilityAi {
+
+    @Override
+    protected AiAbilityDecision checkApiLogic(final Player ai, final SpellAbility sa) {
+        if (!sa.usesTargeting()) {
+            return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
+        }
+        return takeBest(ai, sa) ? new AiAbilityDecision(100, AiPlayDecision.WillPlay)
+                : new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
+    }
+
+    @Override
+    protected AiAbilityDecision doTriggerNoCost(final Player ai, final SpellAbility sa, final boolean mandatory) {
+        if (!sa.usesTargeting()) {
+            return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
+        }
+        if (takeBest(ai, sa)) {
+            return new AiAbilityDecision(100, AiPlayDecision.WillPlay);
+        }
+        // a mandatory trigger with no legal target simply does nothing
+        return new AiAbilityDecision(0, AiPlayDecision.CantPlayAi);
+    }
+
+    private boolean takeBest(final Player ai, final SpellAbility sa) {
+        sa.resetTargets();
+        final List<Card> options = new CardCollection(
+                ai.getGame().getCardsIn(sa.getTargetRestrictions().getZone()));
+        final CardCollection legal = new CardCollection();
+        for (final Card c : options) {
+            if (sa.canTarget(c)) {
+                legal.add(c);
+            }
+        }
+        if (legal.isEmpty()) {
+            return false;
+        }
+        sa.getTargets().add(ComputerUtilCard.getBestCreatureAI(legal));
+        return true;
+    }
+}

forge-game/src/main/java/forge/game/ability/ApiType.java

@@ -26,6 +26,7 @@ public enum ApiType {
     AnimateAll (AnimateAllEffect.class),
     Attach (AttachEffect.class),
     AssembleContraption (AssembleContraptionEffect.class),
+    Assimilate (AssimilateEffect.class),
     AssignGroup (AssignGroupEffect.class),
     Balance (BalanceEffect.class),
     BecomeMonarch (BecomeMonarchEffect.class),

forge-game/src/main/java/forge/game/ability/effects/AssimilateEffect.java

@@ -0,0 +1,102 @@
+package forge.game.ability.effects;
+
+import java.util.Arrays;
+import java.util.Map;
+
+import com.google.common.collect.Lists;
+
+import forge.card.CardType;
+import forge.game.Game;
+import forge.game.GameEntityCounterTable;
+import forge.game.ability.AbilityKey;
+import forge.game.ability.SpellAbilityEffect;
+import forge.game.card.Card;
+import forge.game.card.CardCollection;
+import forge.game.card.CardZoneTable;
+import forge.game.card.CounterEnumType;
+import forge.game.card.CounterType;
+import forge.game.player.Player;
+import forge.game.spellability.SpellAbility;
+import forge.util.Lang;
+
+/**
+ * CR 701.x assimilate: the card ends up under your control as a Borg artifact creature with a
+ * +1/+1 counter, but how it gets there depends on where it started - a card in a graveyard has to
+ * be moved, a permanent only changes hands.
+ */
+public class AssimilateEffect extends SpellAbilityEffect {
+
+    private static final String ANIMATE = "Mode$ Continuous | Affected$ Card.IsRemembered"
+            + " | AddType$ Artifact & Creature & Borg | RemoveCreatureTypes$ True";
+
+    @Override
+    protected String getStackDescription(SpellAbility sa) {
+        return "Assimilate " + Lang.joinHomogenous(getCardsfromTargets(sa)) + ".";
+    }
+
+    @Override
+    public void resolve(SpellAbility sa) {
+        final Game game = sa.getHostCard().getGame();
+        final Player controller = sa.getActivatingPlayer();
+        final CounterType p1p1 = CounterEnumType.P1P1;
+
+        final CardZoneTable triggerList = new CardZoneTable();
+        final GameEntityCounterTable alreadyInPlay = new GameEntityCounterTable();
+
+        for (final Card tgt : getCardsfromTargets(sa)) {
+            final Card gameCard = game.getCardState(tgt, null);
+            if (gameCard == null || !tgt.equalsWithGameTimestamp(gameCard) || gameCard.isPhasedOut()) {
+                continue;
+            }
+
+            // has to happen before any move, or the card enters under the wrong controller
+            if (!controller.equals(gameCard.getController())) {
+                gameCard.runChangeControllerCommands();
+                gameCard.setController(controller, game.getNextTimestamp());
+            }
+
+            if (gameCard.isInPlay()) {
+                gameCard.addCounter(p1p1, 1, controller, alreadyInPlay);
+                animateInPlace(gameCard, sa, game);
+            } else {
+                // riding the zone change is what makes the types apply as the card enters, so a
+                // "whenever an artifact enters" trigger sees it as one
+                sa.putParam("StaticEffect", "AssimilateAnimate");
+                sa.setSVar("AssimilateAnimate", ANIMATE);
+
+                final Map<AbilityKey, Object> moveParams = AbilityKey.newMap();
+                AbilityKey.addCardZoneTableParams(moveParams, triggerList);
+                moveParams.put(AbilityKey.SimultaneousETB, entering(sa));
+                final GameEntityCounterTable counters = new GameEntityCounterTable();
+                counters.put(controller, gameCard, p1p1, 1);
+                moveParams.put(AbilityKey.CounterTable, counters);
+                game.getAction().moveToPlay(gameCard, controller, sa, moveParams);
+            }
+        }
+
+        alreadyInPlay.replaceCounterEffect(game, sa);
+        triggerList.triggerChangesZoneAll(game, sa);
+    }
+
+    /** Everything being assimilated out of a hidden zone enters together. */
+    private static CardCollection entering(final SpellAbility sa) {
+        final CardCollection cards = new CardCollection();
+        for (final Card c : getCardsfromTargets(sa)) {
+            if (!c.isInPlay()) {
+                cards.add(c);
+            }
+        }
+        return cards;
+    }
+
+    /** Nothing is entering, so there is no zone change for the static effect to ride on. */
+    private void animateInPlace(final Card c, final SpellAbility sa, final Game game) {
+        final CardType add = new CardType(true);
+        add.addAll(Arrays.asList("Artifact", "Creature", "Borg"));
+        sa.putParam("RemoveCreatureTypes", "True");
+        AnimateEffectBase.doAnimate(c, sa, null, null, add, new CardType(true), null,
+                Lists.newArrayList(), Lists.newArrayList(), Lists.newArrayList(),
+                Lists.newArrayList(), Lists.newArrayList(), Lists.newArrayList(), Lists.newArrayList(),
+                game.getNextTimestamp(), "Permanent");
+    }
+}

forge-gui-desktop/src/test/java/forge/game/card/AssimilateTest.java

@@ -3,8 +3,11 @@
 import org.testng.annotations.Test;
 
 import forge.ai.AITest;
+import forge.game.ability.AbilityFactory;
+import forge.game.ability.AbilityUtils;
 import forge.game.Game;
 import forge.game.player.Player;
+import forge.game.spellability.SpellAbility;
 import forge.game.zone.ZoneType;
 
 import static org.testng.AssertJUnit.assertEquals;
@@ -112,6 +115,37 @@ public void itKeepsCardTypesAndOnlyShedsCreatureTypes() {
         assertFalse("lost Sheep", ram.getType().hasCreatureType("Sheep"));
     }
 
+    /**
+     * No printed card assimilates a permanent yet, so this drives the API directly. It is the half
+     * of the effect that exists on speculation, and it is the half a future card would use.
+     */
+    @Test
+    public void assimilatingAPermanentTakesItWhereItStands() {
+        Game game = initAndCreateGame();
+        Player ai = game.getPlayers().get(1);
+        Player opp = game.getPlayers().get(0);
+
+        Card host = addCard(QUEEN, ai);
+        Card bears = addCard("Grizzly Bears", opp);
+        game.getAction().checkStateEffects(true);
+
+        SpellAbility sa = AbilityFactory.getAbility(
+                "DB$ Assimilate | ValidTgts$ Creature.OppCtrl", host);
+        sa.setActivatingPlayer(ai);
+        sa.getTargets().add(bears);
+        AbilityUtils.resolve(sa);
+        game.getAction().checkStateEffects(true);
+
+        assertEquals("stays on the battlefield", ZoneType.Battlefield, bears.getZone().getZoneType());
+        assertEquals("changes hands", ai, bears.getController());
+        assertEquals(1, bears.getCounters(CounterEnumType.P1P1));
+        assertTrue("is an artifact", bears.isArtifact());
+        assertTrue("is a Borg", bears.getType().hasCreatureType("Borg"));
+        assertFalse("lost Bear", bears.getType().hasCreatureType("Bear"));
+        // 2/2 base, +1/+1 counter, +2/+0 now that it is our artifact creature
+        assertEquals(5, bears.getNetPower());
+    }
+
     @Test
     public void aCreatureOnTheirBattlefieldIsNotReachable() {
         Game game = initAndCreateGame();

forge-gui/res/cardsfolder/upcoming/borg_queen_perfection_manifest.txt

@@ -4,7 +4,6 @@ Types:Legendary Artifact Creature Borg Noble
 PT:1/4
 S:Mode$ Continuous | Affected$ Creature.Artifact+YouCtrl | AddPower$ 2 | Description$ Artifact creatures you control get +2/+0.
 T:Mode$ ChangesZone | Origin$ Any | Destination$ Battlefield | ValidCard$ Card.Self | Execute$ TrigAssimilate | TriggerDescription$ When NICKNAME enters, assimilate target creature card from an opponent's graveyard. (Put it onto the battlefield under your control with a +1/+1 counter. It's a Borg artifact creature and loses all other creature types.)
-SVar:TrigAssimilate:DB$ ChangeZone | Origin$ Graveyard | Destination$ Battlefield | ValidTgts$ Creature.OppOwn | TgtPrompt$ Select target creature card in an opponent's graveyard | GainControl$ True | WithCountersType$ P1P1 | StaticEffect$ Animate
-SVar:Animate:Mode$ Continuous | Affected$ Card.IsRemembered | AddType$ Artifact & Creature & Borg | RemoveCreatureTypes$ True
+SVar:TrigAssimilate:DB$ Assimilate | TgtZone$ Graveyard | ValidTgts$ Creature.OppOwn | TgtPrompt$ Select target creature card in an opponent's graveyard
 DeckHas:Ability$Graveyard|Counters
 Oracle:Artifact creatures you control get +2/+0.\nWhen Borg Queen enters, assimilate target creature card from an opponent's graveyard. (Put it onto the battlefield under your control with a +1/+1 counter. It's a Borg artifact creature and loses all other creature types.)