⚙️ Blueprint Functions and Macros

Why Functions Matter

Imagine building a game where enemies take damage. You write the damage logic once in Enemy 1's Blueprint. Then Enemy 2 needs the same logic—so you copy it. Then Enemy 3. Then you realize the damage calculation is wrong and need to fix it in three places. Miss one, and you have inconsistent behavior.

This is why functions exist.

The Problem: Spaghetti Code

flowchart TD
    A[Event BeginPlay - 200 nodes] --> B[Nested branches]
    B --> C[More branches]
    C --> D[Loops]
    D --> E[More logic]
    E --> F[Even more logic]
    F --> G[Can't find anything]
    G --> H[Debugging nightmare]
    
    style A fill:#e74c3c,stroke:#c0392b,color:#fff
    style G fill:#ff9800,stroke:#e65100,color:#fff
    style H fill:#e74c3c,stroke:#c0392b,color:#fff

Figure: Without functions, Event Graphs become unmanageable tangles.

The Solution: Modular Functions

flowchart TD
    A[Event BeginPlay] --> B[InitializePlayer]
    A --> C[SetupUI]
    A --> D[LoadGameState]
    
    B --> B1[Small, focused logic]
    C --> C1[Small, focused logic]
    D --> D1[Small, focused logic]
    
    style A fill:#4CAF50,stroke:#2e7d32,color:#fff
    style B fill:#2196F3,stroke:#1565c0,color:#fff
    style C fill:#2196F3,stroke:#1565c0,color:#fff
    style D fill:#2196F3,stroke:#1565c0,color:#fff
    style B1 fill:#e3f2fd,stroke:#2196F3
    style C1 fill:#e3f2fd,stroke:#2196F3
    style D1 fill:#e3f2fd,stroke:#2196F3

Figure: Functions break complex logic into manageable, named pieces.

Benefits of Functions

Real-World Example

Without functions:

Enemy 1 TakeDamage logic (50 nodes)
Enemy 2 TakeDamage logic (50 nodes, slightly different)
Enemy 3 TakeDamage logic (50 nodes, different again)
Boss TakeDamage logic (50 nodes, more different)

Total: 200 nodes, inconsistent behavior, maintenance nightmare

With functions:

Function: CalculateDamage(BaseDamage, Armor, IsCritical)
  → Returns final damage value
  → 15 nodes, one place

Enemy 1: Call CalculateDamage
Enemy 2: Call CalculateDamage
Enemy 3: Call CalculateDamage
Boss: Call CalculateDamage

Total: 15 nodes in function + 4 function calls = 19 nodes
Consistent behavior, easy to maintain

Creating Blueprint Functions

Functions live in the My Blueprint panel alongside variables and event graphs.

How to Create a Function

1. Open your Blueprint
2. In My Blueprint panel, find the Functions section
3. Click the + Function button
4. Name your function (e.g., CalculateDamage)
5. Press Enter
6. A new function graph opens—this is your workspace

Figure: Functions appear in My Blueprint panel and have their own graph workspace.

Function Structure

Every function has two special nodes automatically created:

• Entry Node (Green): Where execution begins when function is called
• Return Node (Red): Where execution ends, returns to caller

You add your logic between these two nodes.

Simple Function Example: Say Hello

1. Create function: SayHello
2. Between Entry and Return:
   • Add Print String node
   • Set text to "Hello, World!"
3. Connect: Entry → Print String → Return
4. Compile

Using the function:

1. In Event Graph, drag the function from My Blueprint panel
2. Connect execution flow to it
3. When executed, it prints "Hello, World!"

Event BeginPlay → SayHello → (prints "Hello, World!")

Function Inputs and Outputs

Functions become powerful when they accept inputs (parameters) and return outputs (results).

Adding Inputs (Parameters)

1. Select your function in My Blueprint panel
2. In Details panel, find Inputs section
3. Click + (New Parameter)
4. Name it (e.g., DamageAmount)
5. Set type (e.g., Float)
6. Optionally set default value
7. Compile

The input appears as a pin on the Entry node and when calling the function.

Adding Outputs (Return Values)

1. Select your function in My Blueprint panel
2. In Details panel, find Outputs section
3. Click + (New Parameter)
4. Name it (e.g., FinalDamage)
5. Set type (e.g., Float)
6. Compile

The output appears as an input pin on the Return node and as an output pin when calling the function.

Figure: Function with inputs and outputs showing data flow.

Example: Calculate Damage Function

Function Definition:

Function: CalculateDamage
  Inputs:
    - BaseDamage (Float)
    - Armor (Float)
    - IsCritical (Boolean)
  Output:
    - FinalDamage (Float)
  
  Logic:
    1. Subtract Armor from BaseDamage
    2. If IsCritical, multiply by 2.0
    3. Return result as FinalDamage

Using the function:

Enemy TakeDamage Event
  → Call CalculateDamage(BaseDamage=50, Armor=10, IsCritical=false)
  → Returns FinalDamage=40
  → Subtract FinalDamage from Enemy Health

Multiple Inputs and Outputs

Functions can have multiple inputs and multiple outputs:

Function: GetPlayerStats
  Inputs: (none)
  Outputs:
    - CurrentHealth (Float)
    - MaxHealth (Float)
    - Level (Integer)
    - ExperiencePoints (Float)
    - IsAlive (Boolean)

All outputs appear as pins on the function call node, giving you access to all return values simultaneously.

Pass by Reference (Advanced)

By default, inputs are "pass by value" (copies). You can make inputs pass by reference to modify the original:

1. Select the input parameter in function details
2. Check "Pass by Reference"
3. The input becomes bidirectional—you can modify it

Example: A function that modifies an array directly instead of returning a modified copy.

Local Variables

Functions can have their own local variables—temporary storage that only exists while the function runs.

Creating Local Variables

Method 1: Promote to Local Variable

1. Inside your function graph, create a node that outputs a value
2. Right-click the output pin
3. Choose "Promote to Local Variable"
4. Name it
5. A Set node appears for that local variable

Method 2: Add from My Blueprint Panel

1. With function graph open, click + Variable in My Blueprint
2. The variable is automatically local to this function
3. Name and configure it

Local vs. Instance Variables

Example: Calculate Average Function

Function: CalculateAverage
  Inputs: NumberArray (Array of Floats)
  Output: Average (Float)
  
  Local Variables:
    - Sum (Float) = 0.0
    - Count (Integer) = 0
  
  Logic:
    1. ForEach Loop through NumberArray
       → Add each number to Sum
       → Increment Count
    2. Divide Sum by Count
    3. Return as Average

Sum and Count are local—they only exist during this function call and can't be accessed elsewhere.

flowchart TD
    A[Function Called] --> B[Create Local Variables: Sum=0, Count=0]
    B --> C[ForEach Loop: Process Array]
    C --> D[Update Sum and Count]
    D --> E{More Elements?}
    E -->|Yes| C
    E -->|No| F[Calculate: Average = Sum / Count]
    F --> G[Return Average]
    G --> H[Destroy Local Variables]
    
    style A fill:#4CAF50,stroke:#2e7d32,color:#fff
    style B fill:#2196F3,stroke:#1565c0,color:#fff
    style C fill:#ff9800,stroke:#e65100,color:#fff
    style D fill:#2196F3,stroke:#1565c0,color:#fff
    style E fill:#ff9800,stroke:#e65100,color:#fff
    style F fill:#2196F3,stroke:#1565c0,color:#fff
    style G fill:#e74c3c,stroke:#c0392b,color:#fff
    style H fill:#9e9e9e,stroke:#616161,color:#fff

Figure: Local variables are created on function entry and destroyed on exit.

Pure Functions

Pure functions are special—they have no execution pins and can be called from data wires. They're perfect for calculations.

Pure vs. Impure Functions

Figure: Pure functions have no execution pins and connect via data wires only.

Creating a Pure Function

1. Create a function normally
2. Select the function in My Blueprint
3. In Details panel, check "Pure"
4. Execution pins disappear from Entry and Return nodes
5. Function can now be called from data wires

Pure Function Rules

For a function to be pure, it must:

• ✅ Only perform calculations (no Print String, Set Variable, Spawn Actor, etc.)
• ✅ Have at least one output (otherwise, what's the point?)
• ✅ Not modify any state (no setting variables, calling impure functions)
• ✅ Always return the same output for the same inputs (deterministic)

Pure Function Examples

Advantages of Pure Functions

• ✅ No execution wires: Cleaner graphs, less clutter
• ✅ Call anywhere: Can be used in any data context
• ✅ Automatic caching: Unreal may cache results if called multiple times with same inputs
• ✅ Easier to test: No setup needed—just pass inputs, check outputs
• ✅ Predictable: Same inputs always produce same result

Custom Events

Custom Events are like functions but with key differences. They're perfect for event-driven scenarios and Blueprint communication.

Creating a Custom Event

1. Right-click in Event Graph
2. Search "Add Custom Event"
3. Name it (e.g., OnPlayerDeath)
4. The custom event node appears
5. Add logic after the event node

Calling a Custom Event

Once created, you can call it like a function:

1. Right-click in Event Graph
2. Search for your custom event name
3. Select "Call [EventName]"
4. Connect execution flow

Adding Inputs to Custom Events

1. Select the custom event node
2. In Details panel, find Inputs
3. Click + (New)
4. Name and set type
5. The input appears as a pin on both the event and the call node

Note: Custom Events cannot have outputs (return values).

flowchart LR
    A[Event BeginPlay] --> B[Do Setup Logic]
    B --> C[Call Custom Event: OnGameStart]
    
    D[Custom Event: OnGameStart] --> E[Initialize UI]
    E --> F[Spawn Player]
    F --> G[Load Game State]
    
    C -.->|Triggers| D
    
    style A fill:#e74c3c,stroke:#c0392b,color:#fff
    style B fill:#2196F3,stroke:#1565c0,color:#fff
    style C fill:#ff9800,stroke:#e65100,color:#fff
    style D fill:#4CAF50,stroke:#2e7d32,color:#fff
    style E fill:#2196F3,stroke:#1565c0,color:#fff
    style F fill:#2196F3,stroke:#1565c0,color:#fff
    style G fill:#2196F3,stroke:#1565c0,color:#fff

Figure: Custom Events are called like functions but execute as event nodes.

Functions vs. Custom Events

Both organize code, but they have important differences. Choosing the right one matters.

Detailed Comparison

Decision Guide

flowchart TD
    A{Need return value?} -->|Yes| B[Use Function]
    A -->|No| C{Need Delay or Timeline?}
    C -->|Yes| D[Use Custom Event]
    C -->|No| E{Multiplayer replication?}
    E -->|Yes| D
    E -->|No| F{Bind to Event Dispatcher?}
    F -->|Yes| D
    F -->|No| G{Need local variables?}
    G -->|Yes| B
    G -->|No| H[Either works - prefer Function for organization]
    
    style B fill:#4CAF50,stroke:#2e7d32,color:#fff
    style D fill:#ff9800,stroke:#e65100,color:#fff
    style H fill:#2196F3,stroke:#1565c0,color:#fff

Figure: Decision tree for choosing between Functions and Custom Events.

Usage Examples

Blueprint Macros

Macros are like functions on steroids—they can have multiple execution outputs and collapse complex node groups into single reusable nodes.

Why Macros Exist

Functions have limitations:

• ❌ Only one execution output (Entry → Return)
• ❌ Can't use Delay nodes
• ❌ Can't create custom flow control (like Branch with 3+ outputs)

Macros solve these problems—they can have multiple execution outputs, making them perfect for custom logic flow.

Creating a Macro

1. In My Blueprint panel, find Macros section
2. Click + Macro
3. Name it (e.g., SafeDivide)
4. A macro graph opens with Inputs and Outputs nodes
5. Build your logic between them

Macro Structure

Macros have special tunnel nodes:

• Inputs Node: Where execution and data enter
• Outputs Node: Where execution and data exit (can have multiple execution outputs!)

Figure: Macro with multiple execution outputs enables custom flow control.

Macro vs. Function

When to Use Macros

• ✅ Need multiple execution outputs (custom flow control)
• ✅ Creating utility nodes used in many places
• ✅ Simplifying complex node groups into single nodes
• ✅ Building custom Branch-like nodes

Example use cases:

• SafeDivide - Success/Error paths
• TryGetActor - Found/NotFound paths
• ValidateInput - Valid/Invalid paths
• SwitchOnHealth - High/Medium/Low/Critical paths

Function Libraries

Function Libraries are collections of static functions available project-wide—perfect for utility functions you use everywhere.

Creating a Function Library

1. Content Browser → Right-click → Blueprint Class
2. Search for and select Blueprint Function Library
3. Name it (e.g., BP_MathUtilities, BP_StringHelpers)
4. Open it
5. Add functions (all are automatically static)

Example: Math Utilities Library

Blueprint Function Library: BP_MathUtilities

Functions:
  - ClampValue(Value, Min, Max) → Returns clamped value
  - IsInRange(Value, Min, Max) → Returns boolean
  - GetRandomPointInRadius(Center, Radius) → Returns Vector
  - CalculatePercentage(Part, Whole) → Returns Float
  - RoundToNearest(Value, Increment) → Returns rounded value

Now any Blueprint in your project can call these functions without needing a reference to the library—they just appear in the node menu!

Using Function Library Functions

1. In any Blueprint, right-click in Event Graph
2. Search for your function name
3. It appears under the library name
4. Use it like any other function

flowchart TD
    A[BP_MathUtilities Library] --> B[ClampValue Function]
    A --> C[IsInRange Function]
    A --> D[GetRandomPoint Function]
    
    E[BP_Player] -.->|Can call| B
    F[BP_Enemy] -.->|Can call| B
    G[BP_Weapon] -.->|Can call| C
    H[BP_SpawnManager] -.->|Can call| D
    
    I[Available project-wide without instances!]
    
    style A fill:#9c27b0,stroke:#6a1b9a,color:#fff
    style B fill:#2196F3,stroke:#1565c0,color:#fff
    style C fill:#2196F3,stroke:#1565c0,color:#fff
    style D fill:#2196F3,stroke:#1565c0,color:#fff
    style E fill:#4CAF50,stroke:#2e7d32,color:#fff
    style F fill:#4CAF50,stroke:#2e7d32,color:#fff
    style G fill:#4CAF50,stroke:#2e7d32,color:#fff
    style H fill:#4CAF50,stroke:#2e7d32,color:#fff
    style I fill:#ff9800,stroke:#e65100,color:#fff

Figure: Function Libraries provide project-wide utility functions accessible everywhere.

Best Practices for Function Libraries

• ✅ Group by category: BP_MathUtilities, BP_StringHelpers, BP_ArrayUtils
• ✅ Make functions pure when possible (no side effects)
• ✅ Document well—add tooltips to each function
• ✅ Keep functions generic and reusable
• ❌ Don't put game-specific logic here—keep it universal

Common Function Library Categories

Organization and Best Practices

Function Naming Conventions

Documentation: Tooltips and Categories

Adding tooltips:

1. Select your function in My Blueprint
2. In Details panel, find Tooltip field
3. Write a brief description of what it does
4. This appears when hovering over the node

Adding categories:

1. In Details panel, find Category field
2. Type category name (e.g., "Combat", "Movement", "Utilities")
3. Functions are grouped by category in My Blueprint and node menu

Organization Tips

Function Complexity Guidelines

• Small: 5-15 nodes - Perfect! Easy to understand and test
• Medium: 15-40 nodes - Acceptable, consider breaking into helper functions
• Large: 40-100 nodes - Too complex, definitely split it up
• Huge: 100+ nodes - Red flag! This should be multiple functions

Debugging Functions

Techniques:

• Print String: Add temporary prints to track execution flow
• Breakpoints: Right-click node → Add Breakpoint (pauses execution)
• Watch Values: Right-click variable → Watch This Value
• Step Through: When paused at breakpoint, use F10 to step node-by-node
• Return Values: Print return values to verify calculations

Summary

Functions and macros are the organizational backbone of professional Blueprint development. Master them and your code becomes readable, maintainable, and a pleasure to work with.

Key Takeaways

• ⚙️ Functions are reusable, named blocks of logic—write once, use everywhere
• 📥 Inputs and Outputs make functions flexible—accept parameters, return values
• 📍 Local Variables exist only within functions—perfect for temporary calculations
• ✨ Pure Functions have no side effects, no execution pins—ideal for calculations
• 📡 Custom Events can't return values but support Delay, Timelines, and replication
• 🔀 Functions vs. Events: Functions for returns, Events for async/multiplayer/delays
• 🎭 Macros have multiple execution outputs—use for custom flow control only
• 📚 Function Libraries provide project-wide utilities accessible everywhere
• 📝 Best Practices: Descriptive names, tooltips, categories, small functions, consistent patterns
• 🐛 Debugging: Breakpoints, Print String, Watch Values, step-through execution

What's Next?

With functions and macros mastered, the next lesson explores Lesson 3.5: Blueprint Project Organization. You'll learn folder structures, naming conventions, parent/child Blueprint hierarchies, and how to architect large-scale Blueprint projects that scale gracefully as your game grows.