BNes Fork

A map-based NES emulator plugin for Minecraft servers. This fork continues maintenance of MoeWhite19/BNes and uses Nestalgia as the emulation core.

This is a community-maintained fork, not an official release of the original project. Porting, debugging, and some code modifications in this fork were assisted by OpenAI Codex. AI-assisted code may contain undiscovered issues; please test thoroughly before deploying on production servers. Users assume all compatibility and data risks.

---

✨ Features

• ✅ Adapted for Paper 1.21.1, Java 21, and modern Gradle builds
• ✅ Declared support for Folia scheduling environment
• ✅ Integrated via JitPack with Shadow JAR packaging for Nestalgia emulator core
• ✅ Plasmo Voice spatial audio – encodes NES 48 kHz game audio in real-time as Opus and streams to nearby players
• ✅ Fixed Plasmo Voice audio stuttering, PCM frame glitches, buffering delays, reconnection issues, and resource cleanup
• ✅ Uses icon.png as the BNes voice source icon in Plasmo Voice
• ✅ Fixed missing game image for remote players and standalone servers; map packets sent primarily via PacketEvents, with fallback to ProtocolLib and native Paper/NMS, and full first-frame sync for late-joining observers
• ✅ GitHub Actions automatic builds; uploads plugin JAR on GitHub Release, auto-generates changelog when release notes are empty

---

📋 Requirements

Requirement	Details
Java	21
Server	Paper 1.21.1 or compatible
Plasmo Voice	Server plugin + client mod (required for audio)
PacketEvents	Optional but recommended – preferred map packet backend
ProtocolLib	Optional – fallback backend
Vault	Optional – only needed for economy features
Chair plugin	Recommended – can also use minecarts as alternative

---

📦 Installation & Usage

1. Download the JAR from the Releases page.
2. Place it in your server's plugins folder.
3. Start the server once, then place your NES ROMs (that you have rights to use) in plugins/BNes-Fork/roms.
4. Create a console with /bnes create <instance_name> (add min at the end for a single-map version).
5. Place the generated map on a wall. Sit on a chair and right-click the map to join.
6. Up to two players can play simultaneously. To hear game audio, both server and client must have Plasmo Voice properly installed and connected.

The plugin also generates non_card.nes as a default screen when a new console has no cartridge or an invalid ROM.

Upgrading from Original BNes

If upgrading from the original BNes, shut down the server first, then rename or move the original plugins/BNes data directory to plugins/BNes-Fork. Otherwise, the new plugin will create a fresh empty configuration.

---

⌨️ Commands & Permissions

Command	Description	Permission
/bnes	Shows available help	–
/bnes reload	Reloads and normalizes config & language files	bnes.command.reload
/bnes create <name> [min]	Creates a console	bnes.command.create
/bnes map <name> [player]	Gets the console map	bnes.command.map
/bnes close <name>	Closes a console	bnes.command.close
/bnes showfps	Toggles FPS display	bnes.command.showfps
/bnes rename <name> <new_name>	Renames an instance	bnes.command.rename
/bnes card <URL/filename>	Gets a local cartridge or downloads an iNES ROM	bnes.command.card
/bnes menu [page]	Opens the cartridge menu	bnes.command.menu
/bnes saves [page]	Manages personal saves (left-click to download as item, right-click to delete)	–
/bnes speed [percentage]	Views or modifies Nestalgia emulation speed	–

---

🎮 Default Key Bindings

Minecraft Action	NES Button
Movement keys	Directional pad
Jump	A
Swap offhand	B
Left-click map	Select
Right-click map	Start
Start + A simultaneously	Reset game
Select + A simultaneously	Write to personal save file

Key bindings can be modified in the plugin configuration file.

---

📄 License

This project continues to use the GPL-3.0 license as in the original repository. See the LICENSE file for details.

---

🙏 Acknowledgements

Thanks to the original BNes author, the Nestalgia project, and all maintainers of related dependencies for their valuable work.