MGCB: Implement UI for editing .mgcb files (integrated MGCB Editor)

[seclerp]

Implementation status

• MGCB Editor tool window
  • .mgcb file drop-down selector
  • Toolbar actions
  • Content items tree
  • Properties table
• MGCB Build Log tool window
• MGCB Build engine
  • Build regular assets
  • Build effects
• Remove old tools infrastructure

Motivation

Dealing with dotnet-mgcb-editor and satelite tools like dotnet-mgcb-editor-mac is complicated:

1. MGCB Editor still doesn't work on Apple Silicon chips properly
2. "Open in MGCB Editor" requires complex .NET Tools tracking in different places for different versions of MonoGame
3. The MGCB Editor installation process relies on the user's .NET Tools setup, including proper .dotnet/tools folder mapping

Because of bullet 1, we also can't ship the tool binaries together with the plugin.

So, it makes sense to introduce a UI for editing..mgcb files without direct dependency in the dotnet-mgcb-editor tool. It will also replace MGCB Previewer for .mgcb files, which is currently available as a separate previewer pane.

Analysis

Standalone MGCB Editor looks like this:

Designing .mgcb

It has the following major UI parts:

• "Project" pane: a content items tree, representing the structure of content items in the file
• "Properties" pane: a classic key-value table that allows editing properties of content items
• "Build Output" pane: a log showing the content build results and diagnostics

There are also a couple of actions to add new content to the file:

• Add/New Item: creates a known file from template (.fx, .spritefont, etc)
• Add/New Folder: creates a new directory
• Add/Existing item: adds an existing content file, including option to copy to the Content directory
• Add/Existing Directory: add multiple content files
• File/Import: special action to import old XNA-related entities

Building .mgcb

MGCB Editor has such build-related toolbar actions:

• Build: builds items to the /bin and /obj subdirectories relative to .mgcb file
• Rebuild: the same as Build but with cleaning directories before
• Clean: cleans directories

Design

MGCB Editor tool window

The new editor will be implemented as a separate tool window called "MGCB Editor", instead of an embedded previewer pane near the file. It will have a .mgcb file selector to switch between multiple files (in case of a multi-platform solution setup).

Selecting the .mgcb file in the Solution view or in the code editor will by default switch the file in the tool window to the selected one.

The "MGCB Editor" tool window will have an identical layout to the existing previewer - 2 panels divided by a splitter:

Additionally, the new tool window will have toolbar actions, similar to the standalone editor's actions.

By default, MGCB Editor will be placed in the upper-right corner (e.g. Database)

MGCB Build Log tool window

Build actions will request content build, representing its result in a separate Build-like tool window called "MGCB Build Log". It will have the same or a similar output as the standalone MGCB Editor's build output.

Implementation notes

The vast majority of content-related boilerplate and additional stuff is implemented in the MonoGame.Framework.Content.Pipeline library. It can be reused to build content and read metadata.

We don't need to write new parser MGCB files to pass them to the build engine. We already have parsers on frontend, based on IJPL's PSI.

Note: Backend PSI coming with feature/mgcb-backend-psi branch will help too.

Open questions

• Maybe it's better to stick with the previewer entry point for MGCB Editor instead of the toolwindow?

• Do we really want to introduce an "integrated" build approach or keep it "external", based on the dotnet mgcb tool?

• Runtime compatibility between the plugin TFM and MG.F.Content.Pipeline TFM. Settings both to have net8.0 might break the PSI-related stuff in the feature/mgcb-backend-psi branch

• Effects compiling:

  1. Requires complex low level logic
  2. Compiling .fx files on macOS and Linux requires Wine.

  Maybe we will consider bundling the MGFXC executable together with the plugin to solve both issues.

Links

• https://docs.monogame.net/articles/getting_started/tools/mgcb_editor.html
• https://docs.monogame.net/articles/getting_started/content_pipeline/using_mgcb_editor.html