Modding Guide – Abilities – The Hand of Merlin

Modding Guide – Abilities – The Hand of Merlin 1 -
Modding Guide – Abilities – The Hand of Merlin 1 -

Extensive and detailed guide for creating new abilities or modifying existing abilities in The Hand of Merlin, written by its game designer Mat.


  • Introduction
  • Identification – How to set up the file, its ID and Description strings
  • Basic Configuration – Set which Class the ability is for, as well as its Category and Type
  • Targeting – Set where and how to aim and use the ability
  • Visuals – VFX and Projectiles
  • Costs – AP, Mana, Charges, and Cooldownds
  • Triggered Effects – What does it do, how, when, and why
  • Upgrades – Setup what your ability upgrades to
  • Complex Behaviours – Make it special



Creating new abilities in The Hand of Merlin

Hello! I’m Mat, Game designer for The Hand of Merlin. Now that our editor is available to the wider public, I’d like to write up a few guides on how to create some content in our game for your modding purposes.
In this guide, I’d like to start with Abilities!
As an example, we’ll be creating a Ranger ability called Pin Down.
Modding Guide - Abilities - The Hand of Merlin - Introduction - 2571FBA41

What is an Ability?

These are actions that units perform in the combat state. These can be skills that the characters learn as they level, spells associated with a core, or even abilities given by special relics. We’ll be creating each of those other entities in the next few guides.
Abilities are stored in Resource (.rsc) files in the Content/Merlin/Abilities folder.
To create a new one, you can go to File, click New, and then Document, or just use the Ctrl+N hotkey. In the dialog box that pops up, choose the Generic group, and the (Merlin) Ability Params. Type. Then, press OK.
Modding Guide - Abilities - The Hand of Merlin - Introduction - 9DC5F3981
You’ll be drawn to the ability inspector. There’s a lot to unpack here, and we’ll do it in a second. But first, let’s save this ability. Go to File and choose Save (or use the Ctrl+S hotkey), and save your file in the Content/Merlin/Abilities folder – this is important if you want the game to use your ability for level up purposes!
Modding Guide - Abilities - The Hand of Merlin - Introduction - 0F6EBD24C
Now that your work is saved, let’s get cracking.


What’s your ability called?

A good place to start is the first four entries in our ability – Name, Description, Icon, and Branch.
Modding Guide - Abilities - The Hand of Merlin - Identification - 8F2466E25
They are quite self-explanatory, but have a few interesting quirks. Let’s start with the first two.
Name is the title of your ability, in our case Pin Down.
Description is the tooltip associated with the ability, such as “Deal 5 damage and apply 1 stack of Rooted to a target”.
Because these are text properties, you have two fill in two fields: the Identifier and the String. This is to make it easier for translations. If you are making a big mod, you might want to have your own identifier naming conventions, but here’s ours: we use HOM.Ability.[AbilityName] for names, and HOM.Ability.[AbilityName].Description for the descriptions.
Modding Guide - Abilities - The Hand of Merlin - Identification - 3CBF1FBDA
Now, let’s look at the actual description of the ability:
Deal <special>{dmg}</special> damage to a target, and apply <special>{eff.strength}</special> stacks of <debuff>{eff}</debuff>.
So many tags!
<special></special> is a wrapper you can use when you want that part of the text to be accented. We have several of these, described in Merlin/databases/DescriptionParser.rsc, but unless you want to change something, you can just use four:

  • <special> for white bold text
  • <debuff> for the purple debuff text
  • <buff> for the blue buff text
  • <marker> for the yellow passive text

The {dmg}, {eff} and {eff.strength} things are to be filled in dynamically by the game, in a way that we’ll set up. For Pin Down, I want damage to just be equal to the Power attribute of a character, so there’s no way I can know that value while I’m making my skill: That’s why I use these ID objects. We’ll talk more about them when we are actually adding triggered effects later in this document, but remember that you can use the period ( . ) to access entries of a specific effect, like we did for eff.strength – the “strength” entry of the “eff” effect.
Next up, we have an Icon to select. The Icon entry only accepts .tex files, which is a sort of “curated” png. If you have an image already prepared, you can browse it here. We recommend 88×88 as a good icon size.
You can create your own .tex files by using the Texture>Create new texture dialog, or via the Ctrl+Shift+T hotkey.
Finally, in the same vein, you can add Branches. These are the names of the small sub-icons that some abilities have, shown in the action bar. In the base game, we add them to tier-3 upgrades, like the green diamond here:
Modding Guide - Abilities - The Hand of Merlin - Identification - 77FBF8491
For Pin Down, we won’t be using those. We’ll be browsing the Suppression_CM texture, though. Adding it all together, this is how our ability currently looks like in game.
Modding Guide - Abilities - The Hand of Merlin - Identification - 372F56F05
Don’t worry about the red text, it’s a sign the game doesn’t know what to put in place of the {dmg} or the {eff} stuff we put it in the description. We’ll fill these in later.

Base Configuration

What is your ability for?

Now, we’ll start configuring how the ability behaves, and where the players can see them. Note the next few entries:
Modding Guide - Abilities - The Hand of Merlin - Base Configuration - ACFA801C5
These are quite simple, but serve to help the game understand what ability you are making.

  • Unit Role – fill this in with Tank(Warrior), Nuker(Ranger) or Support(Mystic) if you want this ability to show up as a possible option when characters pick new abilities at Rank 2 and 3.
  • Skill Category – This is where you describe if your ability is Offensive,Defensive or Utility. This doesn’t do anything on its own, but interfaces with other mechanics, such as the Staggered status effect disabling Offensive abilities. If you want to follow our guidelines, use Offensive for anything that deals damage, and Defensive (which is seen as “Support” in-game) for anything else that the player can use. Finally, use Utility for abilities that are hidden mechanics and are not seen by the player.
  • Ability Type – this is where you determine if an ability is a Spell or a Skill. This is important – Spells interact differently with some in-game effects, such as the Resistance status effect. In the base game, we save the Spell type for the magical effects of Guardians, which usually cost mana.
  • Ability Tags – This is automatically detected! If you add a debuffing property to your ability, like I have, it will get the Debuffing tag. Some game effects can use these properties, like a relic that grants you power whenever you are hit with a debuff effect!
  • Execution Model – This is an important one! You have three choices – Attack, Run and Teleport. This choice dictates how the ability functions and the way it does its effects. Use Run for movement abilities, Teleport for self teleportation effects, and Attack for anything else.

Pin down is a Nuker Offensive ability, of the Skill type. It has the Damaging, Debuffing and Skill tags, and the Attack execution model.


How do I use your ability?

Now, we come to the Targeting configuration. This is a tricky part, but it dictates how one can use your ability.
First off, let’s decide on a Targeting style. Most of the abilities are “Target with radius”, meaning that the player aims at a tile, and the effect happens on a radius off that tile. Your other option is “Direction with angle” for your cone-shaped abilities, like Noxious Fumes.
Then, we have three topics to worry about: Cast area, Effect Area, and Visualization.
Modding Guide - Abilities - The Hand of Merlin - Targeting - BC4BBA370
(1) is where you can cast the ability. It’s your range calculations, for the most part. The most important aspect is the Cast Area entry.
Modding Guide - Abilities - The Hand of Merlin - Targeting - 7A8E3FAF1
Here’s where you describe how far you can aim the ability. You can set up a maximum area, scale it from any attribute, and even make it behave like Run, where you can spend more action points to go farther. The above is our configuration for Pin Down. We add a 1.5 min range as most Ranger skills, to make it so that the target can’t target adjacent tiles (including diagonals!)
Then, we can work on Line of Sight . This is to describe how exactly your ability behaves around covers and other tiles. To work on those, we have to understand tile modificators.
The hand of Merlin has 8 tile modificators:

  • Deep and Low abyss signify deep or shallow holes in the ground. It usually means that it is unwalkable, but projectiles can be shot over.
  • Then, we have Walking Obstruction. These work like abysses, but they are created with props in the ground – think fireplaces and dead bodies! Usually, they are destructable, meaning that a well-placed bomb will clear that right up.
  • Low cover and High cover mean objects placed in the world of a certain size. They are usually destructible as well. Think boxes, tables, trees… Low means that they hit a human around the waist, and high is anything above shoulder height, ish. They are never really wakable.
  • Low and High Cliff work exactly like cover, but they are by terrain, and thus are not breakable. Small hills, cliffsides, that sort of thing.
  • Finally, we got units. Self-explanatory, I’d hope: these at the tiles where a unit is in!

Here, you can see a scenario with all tile types, as an example:
Modding Guide - Abilities - The Hand of Merlin - Targeting - B5A159D61
When deciding how your ability behaves around each tile type, you have three options: Soft, Hard or No Collision.

  • Hard means the ability is blocked, and cannot go further. In most abilities, this is for high cliffs and high covers.
  • Soft means that while the ability isn’t stopped at that tile, units adjacent to such a tile will gain cover benefits (60% extra evasion)
  • No Collision means the ability can pass through that tile type with no issues.

Finally, you can do two things: you can “exclude tiles”, which means that you cannot target a specific tile type (like our teleport spells being unable to target tiles already filled with units), and you can enable “sidestepping”, which allows a unit to try and angle their shot a bit.
To help you understand these topics, here’s a few comparison pictures. Let’s start with sidestepping. It works by allowing the unit to consider their adjacent tiles as possible starting points.
Modding Guide - Abilities - The Hand of Merlin - Targeting - 2C5B090FF
Modding Guide - Abilities - The Hand of Merlin - Targeting - 72BA07648
Note how, if we exclude covers, the outline carves out that space, and you can’t even aim there. I think it looks clean!
Modding Guide - Abilities - The Hand of Merlin - Targeting - 95A6C2162
Modding Guide - Abilities - The Hand of Merlin - Targeting - 28A019DB4
(2) works pretty much the same way, but now we’re talking about Area of Effect. I won’t explain it all again, but here’s where you’ll decide the AoE, if the ability propagates through which tile types (line of sight) starting from the tile the user picked as the origin. Hopefully, you can apply the same knowledge here.
(3) is a bit of UI. You can play around with how people can perceive the ability when they try to aim it. Here are two examples:

  • (Hallow) Casting area: Blue Outline, Blue Fill / Effect Area: Yellow outline, no Fill
    Modding Guide - Abilities - The Hand of Merlin - Targeting - 5575F55C0
  • (Lunge) Casting area: Blue Outline, Blue Fill / Effect Area: Yellow outline, no Fill
    Modding Guide - Abilities - The Hand of Merlin - Targeting - 7977DDFE6

Note that you can color the ability’s fill and outlines in unique colors! In the ability configuration, you can select a number from 0 to 15. These numbers relate to the “Generic Colors for Abilities” entry of the Skirmish State Params file, found in Content\Merlin\Databases. Note how each color looks doubled – we just have a version with low alpha in the even numbers, so you can put it on your fill entry.
Modding Guide - Abilities - The Hand of Merlin - Targeting - B817793C0
Now, you still have a couple options in the bottom of this category to explore. The allow/disallow feature in particular can come in handy when you are making an ability that only works when targeting covers or something like that.

For Pin Down, we’ll use pretty much the same configuration as we use in most ranger abilities. It is a projectile based, damaging ability with a single target, so here’s how the targeting looks like:
Modding Guide - Abilities - The Hand of Merlin - Targeting - 5FCD664B5


What does your ability look like?

There are a couple things we can do to make our ability look the way we want.
Modding Guide - Abilities - The Hand of Merlin - Visuals - 554AC5049
Animation is the model’s movement when playing the ability. It’s an important step, as some mechanics can wait for the animation to trigger them.
If you are implementing your own character, make sure that you name an animation that exists. Otherwise, I recommend using some of our general use animations Attack, Use_01 and Throw. Note that both the Mystic and the Ranger rely on projectiles in their Attack animations!
Related to this same topic, you can have the unit orient to target tile ticked. If it is, the unit will rotate towards the target when playing its animation. Most abilities do that, but you never know.
Then, you got Effect on Use. This takes what we call an Effect Preset, a resource file filled with sounds, visual effects, post processing profiles… all that good stuff. We’ll talk more about them at another guide, for you can put anything you want to happen at casting time, on the caster, here.
Finally, we got Projectile Delivery details. This is what you’ll configure if you want your ability to toss something towards a target. It’s mostly a visual entity, but often projectile abilities wait for the projectile to actually hit the target to perform the effects.
Modding Guide - Abilities - The Hand of Merlin - Visuals - BD942AE04
It is mostly self-explanatory, but take note of a few quirks:
A “Fixed flight duration” of -1 will make the projectile follow a more natural trajectory, and we tend to make most abilities be set at that value.
Travel and Arrival effect presets take those same Effect Presets we talked about.
The projectile params file defines the model and the velocity that the projectile will take. We have some ready made ones on Content\Merlin\Projectiles for you to peruse and adjust to your liking!


What’s the cost of your ability?

Here’s an easy one.
In The Hand of Merlin, abilities have “costs” and limits. Here’s what they mean:
Modding Guide - Abilities - The Hand of Merlin - Costs - ACFA801C5

  • AP – Action points. Units tend to start with 2.
  • Charges – how many times an ability can be used in a specific match. -1 means “no charges”
  • Mana – fuels spell effects, granted by your Guardian.
  • Cooldown – How frequently you can use this ability, in turns
  • Status Effect Condition – which status effects you need to have to use this ability (we don’t use that often!)

Also note a few extra options: you can make an ability require a specific amount of available AP to be used (“only usable if you have no AP left” or something), and overrides, meaning that you can start with a cooldown already active, or less than the maximum charges. Lots of design space for unique abilities there!

Triggered Effects

What does your ability do?

Alright! Finally, it’s time to work on actual mechanics. The Triggered Effects entry is where the magic happens.
Modding Guide - Abilities - The Hand of Merlin - Triggered Effects - EB111541C
You can set multiple Triggered Effects, and each one is defined by 3 entries, seen in #1 in the above image.
First of all, Target Source: Do you only check for units/tiles in the affected area (defined in the targeting entry) or do you want to affect all units in the map?
Then, Target Selection. This is for effects towards units. Do you get Foes, Friends, or Self? You can get any combination of the three.
Finally, Trigger Event – When does this series of effects happen? Most often, it’s ‘On Contact’, meaning when the animation is at its apex, or when a projectile is hit. You can have effects on Start and End of the sequence as well, if you prefer.

Now, each Triggered effect has two big parts: Effects on Units and effects on Tiles. Units are a bit more complicated, so let’s work on those before.
First, note #2. This is the basic configuration. The ID is that small piece we worked on the description, remember? The “{eff}” and the “{dmg}” symbols are looking for triggered effects with these IDs, as you can see there.
Then, you decide if this effect is optional. If it is, that means that the ability can be used even if this effect is impossible – say, if you have a shoot -type ability like this and the damage is optional, then you are able to target empty tiles! We usually have at least 1 effect set to not optional, to avoid that.
Then, you have the Effect Type. This is your biggest decision: What does this ability actually do?! Here’s a rundown of every single one for the Unit category. You’ll note that most of the other entries in this stage are ways for you to fill in the details for each effect type.

  • Heal – Restores a certain amount of Health, Armor or both, based on Life Change type and Effect Strength.
  • Damage – Similar to Heal, but it actually deals damage. This also triggers Wound animations and the like. Pin Down uses this for the damage property.
  • Knockback – Tosses an enemy in a direction, dictated by effect strength and point of origin. Can also trigger abilities when obstructed, as seen on the last few entries there.
  • Pull In – Similar to knockback, but inverse, bringing people to a point.
  • Change Class – turns an unit type into another, defined by Unit Params.
  • Grant AP – Grants Action Points to the target, as defined by effect strength.
  • Grant Status Effect – affected units gain stacks of a specific Status Effect, described in effect strength and the status effect entry. Pin Down uses this to grant 3 stacks of Slow.
  • Swap Places – Swaps caster with target unit. Be careful when allowing large units to swap with smaller units, as it can break positioning.
  • Apply Aura – Affected unit becomes an emitter of a specific aura. Effect Strength is passed to the aura, as is Duration.
  • Become Reactor

[/b] – This allows the affected unit to become a reactor, like in Archer’s Vigil. This is usually associated with a status effect and you can even set the flags to watch as well. More on Reaction trigger Flags later in this guide.

  • Change Ability Cooldown – You can modify the cooldown of specific abilities, all abilities, or just a specific kind (remember Ability Type?), based on effect strength.
  • Change Ability Charges – similar to Cooldown, but for ability charges.
  • Delay Ability – This is how the bandits use their bombs! You can set an ability to be cast when a listed status effect expires. Be careful – the targeting you set up for this ability will carry over to the other ability.
  • Gain Reaction Turn – This allows a unit to act immediately after this ability, injecting a turn.
  • Play Animation on Target – This forces an animation to play on the affected unit. We usually put “wound” animations in some debuffs abilities, even if they don’t deal damage.
  • Show Effects on Target – Remember Effect Presets? You can put some to play on each target unit when the effect is triggered
  • Cancel Reactions – This cancels a reaction that another unit is readying, like Bash does.
  • Cancel Delayed Abilities – Similar, but to delayed abilities.
  • Grant Mana to target’s Warband – This gives mana to the target’s warband equal to the effect strength. Works once per target, so be careful.
  • Expire Status effects – You can force a specific status effect, or types, to be instantly expired.
  • Show Combat Message – This plays a string on top of the affected unit. We tend to use this for those “Triggered – whatever” strings, to help clarify what’s going on.
  • [/list]
    That’s the basics, but feel free to explore.
    Do note: If your effect type uses something (like an Aura) and you haven`t browsed it, it’s likely to cause a crash. Likewise, avoid browsing entries that you don’t use. If your effect is not about adding an aura, make sure to leave the Aura entry as (none)!
    Now, let me show you another important thing – note #3, Conditions.
    Modding Guide - Abilities - The Hand of Merlin - Triggered Effects - 899F07CC9
    This is a great tool to implement conditional effects to your abilities, like “Against abominations, deals extra X damage”. There are many condition types, but they are easy to understand. Like with Triggered effects, most other entries here serve only to qualify whatever condition type you set up. Now, be careful – Conditions are not checked when in Optional effect check!
    Another thing: We talked a lot about #4 Effect Strength, but if it wasn’t clear enough, here’s a (hopefully) better breakdown:
    Modding Guide - Abilities - The Hand of Merlin - Triggered Effects - 19B47F2DA
    This “struct” will be found all over the place in The Hand of Merlin. Here, you have an add component and a mul component, and then an attribute. This is then resolved in a simple formula, where Result = (Attribute * Mul) + Add. In the case shown above, the result is equal to the Power attribute of the character, as there is no Add, and Mul is 1. This is our “damage” component for pin down!
    Now, a quick tangent to talk about Effects to Tiles. Some abilities target tiles instead of units, but the configurations are pretty similar.
    Modding Guide - Abilities - The Hand of Merlin - Triggered Effects - BCBFEDA96
    But let’s do the same breakdown for our Tile Effects, to cover our bases.

    • Spawn Unit – This creates a new unit on the map, in the same warband as the caster. Note the entries about action points and turn types to further specify how the summoned unit acts.
    • Spawn Destructible – This creates a cover.
    • Spawn Ground Effect – This creates a ground effect to each target tile. When coupled with the movement Execution Type, this can leave ground effects when walking! Standby for
    • Spawn Aura – This is for Auras that have no specific unit. It’s similar to a ground effect, but its about granting status effects.
    • Teleport – This will teleport the caster to the target location.
    • Remove Ground effect – This clears ground effects in the target area.

    Also note that you can use Tile and Occupancy filters to, say, only target places without cover, or not affect tiles with units on it.
    Finally, note #5, a few minor aspects – If you want your ability to Destroy Cover, there’s your checkbox. If your ability checks for accuracy and evasion and can miss, that’s where you define it as well. In general, we try to only leave single-target damaging abilities being able to miss!


    Does your ability evolve?

    If you intend your ability to be picked in normal play, you’ll probably want to set up some upgrades for it. Those are straightforward: just browse the “upgraded abilities” for your ability in that space, and it’ll show in-game in card form to be picked.
    Here’s an example for the Shoot ability.
    Modding Guide - Abilities - The Hand of Merlin - Upgrades - 51DE87292
    In game, unless you alter it, we generate 2 cards per upgrade, so it looks like this:
    Modding Guide - Abilities - The Hand of Merlin - Upgrades - 3D34A3B37

    Complex Behaviors

    What nifty things does your ability do?

    There’s plenty to explore in this mammoth of a configuration file, but I’ll leave you with a few pointers on some more interesting entries:
    Manual Waypoints relate to the possibility of aiming movement-type abilities just on a straight line, or otherwise. We generally leave it enabled, but Charge has it disabled.
    Reaction Trigger Flags describe how your ability trigger effects like Archer’s Vigil. If you want your movement to not trigger reaction shots, for instance, you can leave it empty.
    Attribute Modifiers when using this Ability: If, for some reason, you need the user’s stats to be different somehow when using this specific ability, you can use this entry. We reduce accuracy in some Ranger skills, for instance.
    Passive Status Effects: Similarly, if you want a specific status effect to only be active while this ability is being performed, this is the place for it.
    Explode targets on kill… explodes targets when the damage is considered fatal!
    Attack Execution Type, Repeat count, # of required targets… These take some messing around with, but you can do barrage-type effects, multiple hits… Take a look at the Equal Measure spell or Quick Draw for some examples!
    Created Target Location – this is big brain stuff. If your ability does something with adjacency, you can use this “automated targeting” system to query for more units. We don’t use those currently in game, preferring to use status effect-driven abilities, but feel free to take a look as well.
    That’s pretty much it! Go forth and create your own abilities, or mix and change those already in-game!

    Written by Mibs

    I hope you enjoy the Modding Guide – Abilities – The Hand of Merlin guide. This is all for now! If you have something to add to this guide or forget to add some information, please let us know via comment! We check each comment manually!

    Be the first to comment

    Leave a Reply

    Your email address will not be published.