間違い探しに挑戦！

まずは次のグラフを見てほしい。

A,B,C,Dの４つのブロック（関数ノード、Get変数ノードの組）がある。A,B,C,Dはすべて異なるノードで構成されている。さて、どの辺が違うのかよく見てほしい。

分かった人は次へ。分からない人も次へ。

答え合わせ

• Aは特に _ を使用していない
• Bは語頭に _ を使用。関数ノード名でスペースが多いことに気が付いた人もいるだろう。
• Cは語尾に _ を使用
• Dは単語の区切りに _ を使用

おそらく大半の人がBの関数ノード以外の違いを見分けられなかっただろう。

なんでこんなことがおきるのか？

グラフエディタ上では_はスペースに変換される、という機能があるため。

元々UE4では名前の命名規則はPascalCaseが採用されている。

https://wa3.i-3-i.info/word13955.html

wa3.i-3-i.info

このPascalCaseを一般的な英文にして読みやすくするために単語の区切りに自動的にスペースを表示してくれる、というのがBPなどのグラフエディタの便利機能としてある。この時、略字と単語が続く（例：XMLAndHTML）時などにどこからが区切りかわからないために区別がつくように_で単語の区切りを示す書き方があり（例：XML_AndHTML）、この書き方にも対応したために_をスペースに表示する機能になった、と思われる。

なので本来はこれは便利な機能のはずなのだ。

問題が起きる条件

見た目でスペースと区別がつかない、という問題が起きる条件は次になる。

語頭（プレフィックス）に「_」

テキスト系のスクリプト言語ではグローバルな変数とローカルな変数の名前被りを避け、ローカルであることを明示するために語頭(プレフィックス)に_を付けるルールを設けていることがしばしばある（JavaScriptやPythonなど）。

その感覚でローカルな関数や変数名の頭に_を付けてしまうと、グローバルなものと区別がつかない、という残念なことが起きる。

語尾（ポストフィックス）に「_」

語頭の場合と異なり意識的につける文化などはないので大きく問題にはなりがちではないが、区別のつかなさでは語頭にあるよりも凶悪でまったく区別がつかない。

語頭にある場合、スペースの幅分でかろうじてわかることもあるが、語尾は無理！
混乱の危険性ではよりこちらのほうが上である。

大文字が続かない場合の語中の「_」

前述の通り、 略字などで単語の区切りなのに大文字が続く場合を除いて 、語中、特に単語の区切りに_を入れては全く区別がつかなくなる。

余談：単語の区切りに「　(スペース)」

_ではないが、自動でスペースが入力される位置にスペースを入力するのも危険。
UE4のBPのグラフ・関数・変数名にはスペースが入れられるためにこれも併せて要注意。

まとめ

• BPのグラフ・関数・変数名で次は危険なので避ける
  • 語頭（プレフィックス）に「_」
  • 語尾（ポストフィックス）に「_」
  • 大文字が続かない場合の語中の「_」
  • 単語の区切りに「　(スペース)」

Gamemakin UE4スタイルガイドにもこの辺は書いていないので要注意。
新しく始めるプロジェクトでは是非このルールを採用してほしい。

akenatsu/ue4-style-guide

An attempt to make Unreal Engine 4 projects more consistent - akenatsu/ue4-style-guide

github.com

UE4のブループリント（以下、BP）はビジュアルスクリプティング言語¹と呼ばれるグラフィカルなプログラミング言語である。

ビジュアルスクリプティング言語はテキストベースのスクリプティング言語に比べて歴史が浅く、言語ごとに特性も大きく変わることなどから「こう書くべき」というノウハウがあまり溜まっていない。また、UE4のBPはゲームデザイナーやアーティストなどのノンプログラマ向けに作られた経緯もあることから、使用者が書き方・スタイルガイドへの意識やノウハウが少ない。

#UE4 のBlueprintはとても良いんだけど、文字通りスパゲッティ化しやすいという欠点も。スタイルフォーマッター的なツールがない ＆ 主に使うノンプログラマはノウハウ持ってない ＆ 見やすいスタイルが固まってない などが理由。

— K. S. (@ConquestArrow) 2017年4月24日

結果以下のような問題をBPは抱えている；

• 👎ノードをつなぐワイヤーのスパゲッティ化
  • 見て理解するのが困難になり生産性が落ちる
  • 問題のある処理を見逃しがちになる
• 👎ワイヤー繋げなおしの手間がかかることによる処理の移植のしにくさ
• 👎一画面に処理が収まりきらず処理を理解するために画面スクロール・ズームを多用せざるを得ない
  • UE4のエディタは一般的にDual Displayだと足りないといわれる一因

以下紹介する書き方は上記問題を解決し、不具合を防止し生産性を上げるBPの書き方のノウハウになる。

なお、以下に記載以外は原則 出典
Gamemakin UE4スタイルガイド に従うのが良い。

akenatsu/ue4-style-guide

An attempt to make Unreal Engine 4 projects more consistent - akenatsu/ue4-style-guide

github.com

基本単位は実行ピンのあるノード単位でまとめ、まっすぐに並べる

まず、実行ピン² が入出力ピンとしてついているノードを基本の単位として考える。

該当するのはフロー制御ノード、イベントノード、普通の関数ノード、変数のSetノード、マクロノード、サブグラフ(折りたたみグラフ)ノード等。

BPの処理は実行ピン同時をつなぐ 実行ワイヤー³ をたどって処理が行われる。実行ピンの付かないノードはその意味では「脇道」なので基本的な流れを追いかけるのはこの 基本単位⁴ を追いかければよい。

次に、『Gamemakin UE4スタイルガイド』⁵ を参考に実行ピン付ノード同士を直線状に並べてゆく。

前述のように、BPの処理は実行ピン同時をつなぐ 実行ワイヤー³ をたどって処理が行われるので、これらのノードがわかりやすく整列して並んでいないと人間の理解が困難になってゆく。仮に迷路のような並び方をしていた場合、遅かれ早かれバグの温床になってしまう。

実行ピン付ノードをまっすぐに並べる事で、 どこを目で追いかければよいかが一発で見分けられるようにする のが目的。
また、以降に記載するルールの恩恵を得るための基本的な前提となる。

• 出典StyleGuide 3.4.3 3.4.3 白い実行ワイヤーを最優先にするべき

実行ピン付ノードの下に実行ピン無しのノードを積み重ねる

実行ピン付のノードには「実行ピンではない入力ピン」（プログラミング用語でいえば関数の引数に当たる）があることがある。
そのピンへワイヤーを繋ぐ元のノードが実行ピン付でない場合は、実行ピン付ノードから位置を離すのではなくすぐ下に重ねるように隣接して設置する。

実行ピン無しノードからさらに実行ピン無しノードが繋がっている場合（例：コンポーネントの変数をGetするときなど）は、さらにその下に配置して、先がなくなるまで下に重ねてゆく。

該当するのは、数値の四則演算ノードや変数のGetノード、pureに指定された関数(純粋関数⁶)ノードなど。

実行ピン付のノードとそれ同士の繋がりを「木の幹」とすると、実行ピンの付かないノードは「木の枝葉」に当たる。
木の幹と枝葉（本筋と脇道）が一目で分かるように、並べ方で区別がつくようにする のが一つ目の目的である。

もしこのルールに従わない場合、ワイヤーの色に差があるとはいえメインの処理の流れにみえるように配置することも可能であり、人間の理解が困難になる。

二つ目の目的としては、 基本単位（実行ピン付きノード＋それから参照される実行ピン無しノード）をブロック状に一定範囲にまとめておくことで矩形選択しやすくする ことである。矩形選択しやすいということは処理の単位で動かしやすく整理しやすい、コメントノードでくくりやすい⁷、あるいはコピーやカットなど移植がしやすいということにつながる。

もしこのルールに従わない場合、グラフを見やすく整理したり、リファクタリングしたり、処理を移動する際に、マウスクリックやコピーペーストなどの作業が何度も発生し、「書くのが大変」という状況になってしまう。

同じ基本単位のノード群は左端でそろえる

そろえることで 基本単位⁴を視覚的に認識しやすくする のが目的。
ただし、四端どこでもよいわけではなく左端でないといけない。

BPのノードは大きさが可変である。UE4エディタの表示言語を切り替えたり⁸、ノードの入力欄の内容の変化、ノードの対象や属するもの（例：関数ノードの属するBPクラス名）の名称の変更などによって、いくらでも大きさが変わる。

そのため右端でそろえたとしてもいつでもそろわなくなる可能性があり、あまり意味がない（かけた手間が無駄になる可能性が高い）。
左上が原点となるので、下に重ねるノード群も同じ左端でそろえるようにすることで ノードサイズの可変にも耐えられるようにする 。

実行ピン付ノード引数の順番とノードの積み重ね順を合わせる

順番を合わせることで理解をしやすく し、また 矩形選択しやすくする のが目的。

一つの基本単位に関連するノードを重ねた場合など、縦に大きくなることがしばしばある。この場合、仮に入力ピンの順番と繋がった先のノード群の並びの順番がバラバラであると、どのようにつながっているのかわかりにくい。また矩形選択も関係ないノードが混ざりこむためにしにくくなる。

ノードの入力ピンが多い場合はノード２つ分の幅を使って並べる

過剰に縦に長い基本単位ができるのを防ぐ のが目的。

入出力ピンから伸びるワイヤーを一本に絞る

１つ目の目的は スパゲッティ化の防止 。

特にあるノードの出力ピンから複数のノードでワイヤーが繋がっている場合、まるでタコ足配線のようにあちこちにワイヤーが繋がることになる。このような場合ワイヤーがノードと重なる可能性が高く、ワイヤーを目で追うときに邪魔になって理解がしにくくなる。また、遠く離れたノードからワイヤーを伸ばすことにもなり、画面をスクロールしないと処理が追えないという読みにくさにもつながる。

２つ目の目的は 基本単位の移植時にワイヤーの接続情報を維持する ことである。

具体的には次のルールに従う。

基本単位内で使うものは基本単位内で完結するようにする

たとえば　基本単位A　と　基本単位B　の２つの基本単位があり、ローカル変数Xの値を参照する共通の処理があるとする。

この時何も考えずに思わず、Get Xノードからそれぞれの基本単位内のノードにつなげたくなるが、そうしてしまうとスパゲッティ化の第一歩（２本のワイヤー だけ で済むならよいが本当に将来も２本だけなのかは 誰にも保障できない 。気が付いたらスパゲッティ化している。）につながるうえに、矩形選択時に一つだけGet Xノードが漏れるため選択しにくくなってしまう。

この例ではGet Xノードを２つ配置し、それぞれ　基本単位A　と　基本単位B　のブロックの中に納まるように配置する。

こうすることで 将来にわたってもスパゲッティ化を起こさず、矩形選択しやすさを維持できる。

複数本の実行ワイヤーは入力ピンにつなぐ前にRerouteノードでまとめる

ワイヤーを直接一つのピンにつなぐのではなく、一旦 Rerouteノード⁹ で束ねたうえで入力ピンには１本だけ繋ぐようにする。

コピー＆ペーストやカットなどで処理を移植する際に、Rerouteノード込みで選択しておくことで、 ワイヤーのつながりが維持される のが目的。繋ぎなおす手間、覚えておく手間を減らし、つなぎ間違いによるケアレスミスを防止する。

仮に、いきなりつながったままだと移植後にワイヤーが切れてしまい、繋ぎなおす手間がかかる。また、ちゃんと覚えていられれば良いものの、つなぐ先を間違ってしまい、処理を移植したことでエンバグする恐れがある。

原則、処理の結果は変数に入れ、他の処理単位にワイヤーで繋がない

「基本単位内で使うものは基本単位内で完結するようにする」のメリット、 スパゲッティ化防止・移植性の維持 を得るために、原則処理結果は変数に確保し、直接ワイヤーで繋がないようにする。

• 例外：
  • １回しか使用しない場合
  • 実行ノード同士が隣接する

実行ワイヤーで繋いだ”行”はSequenceノードを用いて繋ぐ

基本単位⁴ をつないでいくとき、処理の意味として区切りを作ることができる。これを”行”とみなす。
そうとらえることで、”改行”することができる。

“改行”をして”行”単位で分離することで、コメントノードで分かりやすく区別できるようにする ことが目的。また　行単位での移植性も確保 できる。

“改行”の実現方法としてはZの文字のようにワイヤーをつないでいくことができるが、行内の処理を変更するたびにつなぎなおしたり、斜めにワイヤーが張られることでノードにかぶったりとあまり好ましくならない。

そこで Sequenceノード¹⁰ を使って複数の”行”をつなぐことで、行末端のノードからワイヤーを排除できる。例えば変数の初期化処理をまとめた行があった場合、Z字につないでいる場合は変数が増えるたびにつなぎなおしが必要になってしまうが、Sequenceノードを使えば単に後ろに初期化のノードを繋いでいくだけでよくなる。

Sequenceノードを使った”改行”は、 行単位での移植性をより高めておく のが目的。

なお、Sequenceノードはいくつか注意点がある。

例 : Delayノードは想定の挙動にならない

[UE4] SequenceとDelayの関係 - もんしょの巣穴blog

monsho.blog63.fc2.com

例 : 途中の出力ピンのワイヤー末端でReturnノードが来るとSequenceの処理は中断される。

このような点に注意して使用する。

“行”の途中の折り返しはRerouteノードを使ってノードに被らないよう直線的に引く

ワイヤーがノードなどに被ることを防止する ことが目的。

“行”があまりにも横に伸びてしまった場合や、ForEachLoopWithBreakノード等があった場合、”行”の折り返しが必要になる。何も考えずにそのままつなぐと、ノードや基本単位の中にワイヤーがかぶることで処理が追いにくくなってしまう。

ワイヤーが一つのノードにループして戻ってくる場合は上を通す

読みやすさを維持しながら更新のコストを下げる のが目的。

そのままつなぐと確実にワイヤーとノードが重なって処理が追いにくくなるのでRerouteノードで整理する。

下をぐるっと通すこともできるが、以下の問題がある。

• これまでのルールでノードを下に重ねるようにしたためかなり大回りになってしまう
• 処理を追加した場合など繋ぎなおし・Rerouteノードの配置しなおしが発生する
• ForEachLoopWithBreakノードのCompletedピンのように下に続きの処理が伸びる時に交差する

上を通すことで最小限のメンテコストで見やすさを維持できる。

https://blueprintue.com/blueprint/k21kb8k4/

余談：BP以外での活用方法

AnimBPのAnimノードグラフやマテリアルのノードグラフの場合、BPのグラフに比べて実行ワイヤーが少ない。その点注意すればこのルールを活用することもできる。

まとめ

ルールと目的まとめリスト

• ルール 基本単位は実行ピンのあるノード単位でまとめる
• ルール 基本単位同士をまっすぐに並べる
  • どこを目で追いかければよいかが一発で見分けられるようにする
• ルール 実行ピン付ノードの下に実行ピン無しのノードを積み重ねる
  1. 木の幹と枝葉（本筋と脇道）が一目で分かるように、並べ方で区別がつくようにする
  2. 基本単位（実行ピン付きノード＋それから参照される実行ピン無しノード）をブロック状に一定範囲にまとめておくことで矩形選択しやすくする
  • ルール 同じ基本単位（実行ピン付きノード＋それから参照される実行ピン無しノード群）のノードはその左端でそろえる
    • 基本単位⁴を視覚的に認識しやすくする
    • ノードサイズの可変にも耐えられるようにする
  • ルール 引数（入力ピン）が複数あるノードの場合には、そのピンにつながる先のノード群の配置も入力ピンの順番に合わせる
    • 順番を合わせることで理解をしやすく
    • 矩形選択しやすくする
  • ルール ノードの入力ピンが多い場合はノード２つ分の幅を使って並べる
    • 過剰に縦に長い基本単位ができるのを防ぐ
• 入出力ピンから伸びるワイヤーを一本に絞る
  • スパゲッティ化の防止
  • 基本単位の移植時にワイヤーの接続情報を維持する
  • ルール 基本単位内で繋ぐノードは他から繋ぐのではなく基本単位内で完結するようにそれぞれ配置して繋ぐ
    • 将来にわたってもスパゲッティ化を起こさず
    • 矩形選択しやすさを維持できる
  • ルール 複数本の実行ワイヤーは入力ピンにつなぐ前にRerouteノードでまとめる
    • ワイヤーのつながりが維持される
• ルール 原則、処理の結果は変数に入れ、他の処理単位にワイヤーで繋がない
  • スパゲッティ化防止・移植性の維持
• 実行ワイヤーで繋いだ”行”はSequenceノードを用いて繋ぐ
  • ルール 意味のある実行ピン付ノードの繋がりを”行”とみなし適宜”改行”する
    • コメントノードで分かりやすく区別できるようにする
    • 行単位での移植性も確保
  • ルール “行”同士をSequenceノードで繋ぐ
    • 行単位での移植性をより高めておく
• ルール “行”の途中の折り返しはRetouteノードを使ってノードに被らないよう直線的に引く
  • ワイヤーがノードなどに被ることを防止する
  • ルール ワイヤーが一つのノードにループして戻ってくる場合は上を通す
    • 読みやすさを維持しながら更新のコストを下げる

ルールの方針まとめ

これまでのルールは大きく以下の判断基準に沿ったもの。

1. 読みやすさの維持
2. メンテコストの削減
3. 選択しやすさ・移植性の確保

上記に見合うこれら以外に良いルールがあればどんどん採用して「きれいな」BPを書くべし。