Python

Blueprint Scribe’s editor subsystem, TABlueprintScribeSubsystem, gives Blueprint and Python access to the same scan and export as the panel.

Note

Python scripting requires Unreal’s Python Editor Script Plugin to be enabled in your project.

Get the subsystem

import unreal

scribe = unreal.get_editor_subsystem(unreal.TABlueprintScribeSubsystem)

In Blueprint (for example in an Editor Utility Widget), get the Blueprint Scribe editor subsystem (class TABlueprintScribeSubsystem) and use the functions in the ta Blueprint Scribe category.

Functions

Function	Returns
scan_paths(paths, show_progress=True)	TABlueprintScribeReport
scan_project(show_progress=True)	TABlueprintScribeReport
scan_assets(assets, show_progress=True)	TABlueprintScribeReport
get_default_export_options()	TABlueprintScribeExportOptions
export(report, options, show_progress=True)	TABlueprintScribeExportResult
get_ai_text(report, assets, include_private=True)	str
copy_for_ai(report, assets, include_private=True)	int
find_cleanup(assets)	Array of TABlueprintScribeCleanupItem
apply_cleanup(items)	TABlueprintScribeCleanupResult
render_graph_image(blueprint, graph_path, file_path, zoom=1.0, max_size=4096)	bool
focus_issue(issue)	bool
focus_graph(asset, graph_path)	bool
open_panel_with_paths(paths)	Nothing
open_panel_with_assets(assets)	Nothing
select_in_panel(asset)	Nothing
show_panel_page(page)	Nothing
export_from_panel()	Nothing
open_cleanup_preview(assets)	Nothing

scan_paths, scan_project and scan_assets

Document and audit assets and return a report with every asset and every finding, like a scan in the panel.

• scan_paths scans content folders such as "/Game/Blueprints" and their subfolders. Excluded Paths from the settings are skipped.
• scan_project scans the Included Paths from the settings.
• scan_assets scans a list of unreal.AssetData, for example the Content Browser selection. Assets other than Blueprints, structures and enums are ignored.

With show_progress=True a progress dialog with a Cancel button is shown; cancelling returns the assets scanned so far. Pass False in scripts that run unattended.

These functions don’t wait for the Asset Registry. Right after the editor starts, wait until asset discovery has finished, or some assets will be missing. (An editor started with -ExecutePythonScript waits for discovery before it runs the script.)

get_default_export_options

Returns the export options from Project Settings > Plugins > ta Blueprint Scribe. Change the copy you get back and pass it to export; the settings themselves don’t change.

export

Renders the graph images and writes the HTML site, the Markdown files, the JSON report and the AI-ready text of a report, exactly like Export docs in the panel, including cleaning the output folder. It doesn’t open the result in a browser.

Graph images need the editor UI. In a commandlet they are skipped with a warning in warnings. With show_progress=True the image rendering shows a progress dialog with a Cancel button.

If no format is selected, nothing is written and errors contains “No output format is selected (HTML, Markdown, JSON or AI-ready text).”

get_ai_text and copy_for_ai

get_ai_text returns the AI-ready text of the assets in assets (a list of unreal.SoftObjectPath), or of every asset of the report when the list is empty. One asset gives its text alone; several start with the title and a short guide to the format. copy_for_ai puts the same text on the clipboard and returns its length in characters. With include_private=False private variables and functions are left out.

find_cleanup, apply_cleanup and open_cleanup_preview

find_cleanup loads the Blueprints in assets and returns what a cleanup would remove, and what looks unused but is kept (safe is False, with the reason). It changes nothing. Set selected to False on items you want to keep.

apply_cleanup removes the items that are safe and selected, in one Undo step, and compiles the changed Blueprints. They are not saved. Before removing, each Blueprint is checked again; items that are no longer safe are skipped and listed in skipped.

open_cleanup_preview opens the panel’s cleanup preview for assets scanned in the panel, without blocking the script.

show_panel_page and export_from_panel

show_panel_page opens the panel at a page: "Blueprints", "Audit", "Migration" or "Export". export_from_panel exports the panel’s last scan with the options of its Export page, like its Export docs button.

render_graph_image

Saves one graph of a Blueprint as a PNG file. graph_path is the path of a graph in the report, for example "EventGraph" or "EventGraph/Collapsed Graph". A relative file_path starts at the project folder; missing folders are created. zoom and max_size work like the image options; here the zoom is limited to 0.1 – 2.0 and the size to 256 – 16384. Returns False and logs a warning when the graph isn’t found or can’t be rendered. Needs the editor UI.

focus_issue and focus_graph

focus_issue opens the asset of a finding in its editor, at the finding’s node or graph when it has one, like Go to node in the panel. focus_graph opens a Blueprint (an unreal.SoftObjectPath) at a graph path. Both return False if nothing could be opened.

open_panel_with_paths, open_panel_with_assets and select_in_panel

Open the Blueprint Scribe panel and scan these folders or assets, or select an already scanned asset on its Blueprints page.

Types

All properties of the report types are read-only. The export options can be changed.

TABlueprintScribeReport

Property	Type	Meaning
assets	Array of TABlueprintScribeAsset	Every documented asset, sorted by package path
issues	Array of TABlueprintScribeIssue	Every finding
scope	Array of str	The scanned folders, or the names of the scanned assets
time	DateTime	When the scan started
seconds	float	Duration of the scan
complexity_score	int	Average complexity of the Blueprints with logic, 0 to 100

The health score and the overall coverage are not properties of the report. scribe.json contains them as healthScore and docCoverage, or you can calculate them from the report; see Examples.

TABlueprintScribeAsset

Property	Type	Meaning
name	str	Asset name
package	str	Package path, for example /Game/Blueprints/BP_Door
object_path	SoftObjectPath	Object path
asset_class	str	Asset class, for example Blueprint or WidgetBlueprint
kind	TABlueprintScribeAssetKind	ACTOR, COMPONENT, OBJECT, WIDGET, ANIMATION, INTERFACE, FUNCTION_LIBRARY, MACRO_LIBRARY, STRUCT or ENUM
id	str	File name of the asset’s pages, for example Game.Blueprints.BP_Door
description, category, display_name, namespace	str	Description and Class Settings values
parent_chain	Array of TABlueprintScribeLink	Parent classes, from the direct parent up to (without) Object
interfaces	Array of TABlueprintScribeLink	Implemented interfaces
components	Array of TABlueprintScribeComponent	Components of an Actor Blueprint
variables	Array of TABlueprintScribeVariable	Member variables, or the fields of a structure
functions, events, dispatchers, macros	Array of TABlueprintScribeFunction	Functions, events, event dispatchers and macros
graphs	Array of TABlueprintScribeGraph	All graphs
notes	Array of TABlueprintScribeNote	Comment boxes and node comments
widgets	Array of TABlueprintScribeWidget	Widget hierarchy of a Widget Blueprint
widget_animations	Array of str	Widget animation names
enum_entries	Array of TABlueprintScribeEnumEntry	Entries of an enum
target_skeleton	TABlueprintScribeLink	Skeleton of an Animation Blueprint
uses, used_by	Array of TABlueprintScribeLink	References from and to this asset
compile_status	str	Up to date, Warnings, Error, Dirty or Unknown; empty for structures and enums
metrics	TABlueprintScribeMetrics	Size, logic and documentation numbers
migration	TABlueprintScribeMigration	C++ migration score, verdict, reasons and upgrade notes

The fields have the same meaning as in the JSON report.

TABlueprintScribeMetrics

Property	Type	Meaning
nodes	int	Nodes in all graphs, without comments and reroute nodes
largest_graph_nodes, largest_graph	int, str	Size and name of the largest graph
hard_reference_packages	int	Packages loaded together with the asset through hard references (recursive, without C++ packages)
hard_reference_bytes	int	Disk size of those packages in bytes
referencers	int	Packages that reference this asset
documentable	int	Members that can have a description
documented	int	Members that have one
branches, loops, casts, math_nodes	int	Enabled branch, loop, cast and math nodes
tick_nodes, tick_loops	int	Nodes and loops that Event Tick runs every frame
complexity	int	Complexity score, 0 to 100; 0 for assets without logic

TABlueprintScribeMigration

Property	Type	Meaning
score	int	C++ score, 0 (fine in Blueprint) to 100 (strong C++ candidate)
verdict	str	Strong C++ candidate, Consider C++, Fine in Blueprint or No logic
reasons	Array of str	Why, most points first
upgrade_notes	Array of str	What to fix before an engine upgrade

TABlueprintScribeIssue

Property	Type	Meaning
asset_path	SoftObjectPath	The asset
rule_id	Name	Rule id, for example Graph.Large
severity	TABlueprintScribeSeverity	INFO, WARNING or ERROR
message	Text	The finding
graph	str	Graph path, or empty
node_guid	Guid	Node, or an invalid GUID if the finding has no node

Other report types

Type	Properties
TABlueprintScribeLink	text, target (package; empty for C++ classes and types), note (soft, placed in level or empty)
TABlueprintScribeVariable	name, type (link), category, default_value, description, flags, instance_editable, private, used
TABlueprintScribeFunction	name, description, category, access, flags, inputs, outputs, local_variables, graph_name, owner_graph, override, private, node_guid
TABlueprintScribeParam	name, type (link), default_value, by_ref
TABlueprintScribeComponent	name, class_ (link), parent, description, inherited_from, depth
TABlueprintScribeGraph	name, kind, path, node_count, logic (the graph as readable text), image, image_size
TABlueprintScribeNote	graph, text, node
TABlueprintScribeWidget	name, class_ (link), depth, is_variable
TABlueprintScribeEnumEntry	name, display_name, description, value

class_ has a trailing underscore because class is a Python keyword. A graph’s image and image_size are only filled in the report that export works on internally; in the report returned by a scan they are empty.

TABlueprintScribeCleanupItem and TABlueprintScribeCleanupResult

Type	Properties
TABlueprintScribeCleanupItem	asset (SoftObjectPath), kind (UNUSED_VARIABLE, UNUSED_FUNCTION, DEAD_NODE, DISABLED_NODE or UNUSED_PURE_NODE), name, graph, node_guid, reason, safe (read-only), selected (can be changed)
TABlueprintScribeCleanupResult	removed (number of items removed), changed_assets (the changed Blueprints, not saved), skipped (items that were no longer safe or not found)

TABlueprintScribeExportOptions

Property	Type	Meaning
output_directory	str	Output folder. Relative paths start at the project folder; empty means Saved/BlueprintScribe.
title	str	Title on the pages; empty: the project name followed by “Blueprints”
html	bool	Write the HTML site
markdown	bool	Write the Markdown files
json	bool	Write scribe.json
ai_text	bool	Write the AI-ready text to the ai folder
graph_images	bool	Render graph images (needs the editor UI)
image_zoom	float	Zoom of the graph images (1.0 = 100 %)
max_image_size	int	Longest side of a graph image in pixels
include_private	bool	Document private variables and functions
include_audit	bool	Show the findings on the pages and write audit.html
show_credit	bool	The credit line at the bottom of the pages

TABlueprintScribeExportResult

Property	Type	Meaning
success	bool	True if nothing failed (warnings are allowed)
output_directory	str	Full path of the output folder
index_file	str	index.html, or markdown/index.md, scribe.json or ai/blueprints.md when HTML is off
pages	int	HTML pages (including audit.html and migration.html) and Markdown asset files written
images	int	Graph images written
warnings	Array of str	Problems that didn’t stop the export, for example skipped graph images
errors	Array of str	Problems that failed the export, for example a file that couldn’t be written

Examples

Scan and export

import unreal

scribe = unreal.get_editor_subsystem(unreal.TABlueprintScribeSubsystem)

report = scribe.scan_paths(["/Game/Blueprints"])
for asset in report.assets:
    print(asset.name, asset.kind, asset.metrics.nodes, "nodes,",
          asset.metrics.documented, "of", asset.metrics.documentable, "documented")
for issue in report.issues:
    print(issue.severity, issue.rule_id, issue.message)

options = scribe.get_default_export_options()
options.output_directory = "Docs/Blueprints"
options.title = "My Game Blueprints"
result = scribe.export(report, options)
print(result.index_file, result.pages, "pages,", result.images, "images")

Use the Content Browser selection

selected = unreal.EditorUtilityLibrary.get_selected_asset_data()
report = scribe.scan_assets(selected)

Export only JSON

options = scribe.get_default_export_options()
options.html = False
options.markdown = False
options.json = True
options.output_directory = "Saved/BlueprintScribeJson"
result = scribe.export(scribe.scan_project(False), options, False)
print(result.index_file)  # .../scribe.json

A JSON-only export renders no graph images.

Health score and coverage

report = scribe.scan_project(False)

flagged = {i.asset_path.export_text() for i in report.issues
           if i.severity != unreal.TABlueprintScribeSeverity.INFO}
clean = len(report.assets) - len(flagged)
health = 100 * clean / len(report.assets) if report.assets else 100

documented = sum(a.metrics.documented for a in report.assets)
documentable = sum(a.metrics.documentable for a in report.assets)
coverage = documented / documentable if documentable else 1.0

print(f"health {health:.0f}, {coverage:.0%} documented")

Find and open findings of one rule

report = scribe.scan_paths(["/Game"], False)
ticks = [i for i in report.issues if str(i.rule_id) == "Tick"]
for issue in ticks:
    print(issue.asset_path.export_text(), issue.message)
if ticks:
    scribe.focus_issue(ticks[0])  # opens the Blueprint at the Event Tick node

List the C++ candidates

report = scribe.scan_project(False)
for asset in sorted(report.assets, key=lambda a: a.migration.score, reverse=True)[:10]:
    print(asset.migration.score, asset.name, asset.migration.verdict, "complexity", asset.metrics.complexity)
    for reason in asset.migration.reasons:
        print("  -", reason)

Copy one Blueprint for AI

report = scribe.scan_paths(["/Game/Blueprints"], False)
door = [a for a in report.assets if a.name == "BP_Door"][0]
length = scribe.copy_for_ai(report, [door.object_path])
print(length, "characters on the clipboard")

Clean up with a preview

items = scribe.find_cleanup([door.object_path])
for item in items:
    print(item.kind, item.name, item.safe, item.selected, item.reason)
result = scribe.apply_cleanup(items)  # one Undo step, not saved
print(result.removed, "removed from", len(result.changed_assets), "Blueprints")

Render one graph

blueprint = unreal.load_asset("/Game/Blueprints/BP_Door")
ok = scribe.render_graph_image(blueprint, "EventGraph", "Saved/BP_Door_EventGraph.png", 1.0, 4096)