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/aW1nLzE4Nzc0MDU1LnBuZw==/original/PsSsOo.png?nolink&690}}

//**This page is a work in progress, and will be updating periodically.**//

This plugin allows you to control the appearance of cards through a layer system. This allows the addition of Layers and Badges.

Layers are image components that have a **Priority** value which determines the order in which they appear, with the lowest value being the farthest back and the highest being the farthest in front. Default Layers have the following Priorities:
|  **Back**  |  0  |
|  **Base**  |  100  |
|  **Art**  |  200  |
|  **Text**  |  300  |
|  **Highlight**  |  400  |

Any Custom Layer added will have Priority values between these. So for instance if you have a Custom Layer with a Priority of 250 it will appear above the Art layer but behind the Text layer.

If a card is "flipped over" by inverting its scale or skew, all layers will reorder so that the lowest Priority layer is in front.

Badges are special components that have an image property and a text property.

===== Layer Properties =====

Card Art Layer elements all have the following properties:

|  **Name**  | The name of the Layer. |
|  **Priority**  | A number representing the order of all Elements in the Card. Higher number means farther in front. |
|  **Image**  | The image of the Layer, located in img/CGC/bases for the Back and Base Layers and in img/CGC/art for all other Layers |
|  **Position Offset**  | The offset position of the Layer. |
|  **Condition**  | A code expression that evalues whether the Layer is visible (true) or not (false). The condition evaluates once when the Card Sprite is first created and then again after  battler has taken an action in Battle if the Refresh Layer Visibility parameter is set to true. |
===== Default Layers =====

Default Layers are the Layers that are present for all Cards. Their names and Priorities cannot be changed.

Back and Base images are located in img/CGC/bases, all other images are in img/CGC/art.

|  **Back**  | The layer that appears behind all other layers. This image actually renders backwards. This is because when a card is "flipped over" all components appear backwards, and so by flipping the Back layer to begin with it actually looks correct.\\ \\ If the Back's image is set to "%default", then it will use the following logic:\\ 1. If it has a Card Type that has a Card Back parameter, it will use that.\\ 2. Else it will use DefaultBack.png |
|  **Base**  | The layer that is designed to be uniform across all cards or all cards of a given Type or other group. This represents the "frame" of the card. It's recommended to be the same size as the Back so that the Back is only visible while the card is flipped over.\\ The Base determines the dimensions of the card for purposes of placing any other layer components and for touch input hitboxes.\\ \\ If its image is set to "%default" then the Card will use vanilla CGC logic to determine its card base. That logic being:\\ 1. If it has a <Card Base: fileName> tag, use that image.\\ 2. If it has a Card Type that has a Card Base parameter, it will use that.\\ 3. Else it will use Default.png |
|  **Art**  | The layer that is designed to be unique per skill.\\ \\ If its image is set to "$default" then the Card will use the vanilla CGC logic to determine the card art. That logic being:\\ 1. If it has a <Card Art: fileName> tag, use that image.\\ 2. Else it will use the skill's icon scaled up. |
|  **Text**  | The layer that holds all of the text on the card.\\ \\ This Default Layer does not have an image component because it is designed to be an empty canvas on which the text is written. |
|  **Highlight**  | The layer that contains the Highlights. |

This Default Layer also does not have an image component because Cards contain multiple highlights at once to ensure a smooth transition between states of highlight. This Layer represents all Highlights.

Default Layers, like all layers, can have their values overridden through Skill Notetags.

===== Custom Layers =====

You can define your own Layers which have their own images, offsets, and conditions. These layers will not appear on Cards automatically but instead can be added to specific Cards through Skill Notetags.

Additionally, Custom Layers can be defined entirely through Skill Notetags.
===== Notetags =====

Layers can be added to or changed for a Card using the following Skill Notetag structure:
<code>
<Card Art Layers>
Layer1
Layer2
Layer3
</Card Art Layers>
</code>

Layer properties can be overridden inside these notetags with the following syntax:
<code>
<Card Art Layers>
LayerName (Priority): ImageName | X Y | Condition
</Card Art Layers>
</code>

|  **LayerName**  | The name of the Layer whose values are being overridden. Can have spaces and is case-insensitive. |
| **Priority** | A number from 1 to 500 that overrides the default Priority of the layer. Note this will do nothing for Default Layers. |
| **ImageName** | The name of the image file to use for the Layer. Can have spaces. |
| **X** | The new X offset |
| **Y** | The new Y offset |
| **Condition** | The new condition for the Layer. |

Each one of these components are optional. If a component is not present the Layer will use the default values defined through plugin parameters. The | dividers are still neccessary to override a later property if you aren't overriding an early one.

Example:
<code>
<Card Art Layers>
Dragon
HidingDragon (110)
AboveText: Red Dragon | | user.level > 5
SideDragon (410): SideDragon | 60 -10 | true
</Card Art Layers>
</code>

In the above example, the layer "Dragon" is using all of the values defined through the Custom Layers plugin parameter, so no other components need to be written out.

The "HidingDragon" layer has its Priority set to 110, which is above the Base Layer but below the Art Layer, overriding whatever previous values were set in plugin parameters.

The "AboveText" layer is overriding the Image and Condition components but leaving the Offset component to its default values.

The SideDragon layer is defining each individual component. In this case, SideDragon does not need to be defined through plugin parameters.

Now, in this above example, the Default Layers are not present in the list of Layers. They do not need to be as they are always present on the Card. However, you can include them in the notetags to override default values.

Example:
<code>
<Card Art Layers>
Base: DragonBase
Art: Dragon | 40 40
Highlight: | | false
</Card Art Layers>
</code>

In this example, we are overriding the images for both the Base and the Art Layers. We are also moving the Art Layer 40 pixels down and to the right. Finally, we are making the Highlight layer invisible. These changes apply only to the Skill in which these notetags are present.
===== Badges =====

Badges are special components that have an image property and a text property. Badges have the following properties:

| **Name** | The name of the Badge. |
| **Priority** | A number representing the order of all Elements in the Card. Higher number means farther in front. |
| **Image** | The image of the Badge, located in img/CGC/art. |
| **Position Offset** | The offset position of the Badge. |
| **Text** | A code expression that evaluates into text. More about that below. |
| **Font Settings** | |
| //Font Face// | The font for the text to use. Use GameFont for the project's font. |
| //Font Size// | The font size for the text. |
| **Text Color** | A hexcode for the text color, though certain color |

===== Badge Text =====

The Text property is not a simple text input, but instead code which evaluates into text. In programming, a string of text, referred to simply as a string, is formatted with quotation marks. So if you want static text, you should format it like this:

"Hello World!"     <- would work

instead of like this

Hello World!       <- would NOT work

This property is code so that it can display variables more easily.

Example:
<code>
user.mp + " MP"
</code>

This example would display "3 MP" while the owner of the card had 3 MP.

There are three variables you can use in the Text property to make referencing variables you want easier.

<code>
user - The Actor that owns the card.
card - The Card object itself.
skill - The Skill that the Card is a copy of.
</code>

Examples of how you might use these:

<code>
"LVL " + user.level
card.origin().toUpperCase()
skill.mpCost
</code>

If you're using MYTH_CGC_IndependantCardVariables you can use:
<code>
card.cardVar(1)
</code>

===== Badge Notetags =====

Badge notetags work similarly to Layer notetags and use the following syntax:

<code>
BadgeName (Priority): TextCode | ImageName | X Y | Condition
</code>

|  **BadgeName**  | The name of the Badge whose values are being defined/overridden. Can have spaces and is case-insensitive. |
| **Priority** | A number from 1 to 500 that overrides the default Priority of the badge. |
| **TextCode** | The code that returns the text for the Badge to display. |
| **ImageName** | The name of the image file to use for the Badge. Can have spaces. |
| **X** | The new X offset |
| **Y** | The new Y offset |
| **Condition** | The new condition for the Badge. |

Just like with Layers, you can use notetags to define entirely new Badges or override the values defined through the Custom Badges plugin parameter.
===== Conditions =====

The Condition property determines whether a Layer or Badge is visible. If it returns true, the component is visible, and if it returns false it is invisible.

Note that because Badges are attached to Layers, if a Badge's parent Layer is invisible, it will be invisible too.

Just like with Badge Text, you have three variables you can use to make this evaluation more flexible:
<code>
user - The Actor that owns the card.
card - The Card object itself.
skill - The Skill that the Card is a copy of.
</code>
===== Refreshing =====

The two plugin params - Refresh Layer Visibility? and Refresh Badge Values? determine whether or not Cards will reevaluate each layer and badge's visibility and text after each action in battle.

Depending on the needs of your project, you may prefer to set one or both of these to false. If you have many layers and badges, and many cards, the impact that refreshing has on performance increases exponentially.

On the other hand, a project that has only a few layers but badges that display valuable information may want to disable refreshing for layers and keep badge refreshing enabled.
===== Misc =====

This plugin makes the spawning of Card Sprites more expensive, and more likely to impact performance. We have found that for projects with a medium number of cards in play at a time (40-90) that setting all Zones' "Show Cards?" parameter to "Behind image" or "In front" mitigates this issue.

This frontloads the spawning of Card Sprites to the beginning of battle, during the loading screen between the map and battle. Once loaded in, all cards stay loaded in and do not impact performance.