Unreal Engine 5 · C++ Framework · Blueprint-First

Build Your Own Merge‑Tactics Game

A complete, playable auto-battler project for UE5: board & bench, merge & synergy, shop economy, server-authoritative combat, and the full multiplayer round loop — open the project and press Play. No C++ required to ship your own game with it.

HITZ Merge Tactics unit render
0Setup Needed to Playtest
100%Blueprint Extensible
2Grid Topologies
5Reference Traits Included
Overview

Everything, In One Shot

Board, shop, traits, and combat — the full loop running together.

What's Inside

Every System an Auto-Battler Needs

All systems are data-driven and reachable from Blueprint. C++ is there when you want it, never required.

Stat System

Tag-driven stats and modifiers, replicated efficiently. Adding a new stat is pure data — define a Gameplay Tag, use it. No AttributeSet subclassing, no engine module dependencies.

IHMT_StatProvider · UHMT_StatComponent

Hex & Square Grids

Both topologies ship, chosen per board asset. Neighbor/distance/world-transform math is separate from board state, so layouts stay reusable across every board you author.

IHMT_GridLayout · UHMT_BoardComponent

Merge & Synergy

Configurable copies-to-merge and max star level. Traits activate at count breakpoints with pure-data stat grants — plus an interface hook for traits that need real behavior.

UHMT_UnitCollectionComponent · IHMT_TraitEffect

Shop & Economy

Shared unit pool, gold costs, streak bonuses, interest, income — every number lives on one data asset. Reroll, lock, and bench-first purchasing built in. No player level/XP grind — tier odds are flat all match, Clash Royale Merge Tactics style rather than TFT.

UHMT_ShopComponent · UHMT_MatchRulesAsset

Ruler & World Presence

An optional hero/avatar per player: match HP, a Blueprint passive ability, and a physical presence standing next to their board with a floating name/HP bar that faces the camera. Spectating a bot or another player projects their Ruler too, not just their army.

AHMT_RulerActor · UHMT_RulerDefinition · IHMT_RulerPassive

Game & Tile Modifiers

Match-wide modifiers roll at match start from a data-asset pool — grant a passive building, scale board capacity, anything a Blueprint effect class can do. Tile modifiers apply the same idea per board cell.

UHMT_GameModifierDefinition · IHMT_TileEffect

Authoritative Combat

Combat simulates server-side against locked board snapshots and replicates as a compact event log. Clients replay events for animation — they never compute outcomes.

UHMT_CombatResolver · UHMT_CombatPlaybackComponent

Multiplayer Round Loop

Preparation → Combat → Results, looping to match end. Recency-weighted pairing, ghost boards for odd lobbies, PvE rounds, and spectating — on standard actor replication.

UHMT_MatchStateComponent

Editor Tooling

Click-to-paint board layout editor, live 3D unit preview with per-animation playback buttons, and content validation that flags broken data on every save.

HMT_CoreEditor module

Bundled GAS Bridge

Already invested in GameplayAbilities? A bundled bridge module maps the same stat interface onto your existing AttributeSets — swap in UHMT_ASCStatComponent per unit and every other system keeps working unchanged, since it only ever talks to the interface.

HMT_GASBridge · UHMT_ASCStatComponent
Synergy System

Five Reference Traits Included

Shipped as working example content with exclusive-tier breakpoints — study them, reskin them, or replace them entirely. New traits are data assets, not code.

Warrior trait icon

Warrior

Armor synergy

Ranger trait icon

Ranger

Attack-speed synergy

Assassin trait icon

Assassin

Crit synergy

Brawler trait icon

Brawler

Max-health synergy

Guardian trait icon

Guardian

Reactive heal (behavior trait)

In Action

See It Running

Captures from the included reference project. Click any image to browse them full-size.

Documentation

Setup Guide

Everything from install to a playable match — no C++ needed at any step.

Requirements

  • Unreal Engine 5.8 (installed launcher build is fine).
  • Visual Studio 2022 (or your platform's UE-supported C++ toolchain) — the project ships as source, so it needs to be compiled once before it opens. This is a whole project with real gameplay C++, not a Blueprint-only content pack.
  • No plugins to install separately. GameplayAbilities and every other engine dependency the project needs are already declared in its .uproject and enable themselves.

Installation

Ships as a complete, ready-to-open Unreal project — not a plugin you drop into something else.

  1. Extract the downloaded project anywhere on disk.
  2. Right-click HitzMergeTactics.uproject → Generate Visual Studio project files.
  3. Open the generated solution and build the HitzMergeTacticsEditor target (Development Editor), or just double-click the .uproject — the editor will offer to build it for you on first launch.
  4. Once it opens, press Play — the reference level, GameMode, and sample content are already wired up.
Want to reuse just the framework? The gameplay-agnostic core lives entirely in Source/HMT_Core and Source/HMT_CoreEditor (plus the optional bridge in Source/HMT_GASBridge) — copy those three folders into your own project's Source/, add matching entries to your .uproject's Modules array, and everything else in this guide still applies. Source/HitzMergeTactics is the sample-layer GameMode/PlayerState/UI wiring shown in this guide, not part of the reusable core.

Gameplay Tags

Stats, traits, and status effects are all identified by Gameplay Tags — you declare them once per project.

Add your tags in Project Settings → Gameplay Tags, or paste into Config/DefaultGameplayTags.ini. The reference set used by the sample content:

[/Script/GameplayTags.GameplayTagsSettings]
+GameplayTagList=(Tag="Stat.Health")
+GameplayTagList=(Tag="Stat.AttackDamage")
+GameplayTagList=(Tag="Stat.Armor")
+GameplayTagList=(Tag="Stat.Range")
+GameplayTagList=(Tag="Stat.MoveSpeed")
+GameplayTagList=(Tag="Stat.AttackSpeed")
+GameplayTagList=(Tag="Stat.CritChance")     ; optional — unset = no crits
+GameplayTagList=(Tag="Stat.CritDamage")     ; optional
+GameplayTagList=(Tag="Stat.CastTime")       ; optional — unset = instant casts
+GameplayTagList=(Tag="Status.Stun")         ; optional CC tags
+GameplayTagList=(Tag="Status.Root")
+GameplayTagList=(Tag="Status.Silence")
+GameplayTagList=(Tag="Status.Taunt")
+GameplayTagList=(Tag="Trait.Warrior")       ; one per trait you author
+GameplayTagList=(Tag="Trait.Ranger")

Tag names are entirely yours — the framework never hardcodes them. You tell it which tag means "health" in the next step.

◆
doc-shot-gameplaytags.png
Project Settings GameplayTags panel with the six Stat.* tags registered
Project Settings → Gameplay Tags, six required Stat.* tags registered

Data Assets

All game content is authored as Data Assets — right-click in the Content Browser → Miscellaneous → Data Asset, then pick the class.

1. Match Rules — UHMT_MatchRulesAsset

The single source of truth for economy and match configuration. The important fields:

FieldWhat it does
MinPlayersPlayers needed to start. For solo testing, prefer bFillWithBotsWhenMinPlayersUnmet over setting this to 1 — bots fill the lobby after BotFillWaitSeconds, so pairing/spectating still behave like a real match.
StartingGoldGold each player begins with. Must be > 0 or nobody can buy anything.
ShopTierOddsFlat per-tier roll weights (no player level/XP — odds are the same all match). Needs at least one non-zero entry.
PoolSizeByTier / GoldCostByTierShared pool copies and prices per cost tier (1–5).
AvailableGameModifiers / ModifiersPerMatchMatch-wide modifiers rolled at match start — see Ruler & Modifiers.
Stat tags (Health, AttackDamage, Armor, Range, MoveSpeed, AttackSpeed)Maps your project's tags onto the combat resolver. All six must be set for combat to work.
Crit / CastTime / CC tagsOptional. Leave unset to disable that mechanic entirely — no other config needed.
CopiesRequiredForMerge / MaxStarLevelMerge rules — e.g. 3 copies to merge, 3-star cap. Merges run immediately on every buy, including a bench buy mid-combat.
◆
doc-shot-matchrules.png
A fully configured Match Rules data asset
A correctly filled-out Match Rules asset

2. Board Layout — UHMT_BoardLayoutAsset

  • Topology: Hex or Square — everything else adapts automatically.
  • Columns / Rows, plus optional blocked cells — painted visually with the built-in checkbox-grid editor, no coordinate typing.
  • Tile visuals: assign your own mesh + materials, or leave TileMesh empty for a clean built-in procedural board. Hover / valid-drop / invalid-drop / selected states each take an optional material override.
  • A Preview Board In Level button on the asset spawns throwaway preview tiles so you can eyeball the layout without pressing Play.

3. Units — UHMT_UnitDefinition (one per unit)

  • UnitID (a Gameplay Tag — must be unique per unit), display name, CostTier 1–5.
  • BaseStats: a list of (stat tag, value) pairs — any stats you like.
  • Mesh, AnimSet (idle/move/attack/ability/death montages), Portrait texture, optional audio and FX sets.
  • Traits: the trait tags this unit counts toward.
  • Optional targeting strategy and ability classes — unset falls back to nearest-enemy targeting with basic attacks only.
  • Opening the asset gives you a live 3D preview viewport with buttons to play each montage.
◆
doc-shot-unit-editor.png
Unit Definition asset editor with 3D preview viewport
The custom Unit Definition editor — 3D preview, per-montage Play buttons, scrub bar

4. Traits — UHMT_TraitDefinition (one per trait)

  • Trait tag, display name, icon, description.
  • Breakpoints: e.g. at 2 units → +20 Armor; at 4 → +50 Armor. Highest met breakpoint wins (exclusive tiers, TFT-style).
  • Stat grants are pure data. For behavior beyond stats (like Guardian's reactive heal), set a TraitEffectClass implementing IHMT_TraitEffect — Blueprint subclasses work.

5. PvE Rounds — UHMT_PvERoundDefinition (optional)

  • Monster lineups with fixed board placements, run every Nth round (configured on Match Rules).
  • PvE losses are forgiving by genre convention — no match-HP damage, only a missed clear bonus.

Ruler & Modifiers

Both optional, both pure data + Blueprint — no C++ required for either.

Ruler — player identity, match HP, world presence

  • Create a UHMT_RulerDefinition per Ruler: name, icon, description, optional StartingHPOverride (0 = use Match Rules' default), optional RulerPassiveClass (implements IHMT_RulerPassive — OnMatchStart/OnRoundStart/OnCombatEvent hooks, e.g. a flat team-wide stat bonus or a gold-income modifier), and presentation (Mesh/AnimSet — the same struct units use, including Idle/Victory/Death poses).
  • Add your Rulers to your GameMode's AvailableRulers array — one is randomly assigned per player (bots included) at match start.
  • World presence is optional: leave AvailableRulers empty for HP-only identity with no visible avatar. To get a Ruler actor standing beside each player's board with a floating overhead name/HP bar, use the reference project's RulerActorClass — it hides a Ruler on every machine except its owner's, and shows the spectated player's Ruler as a local-only projected ghost instead, the same way spectating projects their army.
◆
doc-shot-ruler.png
A Ruler Definition data asset with mesh, anim set, and passive class assigned
A Ruler Definition — identity, HP override, passive, and presentation in one asset

Game & Tile Modifiers

  • UHMT_GameModifierDefinition assets roll at match start from Match Rules' AvailableGameModifiers/ModifiersPerMatch and apply for the whole match via a Blueprint class implementing IHMT_ModifierEffect — e.g. the reference project's board-capacity-per-round and passive-mana-building modifiers.
  • UHMT_TileModifierDefinition is the same idea scoped to a single board cell instead of match-wide, via IHMT_TileEffect.

GameMode Wiring

The framework is component-based — your GameMode, GameState, and PlayerState own the components. The reference project shows the complete wiring.

  1. Your GameState owns the match flow: add UHMT_MatchStateComponent and UHMT_ShopPoolComponent.
  2. Your PlayerState owns per-player systems: UHMT_BoardComponent, UHMT_BenchComponent, UHMT_UnitCollectionComponent, UHMT_ShopComponent, UHMT_SynergyManagerComponent, and UHMT_CombatPlaybackComponent.
  3. On your GameMode (Blueprint subclass is fine), expose and assign: your MatchRules asset, BoardLayout asset, the list of available units, registered traits (the step buyers most often miss — no synergy ever activates without it), available Rulers (optional), and any PvE rounds.
  4. When enough players have joined, initialize each player and call StartMatch on the match state component — the reference GameMode does exactly this and is meant to be copied.
◆
doc-shot-gamemode-defaults.png
GameMode Class Defaults with every data-asset field assigned
GameMode Class Defaults, fully wired — this is what "done" looks like
Tip: start by duplicating the reference project's GameMode Blueprint and swapping the data assets for your own — it's the fastest path to a running match, then customize from there.
Durability tip: a Blueprint's hand-set Class Default overrides on data-asset fields aren't guaranteed to survive a future source/engine update that reinstances the class. For config you want bulletproof across updates, set it in your own GameMode subclass's C++ constructor via ConstructorHelpers::FObjectFinder instead — a C++ default can still be overridden per-Blueprint, it just can't be silently wiped.

HUD & UI

A complete reference HUD ships in Content/UI — pure UMG Blueprints, no C++ widget classes.

  • Included widgets: game HUD shell, shop bar with unit cards, trait/synergy panel, top bar (round/phase/timer/spectate/Ruler HP), bench slots, combat health bars and cast bars, and a world-space Ruler overhead name/HP bar.
  • Every widget reads game state through BlueprintCallable getters on the components — there is no hidden C++ binding to break when you restyle. Most poll on a short timer (including the Ruler overhead bar, via its own auto-set OwningRulerActor reference); the unit health bar is the one exception, pushed instantly on hit via IHMT_UnitHealthBarInterface.
  • Use them as-is for prototyping, restyle them, or treat them as living documentation for building your own.
  • Combat UI reacts to the replicated combat event log (OnCombatEventReceived) — the same hook you'd use for hit VFX, damage numbers, or camera shakes.

First Playtest

  1. Set your GameMode on the level (World Settings) or project default.
  2. For solo testing, turn on bFillWithBotsWhenMinPlayersUnmet on your Match Rules rather than setting MinPlayers = 1 — bots fill the lobby after a short wait, so pairing/spectating still exercise the real code paths instead of a degenerate 1-player case.
  3. Press Play. Buy units from the shop, drag them from bench to board, buy a copy to see merging, and let the preparation timer run out to watch combat resolve and play back.

Reference debug controls (from the sample player controller): number keys buy shop slots, R rerolls, C locks the shop, X sells the hovered unit, Tab spectates other boards, Enter force-ends preparation.

Multiplayer

Everything replicates through standard UE actor replication — no custom netcode to configure.

  • In-editor: set Number of Players to 2+ in the Play dropdown (Net Mode: listen server). The match starts automatically once MinPlayers join.
  • Combat is server-authoritative: boards lock into snapshots, the server simulates, clients replay the replicated event log. Clients cannot cheat combat outcomes.
  • Odd player counts pair the odd player against a ghost of a stored board — nobody sits out.
  • Spectating and late-join work through ordinary replication of the same components — no extra setup.

Extending the Framework

Four small interfaces cover the customization points — all implementable in Blueprint.

InterfaceExtend it to…
IHMT_TargetingStrategyChange who a unit attacks — e.g. "lowest current HP" or "farthest enemy". Set per unit definition.
IHMT_AbilityExecutorAuthor active abilities. A combat context API provides AoE queries, damage/heal, forced movement, status effects, and summons.
IHMT_TraitEffectTraits that do things stats can't — react to combat events, heal allies, apply CC.
IHMT_StatProviderSwap the whole stat backend (this is what the bundled GAS bridge does). Most projects never touch it.

Bigger levers: the damage formula is a BlueprintNativeEvent on the combat resolver (subclass + override, then point Match Rules at your resolver class), and merge thresholds accept a per-unit override.

GAS Bridge

For projects already built on GameplayAbilities. The bridge module (Source/HMT_GASBridge) is bundled and compiled in by default — you only need to opt into using it per unit.

  1. Create a UHMT_AttributeTagMapAsset mapping your stat tags to your existing AttributeSet properties — the bridge never ships its own AttributeSet.
  2. Use UHMT_ASCStatComponent in place of the default stat component on your units. Every other system is unchanged — they only ever talk to the interface.
Not using GAS? You can leave every unit on the default UHMT_StatComponent and never touch this — the bridge module simply sits unused. Pulling it out of your own project entirely means deleting Source/HMT_GASBridge and its GameplayAbilities/GameplayTasks dependency lines from the other modules' Build.cs files.

Troubleshooting

The framework logs a named reason for every silent-looking failure — check the Output Log first. Common ones:

SymptomCause & fix
Nothing spawns on PlayMatch hasn't started — fewer than MinPlayers joined. Use 2-player PIE, or enable bFillWithBotsWhenMinPlayersUnmet and wait for the bot-fill timer.
Shop is empty / buying failsCheck GameMode's unit list is populated, each unit has a valid CostTier, and Match Rules has ShopTierOdds, PoolSizeByTier, and StartingGold > 0.
Combat ends instantly in a drawThe six required stat tags aren't set on Match Rules (units spawn at 0 HP). The log names exactly which tags are missing.
No traits ever activateGameMode's RegisteredTraits is empty — this is the step buyers most often miss.
Units are invisible but workNo Mesh assigned on the unit definition — assign a skeletal mesh.
Units slide instead of animatingAnimSet montages unset — the content validator flags this on save.
Crits / cast bars / CC never happenThose tags are optional and unset — set them on Match Rules to enable each mechanic.
A Ruler exists but has no world presence / health barAvailableRulers is empty (no Ruler assigned), or RulerActorClass/OverheadWidgetClass is unset — both optional, see Ruler & Modifiers.
Match config "was set" but the log still says it's missingA Blueprint GameMode's own Class-Default override was lost across a rebuild — see the durability tip under GameMode Wiring.

The included content validator also runs automatically on save and flags broken or incomplete data assets before you ever press Play.

Get the Project

Available on Fab

HITZ: Merge Tactics ships as a complete, playable Unreal Engine project — grab it from the Fab marketplace, open it, and start building.

View on Fab