Skip to content

Avalonia GUI

Jump to bottom
laqieer edited this page Jul 22, 2026 · 6 revisions

Avalonia GUI -- Cross-Platform Interface

FEBuilderGBA includes a cross-platform GUI built with Avalonia UI (v11.2.3), enabling ROM editing on Linux, macOS, and Windows without requiring WinForms. The Avalonia frontend follows the MVVM pattern and currently covers approximately 93% of the WinForms feature set.

Supported Platforms

Platform Architecture Status
Windows 10/11 x64 Fully supported
Linux (Ubuntu, Fedora, etc.) x64 Fully supported
macOS arm64 (Apple Silicon) Fully supported
macOS x64 (Intel) Supported via Rosetta 2 or native build
Android arm64 / x86_64 Experimental native APK — builds + emulator-validated render parity (see Native Android)
iOS / iPadOS arm64 Experimental native .ipa — builds on macOS (Xcode 26.5); on-device runtime maturing (see Native iOS)
Web (WebAssembly) wasm Experimental — runs in any modern browser, live on GitHub Pages (see Native Web)

How to Launch

Avalonia GUI

# Build and run directly
dotnet run --project FEBuilderGBA.Avalonia/FEBuilderGBA.Avalonia.csproj

# Or build first, then run the executable
dotnet build FEBuilderGBA.Avalonia/FEBuilderGBA.Avalonia.csproj
./FEBuilderGBA.Avalonia/bin/Debug/net10.0/FEBuilderGBA.Avalonia

# Open a specific ROM
dotnet run --project FEBuilderGBA.Avalonia/FEBuilderGBA.Avalonia.csproj -- --rom path/to/rom.gba

Cross-Platform CLI

The CLI works on all platforms independently of the GUI:

dotnet run --project FEBuilderGBA.CLI/FEBuilderGBA.CLI.csproj -- --help
dotnet run --project FEBuilderGBA.CLI/FEBuilderGBA.CLI.csproj -- --version
dotnet run --project FEBuilderGBA.CLI/FEBuilderGBA.CLI.csproj -- --rom rom.gba --lint

See Command-Line Interface for full CLI documentation.

Self-Contained Publish

Pre-built self-contained binaries are available from CI for each platform:

# Publish locally
scripts/publish-all.sh   # Produces cli-{rid} and avalonia-{rid} artifacts

Architecture

MVVM Pattern

Every view (.axaml) has a corresponding ViewModel (.cs). All ViewModels inherit from ViewModelBase. Views define UI layout; ViewModels hold state and command logic.

FEBuilderGBA.Avalonia/
+-- Views/           # 357 AXAML view files
+-- ViewModels/      # 367 ViewModel classes
+-- Controls/        # 7 shared reusable controls
+-- Services/        # Platform services (undo, dialogs, image export/import)
+-- Dialogs/         # File/message dialog helpers
+-- App.axaml        # Application entry point
+-- Program.cs       # Startup and ROM initialization

Shared Controls

Control Description
AddressListControl Reusable list for ROM address entries with selection and navigation
GbaImageControl Reusable GBA image display control with zoom and palette support
BitFlagPanel Reusable 8/16/32-bit flag toggle panel
EditorTopBar / EditorTopBarWithInputs Shared editor top bar (Jump / Pick / navigation)
IconPreviewControl Reusable icon / wait-icon preview control
IdFieldControl Type-ID field: label + NumericUpDown + name preview + Jump + Pick (#366)

Key Services

Service Description
UndoService Wraps Core undo system for all write operations
WindowManager Editor window lifecycle, pick-and-return navigation
ImageExportService Export GBA images to PNG/BMP
ImageImportService Import images with palette validation
PatchDetectionService Detect installed patches and show patch-aware UI
ProgressDialogService Long-running operation progress feedback
ComboResourceHelper Populate combo boxes with ROM data (units, classes, items)
NameResolver Resolve ROM IDs to human-readable names
ScriptEditorHelper Event/AI/Procs script editing support
TableExportImportHelper CSV/TSV export and import for tabular data

Pick-and-Return Navigation

Eight editors implement IPickableEditor for cross-reference navigation:

  • ClassEditor
  • ClassFE6
  • PortraitViewer
  • ItemEditor
  • ItemFE6
  • UnitEditor
  • SongTable
  • SongTrackImportSelectInstrument

Use WindowManager.PickFromEditor<T>() to open an editor and return a selected value.

Feature Comparison with WinForms

What Works

Feature Status
ROM loading and version detection Complete
All 5 ROM variants (FE6, FE7J, FE7U, FE8J, FE8U) Complete
Unit, Class, Item editors Complete
Map editors (settings, tiles, terrain, style) Complete
Event script editing (viewing + category/template navigation) ~40% (raw script editing limited)
Event conditions Complete (write-enabled editor)
Event unit placement Complete (write-enabled, incl. New Allocation)
AI script editing Complete
Procs script editing Complete
Image/portrait viewing and editing Complete
Portrait rendering and export Complete
Battle animation sprite metadata Complete
Audio/song table editing Complete
MIDI export, parsing, and GBA write-back (import → ROM, #972) Complete
Text viewing and editing Complete
Text validation and cross-references Complete
Support conversation editing Complete
World map editing Complete
Hex editor Complete
Disassembler Complete
Pointer tools Complete
Patch manager (browse, filter, install, uninstall) Largely complete
Three-way merge Complete
Undo/redo on all editors Complete
Stat growth simulation Complete
FE Lint validation Complete
ROM rebuild Complete
Data expansion Complete
CSV/TSV export and import Complete
Easy mode (simplified menu) Complete
Skill system editors Complete
Drag-and-drop ROM loading Complete

What Is Still in Progress

Feature Status Notes
OAM sprite assembly (battle animation) Partial Import-side OAM assembly works (magic / world-map border / battle-anime import via BattleAnimeOAMImportCore); a full battle-animation frame editor is not ported
Animation playback Not implemented No frame-by-frame animation preview
InputFormRef auto-wiring Not implemented WinForms convention-based control linking has no Avalonia equivalent
Emulator memory access (RAM viewer) Limited P/Invoke-based, Windows-only in WinForms

Editor Reference by Category

The Avalonia GUI contains 357 AXAML views across 27 functional categories. Below is a summary of each category. For the complete view-by-view reference with ViewModel mappings, see docs/avalonia-forms.md.

1. Application Shell (8 views)

Main window, welcome screen, version info, options, and ROM detection dialogs.

  • MainWindow, WelcomeView, VersionView, OptionsView
  • OpenLastSelectedFileView, LogViewerView
  • ErrorUnknownROMView

2. Unit & Class Editors (20 views)

Full unit and class editing for all ROM versions, including movement costs, weapon locks, promotion lists, and growth simulation.

  • Units: UnitEditorView, UnitFE6View, UnitFE7View, UnitMainView
  • Unit data: UnitActionPointerView, UnitCustomBattleAnimeView, UnitIncreaseHeightView, UnitPaletteView, UnitsShortTextView
  • Extra units: ExtraUnitView, ExtraUnitFE8UView
  • Classes: ClassEditorView, ClassFE6View, CCBranchEditorView
  • Movement: MoveCostEditorView, MoveCostFE6View
  • Other: SomeClassListView, VennouWeaponLockView, SMEPromoListView, GrowSimulatorView

3. Item Editors (16 views)

Complete item and weapon editing including effects, bonuses, shops, and weapon triangle.

  • Items: ItemEditorView, ItemFE6View
  • Effects: ItemWeaponEffectViewerView, ItemEffectPointerViewerView, ItemUsagePointerViewerView
  • Bonuses: ItemStatBonusesViewerView, ItemStatBonusesSkillSystemsView, ItemStatBonusesVennoView
  • Effectiveness: ItemEffectivenessViewerView, ItemEffectivenessMainView, ItemEffectivenessSkillSystemsReworkView
  • Other: ItemPromotionViewerView, ItemShopViewerView, ItemWeaponTriangleViewerView, ItemIconViewerView, ItemRandomChestView

4. Map Editors (40 views)

Comprehensive map editing: settings, tiles, terrain, style, exit points, and visual tile editor.

  • Settings: MapSettingView (+ FE6, FE7, FE7U variants), MapSettingDifficultyView/DialogView
  • Map data: MapChangeView, MapExitPointView, MapPointerView (+ NewPLIST)
  • Tile animation: MapTileAnimationView, MapTileAnimation1View, MapTileAnimation2View
  • Visual editor: MapEditorView (+ resize, margin, map change dialogs), including deterministic one-click random-map generation with an inline Cancel action; optional external FEMapCreator setup and per-tileset mapping live in Options, generation-time tileset/profile identity resolution and backend work stay off the UI thread and cancellable, Save Mapping re-checks cancellation immediately before durable persistence, external executable/image/generation-data identity is revalidated after FEMapCreator exits, generation fails closed before either backend if the live source grid cannot be decoded, and successful output is rejected unless its cell count matches the map dimensions, every MAR has a complete TSA block in the resolved tileset, and at least two distinct MAR values are present
  • Style: MapStyleEditorView (+ append, warning, import options)
  • Terrain: MapTerrainNameView, MapTerrainNameEngView, MapTerrainBGLookupView, MapTerrainFloorLookupView
  • Other: MapMiniMapTerrainImageView, MapLoadFunctionView, TerrainNameEditorView

5. Event Script Editors (39 views)

Event scripts, conditions, unit placement, battle conversations, death quotes, and templates.

  • Scripts: EventScriptView (+ Main, Inner, Template, CategorySelect, Popup)
  • Conditions: EventCondView, EventCondMainView
  • Units: EventUnitView (+ FE6, FE7, Sim, Color, ItemDrop, NewAlloc variants)
  • Battle talk: EventBattleTalkView (+ FE6, FE7 variants), EventBattleDataFE7View
  • Death quotes: EventHaikuView (+ FE6, FE7 variants)
  • FE7-specific: EventFinalSerifFE7View, EventMoveDataFE7View, EventTalkGroupFE7View
  • Templates: EventTemplate1-6View, EventTemplateImplView

6. AI Script Editors (13 views)

Enemy AI behavior editing.

  • AIScriptView, AIScriptCategorySelectView, AIASMCALLTALKView, AIASMCoordinateView, AIASMRangeView
  • AIMapSettingView, AIPerformItemView, AIPerformStaffView, AIStealItemView, AITargetView, AITilesView, AIUnitsView
  • AOERANGEView

7. Procs Script Editors (2 views)

Process/animation script editing.

  • ProcsScriptView, ProcsScriptCategorySelectView

8. Image & Graphics Editors (40 views)

Portraits, battle animations, backgrounds, CGs, tilesets, palettes, magic effects, and system graphics.

  • Portraits: PortraitViewerView, ImagePortraitView (+ FE6), ImagePortraitImporterView, ImageGenericEnemyPortraitView
  • Battle: ImageBattleAnimeView, ImageBattleAnimePalletView, ImageBattleBGView, ImageBattleScreenView
  • CG: ImageCGView, ImageCGFE7UView, BigCGViewerView
  • Unit sprites: ImageUnitPaletteView, ImageUnitWaitIconView, ImageUnitMoveIconView
  • System: ImageSystemAreaView, SystemIconViewerView, SystemHoverColorViewerView
  • TSA: ImageTSAEditorView, ImageTSAAnimeView, ImageTSAAnime2View
  • Magic: ImageMagicFEditorView, ImageMagicCSACreatorView
  • Tools: GraphicsToolView, GraphicsToolPatchMakerView, DecreaseColorTSAToolView

9. Palette Tools (3 views)

  • PaletteChangeColorsView, PaletteClipboardView, PaletteSwapView

10. Audio & Music Editors (18 views)

Song tables, tracks, instruments, MIDI import, sound room, and boss BGM.

  • Songs: SongTableView, SongTrackView (+ AllChange, Change, ImportMidi, ImportSelectInstrument, ImportWave)
  • Instruments: SongInstrumentView, SongInstrumentDirectSoundView, SongInstrumentImportWaveView
  • Sound data: SoundBossBGMViewerView, SoundFootStepsViewerView
  • Sound room: SoundRoomViewerView, SoundRoomFE6View, SoundRoomCGView

11. Text & Translation Editors (15 views)

Game text editing, fonts, translation tools, and text utilities.

  • Text: TextViewerView, OtherTextView, CStringView
  • Fonts: FontEditorView, FontZHView
  • Utilities: TextEscapeEditorView, TextDicView, TextCharCodeView, TextBadCharPopupView, TextRefAddDialogView
  • Translation: DevTranslateView, ToolTranslateROMView, TextToSpeechView

12. Support System Editors (6 views)

  • SupportUnitEditorView, SupportUnitFE6View, SupportAttributeView
  • SupportTalkView, SupportTalkFE6View, SupportTalkFE7View

13. Arena, Monster & Summon Editors (8 views)

  • ArenaClassViewerView, ArenaEnemyWeaponViewerView, LinkArenaDenyUnitViewerView
  • MonsterProbabilityViewerView, MonsterItemViewerView, MonsterWMapProbabilityViewerView
  • SummonUnitViewerView, SummonsDemonKingViewerView

14. Menu Editors (4 views)

  • MenuDefinitionView, MenuCommandView, MenuExtendSplitMenuView, FE8SpellMenuExtendsView

15. Ending Editors (5 views)

  • EDView, EDStaffRollView, EDFE6View, EDFE7View, EDSensekiCommentView

16. World Map Editors (11 views)

  • WorldMapPointView, WorldMapBGMView, WorldMapEventPointerView (+ FE6, FE7)
  • WorldMapPathView, WorldMapPathEditorView, WorldMapPathMoveEditorView
  • WorldMapImageView (+ FE6, FE7)

17. Opening Editors (12 views)

  • OPClassDemoViewerView (+ FE7, FE7U, FE8U), OPClassFontViewerView (+ FE8U)
  • OPClassAlphaNameView (+ FE6, FE6Extra), OPPrologueViewerView
  • ClassOPDemoView, ClassOPFontView

18. Status Screen Editors (5 views)

  • StatusParamView, StatusRMenuView, StatusUnitsMenuView, StatusOptionOrderView, StatusOptionView

19. Skill System Editors (12 views)

Multiple skill system implementations: SkillSystem, CSkillSys, and FE8N.

  • SkillSystem: SkillAssignmentUnitSkillSystemView, SkillAssignmentClassSkillSystemView, SkillConfigSkillSystemView
  • CSkillSys: SkillAssignmentUnitCSkillSysView, SkillAssignmentClassCSkillSysView, SkillConfigFE8UCSkillSys09xView
  • FE8N: SkillAssignmentUnitFE8NView, SkillConfigFE8NSkillView (v1, v2, v3)
  • Other: SkillSystemsEffectivenessReworkClassTypeView, SkillSystemsCSkillRechainView

20. Patch Management (7 views)

  • PatchManagerView, PatchFilterExView, PatchFormUninstallDialogView, PatchUninstallDialogView
  • HowDoYouLikePatchView, HowDoYouLikePatch2View, ToolCustomBuildView

21. Hex Editor & Disassembly (10 views)

  • HexEditorView (+ Jump, Mark, Search), DisASMView, DisASMDumpAllView, DisASMDumpAllArgGrepView
  • ToolASMEditView, ToolASMInsertView, ToolDecompileResultView

22. Pointer & Memory Tools (8 views)

  • PointerToolView (+ BatchInput, CopyTo), MoveToFreeSpaceView, PackedMemorySlotView
  • EmulatorMemoryView, RAMRewriteToolView, RAMRewriteToolMAPView

23. Bit Flag Editors (3 views)

  • UbyteBitFlagView (8-bit), UshortBitFlagView (16-bit), UwordBitFlagView (32-bit)

24. Structural Data Editors (4 views)

  • Command85PointerView, DumpStructSelectDialogView, DumpStructSelectToTextDialogView, ResourceView

25. Error & Notification Dialogs (9 views)

  • ErrorReportView, ErrorPaletteMissMatchView, ErrorPaletteShowView, ErrorPaletteTransparentView, ErrorTSAErrorView, ErrorLongMessageDialogView
  • NotifyDirectInjectionView, NotifyPleaseWaitView, NotifyWriteView

26. Tool Utilities (32 views)

ROM management, lint, diff, UPS patching, three-way merge, and more.

  • Undo: ToolUndoView, ToolUndoPopupDialogView
  • Validation: ToolFELintView, ToolROMRebuildView, ToolLZ77View
  • Diff/Merge: ToolDiffView, ToolDiffDebugSelectView, ToolThreeMargeView
  • UPS: ToolUPSPatchSimpleView, ToolUPSOpenSimpleView
  • Setup: ToolInitWizardView, ToolUpdateDialogView, ToolEmulatorSetupMessageView
  • Reports: ToolProblemReportView (+ SearchBackup, SearchSav)
  • Work support: ToolWorkSupportView (+ SelectUPS, UpdateQuestionDialog)

27. Simple Menu Mode (4 views)

Beginner-friendly simplified interface.

  • MainSimpleMenuView, MainSimpleMenuEventErrorView, MainSimpleMenuEventErrorIgnoreErrorView, MainSimpleMenuImageSubView

Version-Specific Editors

Many editors have version-specific variants that automatically activate based on the loaded ROM:

ROM Version Suffix Example Editors
FE6 (Japan) FE6 UnitFE6, ClassFE6, ItemFE6, MapSettingFE6, EventUnitFE6, SupportTalkFE6
FE7 (Japan) FE7 UnitFE7, MapSettingFE7, EventUnitFE7, EventBattleTalkFE7, SupportTalkFE7
FE7 (US) FE7U MapSettingFE7U, ImageCGFE7U, OPClassDemoFE7U
FE8 (Japan) FE8N SkillConfigFE8N (v1, v2, v3)
FE8 (US) FE8U ExtraUnitFE8U, OPClassDemoFE8U, OPClassFontFE8U

Statistics

Metric Count
Total AXAML Views 357 (*View.axaml; 369 .axaml incl. controls/dialogs)
Total ViewModels 367
Shared Controls 7
Functional Categories 27
Version-Specific Variants ~25
IPickableEditor Implementations 8
Write-enabled editors (IDataVerifiable) 176

Known Limitations

  1. OAM sprite assembly is partial -- Import-side OAM assembly works (magic / world-map border / battle-anime import via BattleAnimeOAMImportCore), but a full battle-animation frame editor is not ported.
  2. No animation playback -- Frame-by-frame animation preview is not available; only static frames can be viewed.
  3. No InputFormRef auto-wiring -- The WinForms convention-based control linking has no Avalonia equivalent. Cross-references are wired manually in ViewModels.
  4. Emulator memory access is limited -- The RAM viewer uses Windows P/Invoke and is not portable to Linux/macOS.
  5. Raw event-script editing is partial (~40%) -- Event conditions and unit placement are fully write-enabled editors, but the raw event-script editor is still primarily a viewer with category/template navigation.

MIDI→GBA write-back (import → ROM, #972) and patch install/uninstall are now implemented; they are no longer limitations.

Further Reading

Clone this wiki locally