Card Game Combat - Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{https://img.itch.zone/aW1nLzE4NzczOTY5LnBuZw==/original/Mglsyo.png?nolink&690}}

This plugin adds a new Zone to battles called the Field, and with it come several new features.

===== Quick Terminology Reference =====

CardSummonsCore adds a significant amount of new mechanics to CGC. Similar to how the Core Engine has its own vocabulary including Card Actions and Zones which refer to specific things, Card Summons has several more which are detailed below. Each one will have a detailed breakdown, but here is a quick reference.

| **Field** | This is a special Zone with unique properties, including the fact that the Enemy Troop has its own Field. The party's Field will be referred to as the Party Field while the enemy Field will be referred to as the Troop Field. |
| **Field Card** | Cards moved to the Field will be referred to as Field Cards if they do not have a Creature associated with them. |
| **Creature Card** | Cards moved to the Field will be referred to as Creature Cards if they are associated with a Creature. Note that Creatures replace Creature Cards visually, so the Cards are only referenced in this document when necessary. |
| **Creatures** | These are Battler units that exist on the Field. They are extensions of the Enemy class and are created using the Enemies database, but can be put on both the Party Field and the Troop Field. |
| **Field Skills** | These are skills attached to Field Cards or Creatures. You can use these skills by interacting with the Field Card or Creature that they belong to. |
| **Creature Passives** | Like Card Passives, but attached to a Creature. |
| **Stat Display** | A UI element attached to a Creature sprite which displays the current value of a stat belonging to that Creature. |

====== The Field ======

The Field is a special Zone with unique properties. It has a unique appearance, and all Cards that move to it will be arranged in a grid. It has a finite number of Cards that it can fit, determined by the Grid Width and Grid Height parameters.

Additionally, both the Player and the Enemy Troop have their own Field Zone. This means that Enemies have access to Field Cards, even while they don't normally have access to Cards in any other capacity.

===== Field Card Action Changes ======

All Card Actions that reference a ''zoneName'' parameter can use the Field as a value, with a few exceptions which are listed below:

=== Move This ===
Any skill that uses the following Card Action:
    Move this to Field
Will move the Card to the Party Field if used by an Actor, and will create a Card for the Troop Field if used by an Enemy. This means that it will behave normally for an Actor, but will be reinterpreted as the "Add X to Field" Card Action when used by an Enemy. This is a means of ensuring that the same Field Cards and Creature Cards can be used for Actors and Enemies.

=== Selection ===
When using [[plugin-card-action-pack-1#selection_card_actions|Selection Card Actions]], there are new Actions you should use to select from the Field.

    Select X from unitName Field
    Select X Type typeName from unitName Field

With normal Selection Actions, it is assumed the player is selecting from their own Zones, or the Zones of their targets. Since the Field has different properties, it is required that you specify which Unit's Field you are selecting from.

Below is a breakdown of possible ''unitName'' values:
| **Ally** | This will select from the Field of the user. |
| **Opponent** | This will select from the Field of the opposing battler from the user. |
| **Party** | This will select from the player's Field regardless of which side is using the skill. |
| **Troop** | This will select from the Troop Field regardless of which side is using the skill. |

Ex:
    Select 2 Type Spell from Ally Field
This would make the player select 2 Cards from their own Field with the Card Type "Spell."

====== Field Skills ======

Field Skills are Skills which a Card can execute while on the field. Yes, you are attaching skills to a skill. This means that you can select that card and open a menu of skills to execute. 

Any skill executed this way will use the stats of the owner of that card for damage formulas. Similarly, any resources those skills cost will be paid by the owner.

Field Skills can be set through the following notetag structure:

   <Field Skills>
   Skill X
   Skill X Limit Y per Turn
   Skill X Limit Y per Battle
   </Field Skills>

Replace 'X' with a Skill ID.
(Optional) replace 'Y' with the amount of times a skill can be used within a turn/battle.

If a card is removed from the Field and then placed again, its per-battle skills are refreshed.

The <Field Skills> notetag should be placed inside the Skills database for a Field Card and inside the Enemies database for a Creature.

===== Start/End of Turn Forced Actions =====

In base CGC, cards in the hand have access to Card Passives which force actions at the start or end of a turn. Here you can do the same thing for the field.

A card can have effects that trigger at the start or end of a turn if they are on the Field, using the following notetag structure:

    <Card Passives>
    Start of Turn Field: Skill X
    End of Turn Field: Skill X
    </Card Passives>

Replace 'X' with a Skill ID.

This should go inside the Skills database regardless of whether this is for a Field Card or a Creature Card, as it belongs to the card itself.

====== Creatures ======

Creatures are a special Battler which are added to the Field. Creatures inherit behavior from Enemies and are made from the Enemies database, but can exist on either Field.

Because Creatures inherit from Enemies, they have access to all of the stats that Enemies have. Barring any incompatibility, they also benefit from any other plugins that augment Enemies.

===== Behavior and Mechanics =====

Creatures can execute Field Skills on the Player's turn and Action Patterns at the end of the turn. 

==== Field Skills ====

While a Field Card's Field Skills will use the Actor/Enemy's stats for damage calculation, a Creature's Field Skills will use the Creature's own stats, as the Creature will be the one considered executing the skill. However, any Card Actions executed will still be technically executed by the summoner.

The Enemy AI will not make use of Field Skills, and will instead use Action Patterns to determine what skills a Creature will use. The Troop Field's Creatures are using RPG Maker's Enemy AI system to determine actions, and thus can be affected by plugins that change that behavior.

==== Action Patterns ====

Action Patterns are RPG Maker's means of determining Enemy AI, found in the Enemies database, and Creatures inherit this behavior.

Creatures will automatically attack at the end of the turn its Action Patterns. Creatures move after their respective summoners in the turn order. Both Party Field and Troop Field Creatures will use these Action Patterns unless the Ignore Action Patterns For Player passive is in use, as detailed in the following section.

==== Creature Passives ====

Creatures have passive notetags which use the following syntax inside the Enemies Database:
    <Creature Passives>
    passive
    passive
    </Creature Passives>

The Creature Passives include:

    First turn attack: true/false

This will override the default behavior for whether or not Creatures have access to their skills on the same turn they are summoned. Set the default behavior through Plugin Parameters.

    Ignore Action Patterns for Player

This will prevent a Player-side Creature from auto-attacking using Action Patterns. This is useful when you want the same Creature to be used by the party and by the enemy troop - the player's options inside Field Skills and the enemies' options inside Action Patterns.

===== Summoning and Appearance =====

Inside a card, you can set it to summon a Creature when it moves to the Field through the following Skill Notetag:
    <Field Creature ID: X>
Replace 'X' with an Enemy ID.

When a card summons a Creature by moving to the field, the card is made invisible, but is still present underneath the Creature. When a Creature's HP reaches 0, its card is moved to the discard. Likewise, if a card is moved off of the field, its Creature dies.

An animation can be played on the Creature when it is summoned by using the following Skill Notetag:

    <Summon Animation ID: X>

Replace 'X' with an Animation ID.

The specific placement of a Creature within the Field is relative to what RPG Maker considers its "center point," which is its center bottom in MV and its actual center in MZ. You can offset the location it will spawn in its place in the field using the following Enemy Notetags:

    <Grid Offset X: Z>
    <Grid Offset Y: Z>
  
Replace 'Z' with a number, positive or negative.

==== Creatures' Stat Display ====

Creatures are made up of Enemies, and as such have all of the stat parameters that enemies have. In most games, the relevant stats need to be made visible. 

Using the Stats to Display param, you can specify which stats will appear on the Creature, their coordinates relative to the center of the Enemy Sprite, and whether they display on a Card with a <Field creature ID> notetag.


You can also specify if the stat will show on all creatures. If you set the Show on All Creatures? to false, the stat will not appear on any Creature or Card by default.

You can override default display behavior by using the following notetags:

   <Show Stat X>
   <Hide Stat X>

Replace 'X' with the stat/param associated with the Stat Display.

Stat Displays also have a list of Text Color Conditions, which determine what color the text will be that displays the stat. This allows you to use a system where a number changes color when it lowers.

Each item in the list contains a color and a condition.
  * The color should be a hex value, though [[https://htmlcolorcodes.com/color-names/|some color names]] are also accepted.
  * The condition is code which evaluates to true or false.

The Stat Display will use the color of the first condition that returns true in the list.

===== Summons Scope =====

Base RPG Maker allows you to select the Scope of a skill, which determines who can be targeted for it. The addition of Creatures complicates this, and so you should work both with RPG Maker's Scope menu and the system below in tandem to get the scope you want.

By default, all skills can target both Battlers and Creatures, and you can modify this with the following notetags:

    <Card Summons Scope>
    Battler
    </Card Summons Scope>

    <Card Summons Scope>
    Creature
    </Card Summons Scope>

In addition, scope can be made to include Battlers or individual Creatures when certain conditions are met, like so:

    <Card Summons Scope>
    if [expression]
    Creature
    </Card Summons Scope>

These if expressions are similar to the If Action in the Core Engine. They evaluate a code expression.

However, in this condition the user has access to the variable "target", which represents any given Creature or Battler, and can be used to evaluate if that specific target is valid for the scope.

For example:

    <Card Summons Scope>
    Battler
    if target.hp >= target.mhp
    Creature
    </Card Summons Scope>

In the above example, a skill could target the opponent Battler, and any Creature whose HP is greater than or equal to their Max HP - any Creature who hasn't taken damage.

Creatures that cannot be targeted will be greyed out during selection.

Another example:

    <Card Summons Scope>
    if target.friendsUnit().fieldCreatures().count == 0
    Battler
    if user.mp < user.mmp
    Creature
    </Card Summons Scope>

The above example could target the opponent Battler only if there are no Creatures on their side of the field. It also can only target Creatures if the user's MP is not full. If neither condition is met there are no valid targets.

===== Card Actions =====

^  Card Action Syntax  ^ Description  ^
|  <code>Select X from unitName Field</code>  |Replace 'X' with a number or game variable, and replace 'unitName' with 'Ally', 'Opponent', 'Party', or 'Troop'. This activates the respective Field to select the specified number of Cards.  |
|  <code>Select X Type typeName from unitName Field</code>  |Replace 'X' with a number or game variable, and replace 'unitName' with 'Ally', 'Opponent', 'Party', or 'Troop'. Replace 'typeName' with a Card Type. This activates the respective Field to select the specified number of Cards, only being able to select the specified Type.  |
|  <code>Select All from unitName Field
Select All Type typeName from unitName Field</code>  |Works just like the above two Card Actions, but automatically selects all available Cards on the field. |
|  <code>Use Skill X on Selected</code>  |Replace 'X' with a number or game variable. This performs a skill matching the ID of X on any Creatures selected using the above Select actions, using the Battler performing this Card Action as the subject for damage calculation.  |
|  <code>Battle Log: message</code>  |Replace 'message' with text. This will push that text to the Battle Log.  |
|  <code>Add X to Opponent Field</code>  |This adds a Card of the specified skill to the opponent's Field.  |
===== Enemy Status Window =====

The Enemy Status Window behaves like the Actor Status Window from [[plugin-party-ui-a|Party UI A]], except that it showcases the Enemy in charge of a given battle. As such it reuses the values given to the parameters for the Actor Status Window.

However, Enemies do not have Face images like Actors do. For this reason, you have a few options for how to display the appearance of the Enemy within the window within the Display Enemy Mode parameter:

| **Mugshot** | This takes a cropped section of the Enemy sprite and puts it in the corner of the window in the same way the Actor Status Window crops the Actor's Face image. |
| **Full Image** | This shows the entire Enemy sprite inside the window, behind all text components. |
| **None** | This does not display the Enemy sprite at all within the Window. |

In the Enemies database, you can adjust the position of the Enemy sprite within the Enemy Status Window using the following notetags:

    <Status Window Offset X: Z>
    <Status Window Offset Y: Z>

Replace 'Z' with a number, positive or negative.

In Mugshot mode, this will determine what section of the Enemy Sprite is cropped within the corner of the window.
In Full Image mode, this will determine the placement of the Enemy Sprite within the window.

===== Debug Mode =====

Card Summons has a Debug feature which may be useful for lining up parameters.

If the user hits F11 in battle during a playtest, some debug visuals will appear that show each side's field grid based on the user's parameters, as well as the "center" of Cards and Creatures.

This can help the user set their parameters to match up with the images they're using to represent the field.

===== Plugin Commands =====

^  Command Syntax  ^  Event Usage  ^  Description  ^
| <code>DisableCardField</code> |  Map Only  | Disables the Summons Field and returns to normal CGC battle. |
| <code>EnableCardField</code> |  Map Only  | Enables the Summons Field if it's been disabled. |
====== Parameters ======

^  Field Grid Settings  ^^
| **Grid Width** | The amount of squares wide the Field is for each side. |
| **Grid Height** | The amount of squares tall the Field is for each side. Width * Height = The total amount of cards that can move onto the Field. |
| **Tile Width** | The amount of pixels wide each tile on the Field is. When Cards move to the Field, they move to the center of the first available tile. |
| **Tile Height** | The amount of pixels tall each tile on the Field is. |
| **Troop Field Image** | The image in img/CGC/summons that makes up the troop's Field. |
| **Troop Field Position** | The coordinates for the troop's Field. This will determine the top-left placement of the Field Image. |
| **Party Field Image** | The image in img/CGC/summons that makes up the party's Field. |
| **Party Field Position** | The coordinates for the party's Field. This will determine the top-left placement of the Field Image. |
| **Grid Tile Offset** | The pixel offset between where the image coordinates are and where the tiles are computed. Essentially, the pixel coordinate of each Field Image for where the first Tile is. This value is used for both the Party Field and the Troop Field. |
| **Troop Selection Image** | The image in img/CGC/summons that makes up the highlight for a Tile in the Troop Field. |
| **Party  Selection Image** | The image in img/CGC/summons that makes up the highlight for a Tile in the Party Field. |

^  Field Zone Info  ^ This is a struct much like the Zone structs, simplified to remove extraneous information. ^
| **Card Scale** | The scale Cards will become as they move to this Zone. Set this to a value less than 1 if you want cards to shrink as they approach the Zone, and greater than 1 if you want them to grow. ||
| **Skew** | This parameter contains X/Y values that can be used together to simulate isometric 3D rotation. Like Scale, Cards will change their skew to match this value when they enter this Zone. ||
| **Card Rotation** | Card Rotation is measured in degrees between -360 and 360. ||
| **Card Enter SFX** | The SE that will play when a Card enters this Zone. Leave blank for no SE. ||
| **Card Enter SFX** | The SE that will play when a Card exits this Zone. Leave blank for no SE. ||
| **Card Actions on Empty** | See [[card-actions#card_actions_on_empty|Card Actions on Empty]] ||

^  Creature Behavior  ^^
| **Attack First Turn?** | The default behavior for whether Creatures can attack in the same turn they're summoned. This can be overridden using the First Turn Attack Creature Passive in notetags. |
| **Animation Scale** | The scale for attack animations when targeting Creatures. |

^  Creature Stats  ^^
| **Stats to Display** | This is an array of Stat Display setting structs, which will be detailed in the table below this one. |
| **Font Size** | The font size for the value of stats inside Stat Displays. |
| **Font Face** | The name of the font used to display stat text for creatures. Use "GameFont" for default. |

^  Stat Display  ^ The struct inside the Stats to Display parameter. ^^
| **Parameter** | The name of the stat/parameter for this Stat Display to display. Eg., atk, mhp, hp, etc. ||
| **Coordinates** | The position relative to the bottom center of the Creature for this stat to display. ||
| **Display on Card?** | Determines whether this Stat Display will appear on Cards with a <Field Creature ID> notetag. ||
| **Card Coordinates** | The position relative to the center of the Card for this stat to display, if Display on Card? is set to True. ||
| **Background Image** | The image to draw behind the text, in img/CGC/summons. ||
| **Text Color Conditions** | This is a list of colors and conditions for the stat text to display in that color. ||
| ::: | **Text Color** | The hexcode value for the text to be under this condition. Some color names also work. |
| ::: | **Condition** | An expression that evaluates to true/false. Use battler.statName, value, or originalValue. |

^  Field Skill Window  ^ This is the window that opens when you select a Creature or Field Card to use its Field Skills. ^
| **Static Position** | The default position of the window. |
| **Follow Conditions** | Determines whether the Field Skill Window follows the currently selected tile on the Field at an offset. If false, it will use the Static Position instead. |
| **Follow Offset** | Determines the offset value of the window relative to the selected tile. Ignore if Follow Conditions is false. |

^ Enemy Status Window ^ This is the window that displays the Enemy's status. ^^
| **Display Enemy Mode** | Determines how the Enemy Status Window visually displays the Enemy. Options are: ||
| ::: | **Mugshot** | This takes a cropped section of the Enemy sprite and puts it in the corner of the window in the same way the Actor Status Window crops the Actor's Face image. |
| ::: | **Full Image** | This shows the entire Enemy sprite inside the window, behind all text components. |
| ::: | **None** | This does not display the Enemy sprite at all within the Window. |
====== Version History ======

<code>
**v1.0.5**
- Fixed bug where Creature Stat fonts wouldn't work properly in MZ.
- Fixed default Parameter values being missing leading to a crash if not properly initialized by the user.
- Fixed Select All Type typeName from Ally/Opponent Field not working properly. 
- Implemented system to use default values if Plugin Parameters are not filled out.
- Card Type names inside Card Actions now support all languages.
- Added Card Action Add X to Ally/Opponent/Troop/Party Field.

**v1.0.4**
- Fixed Card Summons Scope being unable to reference 'this' in its conditional eval.
- Added utility function card.refundFieldSkilluse(index, amount)
- The Require Card Passive now works on Field Creature Skills.
- Added Creature compatibility with TurnStartPlus.
- Improved timing for End Turn Field Skills.
- Added Message Warning infrastructure for multiple languages.

**v1.0.3**
- Added extra error handling when PartyUI_A is missing/below Card Summons, and when notetags reference an Enemy ID higher than is present in the project.

**v1.0.2**
- Fixed bug where Help Window would not open after using a Selection skill on the Field while using HelpBoxControl.

**v1.0.1**
- Fixed Use Skill on This Card Action targeting the wrong Creature when the Creature was not the most recently played Card.

**v1.0.0**
- Released plugin
</code>