Lua Lesson #4: Custom Champion Cards

In this lesson, we will be walking through creating custom champion cards and using them in Hero Realms Lua games. So far in this lesson series, we have covered actions/items. Champions, as you might expect, behave differently than actions/items because they are played from your hand into the “inPlay” location on the left side of your screen and remain there every turn until stunned. This means that a champion’s abilities can be activated every turn and in some cases multiple times in one turn. When stunned, they go to the discard pile like any other card. Fortunately, the Hero Realms game engine handles most of the tedious part of preparing each champion in play as well as triggering a few of their abilities automatically at the start of your turn. It also handles the interaction of your opponent attacking/stunning them. We will also be taking a first look at using Lua selectors to apply effects to specific cards.

As in the other lessons, here is the link to the final product Lua script that goes with this lesson for you to get started with. Give the comments a read as you go so you understand the new keywords associated with a champion card such as their health.

Designing the Champion Card

A champion has a completely different layout than items/actions. There is a health (shield) indicator in the lower right corner that designates the amount of damage the champion takes to destroy. It can also be a black icon, meaning the champion is a guard. On the right, you can see the custom champion we will be making in this lesson.

To make this champion, I started with this layout I borrowed from the Lua Doc. I covered how to take a layout like this and transform it to your needs (in lesson #2). The big white arrow icon implies the champion will be expended in order to activate the ability.

The Layout

Here is the layout portion of the Lua file. The only thing here that is different than an item or an action is that the “cardTypeLabel” is “Champion” so it displays at the top of the card.

Making the Champion Function

Here is the champion object data creation section which is broken down in the next segment.

Since we are creating a champion, the Lua function “createChampionDef” is used. This identifies this card as a champion so it interacts with the rest of the Hero Realms engine as expected. Since this is a champion, two new keywords need to be set up, “health” and “isGuard.” The first determines how much damage is needed to stun the champion, and the second marks it as a guard that must be stunned before you can attack other non-guards.

The last thing to mention here is that Hero Realms has several “types” of things you can associate with your cards to get them to interact in new ways. You could add “bowType” to a card to get it to work with ranger arrows, for example. You can also invent your own new types by putting them in the types array of a card. If you use a type that is in the Lua doc (ie HR official) it will show up on the side of the card in-game when you go to view the details (ie Ef as seen to the right). If you use a custom type, it will not display but you can still use the type in the places in your Lua file and it will function.

The Champion’s Abilities

Here are the champions ability definitions. As previously mentioned, champions stay on the field and are expended to activate their ability every turn. Unless there is another card ability preparing them, this normally only happens once.

The Primary Ability

By convention, if the only effects an ability has are gaining gold/combat/healing, the ability is automatically triggered at the start of the players turn. Since the main ability (baitMain) here is just gain 3 combat, the ability has an auto trigger that will go off at the start of the turn. Because this ability belongs to a champion, the cost for this ability is “ExpendCost” so the ability wont trigger again in the same turn. Many other things such as skills/abilities/armor use the “Expended” state to denote something has already been used. It is more important for the champion because there are other HR cards that can alter this state by “expending/preparing” champions.

The Sacrifice Ability

A champion that sacrifices itself is not a common ability you find in actual HR cards. Champions make their mark on the game by staying in play as long as possible or soaking up the opponent’s damage to take them out. I chose to use one in this lesson because sacrifice abilities are “activation” ability. You decide when you want to do it and toggle it from the cards UI. That is why the sacrifice ability (baitSacrifice) has a UI trigger. Once the ability resolves, the card is automatically sacrificed by the cost.

In order to understand how this ability works there are 3 new HR Lua topics that need to be explained.

• • Effect Sequencing

    • • If you want one effect (A) to happen before another (B) you need to use the .seq() wrapper like this A.seq(B) and A will fully resolve before B does.
    • • This is necessary for this ability because you want the player to draw 2 cards first and then discard 1.
    • • You can chain as many effects together as needed A.seq(B).seq(C)…..

• • Targeted Effects

    • • In order to allow the player to make a selection of which card(s) to use in an effect, you need to use a “pushTargetEffect” effect.
    • • This will tell the player how many cards to select and highlights the cards that are even valid for targeting.
    • • There is a min/max number of choices so a user can opt to not use all of them (when you see “Select None” in game.)
    • • Once cards are targeted, the “targetedEffect” will then occur to each of the targets which in this case is being discarded.

• • Selectors

    • • Selectors are a bit of a broad topic and maybe one rung up on the Lua difficulty ladder than this lesson is targeted towards but I will breach the subject now because they will come up again later.
    • • You can read up on them in the Lua Doc for all the details.
    • • The TLDR for now is that there is a programmatic method for selecting any card/skill/ability/armor/buff in any location hand/deck/discard/market which is also able to differentiate between both players (current vs opponent.)
    • • For this ability, we want the player to pick a card in their own hand to discard so we set that up in the “validTargets” keyword.
    • • selectLoc() is a function that selects a location and loc() is a function that denotes a specific location. “currentPid” is the player ID of the current turn player and “handPloc” is the player location for the hand.
    • • When you put it all together , “selectLoc(loc(currentPid,handPloc))” selects the current player’s hand.

After getting the “effect” keyword formatted correctly (see previous image) it will now give you the desired ability as printed on the card and the player will active it, draw 2 and then discard 1 from their hand. The champion card is then sent to the sacrificed area by the game engine.

Time to Test

As previously covered in the other lessons, the last step is to declare the card in the game setup and add the card to a player’s deck.

Now you can run the script and see the end result. I suggest taking some time to try making some tweaks to the file to see what else you can get the champion to do.

Thanks for making it to the end of the lesson and as always, feel free to reach out with any questions and I hope to see you back for Lua Lesson #5