Development

10. Development Guide

This chapter is for contributors or anyone working on Oxide from source.

Requirements

• Rust toolchain
• Desktop environment supported by eframe
• Audio output device if buzzer testing matters

Common commands

Check the project

cargo check

Run the app

cargo run

Build release

cargo build --release

Useful directories

• src/: application source
• src/ui/: UI modules
• src/debug/: debug localization
• src/assets/: bundled fonts, icons, splash logo
• docs/: repository technical docs
• images/: repository/project visuals
• logs/: generated local logs
• savestates/: generated local save states

Working on UI

Main rendering files:

• src/ui/top_bar.rs
• src/ui/bottom_bar.rs
• src/ui/main_panel.rs
• src/ui/settings.rs
• src/ui/debug_terminal.rs

Theme visuals are centralized through visuals_for_theme() and the custom Kiwano setup in src/app.rs.

Working on localization

UI strings:

• src/i18n/common.json
• src/i18n/<lang>.json

Debug strings:

• src/debug/i18n/common.json
• src/debug/i18n/<lang>.json

Working on save states

Save-state logic is centered in src/app.rs.

Keep in mind:

• save states are ROM-specific
• settings persistence and save-state persistence are separate systems

Encoding guidance

The repository is configured to reduce mojibake risk through:

• .editorconfig
• .gitattributes
• UTF-8-oriented editor setup

Recommended on Windows:

• UTF-8-capable terminal
• PowerShell 7

Suggested workflow

1. Switch to your working branch
2. Run cargo check before and after changes
3. Update docs when behavior changes
4. Keep user-facing strings in i18n JSON files
5. Keep technical constants in Rust code
6. Verify detached viewports still behave correctly
7. Commit once code and docs match reality