Skip to content

Drag'n Wash ModFramework 1.2.0

Choose a tag to compare

View all tags
@github-actions github-actions released this 17 Sep 13:45
· 293 commits to main since this release
v1.2.0
37f5ec5

Drag'n Wash ModFramework 1.2.0

The framework's second feature release. The core goes to 1.2.0 and three of the five libraries to 1.1.0. Nothing a mod built on 1.0.0 or 1.1.x uses has changed; every addition is new API. Released together with Drag'n Wash Localization v1.2.0, which needs this version.

Plugin Version
Drag'n Wash ModFramework (core) 1.2.0 Developer tools switch, text and key settings on the Mods screen, GameEvents, SettingMeta, reloading a mod while the game runs, mods that go online say so, a new logo and Mods button
Preloader patcher 1.2.0 Unchanged; follows the core
Tool window 1.1.0 Console tab, drawing over the game
Assets 1.1.0 Texture replacements, reloading, the Assets tab with previews
Dialogue 1.1.0 Stable line keys
Inspector 1.0.0, experimental New library: an Inspector tab in the Tool window, with a Code view and a debug view
Text, Flags and saves 1.0.0 Unchanged
Installer (installer/) unchanged Same Install.exe as 1.1.0

Core 1.2.0

One switch for everything meant for mod makers. Options → Mods → Drag'n Wash ModFramework → Developer tools, off by default. While it is off, the F1 window stays closed, texture reloading is refused, and the mods built on the framework keep their own exports and hot reload off too. Someone who only installed a mod to play never sees a debug window or gets a folder of exported files. For authors: DeveloperTools.Enabled, Changed, WhenEnabled, and GUIDE rule 8.

The Mods screen edits more. A mod's settings page used to handle on/off, numbers and choices; strings, key bindings, colours and anything else BepInEx stores as text could only be changed in the config file. Now they get a text field (Enter applies; a value the config parser refuses is put back with the reason), and a key binding also gets Capture key: press the key you want, with the modifiers held.

Mods can shape their settings page. SettingMeta and SectionMeta in a ConfigDescription's tags give an entry a display name, an order, an Advanced flag (hidden until Show advanced settings at the top of the page is on) and a RequiresRestart note; a section gets a display name, a description and an order. ConfigurationManager's IsAdvanced, DispName and Order are read the same way, so a mod that already has them needs no change. The framework's own settings use it. Wiki: Settings meta

GameEvents: the game's events, one mod at a time. A handler subscribed straight to SceneManager.sceneLoaded that throws stops every mod that subscribed after it, and nobody can tell which mod it was. GameEvents.OnSceneLoaded, OnSceneUnloaded, OnGameStarted and OnQuitting take the mod's GUID and run each handler on its own: one that throws is logged, named on the Mods screen under its mod, and switched off after three failures in a row, while the others keep running. There is no per-frame event on purpose. The Assets library uses it; GUIDE rule 9 asks other mods to. Wiki: Game events

Mods that go online say so. A mod with network features is also where malware could hide, so going online is now something a mod states openly. ModInfo.Network lists each host a mod connects to, what for, what is sent and how to turn it off. The Mods screen tags such mods Online and gives them an Internet page, and NetworkWatch (on by default, Watch connections) notes which mod actually connected where and marks, in warning colour, a connection nobody declared. It only watches: nothing is blocked, and it is not a security boundary. The framework declares its own once-a-day update check. GUIDE rule 11, Wiki: Going online.

Reload a mod without restarting the game (developer tools). A mod that says it is reloadable (ModInfo.Reloadable) is swapped for its new build while the game runs: its registrations and Harmony patches are taken out by its GUID, and the new plugin is started in its place. Build to <Mod>.dll.new next to the DLL and it is picked up by itself; mods reload <guid> does it by hand. Libraries are never reloaded. GUIDE rule 10, docs/MOD_RELOAD.md.

GameHooks.Require also takes Harmony's "Type:Method" in one string, the form the Inspector copies.

GameHooks.Unavailable(guid, feature, reason) marks a feature unavailable for a reason other than a missing game member (refused on this renderer, switched off after a crash), shown on the Mods screen like a failed check.

A new logo, and a drawn Mods button

The framework has a new logo and Mods screen icon, a sponge and a gear, drawn by NotaGames (@NotaGames) after the game's own logo, with the developers' OK. The Options screen's Mods button is drawn now, in the game's menu style, by Mister ERIO (@mistererio). Thank you!

Tool window 1.1.0

Console tab. Every BepInEx log line as it happens, from every mod and from Unity, with its level and source, in colour, the last 2,000 kept. Which levels and sources are shown is the user's choice, from the tab's buttons, from commands or from the Mods screen, and it is remembered. Below the log, a command line with completion: help, log, mods, scene, clear; the Assets library adds assets, and any mod adds its own with ToolWindow.AddCommand(guid, name, help, run). A command that throws prints the error in red with the mod that owns it. mods network lists what each mod declares online and what it was seen connecting to; mods reload and mods watch drive reloading. There is no scripting language. docs/CONSOLE.md

Drawing over the game. ToolWindow.AddOverlay, BlockGameInput and Drawable are public, for tabs that work in the game view, as the Inspector does.

Assets 1.1.0

Texture replacements. A mod ships BepInEx/plugins/<Mod>/assets/textures/<texture name>.png and the library puts it into every material and sprite that used the game texture of that name, read at startup (when uploads are safe on Direct3D 12) and applied at each scene load. Two mods replacing the same texture are both named in the log and on the Assets tab; nothing is overridden silently. Meshes and shaders are not covered yet.

The Assets tab (F1) lists loaded textures with a filter, shows which replacements are in place and where two mods clashed, and has Apply replacements and Reload files. Reloading re-reads changed PNGs while the game runs; [Reload] WatchFiles does it by itself when a file changes, never on Direct3D 12. A crash during a reload is caught at the next start through a marker file: the Mods screen says so and reloading stays off until turned back on. Clicking a texture shows a preview of it, and Inspect opens the material that uses it in the Inspector. AssetCatalog gives mods the same listings. docs/ASSET_TOOL.md

Inspector 1.0.0 (experimental, and it stays that way)

A new library on top of the Tool window, for people who make mods: an Inspector tab with the scene's objects (a tree with search, or Pick to click one in the game), their components and materials, and every field and property, readable live and editable (numbers by typing or by dragging the field, vectors and colours per component, a colour picker with a square and a hue bar). A transform gizmo (Move / Rotate / Scale) in the game view, a History of every edit with Revert / Redo and Undo, Reset per row and per axis, keyboard shortcuts as in Unity's scene view (W/E/R/Q, P, H, T, Ctrl+Z). Nothing is saved: an edit lasts until the scene reloads or the game quits.

  • Code view per component: its type, its methods, the Harmony patches other mods put on them and whose they are, its UnityEvents' listeners, and a method's IL. Copy gives Type:Method; Patch copies a whole Harmony patch, the GameHooks.Require check included, with the parameters Harmony fills in, ready to paste into a mod.
  • Debug view: every renderer the camera sees, the selection's children or what the search matches, outlined at once, plus colliders, triggers and lights drawn in their own shape. A mesh collider that only the physics engine can describe is scanned with rays and labelled as an estimate.
  • Bones (click a joint to select it), Wireframe, a free camera, and Edit mesh vertices, which is experimental even within the Inspector.

The Inspector is experimental and marked so on the Mods screen: it may change or go away, and an edit made with it can break the running session. docs/INSPECTOR.md

Installing it by hand. The Inspector is not in the installers that mods ship, and Drag'n Wash Localization leaves it out, so it has to be installed by hand: download DragNWash.ModFramework-1.2.0.zip from this page and copy its BepInEx/plugins/DragNWash.ModFramework.Inspector folder into the game's BepInEx/plugins folder. Then turn on Developer tools (Options → Mods → Drag'n Wash ModFramework) and press F1. To remove it, delete that folder.

Dialogue 1.1.0

Stable line keys. A translation or any per-line mod used to lose a line whenever a game update edited its English. LineKey and LineResolver identify a line by its Yarn line ID first, then by the exact text's hash, a normalized hash and a fingerprint of the text, tried strongest first; a match by anything but the exact text is flagged for review. tools/linekeys.py has the same definitions and CI checks the two against shared vectors. docs/STABLE_LINE_KEYS.md

Compatibility

  • A mod built against 1.0.0 or 1.1.x runs unchanged; nothing public was removed or altered.
  • A mod that uses the new API needs [BepInDependency] on core 1.2.0 (and Dialogue / Assets / Tool window 1.1.0 where it uses those). The Mods screen tells the player when an installed mod needs a newer framework.
  • Everything new is marked experimental in the CHANGELOG: the APIs are public and follow semantic versioning from here, but this is their first release.

Known issues

  • On Direct3D 12 (the default on Windows), opening the F1 window or reloading textures can, rarely, crash the game (Unity UUM-140564). Playing with developer tools off is unaffected. When working with them, add -force-d3d11 to the game's Steam launch options.
  • macOS is still not supported: BepInEx's Doorstop cannot hook Unity 6.3 there (UnityDoorstop#108).

Full list: CHANGELOG.md. Documentation: the wiki (English and Japanese). This is an unofficial fan project, not affiliated with Gator Dragon Games, and contains no game files.

Drag'n Wash ModFramework 1.2.0（日本語）

フレームワークの 2 回目の機能リリースです。中核が 1.2.0、5 つのライブラリのうち 3 つが 1.1.0 になります。1.0.0 や 1.1.x の上で作られた Mod が使っているものは何も変えていません。増えたのはすべて新しい API です。この版を必要とする Drag'n Wash Localization v1.2.0 と一緒にリリースします。

プラグイン バージョン
Drag'n Wash ModFramework（中核） 1.2.0 開発者ツールのスイッチ、Mods 画面での文字列とキーの設定、GameEvents、SettingMeta、ゲームを動かしたままの Mod のリロード、通信する Mod の申告、新しいロゴと Mods ボタン
プリローダーのパッチャー 1.2.0 変更なし。中核に合わせる
Tool window 1.1.0 Console タブ、ゲーム画面への描画
Assets 1.1.0 テクスチャの差し替え、リロード、プレビュー付きの Assets タブ
Dialogue 1.1.0 安定した行キー
Inspector 1.0.0、実験的 新しいライブラリ：Code 表示とデバッグ表示を持つ、Tool window の Inspector タブ
Text、Flags and saves 1.0.0 変更なし
インストーラー（installer/） 変更なし 1.1.0 と同じ Install.exe

中核 1.2.0

Mod を作る人向けの機能をまとめる 1 つのスイッチ。 Options → Mods → Drag'n Wash ModFramework → Developer tools。既定はオフです。オフの間は F1 の窓は開かず、テクスチャのリロードは断られ、フレームワークの上の Mod も自分の書き出しやホットリロードを止めます。遊ぶために Mod を入れただけの人が、デバッグ用の窓を見たり、書き出されたファイルのフォルダを手にしたりすることはありません。作者向けには DeveloperTools.Enabled、Changed、WhenEnabled と、GUIDE のルール 8。

Mods 画面で編集できるものが増えました。 Mod の設定ページはこれまでオン・オフ、数値、選択肢だけを扱い、文字列、キー割り当て、色など BepInEx が文字で保存するものは設定ファイルでしか変えられませんでした。いまは入力欄が付き（Enter で反映。設定のパーサーが受け付けない値は理由つきで元に戻ります）、キー割り当てには Capture key もあります。押していた修飾キーごと、次に押したキーが入ります。

Mod が自分の設定ページの形を決められます。 ConfigDescription のタグに SettingMeta と SectionMeta を入れると、項目に表示名、並び順、Advanced（ページ最上段の Show advanced settings をオンにするまで隠す）、RequiresRestart の注記を、セクションに表示名、説明、並び順を付けられます。ConfigurationManager の IsAdvanced、DispName、Order も同じように読むので、すでに付けている Mod はそのままで構いません。フレームワーク自身の設定で使っています。Wiki: Settings meta

GameEvents：ゲームの出来事を、Mod ごとに。 SceneManager.sceneLoaded に直接つないだ処理が例外を投げると、あとから登録したすべての Mod の処理が止まり、どの Mod のせいかも分かりません。GameEvents.OnSceneLoaded、OnSceneUnloaded、OnGameStarted、OnQuitting は Mod の GUID を受け取り、処理を 1 つずつ切り離して実行します。例外を投げた処理はログに残り、Mods 画面でその Mod の下に表示され、3 回続けて失敗すると止まりますが、ほかの処理は動き続けます。毎フレームの出来事は意図的に用意していません。Assets ライブラリが使っており、GUIDE のルール 9 でほかの Mod にもお願いしています。Wiki: Game events

外と通信する Mod は、そのことを申告します。 通信機能を持つ Mod は、マルウェアが紛れ込む場所にもなります。そこで、外と通信することを Mod が公に申告する決まりにしました。ModInfo.Network に、接続先・目的・送る内容・止め方を並べます。Mods 画面はそうした Mod に Online の印と Internet ページを付け、NetworkWatch（既定でオン、接続を見張る）は、どの Mod が実際にどこへ接続したかを記録し、申告のない接続を警告色で示します。見張るだけで何も止めず、安全を保証する仕組みではありません。フレームワーク自身の 1 日 1 回の更新確認も申告しています。GUIDE のルール 11、Wiki: 外と通信する Mod。

ゲームを再起動せずに Mod をリロード（開発者ツール）。リロードできると宣言した Mod（ModInfo.Reloadable）は、ゲームを動かしたまま新しいビルドに入れ替わります。GUID を手がかりに登録と Harmony パッチを外し、新しいプラグインを同じ場所で起動します。DLL の隣に <Mod>.dll.new としてビルドすれば自動で拾い、mods reload <guid> で手動でもできます。ライブラリはリロードしません。GUIDE のルール 10、docs/MOD_RELOAD.ja.md。

GameHooks.Require は、Harmony と同じ "Type:Method" の 1 つの文字列も受け取ります。Inspector がコピーする形です。

GameHooks.Unavailable(guid, feature, reason) は、ゲームのメンバーの有無以外の理由（このレンダラーでは不可、クラッシュ後に停止）で機能を使えない印にします。確認の失敗と同じように Mods 画面に出ます。

新しいロゴと、手描きの Mods ボタン

フレームワークのロゴと Mods 画面のアイコン（スポンジと歯車）が新しくなりました。NotaGames さん（@NotaGames）がゲームのロゴをもとに描いたもので、開発元からも問題ないとの返事をいただいています。Options 画面の Mods ボタンが、ゲームのメニューに合わせた絵になりました。描いてくださったのは Mister ERIO さん（@mistererio）です。ありがとうございます！

Tool window 1.1.0

Console タブ。 すべての Mod と Unity からの BepInEx のログ行を、流れてくるままに、レベルと出どころつきで色分けして表示し、最新 2,000 行を保持します。どのレベルとどの出どころを見せるかは使う人が、タブのボタン、コマンド、Mods 画面のどれからでも選べ、記憶されます。ログの下には補完付きのコマンド行。help、log、mods、scene、clear があり、Assets ライブラリが assets を足し、どの Mod も ToolWindow.AddCommand(guid, name, help, run) で自分のものを足せます。例外を投げたコマンドは、持ち主の Mod 名とともに赤で出ます。mods network は、各 Mod の通信の申告と、実際に見られた接続を並べます。mods reload と mods watch でリロードを操作します。スクリプト言語はありません。docs/CONSOLE.ja.md

ゲーム画面への描画。 ToolWindow.AddOverlay、BlockGameInput、Drawable を公開しました。Inspector のように、ゲーム画面の上で働くタブのためのものです。

Assets 1.1.0

テクスチャの差し替え。 Mod が BepInEx/plugins/<Mod>/assets/textures/<テクスチャ名>.png を同梱すると、ライブラリがその名前のゲームのテクスチャを使っていたすべてのマテリアルとスプライトにそれを入れます。読み込みは起動時（Direct3D 12 でアップロードが安全な時点）、適用はシーンの読み込みごとです。同じテクスチャを 2 つの Mod が差し替えたら、ログと Assets タブに両方の名前が出ます。黙って上書きすることはありません。メッシュとシェーダーはまだ対象外です。

Assets タブ（F1）は、読み込まれているテクスチャを絞り込み付きで一覧し、どの差し替えが当たっているか、どこで 2 つの Mod がぶつかったかを示し、Apply replacements と Reload files があります。リロードは、変わった PNG をゲームを動かしたまま読み直します。[Reload] WatchFiles なら、ファイルが変わったときに自動で読み直します（Direct3D 12 では動きません）。リロード中のクラッシュは印のファイルで次の起動時に検知し、Mods 画面にそう出て、自分で戻すまでリロードはオフになります。テクスチャをクリックするとプレビューが出て、Inspect でそれを使っているマテリアルを Inspector で開けます。AssetCatalog で Mod からも同じ一覧が取れます。docs/ASSET_TOOL.ja.md

Inspector 1.0.0（実験的。今後もそのまま）

Tool window の上に載る新しいライブラリで、Mod を作る人向けです。Inspector タブに、シーンのオブジェクト（検索付きの木、または Pick でゲーム内をクリック）、そのコンポーネントとマテリアル、すべてのフィールドとプロパティが出て、動いたまま読め、編集できます（数値は打ち込みでも欄のドラッグでも、ベクトルと色は成分ごと、彩度×明度の正方形と色相バーのカラーピッカー）。ゲーム画面のトランスフォームギズモ（Move / Rotate / Scale）、すべての編集の History（Revert / Redo / Undo）、行ごと・軸ごとの Reset、Unity のシーンビューと同じショートカット（W/E/R/Q、P、H、T、Ctrl+Z）。何も保存しません。編集はシーンの読み直しかゲームの終了まで残ります。

  • コンポーネントごとの Code 表示：型、メソッド、ほかの Mod がそれに当てている Harmony パッチとその持ち主、UnityEvent のリスナー、メソッドの IL。Copy は Type:Method を、Patch は GameHooks.Require の確認まで含めた Harmony パッチ一式（Harmony が渡す引数付き）をコピーし、そのまま Mod に貼れます。
  • デバッグ表示：カメラに映るすべての Renderer、選択の子孫、検索に合うものをまとめて枠で示し、コライダー・トリガー・ライトは形のまま描きます。形を物理エンジンだけが持っている MeshCollider は、レイで写し取り、推定であることをラベルに出します。
  • Bones（関節をクリックで選択）、Wireframe、フリーカメラ、そして Inspector の中でもさらに実験的なメッシュの頂点編集。

この Inspector は実験的な機能で、Mods 画面にもそう表示します。変わったりなくなったりすることがあり、これで加えた編集は動いているセッションを壊すことがあります。docs/INSPECTOR.ja.md

手動での導入が必要です。 Inspector は、Mod に同梱されるインストーラーには入っておらず、Drag'n Wash Localization にも入っていません。使うときは、このページから DragNWash.ModFramework-1.2.0.zip をダウンロードし、中の BepInEx/plugins/DragNWash.ModFramework.Inspector フォルダーを、ゲームの BepInEx/plugins フォルダーにコピーしてください。そのうえで Developer tools（Options → Mods → Drag'n Wash ModFramework）をオンにし、F1 を押します。外すときは、そのフォルダーを削除します。

Dialogue 1.1.0

安定した行キー。 翻訳や行単位の Mod は、ゲームの更新で英語の文面が変わるたびにその行を失っていました。LineKey と LineResolver は、まず Yarn の行 ID で、次に文面そのもののハッシュ、正規化したハッシュ、文面のフィンガープリントで、強い順に行を見つけます。文面そのもの以外で一致したものは要確認の印が付きます。tools/linekeys.py に同じ定義があり、CI が共通のベクターで両者を照合します。docs/STABLE_LINE_KEYS.ja.md

互換性

  • 1.0.0 や 1.1.x に対して作った Mod はそのまま動きます。公開されているものは何も消しておらず、変えてもいません。
  • 新しい API を使う Mod は、中核 1.2.0（使うなら Dialogue / Assets / Tool window の 1.1.0 も）への [BepInDependency] が必要です。入れた Mod がより新しいフレームワークを必要とするときは、Mods 画面がそう伝えます。
  • 新しいものはすべて CHANGELOG で「実験的」としています。API は公開されていて、ここからセマンティックバージョニングに従いますが、これが最初のリリースです。

既知の問題

  • Direct3D 12（Windows の既定）では、F1 の窓を開いたときやテクスチャのリロード中に、まれにゲームが落ちることがあります（Unity UUM-140564）。開発者ツールがオフなら影響はありません。使うときは、Steam の起動オプションに -force-d3d11 を付けてください。
  • macOS は引き続き非対応です。BepInEx の Doorstop が Unity 6.3 にフックできません（UnityDoorstop#108）。

すべての変更：CHANGELOG.md。文書：Wiki（英語と日本語）。非公式のファン制作物で、Gator Dragon Games とは関係ありません。ゲームのファイルは含みません。

Assets 3
Loading