> For the complete documentation index, see [llms.txt](https://docs.devlevy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devlevy.com/ue-code-plugin/bptracker/documentation.md).

# 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:

```
+ N|Branch@a1b2c3d4          (a node you added)
~ P|MyVariable.DefaultValue  Old: 0  New: 42
```

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:

```json
{"t":"2026-04-14T12:34:56.000Z","sid":"...","a":"UserName","asset":"/Game/Foo.Foo","type":"Material","event":"save","d":[{"cat":"properties","key":"BlendMode","op":"~","old":"Opaque","new":"Translucent"}]}
```

`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:

* 📧 **<lv.stack.co@gmail.com>**
* [**Discord Channel**](https://discord.gg/jCJy4At9p)

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.