Effekseer をバックエンドにした、簡素なパーティクルエディタ。
スライダーをいじると即座にプレビューへ反映され、作ったものは Effekseer の
データファイル (.efk / .efkefc) として書き出せる。書き出したファイルは
Unity / Unreal Engine / Godot / Cocos2d-x / DXLib / WebGL など、Effekseer の
各種ランタイムでそのまま再生できる。
もともとは吉里吉里Z 用 Effekseer プラグイン
krkreffekseer 向けの簡易素材を
手早く作るために開発したもの。.efkzip の書き出しやプレビューの座標系は
このプラグインに合わせてある (プラグイン無しの環境でも普通に使える)。
参照した UI のスコープは ICS の Particle Develop。
dotnet run --project src/ParticleEdit
ブラウザで http://localhost:5188 を開く。必要なのは .NET SDK だけで、 Node.js もバンドラも要らない。閉じるときはブラウザのタブを閉じればよい。 サーバは使われなくなると自分で終了する (詳しくは「使い終わると自分で畳む」)。
src/ParticleEdit/ エディタ本体 (ASP.NET Core minimal API)
EffectSpec.cs UI が扱うパラメータ定義
EffectBuilder.cs パラメータ -> Effekseer ノードツリー -> .efk / .efkefc
ShapeSpec.cs パーティクル 1 粒の形の定義
MotionSpec.cs エミッタの動き (軌道) の定義
ExportManifest.cs 書き出す ZIP に入れる目録と軌道
ShapeRenderer.cs 形からテクスチャを実行時に生成
BuiltinTemplates.cs 組み込みテンプレート
ProjectStore.cs プロジェクト / ユーザーテンプレートの保存
SceneSpec.cs シーン (保存したものを並べたもの) の保存と .efkset の書き出し
Png.cs 依存なしの最小 PNG エンコーダ
Watchdog.cs 使われなくなったら自分で畳む番人 (裏に残らないように)
wwwroot/ UI (素の HTML/CSS/JS) と effekseer.js ランタイム
scene.js 「シーン」タブ (app.js より先に読む)
third_party/EffekseerCore/ Effekseer 公式エディタのコア (MIT, 無改変)
なぜこの形か:
- バイナリフォーマットを自前実装していない。
.efk/.efkefcの書き出しは Effekseer 公式エディタのコア (EffekseerCore, 純マネージド C#) をそのまま呼んでいる。 このプロジェクトが書いているのは「UI のパラメータ」→「Effekseer のデータモデル」の マッピングだけなので、フォーマットの追随コストがない。 - プレビューは公式の WebGL ランタイム (
effekseer.js+effekseer.wasm) に任せている。 サーバが返した.efkのバイト列をloadEffect(ArrayBuffer)にそのまま渡すため、 ファイルの書き出しを挟まずに数十 ms で差し替わる。 - 触るツールは .NET SDK ひとつ。 配布は下記のとおり
dotnet publishだけで済む。
dotnet publish src/ParticleEdit -c Release -r win-x64 # osx-arm64 / linux-x64 など
出るのはこれだけ。フォルダごと渡せば .NET の入っていない環境でも動く。
ParticleEdit.exe ランタイム同梱の単一ファイル (100MB 前後)
wwwroot/
index.html
app.js
style.css
vendor/effekseer.js
vendor/effekseer.wasm
RID を指定したときだけ配布用の設定が効くようにしてあるので、オプションを 覚えておく必要はない。実行するとコンソールに URL と、読み書きする場所が出る。
素の dotnet publish は要らないものも並べてくるので、csproj で止めている。
いずれも自前ホストで動かすぶんには使われない。
| 出るもの | 止めかた | 要らない理由 |
|---|---|---|
web.config |
IsTransformWebConfigDisabled |
IIS 用 |
*.staticwebassets.endpoints.json |
publish 後に消す target | MapStaticAssets を使っていない |
*.gz / *.br |
CompressionEnabled |
UseStaticFiles() は事前圧縮を配れない |
EffekseerCore.pdb |
AllowedReferenceRelatedFileExtensions |
参照先のデバッグ情報 |
effekseer.d.ts |
Content Remove |
型定義。読む人のために置いてあるだけ |
対応表だけは SDK 側に出さないスイッチが無い
(CopyStaticWebAssetsEndpointsManifest はファイルがあれば無条件にコピーする)
ので、publish の後に消す target を書いている。
IncludeAllContentForSelfExtract を有効にしてある理由: EffekseerCore が
Assembly.Location から自分の場所を求めており、素の単一ファイルではこれが空になって
Core.Initialize が落ちる。自己展開形式にすると実体がディスクに出るので通る。
組み込み先のプロジェクト直下に置くなら、こういう形になる。
@echo off
setlocal
set "EDITOR=%~dp0tools\particleedit"
rem 起動を少し待ってからブラウザを開く (本体はこのウィンドウで動き続ける)
start "" /b cmd /c "timeout /t 3 /nobreak >nul & start http://localhost:5188/"
cd /d "%EDITOR%"
"%EDITOR%\ParticleEdit.exe"実行ファイルはフルパスで書くこと。 cd してから名前だけで叩くと、
NoDefaultCurrentDirectoryInExePath が設定されている環境で
「内部コマンドまたは外部コマンドとして認識されていません」になる。
cd 自体は残しておく (設定ファイルの相対パスがそこを基準に解決される)。
裏でサーバとして動くので、放っておくとプロセスが残りがちになる。これを避けるため、 次のどちらかで自分から終了する。
- ブラウザを閉じたとき … 開いているページはサーバへ定期的に心拍を送っている。 タブを閉じれば心拍が途絶え、十数秒で畳まれる (閉じる瞬間に合図も送るので、 たいていはもっと早い)。複数タブを開いているときは、最後の 1 つを閉じるまで残る。
- 起動元のコンソール/親プロセスが消えたとき … 標準入力が切れたのを検知して畳む。
どちらも「そのプロセスが自分を止める」だけで、他のプロセスには触らない。したがって
別フォルダで起動した別インスタンスは別扱いで、互いに干渉しない (同時に使うなら
particleedit.json の port を分けること。同じポートは同時には使えない)。
書き込むのは設定で決めた場所だけで、実行ファイルの隣に勝手に何か作ることはない (既定のままだと隣になる、というだけ)。テクスチャの作業用フォルダは既定で OS のテンポラリに置く。中身は消しても作り直される中間物しかない。
実行ファイルの隣 (dotnet run なら src/ParticleEdit/) に particleedit.json を
置くと、読み書きする場所を変えられる。無くても動く。
{
"port": 5188,
"projects": "../../resources/effect",
"export": "../../data/effect",
"game": "http://127.0.0.1:8898"
}| キー | 既定 | 意味 |
|---|---|---|
port |
5188 | 待ち受けポート |
projects |
projects |
プロジェクト (編集を再開できる形式) の置き場 |
templates |
templates |
自分で追加したテンプレートの置き場 |
images |
images |
取り込んだ画像の置き場 |
work |
(OS のテンポラリ) | テクスチャの作業用。消しても作り直される |
export |
(なし) | 書き出し先 |
game |
(なし) | 組み込み先のゲームの URL。書くと**「ゲームで再生」**が使える |
gameDir |
(書き出し先のフォルダ名) | ゲームから見た素材フォルダ名 |
パスは設定ファイルからの相対。絶対パスも書ける。work は空にしておくと
OS のテンポラリを使う (実行ファイルの隣を汚さない)。中間物しか置かないので、
バージョン管理に入れる必要はない。
export を指定すると、エクスポートがそのフォルダへ直接ファイルを置く
(指定しなければブラウザのダウンロード)。ブラウザからは保存先を選べないので、
置き場が決まっている運用ではこちらのほうが手数が少ない。
起動時にどこを見ているかがコンソールへ出る。
src/ParticleEdit/EffectSpec.csにプロパティを足すsrc/ParticleEdit/EffectBuilder.csで Effekseer 側のどの値に対応させるか書くsrc/ParticleEdit/wwwroot/app.jsのGROUPSに 1 行足す (UI は自動生成)
GROUPS の各グループには tab を持たせてある。UI はこれを見てタブに振り分ける
(同じ tab を書けば 1 つのタブにまとまり、そのときだけグループ名の見出しが出る)。
help を書くと、その行にマウスを乗せたときの説明になる。
プレビューは 1 ワールド単位 = 1 ピクセル / 画面中央が原点 / +Y が画面上方向。
これは吉里吉里プラグイン (krkreffekseer) の既定と一致している
(src/Effect.cpp の updateMatrices(): 既定は平行投影 + MakeOrthographicRH_OpenGL(proj, w, h, …) で
サーフェイスの幅高さをそのまま使い、カメラは原点正面・up = (0,1,0))。
つまりエディタで見えている大きさ・位置がそのまま組み込み先のピクセル数になる。
パラメータは 発生 / 粒 / 色 / 形 / 表示 / 動き のタブに分かれている。選んだタブは 次に開いたときも残る。ヘッダの ? ヘルプ (F1) に一通りの説明が入っている。
「表示」タブの 画面サイズの枠 は組み込み先の画面 (既定 1280×720) を 枠として重ねるもの。枠が収まるようプレビュー全体を縮小して表示し、倍率をラベルに出す。
背景画像は「表示」タブから敷ける。組み込み先の絵に重ねたときの見えかたを 確かめるためのもので、中央に原寸で置くだけ (枠と同じ寸法の絵ならちょうど枠を埋める)。 明るさを下げて粒を見やすくもできる。
エフェクトのデータには一切入らず、プロジェクトにも保存しない (背景はエフェクトの 一部ではないし、入れるとファイルが重くなるため)。代わりにブラウザ側へ覚えさせて いるので、開き直しても残る。
CSS でキャンバスの裏に敷くのではなく、同じキャンバスの中へ Effekseer より先に 描いている。透明なキャンバス越しに加算合成の粒をブラウザに合成させると色が 変わってしまうため。
発生位置はプレビュー上の十字をドラッグして決められる (「発生」タブの 発生位置 X / Y と同じ値。細かく合わせたいときはつまみで、中央へ戻すときは 発生位置を中央へ戻すで)。この値はエフェクトデータに埋め込まれるので、 組み込み先でも同じ場所から出る。
十字は再生側の操作を掛けた後の位置に出る (粒の出どころと一致する)。 ズームや回転が掛かっていてもドラッグ量はそのぶん換算されるので、指の動きとずれない。
組み込み先は再生中にエフェクトの位置を動かせる (吉里吉里プラグインなら player.setCoord())。
そのときすでに出ているパーティクルがどうなるかを「エミッター」グループの
発生位置を動かしたとき で選ぶ。
| 設定 | 挙動 |
|---|---|
| その場に置き去り (既定) | 発生した場所に残る。エミッターを動かすと軌跡になる |
| まるごと追従 | 生存中の粒まで一緒に移動する。かたまりごと動く |
Effekseer 側のノードの「位置への影響」(生成時のみ / 常に) に対応する。 Effekseer の既定は「常に」なので、何もしないと軌跡が出ない。 発生位置を動かさない使い方なら、どちらでも見た目は変わらない。
なお「その場に置き去り」を選ぶと、平行移動については既存の粒が追従しなくなる (拡縮と回転は追従したまま)。追従の判定が平行移動 / 回転 / 拡縮で別々のため。
なお Effekseer 自体に「2D モード」はない。2D はホスト側が平行投影を張ることで実現するもので、
プラグインもそうしている。Effekseer 側で 2D に関係する設定は
ビルボードの種類 (2D なら Fixed)、読み込み時の magnification (全体の拡大率)、
描画順 (ZSort / DrawingPriority)、スプライトの基準点あたり。
書き出されるエフェクトは 2 段 (発生位置を動かすとき・ループするときは足されて最大 4 段) のノードでできている。
Root
└ Emitter 発生位置を動かすときだけ挟まる。描画しない 1 インスタンス
└ Loop ループするときだけ挟まる。周期ごとに生まれ直して発生をやり直す
└ Spawn 描画しない。粒 1 つにつき 1 インスタンス。その粒が「発生した場所」を持つ
└ Particle 実際に描かれる粒。初速・重力・大きさ・色・回転はこちら
なぜ分けているか。 初速の「方向 ± 広がり」は扇形だが、Effekseer の速度 (PVA) は 軸ごとの min/max しか持たないので扇形を表せない。そこで **生成位置 = 円 (半径 0) + 「回転を適用」**を使い、粒ごとに Z 軸まわりの回転を与えて、 局所 +Y 方向へ出した初速をその向きへ回している。速度の大きさは向きに依らず一定になる。
ただしこの「回転を適用」は位置のオフセットまで一緒に回してしまう。発生位置を同じ ノードに置くと粒ごとにランダムな角度で回ってしまうので、発生位置は親 (Spawn) が持ち、 子 (Particle) のローカル位置は常に 0 にしてある。回っても影響が出ない。
粒 1 つにつきインスタンスが 2 つ要る。プレビューの particles: は粒の数に直した値。
回転との兼ね合い: 「回転を適用」はスプライトの向きにも乗る。回転のパラメータを 使っていないときは素のビルボード (ノードの回転を捨てる) にして粒を画面に対して 立たせたままにし、使っているときだけ回転ビルボードにしている。つまり回転を使うと、 角度は画面ではなく進行方向からの相対になる。
「発生」タブの 同じパターンを繰りかえす で、周期 N フレームごとに発生をやり直すようにできる。 発生する長さ B を N より短くすると「どっと出て、消えて、また出る」になる (B = N なら出しっぱなし)。
Effekseer にエフェクト全体のループ指定は無い。 .efkefc の <IsLoop> はエディタの
プレビュー再生用で .efk には入らないし、ランタイムにも「このエフェクトはループする」という
概念が無い。用意されているのは次のものだけ:
- ノードの 生成回数 = 無限 + 生成間隔 (出し続ける。周期という考えは無い)
- FCurve の端の扱い (
Loop) … 軌道のループ。ただし終端の値を拾う癖がある - UV アニメの
LoopType… テクスチャアニメの話 - ランタイム側で再生し直す
そこでノードの生まれ変わりで周期を作っている。Loop ノードは
「生成回数 = 無限 / 生成間隔 = N / 寿命 = B」で、N フレームごとに生まれ直し B フレームで死ぬ。
生きている間しか下の Spawn を作らないので、そこが発生している時間になる。
Spawn は「親が消えたら消える」を立てていないので、既に出ている粒は周期をまたいで生き残る。
軌道のループ (MotionSpec.Loop) も同じ手で作ってあり、両方使うときは
軌道の長さと周期を揃える こと (揃っていないと 1 周ごとに位置がずれる)。
粒ごとの乱数は周回ごとに引き直されるので、1 周ごとに寸分たがわず同じ絵にはならない (Effekseer にノード単位で乱数種を固定する仕組みが無い)。周期・発生のタイミング・粒の数は揃う。 アニメパターンとして焼けば、そちらは完全な繰りかえしになる (次節)。
ループを入れておくと、ヘッダの アニメパターン… からエフェクトを絵の連なりに焼ける。
形式はシート PNG / 連番 PNG / .amv (吉里吉里の AlphaMovie プラグイン)。
継ぎ目のないループになる。 仕掛けは 3 手:
- 「1 周期ぶんだけ発生する」エフェクトを作る (
/api/effect.efk?cycle=one。Loopノードの 生成回数を無限から 1 にするだけ) - 粒が全部消えるまで回して、1 フレームずつ絵を取る
- 周期ごとに折り返して重ねる。i コマ目 = 0 周目の i + 1 周目の i + 2 周目の i + …
3 がすべて。1 周期ぶんの粒を N フレームおきに何度も重ねたものは、 「その粒たちを N フレームおきに出し続けている状態」そのものなので、 出来上がりは数式のうえで完全な周期関数になる。周期をまたいで生き残る粒があっても、 その粒は次の周の頭に重なって出てくるので破綻しない。
重ねかたは合成方法に合わせる。加算はそのまま足し、通常合成は「後の周ほど古い粒」なので
下へ潜らせる (dst + src×(1-dst.a))。どちらもアルファ乗算のまま計算して、最後に割り戻す。
コマを作るのはブラウザ (エフェクトを描けるのが WebGL の上の effekseer.js しか無いため)。
サーバへは生の RGBA が送られてきて、並べたり詰めたりするだけ (PatternWriter)。
プレビューとは別の WebGL コンテキストで焼くので、焼いている間も表示は壊れない。
写すのはプレビューの中央で、再生側の操作 (位置・ズーム・回転) は掛からない。
1 コマの大きさは 16 の倍数に丸める (.amv の決まり)。
コマ数は なめらかさ (fps) で指定する。エディタが 60fps 基準なので、内部では
「何フレームおきに 1 コマ焼くか」(patternStep) に読み替えている。60 を割り切れる値だけ選べる。
間引いたコマは更新だけ回して描画しない (絵を貯める領域も焼く枚数ぶんしか要らない)。
それでも大きなコマを高い fps で焼くとメモリを食うので、見込みが 400MB を超えるときは断る。
吉里吉里の AlphaMovie プラグイン が読む
アルファ付き動画。書き出しは AmvEncoder。形式は同プラグイン (再実装版) の
AlphaMovie.cpp のデコーダ (オリジナル DLL の解析による再実装) に合わせてある。ふつうの JPEG とは違うところがあるので注意:
- マーカーが一切無い。
SOIもDQTもDHTも無く、エントロピー列がじかに入る。 量子化テーブルはファイルヘッダに、ハフマンテーブルは標準表の決め打ち - DC 予測子をハフマンテーブル単位で共有する (Cb と Cr で 1 本)。標準の JPEG は 成分ごとに独立なので、ここを間違えると色がずれていく
- 幅・高さは 16 の倍数 (MCU 16x16 / 4:2:0)
2 経路あるうち zlib-alpha (アルファは zlib で可逆、色は Cb,Cr,Y の 3 成分 JPEG) を書いている。 アルファが可逆なので粒の縁が汚れない。色は 8x8 単位で潰れるので、 透明なところへ隣の色をにじませてから圧縮している (そのままだと黒が縁へ漏れる)。
ヘッダの 0x04 と 0x10 はデコーダが見ていない領域で、それぞれファイル全体の大きさ /
フレーム部の大きさ、という推測で埋めてある。オリジナルの AlphaMovie.dll で読ませる場合は
そこだけ検証していない (再実装版では確認済み)。
発生位置そのものを動かせる。「エミッタの動き」グループの 動かしかた で決める。
| 動かしかた | 何が起きるか |
|---|---|
| 動かさない (既定) | 発生位置は固定 |
| 軌道を焼き込む | 選んだ軌道をエフェクトに埋める。再生すればそう動く。組み込み先のコードは要らない |
| 組み込み先から動かす | 発生位置を動的パラメータに繋いだ形で書き出す。値は組み込み先が毎フレーム差し込む |
軌道の作りかた: 「記録…」を押してプレビューの上をドラッグする。押している間の 位置を毎フレーム拾うので、ゆっくりなぞればゆっくりな動きになる。離すと名前を聞かれる。 軌道は何本でも持てて、プロジェクトに一緒に保存される。選んでいる軌道はプレビューに 点線で重なる。
粒が軌跡として残るかどうかは「エミッター」グループの発生位置を動かしたときで決まる (既定はその場に置き去り = 軌跡になる)。
軌道を選んでいる間は、いまの発生位置がプレビュー左下に出る。 「組み込み先から動かす」で書き出す場合も、エディタ側が動的パラメータへ値を差し込んで 動かして見せるので、焼き込みと同じように確認できる。
「動き」タブの下半分は、組み込み先がエフェクト全体に掛ける配置を真似るためのもの
(吉里吉里プラグインの setCoord / setZoom / angle にあたる)。
エフェクトのデータには入らない。
ここを動かすと、平行移動には既に出ている粒が付いてこないのに、拡縮と回転は付いてくる のが見える。Effekseer が追従の判定を平行移動 / 回転 / 拡縮で別々に持っているためで、 組み込んでから気づくと厄介なのでエディタ側で確かめられるようにしてある。
軌道は上段の Emitter ノードの位置 F カーブになる。書き出し時に一定間隔でサンプリング されるので、間隔は 2 フレームに詰めてある (既定の 10 では手で描いた動きが落ちる)。
繰り返しは Emitter ノード自体を軌道の長さで生まれ変わらせて作っている。 F カーブ側にも「ループ」があるが、端の処理に癖があって終端の値を拾った粒がたまに 混じるので使っていない。親が消えても既に出ている粒は生き残るので、繋ぎ目は見えない。
Effekseer の動的パラメータを使う。発生位置を式に繋いだ状態で書き出すので、 組み込み先は入力に値を差し込むだけでよい。吉里吉里プラグインなら:
// 対応は effect.json から自動で読まれるので、名前でそのまま差し込める
player.setDynamicInputByName("emitter.x", x); // 発生位置。progress() より前に
player.setDynamicInputByName("emitter.y", y);
player.progress(tick);
渡す座標は setCoord と同じ画面中央が原点 / +Y が画面下方向 / ピクセル。
符号の反転はエフェクト側の式に入れてあるので、組み込み先で気にしなくてよい。
入力は Effekseer 側の都合で全部で 4 本しかない (InstanceGlobal が
std::array<float, 4>)。発生位置で 2 本使う。
パーティクル 1 粒の形は、パラメータから手続き的に生成する。
| パラメータ | 意味 |
|---|---|
| 辺の数 | 0 で円、3 以上でその辺数の多角形 |
| 星形 | 1 で正多角形、1 未満で星形 (内側の頂点の半径比) |
| 中抜き | 中心をくり抜く半径比。リングになる |
| ぼかし | 縁のぼかし幅。0 でくっきり、1 で中心から外周まで滑らかに減衰 |
| ぼかしの曲がり | 減衰カーブの指数。大きいほど中心寄りに濃さが集まる |
| 回転 | 度。画面の見た目と一致する (反時計回り、90 度で上) |
| 大きさ | テクスチャいっぱいに対する比率。余白の調整 |
「パーティクル」グループの発生時の角度 / 回転速度は粒そのものを画面内で回す。 向きの決まりは形状の回転と同じ (度、反時計回り、90 度で上)。ただし基準は進行方向になる (理由は「エフェクトの組み立てかた」を参照)。
形は「角度 θ ごとの境界までの半径 R(θ)」として表し、各ピクセルを d = r / R(θ) に
正規化してから縁を処理している。円も多角形も星も同じ 1 本の式で扱えるので、
ShapeRenderer.cs は形ごとの分岐を持たない。
プリセット (ぼかし円 / 円 / リング / 星 / 四角 / 六角 / 光芒) はこのパラメータの 組み合わせでしかなく、押すとその値がスライダーに入る。そこから自由に動かせる。
ハートだけは辺の数では表せないので、輪郭を陰関数 (x² + y² − 1)³ − x²y³ = 0 として持ち、
中心から角度ごとに二分探索して「半径の表」に均してある。以降は多角形とまったく同じ扱いなので、
中抜き・ぼかし・回転・大きさはそのまま効く (辺の数と星形だけ効かない)。
画像の取り込み: 「画像を取り込む…」から手持ちの画像を使える。ブラウザ側で 2 の冪の
正方形 (最大 512) へ整えてから送っている。Effekseer の WebGL ランタイムは非 2 冪の
テクスチャを勝手に縮めるので、揃えておかないとプレビューと書き出しで見た目がずれるため。
取り込んだ画像は src/ParticleEdit/images/<ハッシュ>.png に置かれ、プロジェクトにも同梱される。
テクスチャのファイル名は形の内容から決まる (particle_<ハッシュ>.png) ので、
形を変えれば URL も変わり、プレビュー時にブラウザのキャッシュとぶつからない。
ヘッダの「テンプレート」から、サムネイル付きのグリッドで選べる。
- 組み込み 13 種 (炎 / 噴水 / 爆発 / 雪 / 煙 / きらめき / 星屑 / 泡 / リング波 / 紙吹雪 / 光の玉 / 浮かぶハート / 魔法の粉)。
パラメータの塊でしかないのでファイルではなくコード (
BuiltinTemplates.cs) で持っている - 自分の … 「現在の設定を追加」で
src/ParticleEdit/templates/<名前>.zipに保存される。 中身はプロジェクトと同じ形式。同じ名前の組み込みがあればユーザー側が優先される
サムネイルはプレビューとは別の WebGL コンテキストでオフスクリーンに焼いているので、 一覧を開いても編集中のプレビューは止まらない。一度焼いたものはメモリにキャッシュされる。
ヘッダの「プロジェクト名 + 保存」で、編集状態を名前を付けて保存できる。
保存先はサーバ側の src/ParticleEdit/projects/<名前>.zip。隣のプルダウンから読み込む。
中身:
project.json フォーマット版 + パラメータ + (将来) 形状定義
Texture/*.png そのプロジェクトが使っているテクスチャ
エクスポートと別建てにしている理由: パラメータから Effekseer のデータモデルへの 変換は一方向で、書き出したものを読み戻してもスライダーの位置は分からない。 1 つのスライダーが複数の値に散る (色相 1 つでも開始色と終了色の両方に入る)、 量子化で情報が落ちる (色相 0-360 度 → 0-252 の整数)、そもそもエディタ側にしか 無い値がある (画面枠、形状の定義) といったあたりが理由。 編集を再開するための状態はこの形式でしか持てない。
「シーン」タブで、保存したプロジェクトをいくつか並べて 1 つの画面での見えかたを確かめる。 1 場面に 2 つ 3 つのエフェクトを重ねるときに、エディタの中で全体を見ながら調整するためのもの。
- 並べたうちの 1 つがアクティブ。いつものつまみはそれを編集し、ほかは同じ
EffekseerContext の中で背景として流れ続ける (プレビューの
stopAllをやめて、 差し替えはアクティブのハンドルだけを止めるようにしてある) - アクティブの配置は「再生側の操作」(
playX/playY/playZoom/playRotation) と同じ値。 シーン側はゲームの画面と同じ流儀 (中央原点・Y 下向き・時計回り) で持ち、行き来で符号を直す - 切り替えると、編集途中の状態をそのまま持って背景へ回る。保存はシーンの保存でまとめて行う (変更の有無は見た目だけの値を除いたパラメータで比べる)。シーンから保存するときは 再生側の操作を既定値に戻して保存する (プロジェクト単体で開いたときに配置が残らないように)
- 開始の遅れはプレビューでは 1 フレーム = 1/60 秒で数える。ループで流し直すときは遅れを掛けず、 軌道も続きから回す (どちらもゲーム側の再生と同じ)
保存先は <projects>/scenes/<名前>.json。プロジェクトの一覧 (*.zip) とは混ざらない。
シーンを書き出すと <名前>.efkset と、並べたプロジェクトそれぞれの .efkzip が出る
(efkzip は保存済みのプロジェクトから作るので、書き出す前に変更を保存させている)。
.efkset は吉里吉里プラグイン側の「エフェクトの並び」で、TJS の辞書 (UTF-8 BOM 付き) で書く。
ゲームは Scripts.evalStorage で読むので、JSON にはしていない (json.dll を出荷物に足さずに済む)。
書式の正本はゲーム側の AffineSourceEffekseerSet.tjs の先頭。
%[
"version" => 1,
"width" => 1280, "height" => 720,
"items" => [
%[ "name" => "spark", "file" => "spark.efkzip", "x" => -300, "y" => 150 ],
%[ "name" => "trail", "file" => "trail.efkzip", "x" => 300, "y" => -120, "delay" => 500, "motion" => "circle" ]
]
]
隠したもの (一覧のチェックを外したもの) は書き出さない。
組み込み先のゲームを立ち上げたまま、作っている粒をそのゲームの画面に出して 確かめられる。エディタの黒地では良く見えても、実際のマップやメッセージ窓に 重ねると明るすぎた・小さすぎた、というのが先に分かる。
particleedit.json に game を書くと、ヘッダに 「▶ ゲームで再生」 と
出す場所の選択が現れる (F5 でも実行できる)。押すと
- いまのパラメータを
.efkzipとしてexportのフォルダへ書き出し - ゲームへ「この素材をここに出して」と頼む
までを一息で行う。エクスポートを押す必要はない。
対応しているのは吉里吉里の rpgsys 系の
組み込み先で、POST <game>/ed/fx に次の JSON を投げている
(同じ口を実装すれば、ほかの組み込み先でも同様に使える):
| 出す場所 | 意味 |
|---|---|
| プレイヤーの足元 | ゲームの主人公の立っているところ |
| 選択セル | エディタで選んでいるマス |
| 画面の中央 | 画面座標 (0, 0) |
| 画面の中央 (UI より手前) | メッセージ窓やメニューより手前に出す |
ブラウザからゲームを直接叩くと別オリジンなので CORS で止まる
(localhost:5188 → 127.0.0.1:8898)。組み込み先にヘッダを足させるより、
こちら (ParticleEdit のサーバ) から呼ぶほうが手が少ない。
Effekseer は読み込んだ .efkzip を開いたまま持つ。そのため 2 回目の
「ゲームで再生」が The process cannot access the file ... で失敗する。
これを避けるため、書き出す前に op: "release" を投げて手放してもらう
(それでも間に合わないことがあるので、書き込みは少し粘る)。
ゲーム側が古いままで手放してくれない場合は、ゲームのエディタで
「素材を読み直す」を押すか、ゲームを閉じてからもう一度。
配布用の一方向の書き出し。どの形式もテクスチャを同梱した ZIP になる。
| 形式 | 出力 | 中身 | 用途 |
|---|---|---|---|
efkzip |
<名前>.efkzip |
<名前>.efkefc + Texture/ |
吉里吉里プラグイン用 |
efk |
<名前>.zip |
<名前>.efk + Texture/ |
ランタイムに直接読ませる最小構成 |
efkefc |
<名前>.zip |
<名前>.efkefc + Texture/ |
公式 Effekseer エディタで開いて作り込む |
「組み込み先から動かす」で書き出したとき、または軌道を持っているときは、 ZIP に目録と軌道が足される。Effekseer のランタイムはこれらを見ないので、 読まない組み込み先には影響しない。
effect.json 動的パラメータの名前と入力番号、軌道の一覧
motion/<名前>.json 軌道 1 本ぶん
なぜ目録が要るか: .efk バイナリには動的パラメータの名前が残らない
(入るのは既定値とコンパイル済みのコードだけ)。名前で引きたい組み込み先のために、
名前と入力番号の対応をここで配っている。吉里吉里プラグインはこのファイルを
.efkzip から自動で読んで effect.meta に載せ、setDynamicInputByName() の
対応表として取り込む。名前が特定のツールに寄らないよう effect.json にしてある。
{
"format": 1,
"effect": "sample.efkefc",
"emitterMotion": "dynamic",
"dynamicInputs": [{ "index": 0, "name": "emitter.x" }, { "index": 1, "name": "emitter.y" }],
"motions": [{ "name": "sweep", "file": "motion/sweep.json", "frames": 90, "loop": true }]
}軌道は { name, frames, loop, points: [{ f, x, y }] }。座標は組み込み先の流儀
(画面中央が原点 / +Y が画面下方向 / ピクセル) に直してある。
.efk は再生専用バイナリ ("SKFE" + バージョン + 本体)、.efkefc はその .efk を
BIN_ チャンクに丸ごと含んだうえで編集用の XML (EDIT チャンク) も持つコンテナ
("EFKE")。Effekseer のランタイムはどちらでもロードできる。
吉里吉里プラグイン (krkreffekseer) が読む形式。プラグインの実装
(src/Effect.cpp / src/EffectZip.cpp) に合わせてあり、要件は次の通り:
- 素の ZIP。マニフェストは不要
- エントリ名を指定しなければ、ZIP 内の最初の
.efkefc(無ければ.efk) が本体になる - 資材は
<zipのストレージ名>/<エフェクトからの相対パス>として要求され、 その prefix を除いたパスで ZIP 内を引く (見つからなければファイル名だけでフォールバック)
したがって「ルートに .efkefc を 1 つ + Texture/」で成立する。
エフェクトに埋まっているテクスチャパスと ZIP のエントリ名が一致していることが要点。
-
POST /api/debug… パラメータを渡すと、組み上がった Effekseer 側の値をテキストで返す -
POST /api/effect.efk?cycle=one… ループの 1 周期ぶんだけ発生するものを返す (アニメパターン用) -
GET/PUT/DELETE /api/scenes/{name}… シーンの保存 (GET /api/scenesで一覧) -
POST /api/scenes/{name}/export… シーンを.efkset+ 並べたものの efkzip で書き出す -
POST /api/pattern… 焼いたコマを受け取って書き出す。body は[JSON の長さ (4 バイト LE)] [注文の JSON] [コマ...]、コマは左上原点・アルファ非乗算の RGBA -
http://localhost:5188/#templates… テンプレート一覧を開いた状態で起動する -
http://localhost:5188/#help… 使いかたを開いた状態で起動する -
http://localhost:5188/?tab=形… そのタブを選んだ状態で起動する -
http://localhost:5188/?selftest=1… 自己診断。パラメータを変えながら 5 サイクル + 連打 1 サイクル回して各回で実際に描画されたピクセルをreadPixelsで数え、さらに プロジェクトの保存 → 読み込みでパラメータが往復するかを確認して、結果を<pre id="selftest">に JSON で書き出す。"ok": trueなら全部通っている。アニメパターン (
pattern) もここで測っている。粒の寿命を周期より長くして焼き、 コマごとの濃さがそろっているか (fill) と、最後のコマ → 最初のコマの変化が ふつうのコマ送りと同じくらいか (seamとtypical) を見る。折り返し合成が 効いていないと、頭のコマが出はじめで空になるので必ずここに出る。 3 形式の書き出しが通るかもあわせて確認する。 ヘッドレスブラウザから機械的に確認できる:chrome --headless=new --disable-gpu --use-gl=angle --use-angle=swiftshader \ --enable-unsafe-swiftshader --virtual-time-budget=40000 \ --dump-dom "http://localhost:5188/?selftest=1"
- 形状は 1 エフェクトに 1 つだけ (プロジェクト形式の
shapesは複数形状を見据えた入れ物で、まだ未使用) - ループしても粒ごとの乱数は周回ごとに引き直される。周期・タイミング・数はそろうが、 絵が 1 周ごとに寸分たがわず同じ、にはならない (焼いたアニメパターンのほうは完全な繰りかえし)
.amvは zlib-alpha 経路だけ書ける (JPEG-alpha 経路は書かない)。ヘッダの未使用領域 2 箇所は 推測で埋めてあり、オリジナルのAlphaMovie.dllでの読み込みは未確認
third_party/EffekseerCore と src/ParticleEdit/wwwroot/vendor は
Effekseer Project の成果物 (MIT)。詳細は各ディレクトリの LICENSE / VENDOR.md を参照。