Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Documentation

User Guide

1. Installation

What you need

  • Unreal Engine 5.0 – 5.8 (Windows or macOS editor).

  • Nothing else — BPTracker has no third-party dependencies.

Step by step

  1. Install the plugin.

    • From Fab: install BPTracker to your engine through the Epic Games Launcher.

    • Manual copy: put the BPTracker folder into your project's Plugins/ folder (create Plugins/ next to your .uproject if it doesn't exist yet).

  2. Enable it. In the editor, go to Edit > Plugins, type "BPTracker" in the search box, and tick Enabled.

  3. Restart the editor when prompted. That's it — recording is on by default.

✅ How to check it's working: after the restart, open Project Settings > Plugins > BP Tracker. If you can see the BP Tracker settings page, the plugin is loaded and recording.

Two engine plugins BPTracker uses

Both are standard Epic plugins that ship with the engine and are enabled by default, so normally you don't have to do anything. They only matter if your project has turned them off:

Plugin
What BPTracker uses it for
If it's disabled

Level Sequence Editor

Tracking Level Sequences and jumping to tracks/sections

Re-enable it in Edit > Plugins (category Editor) — Level Sequence tracking needs it

Niagara

Tracking Niagara Systems and Emitters

Optional. BPTracker still works fine; only Niagara assets won't be tracked

Will this affect my game?

No. BPTracker is an editor-only plugin. It is automatically excluded from packaged/shipping builds — zero runtime cost, zero files in your shipped game.

2. Your First Five Minutes — a Hands-On Tour

The best way to understand BPTracker is to watch it catch one change. Try this:

  1. Open any Blueprint in your project (or create a throwaway one).

  2. Move a node, add a variable, or change a default value — anything.

  3. Save the asset (Ctrl+S).

  4. In the Content Browser, right-click that Blueprint and choose View Change History.

A history window opens with a fresh entry at the top. Expand it and you'll see lines like:

Now try these on the diff lines:

  • Hover a line → a tooltip shows the full recorded key and values. If the line is jumpable, it highlights and shows a "double-click to jump" hint.

  • Double-click a Blueprint node line → the Blueprint editor opens focused on that exact node. This works even days later, in a fresh editor session.

  • Right-click a line → copies the raw key to your clipboard (handy for bug reports or searching).

That's the core loop: save → history → jump. Everything else is convenience on top.

💡 Good to know: BPTracker starts recording from the moment it's enabled. It cannot look back in time — changes made before installation are not recoverable. (Baselines are captured when an asset is first opened, so the very first save of an asset records a baseline rather than a diff.)

3. The Three Places to See History

① One asset — Content Browser right-click

Right-click any asset > View Change History. Shows that asset's timeline only. If the history window is already open, it switches to the asset you clicked.

② Everything — Tools menu

Tools > Change History. One merged timeline across all assets, newest first, with each entry prefixed by its asset name. This is the "what happened in the project today?" view. Use the search box to narrow it down — it matches both change text and asset paths, so typing Player finds every change to anything under a Player folder or named Player-something.

ℹ️ You won't find Change History inside an asset editor's Window menu — that's intentional, to keep each view clearly scoped. Use the right-click for one asset, Tools for everything.

③ Statistics — Change Dashboard

Tools > Change Dashboard (also in the main Window menu). A per-asset overview: how many changes, most recently changed, most frequently changed. It merges everything — current session, disk history, shared team history, and archives — so the numbers cover the full recorded lifetime of your project, even after editor restarts. Use Refresh to re-scan and Run Archive Now to tidy up old entries on the spot.

Filters in the history window

  • Search box — filters by change text or asset path.

  • Changes only — hides "asset created / renamed / deleted" event lines so you see only real content edits. (Saves that changed nothing are never recorded at all, so you'll never see empty entries.)

  • Days — how far back to look (the default comes from the Default Filter Days setting).

4. Understanding the Diff Lines

BPTracker names things the way the editor does, so lines are readable without detective work:

You'll see
It means

ScalarParameter:Roughness

A material expression node, by type and parameter name

Branch@a1b2c3d4

A Blueprint node (name + short id — the id only appears when two nodes share a name)

Ch.Volume

A Sequencer channel, by its channel name

Emitter|Smoke.Stk|SpawnRate

A Niagara emitter's stack module

op: + / - / ~

Added / removed / modified

Jumpable line types and where they take you:

Line type
Double-click opens

Blueprint node / pin / comment

Blueprint editor, focused on that node

Material / Material Function node or comment

Material editor, node selected

Sequencer track / section

Level Sequence editor, track selected

Niagara emitter line

Niagara editor for that System/Emitter

Behavior Tree / Blackboard line

Behavior Tree editor

If the target no longer exists (deleted, moved), you get a polite toast message instead of a crash — the history itself is never lost.

5. Settings, Explained

Everything lives in Project Settings > Plugins > BP Tracker. The defaults are sensible — most people only ever touch Asset Types.

Asset Types — what gets tracked

Each asset family has a master checkbox and indented detail options (greyed out until the master is on):

Group
Master
Detail options

Blueprint

Track Blueprint

Components / Node Details / Macros — these detail options apply to every Blueprint kind, including Widget and Anim Blueprints

Widget Blueprint

Track Widget Blueprint

Properties / Slot / Animations / Bindings

Animation

(three toggles)

Anim Blueprint, Anim Montage, Anim Sequence + shared Notify Details

Material

Track Material

Properties / Input Connections / Expression Nodes / Material Instance / Material Function

AI

Track Behavior Tree

BT Node Details (covers Blackboard too)

Data

(seven toggles)

Data Asset, Data Table, Curve, Curve Table, String Table, User Defined Enum, User Defined Struct

Niagara

Track Niagara System

Module Values / Renderer Details

Sequencer

Track Level Sequence

Section Details

Turning a type off stops new recording for it — history already on disk stays and remains browsable. (Heads-up: the first save after switching detail options off compares against the previous, richer snapshot once, so you may see a single bulk "removed" entry. After that, silence.)

Recording — when saves get recorded

  • Enabled — the global switch. Off means nothing is recorded anywhere.

  • Ignore Auto Save (default: on) — editor auto-saves don't pollute your history.

  • Min Save Interval — if you hammer Ctrl+S, only the first save in this window is recorded.

  • Track Save All / Max Save All Assets — what happens when you hit "Save All" and 30 assets save at once: record them (up to the cap) or skip the burst.

Local History — your personal record (default: on)

Writes each asset's log to <Project>/AssetChangeLogs/ — deliberately outside the volatile Saved/ folder, so cleaning Saved/ never destroys your history. Local History Path lets you move it (takes effect at next editor start).

Content History — for teams (default: off)

Also writes logs under Content/, right next to your assets. Commit them with your normal source control flow (Git/SVN/Perforce) and every teammate running BPTracker sees the combined history — including who made each change. On startup, shared logs sync into your local history automatically.

Performance

  • Async Write (default: on) — log writing happens on a background queue: no editor hitches, no lost or garbled lines (the queue flushes on renames and editor shutdown).

  • Baseline Cache Size — how many baselines stay in memory (LRU). Applied at next editor start.

Display

  • Page Size — history entries per page.

  • Default Filter Days — the initial "how far back" of the history window.

  • History / Dashboard Window Default Size and a Reset Window Sizes button if you've dragged things somewhere unfortunate.

Archive — automatic housekeeping

History files grow forever unless you archive. With Enable Archive on:

  • Entries older than Archive Entries Older Than (Months) move to an archive folder.

  • Force Archive When File Size Exceeds (MB) additionally trims oversized live logs.

  • Archive Path — where archived entries go (default <Project>/AssetChangeLogs/_archive, applied at next editor start).

  • Archive After Days (Test) — a testing override; when > 0, the smaller of days/months wins.

  • Archived entries disappear from the live History window but still count in the Dashboard.

  • Run Archive Now runs a pass immediately.

Actions

  • Initialize All Baselines — pre-captures baselines for every tracked asset in the project, so even the first save of an untouched asset produces a proper diff. Nice to run once right after installing. (Requires Enabled to be on.)

  • Clear All Baselines — the factory reset: deletes all baselines, in-memory history, local logs, and archived history (including a custom archive path). A confirmation dialog lists everything that will be removed. This cannot be undone — export anything you care about first.

🔁 Three settings need an editor restart: Local History Path, Archive Path, Baseline Cache Size. The editor reminds you with a notice when you change them.

6. Console Commands

For automation or quick keyboard access (~ console):

Command
Same as

BPTracker.InitAll

Actions > Initialize All Baselines

BPTracker.RunArchive

Archive > Run Archive Now

BPTracker.ClearAll

Actions > Clear All Baselines (asks for confirmation)

7. Where Your Data Lives

  • Each asset gets its own log file: <AssetName>.changelog.jsonl — plain-text JSONL (one JSON event per line, UTF-8). Easy to grep, diff, or parse in CI scripts.

  • Default locations: <Project>/AssetChangeLogs/ (local), Content/ (shared, if enabled), <Project>/AssetChangeLogs/_archive (archive).

A real log line looks like this:

t = timestamp, a = author, d = the list of diffs (op: + added, - removed, ~ modified). Field order isn't guaranteed — parse by key name.

8. FAQ & Troubleshooting

Q. I saved an asset but nothing showed up. Walk this checklist:

  1. Recording > Enabled is on?

  2. The asset's type toggle is on under Asset Types? (e.g. Data Table changes need Track Data Table.)

  3. Did the save actually change anything? Zero-diff saves are never recorded — this is by design, not a bug.

  4. Was it an editor auto-save? Those are skipped by default (Ignore Auto Save).

  5. Was it part of a "Save All" burst with Track Save All off?

Q. I can't find Change History in the asset editor's Window menu. That's intentional — it lives in exactly two places: Content Browser right-click (one asset) and Tools > Change History (all assets). The Dashboard, on the other hand, is in the Window menu.

Q. Double-clicking a Niagara module line opens the editor but doesn't select the module. An engine limitation — the Niagara editor doesn't allow external code to select stack modules. BPTracker opens the correct System/Emitter; find the module by the name shown in the diff line.

Q. My history is suddenly shorter! Check whether Archive is enabled — old entries move to the archive folder (still visible in Dashboard statistics). They're not gone; look in AssetChangeLogs/_archive.

Q. Do my teammates see my changes? Only if Content History is enabled and you commit the generated log files under Content/. Local history is yours alone.

Q. Can I track assets in a plugin folder or engine content? BPTracker tracks project assets (/Game/...). Engine and plugin-mounted content is out of scope.

Q. Does it slow the editor down? Recording happens at save time against an in-memory baseline, and writing is asynchronous. In normal use you shouldn't notice it. If you work with thousands of huge assets, you can trim Asset Types down to what you care about.

Q. How do I completely start over? Actions > Clear All Baselines (read the dialog!), or delete <Project>/AssetChangeLogs/ while the editor is closed.

9. Support

Questions, bug reports, feature requests — we're happy to hear from you:

To help us help you fast, include:

  1. Your engine version (e.g. 5.8.0) and BPTracker version,

  2. The asset type involved,

  3. What you expected vs. what happened,

  4. If possible, the relevant .changelog.jsonl file from <Project>/AssetChangeLogs/.

Copyright 2026 Dev Levy. All Rights Reserved.

PreviousWhat It Tracks ?
NextPlugin Settings

Last updated