Skip to content

Step 1: Quick Start

Jump to bottom
Can TATAR edited this page Jun 11, 2026 · 9 revisions

Ultimate Roguelike Framework - Quick Start Guide

Version: 1.5.0
Last Updated: 2026-06-10
Estimated Time: 5-15 minutes

5-Minute Setup: Basic Playable Game

Get a basic Vampire Survivors-style game running quickly.

This guide uses the production-friendly, component-based setup. The included AURFTestPlayer and AURFTestEnemy classes still work for prototyping, but production projects should use their own ACharacter or APawn Blueprints with URF components.

Step 1: Create Game Instance

  1. Right-click in Content Browser -> Blueprint Class
  2. Search for URFGameInstance
  3. Name it BP_URFGameInstance
  4. Open the Blueprint and add PowerUp Data Assets to the Available PowerUps array:
    • DA_Might
    • DA_MaxHealth
    • DA_MoveSpeed
  5. Go to Project Settings -> Maps & Modes
  6. Set Game Instance Class to BP_URFGameInstance

Step 2: Setup Player Character

You do not need to inherit from AURFTestPlayer.

Create your own player from ACharacter or APawn, then add the URF components you need. The example project includes BP_TestProductionPlayer, a production-style ACharacter example that does not inherit from AURFTestPlayer.

The player does not need to manually register with URFGameDirector. The director automatically uses the pawn possessed by the first PlayerController as the player target.

Required Player Components

BP_PlayerCharacter +-- CapsuleComponent or custom collision +-- SkeletalMesh or StaticMesh +-- SpringArmComponent +-- CameraComponent +-- URFHealthComponent +-- URFExperienceComponent +-- URFWeaponComponent +-- URFPlayerStatsComponent +-- URFLevelUpSystem

URFTargetingComponent may also be added if your project uses it directly, but most weapon targeting is handled through URFWeaponComponent.

Optional Player Components

Add these only if your game uses those systems:

+-- URFCurrencyComponent
+-- URFVacuumComponent
+-- URFPowerUpShopSystem

Configure Player Stats

In URFPlayerStatsComponent:

Stats Data Asset -> DA_DefaultPlayerStats

Configure Starting Weapon

In URFWeaponComponent:

Starting Weapons
+-- DA_MagicWand

Make sure auto-fire is enabled if you want Vampire Survivors-style automatic attacks.

Configure Level Up System

In URFLevelUpSystem, add weapons to the Available Weapons Pool:

Available Weapons Pool
+-- DA_MagicWand
+-- DA_Knife
+-- DA_Garlic

Damage Routing

If you use your own player Blueprint, route Unreal damage into the URF health component.

In the player Event Graph:

Event AnyDamage
-> URFHealthComponent
-> TakeSimpleDamage(Damage, DamageCauser)
Connect `Damage` to `Damage Amount`.
Connect `Damage Causer` to `Damage Source`.

If you use C++, override TakeDamage and call URFHealthComponent::TakeSimpleDamage.

Step 3: Setup Production Enemy

You do not need to inherit from AURFTestEnemy.

Create your own enemy from ACharacter or APawn, then add:

BP_EnemyCharacter
+-- CapsuleComponent or custom collision
+-- SkeletalMesh or StaticMesh
+-- URFHealthComponent
+-- URFEnemyLogicComponent

Optional components:

+-- URFSeparationComponent

URFEnemyLogicComponent contains the reusable enemy-side framework logic:

  • Enemy tag setup
  • Player target acquisition
  • Optional simple follow movement
  • Contact damage
  • GameDirector registration and unregistration
  • XP reward handling
  • XP pickup spawning
  • Random loot drops
  • BlueprintAssignable events

Basic Enemy Health Setup

In URFHealthComponent:

Max Health -> 50
Destroy On Death -> true
Destroy Delay -> 0.1

URFEnemyLogicComponent handles rewards and director unregistration. URFHealthComponent can handle actor destruction.

Basic Enemy Logic Setup

In URFEnemyLogicComponent:

Auto Add Enemy Tag -> true
Auto Enemy Tag -> Enemy
Auto Find Player -> true
Auto Register With Director -> true
XP Reward -> 10
Reward Method -> Direct On Kill

For XP pickup drops instead of direct XP:

Reward Method -> Pickup Only
Guaranteed Pickup Class -> BP_XPPickup

For random loot:

Enable Random Loot -> true
Random Loot Tables -> Add your loot table data asset

Contact Damage Setup

Contact damage is disabled by default. Enable it only for enemies that should damage the player by touching them. Contact damage is overlap-based. If the enemy blocks the player capsule instead of overlapping it, contact damage will not fire. The contact damage component should use overlap settings:

Generate Overlap Events -> true
Collision Enabled -> Query Only or Query and Physics
Collision Preset -> Custom
Pawn Response -> Overlap

For an ACharacter enemy:

Enable Contact Damage -> true
Contact Damage Component Name -> CapsuleComponent
Contact Damage -> 10
Damage Interval -> 1.0

You can also set the contact damage component manually in Blueprint:

BeginPlay
-> URFEnemyLogicComponent
-> SetContactDamageComponent(CapsuleComponent)

Simple Follow Movement

If you use your own AIController, Behavior Tree, or custom movement, leave simple follow movement disabled.

Enable Simple Follow Movement -> false

For quick prototypes, enable simple follow movement.

There are two movement modes:

MovementInput

Uses Unreal's AddMovementInput. Speed is controlled by the owner's movement component, such as CharacterMovement.MaxWalkSpeed.

DirectActorMovement

Moves the actor directly. FollowSpeed controls units per second. This is closer to the old AURFTestEnemy prototype movement.

Recommended quick prototype setup:

Enable Simple Follow Movement -> true
Follow Movement Mode -> DirectActorMovement
Follow Speed -> 100

Recommended production setup:

Enable Simple Follow Movement -> false
Use AIController, Behavior Tree, or your own movement code

Step 4: Setup Game Director

  1. In your level, add actor: URFGameDirector
  2. Configure:
Wave Data Asset -> DA_DefaultWaves
Endless Mode -> true
Auto Find And Follow Player -> true
When enabled, `URFGameDirector` uses the pawn possessed by the first `PlayerController` as the spawn target.
  1. Make sure your wave data uses enemy classes that contain:
    • URFHealthComponent
    • URFEnemyLogicComponent

Step 5: Create Simple UI

  1. Create Widget Blueprint: WBP_PlayerHUD
  2. Add:
    • Progress Bar for Health
    • Progress Bar for XP
    • Text Block for Level

In Event Graph:

Event Tick
-> Get Player Health Percentage (Easy UI)
-> Set Health Bar Percent

Event Tick
-> Get Player XP Percentage (Easy UI)
-> Set XP Bar Percent

Event Tick
-> Get Player Level (Easy UI)
-> Format Text ("Level {0}")
-> Set Level Text

Add the widget to the viewport in your player Blueprint:

Event BeginPlay
-> Create Widget (WBP_PlayerHUD)
-> Add to Viewport

Step 6: Test

Press Play.

You should now have:

  • Player with health and XP
  • Automatic weapon firing
  • Enemies spawning in waves
  • Enemies using URFEnemyLogicComponent
  • XP rewards or XP pickup drops
  • Level-up card selection
  • Basic UI showing player stats

10-Minute Advanced Setup

After the basic setup works, add the extra systems below.

Enhanced Player Setup

Add Pickup Collection

Add:

URFVacuumComponent

This lets the player collect nearby pickups automatically.

Configure More Starting Weapons

In URFWeaponComponent:

Starting Weapons
+-- DA_MagicWand
+-- DA_Garlic

Max Weapon Slots -> 6
Auto Fire Enabled -> true

Configure More Level Up Options

In URFLevelUpSystem:

Available Weapons Pool
+-- DA_MagicWand
+-- DA_Knife
+-- DA_Garlic
+-- DA_HolyWand
+-- DA_KingBible
+-- DA_SantaWater

Fallback cards:

Fallback Cards Pool
+-- DA_FallbackHealthRestore
+-- DA_FallbackCurrencyBonus
+-- DA_FallbackXPBonus

Use Fallback Cards -> true

Level Up UI

  1. Create Widget: WBP_LevelUpMenu
  2. Add 3 buttons for card selection
  3. Bind to the level-up card selection event.

Basic flow:

On Level Up Card Selection
-> Pause Game
-> Create Widget (WBP_LevelUpMenu)
-> Add to Viewport
-> Display Card Options

Button click flow:

On Card Button Clicked
-> Select Card (Easy UI)
-> Resume Game
-> Remove from Parent

PowerUp Shop

  1. Create Widget: WBP_PowerUpShop
  2. Add a scroll box with buttons for PowerUps

Basic flow:

Event Construct
-> Get Shop Items (Easy UI)
-> For Each Shop Item
-> Create Button
-> Set Display Name
-> Set Cost Text
-> Set Enabled (Can Afford AND NOT Is Max Level)

Buy flow:

On Buy Button Clicked
-> Purchase PowerUp (Easy UI)
-> Refresh Shop (Easy UI)

Enhanced Enemy Setup

For a production enemy, use:

BP_EnemyCharacter
+-- URFHealthComponent
+-- URFEnemyLogicComponent
+-- URFSeparationComponent (optional)

Recommended health:

Max Health -> 50
Destroy On Death -> true
Destroy Delay -> 0.1

Recommended rewards:

XP Reward -> 10
Reward Method -> Pickup Only
Guaranteed Pickup Class -> BP_XPPickup

Recommended contact damage:

Enable Contact Damage -> true
Contact Damage Component Name -> CapsuleComponent
Contact Damage -> 10
Damage Interval -> 1.0

Contact damage requires overlap events. If the contact component blocks the player instead of overlapping, damage will not fire.

Recommended collision settings:

Generate Overlap Events -> true
Collision Enabled -> Query Only or Query and Physics
Collision Preset -> Custom
Pawn Response -> Overlap

Recommended movement for prototype:

Enable Simple Follow Movement -> true
Follow Movement Mode -> DirectActorMovement
Follow Speed -> 100

Recommended movement for production:

Enable Simple Follow Movement -> false
Use AIController or Behavior Tree

Complete HUD

Enhance WBP_PlayerHUD with:

  • Timer Display
  • Wave Number
  • Enemy Count
  • Currency Display
  • Weapon Slots Display

Example UI update flow:

Event Tick
-> Get Player Health Percentage (Easy UI)
-> Set Health Bar

Event Tick
-> Get Player XP Percentage (Easy UI)
-> Set XP Bar

Event Tick
-> Get Player Level (Easy UI)
-> Set Level Text

Event Tick
-> Get Timer Display String (Easy UI)
-> Set Timer Text

Event Tick
-> Get Current Wave Number (Easy UI)
-> Set Wave Text

Event Tick
-> Get Alive Enemy Count (Easy UI)
-> Set Enemy Text

Event Tick
-> Get Player Run Currency (Easy UI, "Gold")
-> Set Gold Text

Event Tick
-> Get Formatted Weapon Slots Display (Easy UI)
-> Set Weapon Slots Text

Next Steps

Add More Weapons

Create weapon data assets:

Right-click
-> Data Asset
-> URFWeaponDataAsset
-> Configure weapon name, damage, cooldown, projectile speed, and actor class

Add the new weapon to:

URFWeaponComponent -> Starting Weapons

or:

URFLevelUpSystem -> Available Weapons Pool

Per-Weapon Targeting Example

Weapons can override targeting settings individually.

Example: Boss-only weapon.

In the weapon data asset:

Override Targeting Settings -> true
Targetable Tags -> Boss
Target Unspecified Actors -> false
Only Fire When Target Available -> true

Result:

  • The weapon only targets actors with the Boss tag.
  • It does not fire when no boss exists.
  • It ignores regular enemies.

Example: Door-only weapon.

Override Targeting Settings -> true
Targetable Tags -> Door
Target Unspecified Actors -> false
Only Fire When Target Available -> true

Add Weapon Evolution

In a weapon data asset:

Evolution Config
Required Level -> 8
Required Passive -> BP_EmptyTome
Evolved Weapon -> DA_HolyWand

Add Character Selection

Create character stats data assets:

Right-click
-> Data Asset
-> URFPlayerStatsDataAsset
-> Configure Max Health, Move Speed, Might, Area, Cooldown, etc.

In character selection UI:

For Each Character Data Asset
-> Get Character Name
-> Set Button Text
-> Get Character Icon
-> Set Button Icon
-> Get Character Combat Stats
-> Set Stats Text

On Button Click
-> Get URFCharacterSelectionSubsystem
-> Set Selected Pawn Class

Add Boss Spawns

Option 1: Spawn boss when time limit is reached.

On Time Limit Reached
-> Spawn Actor (BP_BossEnemy)
-> Play Boss Music

Option 2: Spawn boss at a specific time.

On Game Time Updated
-> Branch (Current Time >= 600.0)
-> Spawn Actor (BP_MiniBoss)

For boss-only weapons, make sure your boss actor has the Boss tag and configure the weapon with Targetable Tags -> Boss.

Optimize Performance

Projectile Pooling

Get URFProjectilePoolSubsystem
-> Pre Warm Pool (BP_MagicWandProjectile, 50)

Pickup Pooling

Get URFPickupPoolSubsystem
-> Pre Warm Pool (BP_XPPickup, 100)

Game Director Spawn Layers

Spawn Settings Override
Layer 1 Radius -> 800
Layer 2 Radius -> 2000
Layer 3 Radius -> 3500
Layer 4 Radius -> 4500

Common Patterns

Custom Pickup Type

Create BP_CustomPickup based on URFPickupActor
-> Set Pickup Type: Custom
-> Set Custom Data Tag: PowerUp
-> Set Custom Int Value: 1

On Custom Collected
-> Branch (Tag == PowerUp)
-> Apply PowerUp Effect

Custom Weapon Behavior

Create BP_CustomWeapon based on URFProjectileActor
-> On Projectile Hit
-> Apply Custom Effect
-> Spawn VFX at Hit Location

Dynamic Difficulty

On Wave Started
-> Calculate Difficulty
-> For Each Enemy in Wave
-> Multiply Enemy Health
-> Multiply Enemy Damage

Troubleshooting

Weapons Not Firing

Check:

  1. URFWeaponComponent -> Auto Fire Enabled is true
  2. The weapon data asset is valid
  3. The weapon has a valid actor class if required
  4. The weapon cooldown is not too high
  5. There are valid targets in range
  6. If using per-weapon targeting, the target actor has the required class or tag
  7. If Only Fire When Target Available is enabled, at least one valid target exists

Enemies Not Taking Damage

Check:

  1. Enemy has URFHealthComponent
  2. Enemy has the correct target tag, usually Enemy
  3. Weapon targeting filters allow this enemy
  4. Enemy collision is enabled
  5. The weapon actor applies damage through URF health or Unreal damage routing

Enemy Does Not Disappear On Death

For production enemies, either:

URFHealthComponent -> Destroy On Death -> true

or:

URFEnemyLogicComponent -> Handle Actor Destruction -> true

Recommended setup:

URFHealthComponent -> Destroy On Death -> true
URFEnemyLogicComponent -> Handle Actor Destruction -> false

Enemy Does Not Move

If using simple follow movement:

  1. Check Auto Find Player is true
  2. Check Target Search Radius is large enough
  3. Check Enable Simple Follow Movement is true
  4. For quick prototypes, use:
Follow Movement Mode -> DirectActorMovement
Follow Speed -> 100

If using MovementInput mode:

  1. Make sure the owner is a Pawn or Character
  2. Make sure movement is configured
  3. For Character, check CharacterMovement -> Max Walk Speed
  4. If needed, set Auto Possess AI -> Placed in World or Spawned

Enemy Contact Damage Not Working

Check:

  1. Enable Contact Damage is true
  2. Contact Damage Component Name matches the collision component name
  3. For Character enemies, use:
Contact Damage Component Name -> CapsuleComponent
  1. Collision generates overlap events
  2. Player has URFHealthComponent or supports Unreal damage

Pickups Not Collecting

Check:

  1. Player has URFExperienceComponent for XP pickups
  2. Player has URFCurrencyComponent for currency pickups
  3. Player has URFHealthComponent for health pickups
  4. Pickup collision is enabled
  5. URFVacuumComponent is configured if using automatic pickup collection

Level Up Cards Not Showing

Check:

  1. URFLevelUpSystem -> Available Weapons Pool has weapons
  2. URFExperienceComponent is gaining XP
  3. UI widget is bound to the level-up selection event
  4. Enable Use Fallback Cards if the weapon pool is empty

Enemies Not Spawning

Check:

  1. URFGameDirector -> Wave Data Asset is set
  2. Is Active is true
  3. Spawn target is valid, or Auto Find And Follow Player is enabled
  4. Wave data has valid enemy classes
  5. Enemy classes include required components

PowerUp Shop Not Working

Check:

  1. URFGameInstance -> Available PowerUps has PowerUp data assets
  2. URFPowerUpSubsystem is initialized
  3. URFCurrencySubsystem has currency
  4. PowerUp is not already at max level

Example Game Structure

Content/
+-- Blueprints/
|   +-- BP_URFGameInstance
|   +-- BP_Player
|   +-- BP_Enemy
|   +-- BP_GameDirector
+-- UI/
|   +-- WBP_PlayerHUD
|   +-- WBP_LevelUpMenu
|   +-- WBP_PowerUpShop
+-- DataAssets/
|   +-- Weapons/
|   |   +-- DA_MagicWand
|   |   +-- DA_Knife
|   |   +-- DA_Garlic
|   +-- PowerUps/
|   |   +-- DA_Might
|   |   +-- DA_MaxHealth
|   +-- Characters/
|   |   +-- DA_DefaultPlayerStats
|   +-- Waves/
|       +-- DA_DefaultWaves
+-- Pickups/
    +-- BP_XPPickup
    +-- BP_GoldPickup
    +-- BP_HealthPickup

Tips

  1. Use Easy UI functions. They automatically find player/director references.
  2. Start with the 5-minute setup, then add advanced features.
  3. Test after each step.
  4. Use pooling for projectiles and pickups.
  5. Use Data Assets to create weapon and character variants.
  6. Enable debug logging in components when troubleshooting.
  7. Use AURFTestPlayer and AURFTestEnemy for quick prototypes only.
  8. Use your own ACharacter or APawn plus URF components for production.

Additional Resources

  • Complete Blueprint Reference: FRAMEWORK_BLUEPRINT_REFERENCE.md
  • Example Weapons Guide: EXAMPLE_WEAPONS_GUIDE.md
  • PowerUp Shop Guide: POWERUP_SHOP_QUICKSTART.md
  • Character Selection Guide: CHARACTER_SELECTION_QUICKSTART.md
  • Weapon Configuration: WEAPON_CONFIGURATION_TROUBLESHOOTING.md

Congratulations! You now have a functional Vampire Survivors-style roguelike game.

For detailed information on any system, refer to the Complete Blueprint Reference Guide.

Happy game making!

Community

Clone this wiki locally