【UE5】UnrealPythonの基本的な使い方

2023年7月14日 最終更新日時 : 2025年7月30日 ランカース

プログラマーの尾関です。

今回は UnrealPythonの基本的な使い方について書いていきます。

  • UEバージョン: 5.1

目次

Unreal Pythonとは

Unreal Python は、Unreal Engine（特にエディタ操作）を Python スクリプトで制御できるようにする機能です。主に「エディタ拡張」や「アセットの一括処理」「パイプラインの自動化」などに使われます。

他にも、Editor Utility Widget (EUW) に存在しない機能がなぜか Unreal Python では使用できたりすることもあります。

Information

注意点として、ランタイム（ゲーム実行中）の処理には使えません。あくまで開発サポートの機能として考えたほうが良さそうです。

セットアップ手順

プラグインを設定する

メニューから「編集 > プラグイン」を選びます。

“Scripting” から “Editor Scripting Utilities” と “Python Editor Script Plugin” を有効にします。

UE5.1では、すでに有効になっていたので、その場合は設定不要です。

Pythonの動作確認

Pythonが動作するかどうかを確認します。エディタの下部にある “Cmd” をクリックして、”Python” を選びます。

コマンドに 「print(“hello”)」 と入力して Enterキーで決定します。

するとアウトプットログに「hello」と出力されます。

Pythonスクリプトフォルダにパスを通す

これは必須ではないですが、Pythonスクリプト用のフォルダを作っておくと管理しやすくなります。

コンテンツブラウザから「Python」という名前でフォルダを追加します。

メニューから「編集 > プロジェクト設定」を選びます。

パスを追加すると再起動を促されるので、再起動しておきます。

Pythonスクリプトはコンテンツブラウザから追加できないので、”Python” フォルダを右クリックして「エクスプローラーで表示する」を選びます。

エクスプローラー上で、Pythonスクリプトを追加します。

ここでは “hoge.py” としました。

Pythonスクリプトを実行する

スクリプトは以下のように記述してみます。

print("hello python")

このスクリプトを実行するには “Cmd” に戻して、以下のコマンドを実行します。

py hoge.py

実行すると以下のように アウトプットログに “hello python” と出力されるのが確認できました。

なお、”Cmd” でのコマンドは、キーボードの上を押すことで前回の入力を繰り返し使用することができます。

VSCodeのオートコンプリートを有効にする

Unreal Pythonを書く際、使用可能な関数をオートコンプリートで入力できると便利です。これは必須ではありませんが、VSCodeのオートコンプリートを行う方法について書いておきます。

Pythonスタブファイルの作成

UEのエディタのメニューから「編集 > エディタの環境設定」を選びます。

プラグイン > Python から「デベロッパーモード」にチェックを入れます

再起動を促されるので、エディタを再起動します。

するとプロジェクトの「Intermediate」フォルダに「PythonStub」が作成されます。

VSCodeの設定

VSCodeを起動してメニューから「ファイル > フォルダーを開く」を選びます。

Pythonスクリプトを格納しているフォルダに移動して「フォルダーの選択」をクリック。

フォルダのアクセス権の設定確認が表示されますが、問題ないので「親フォルダー “Content” 内のすべてのファイルの作成者を信頼します」にチェックを入れて、「はい、作成者を信頼します」をクリックします。

メニューから「ファイル > ユーザー設定 > 設定」を選びます。

「ユーザー」タブの状態で、「拡張機能 > Python > Auto Completes: Extra Paths」のところにある「setting.json で編集」を選びます。

この表示がない場合は Python の拡張機能がインストールされていないので、インストールしておきます。

settings.json が開かれたら以下のように PythonStubファイルのパスを指定します。

{
    "python.autoComplete.extraPaths": [
        "C:\\Users\\ozeki\\Documents\\Unreal Projects\\MyProject\\Intermediate\\PythonStub"
    ],
    "python.analysis.extraPaths": [
        "C:\\Users\\ozeki\\Documents\\Unreal Projects\\MyProject\\Intermediate\\PythonStub"
    ]
}

この Jsonファイルを保存して VSCode を再起動します。

するとコードの自動補完機能が有効となります。

スクリプト作成例：アセットの操作

Unreal Pythonの便利機能の作成例として、アセットを操作するスクリプトを書いてみます。

アセットのプロパティを書き換える

アセットのプロパティを書き換えるサンプルとして、メディアプレイヤーを扱ってみます。

まずはメディアプレイヤーを作成します。

Pythonフォルダに「MP_Test」という名前でメディアプレイヤーのアセットを追加しました。

MP_Testを開くと「Play on Open」にチェックがついているのが確認できます。これを Pythonスクリプトで 外すようにしてみます。

hoge.py を以下のように書き換えてみます。

# unrealの操作を行うためのモジュール.
import unreal

# MP_Testを読み込む.
obj = unreal.load_asset("/Game/Python/MP_Test")

# "play_on_open" プロパティを False に書き換える
obj.set_editor_property("play_on_open", False)

“import unreal” は Unrealの機能にアクセスするためのモジュールです。次に “unlreal.load_asset()” でコンテンツからアセットを読み込みます。そして “set_editor_property()” でプロパティを書き換えることができます。

ではコマンドに “py hoge.py” と入力して実行してみます。

“MP_Test” を開くと、“Play on Open” のチェックが外れていることが確認できます。

なお、明示的に型を指定すると、オートコンプリートが有効な場合にプロパティが補完されて入力が便利です。

# unrealの操作を行うためのモジュール.
import unreal

# MP_Testを読み込む.
obj:unreal.MediaPlayer = unreal.load_asset("/Game/Python/MP_Test")

# "play_on_open" プロパティを False に書き換える
obj.play_on_open = False

選択しているアセットを取得する

例えば以下のように “BP_EnemyData” と “DT_EnemyData” を選択しているとします。

以下のように unreal.EditorUtilityLibrary.get_selected_assets() で選択しているアセットのパスのリストを取得できます。

# unrealの操作を行うためのモジュール.
import unreal

# 選択しているアセットを取得する.
for asset in unreal.EditorUtilityLibrary.get_selected_assets():
    # アセットのパスを出力する
    print(asset.get_path_name())

実行結果

Cmd: py hoge.py
LogPython: /Game/Python/BP_EnemyData.BP_EnemyData
LogPython: /Game/Python/DT_EnemyData.DT_EnemyData

スクリプト作成例：レベル操作

エディタで現在開いているレベルを取得する

unreal.EditorLevelLibrary.get_editor_world() でエディタで開いているレベルを取得できます。

import unreal

# 現在エディタで開いているレベルを取得する.
world:unreal.World = unreal.EditorLevelLibrary.get_editor_world()
print(world

選択しているアクターを取得する

import unreal

# 選択しているActorをリストで取得する (取得でない場合リストは空となる).
list_actors = unreal.EditorLevelLibrary.get_selected_level_actors()
print(list_actors)
Information

何も選択していない、または「フォルダー」や「ワールド」を選択している場合は何も取得できません

現在開いているレベルにアクターを配置する

AActorを配置して名前(ラベル名)を変更する
import unreal

# 現在開いているレベルに配置する.
location:unreal.Vector = unreal.Vector(1000, 1000, 500)
rotator:unreal.Rotator = unreal.Rotator(0, 0, 0)
actor_class:unreal.Actor = unreal.EditorLevelLibrary.spawn_actor_from_class(unreal.Actor, location, rotator)
# 名前を変更する.
actor_class.set_actor_label("test")

アクターにスケール値を設定する

set_actor_scale3d()でスケール値を設定できます。

import unreal
import sys

# 現在開いているレベルに配置する.
location:unreal.Vector = unreal.Vector(1000, 1000, 500)
scale:unreal.Vector = unreal.Vector(1, 2, 3)
rotator:unreal.Rotator = unreal.Rotator(0, 0, 0)
actor_class:unreal.Actor = unreal.EditorLevelLibrary.spawn_actor_from_class(unreal.Actor, location, rotator)
actor_class.set_actor_scale3d(scale) # スケール値を設定.

ブループリントクラスを配置する

“BP_Ball” というブループリントクラスをレベルに配置してみます。

# ブループリントクラスの読み込み.
actor_class:unreal.Actor = unreal.EditorAssetLibrary.load_blueprint_class("/Game/Python/BP_Ball")

# 現在開いているレベルに配置する.
location:unreal.Vector = unreal.Vector(1000, 1000, 500)
rotator:unreal.Rotator = unreal.Rotator(0, 0, 0)
unreal.EditorLevelLibrary.spawn_actor_from_class(actor_class, location, rotator)

上記コードを実行すると “BP_Ball” がレベルに配置されました。

スクリプト作成例：UI

プログレスダイアログの表示

unreal.ScopedSlowTask() を使うと進捗ダイアログを表示することができます。

# 進捗ダイアログ表示テスト.
import time
import unreal

total_frames = 100 # トータルフレーム数.
text_label = "しばらくお待ち下さい..." # 表示するメッセージ.
with unreal.ScopedSlowTask(total_frames, text_label) as slow_task:
    slow_task.make_dialog(True)               # ダイアログを表示する.
    for i in range(total_frames):
        if slow_task.should_cancel():         # Cancelボタンを押したら閉じる.
            break
        slow_task.enter_progress_frame(1)     # フレームを進める.
        time.sleep(0.05)                      # 0.05秒待ち

処理時間がかかるときに表示しておくと良いです。

スクリプト作成例：ファイル読み込み

外部ファイル読み込み

外部ファイルの読み込みはUnreal Pythonにはなさそうなので、 “sys” モジュールを使って読み込みます。

import sys

# 起動引数を取り出す.
in_file = sys.argv[1]
# UTF8 BOM付きのファイルを読み込む
f = open(in_file, "r", encoding="utf-8-sig")
print(f.read())

コマンドから引数にファイルパスを渡します（ドラッグ＆ドロップではファイルパスが渡せないので、手入力する必要があります）

py hoge.py C:\Users\ozeki\Desktop\test\test.txt

参考ページ

Unreal Pythonの情報を得るのに役立つページをまとめておきます。

まずは公式ドキュメントの以下のページです。

それと非公式ですが以下のページも参考になりました。

以上、Unreal Pythonを理解するためにこの記事が役立てれば何よりです。

＼ 最新情報をチェック ／

カテゴリー
Python、UE5、Unreal Engine、プログラム
前の記事
ゲーム開発でのコードジェネレーターの使われ方
2022年6月24日
次の記事
【UE5】UnrealPythonでシーケンサーを扱うTips
2023年7月21日