Nesbox扩展开发指南：如何快速编写新的主机内核或新增一种游戏模式

Nesbox扩展开发指南：如何快速编写新的主机内核或新增一种游戏模式

【免费下载链接】emulatorEmulator of NES, Super Nintendo, Sega Mega Drive, GameBoy video consoles项目地址: https://gitcode.com/gh_mirrors/em/emulator

Nesbox 是一款基于 Adobe Flash 技术、直接在浏览器窗口中运行的复古主机模拟器，支持 NES、Super Nintendo、Sega Mega Drive 和 GameBoy 五大主机系统。它采用「外壳 + 内核 + 模式」三层解耦设计：每个主机的模拟内核都是一个独立 SWF，每种游戏玩法都是一个独立模式类。本文带你快速上手 Nesbox 扩展开发——如何编写新的主机内核（Host Core），或为它新增一种游戏模式，让你像插件一样扩展这款经典模拟器。

开发前先获取源码仓库：git clone https://gitcode.com/gh_mirrors/em/emulator

一、Nesbox 架构总览：内核是"动态加载的插件" 🎮

理解 Nesbox 的扩展机制，只需看三条主线：

层次	关键文件	职责
外壳（Shell）	Nesbox.as	入口，解析 URL 参数，负责模式路由
数据层	GameData.as	根据system参数动态加载内核 SWF 并拉取 ROM
内核（Core）	各主机 SWF（如 nes.swf、snes.swf）	实现 CPU/画面/音频模拟，实现ICoreModule接口
模式（Mode）	src/mode/	单人、联网、房间等玩法，继承Base类

工作流程非常清晰：

1. 页面通过swfobject嵌入 Nesbox.swf，并传入system、url、action等参数；
2. GameData.init() 将system + '.swf'拼成 URL，用Loader动态加载内核；
3. 加载完成后把内核内容强制转型为ICoreModule接口对象，交给当前模式使用；
4. 每帧由EnterFrame事件驱动内核的tick()方法，画面直接写入一块BitmapData。

📌 核心结论：新增主机 = 新增一个实现ICoreModule的 SWF；新增玩法 = 新增一个继承Base的模式类。两者互不干扰，这正是 Nesbox 最优雅的设计。

二、编写新的主机内核：实现 ICoreModule 接口

1. 内核契约：ICoreModule 定义了哪些方法

内核与外壳之间的唯一契约就是 ICoreModule.as，它包含两部分：

模拟核心方法

• init(ntsc, rom, region)— 初始化模拟器，注入 ROM 数据
• tick(input, bitmapData)— 每帧调用，input是按键位掩码，画面写入bitmapData
• sound(data)— 向data中填充音频采样
• save() / load(data)— 导出/恢复状态（用于存档）
• muted属性 — 静音开关
• getWidth() / getHeight()— 返回画面尺寸，外壳据此设置舞台

手柄模块方法（继承自 IGamepadModule.as）

• getGamepadKeysNames()— 按键名列表（如 up、down、a、b、start…）
• getGamepadDefaultKeys()— 默认键盘映射
• getGamepadImage()/getGamepadButton(name)— 手柄 UI 素材
• getSettingsUid()— 设置项唯一标识

2. 内核是如何被驱动的 ⚡

你不需要自己写渲染循环。CorePlayerBase.as 已经封装好了：

• 画面：构造时按Variables.Width/Height创建BitmapData，tick()后直接作为 Bitmap 显示；
• 音频：监听SAMPLE_DATA事件，把采样数据转发给coreModule.sound()；
• 键盘：onKey(code)将按键码转成位掩码inputFlags，再传给tick()；
• 手柄：通过本地 Socket（127.0.0.1:8087）连接 Nesbox Companion 桌面程序，把手柄事件换算成同样的位掩码；
• 帧率：按 NTSC/PAL 自动设置stage.frameRate。

所以你的内核 SWF 只需专注模拟本身：把画面画进bitmapData，把声音填进sound(data)，把状态存进save()。

3. 部署与接线：三步完成新主机接入

以新增「PC Engine」主机为例：

1. 编译内核：将实现了ICoreModule的 ActionScript 3 代码编译为pce.swf；
2. 部署：把pce.swf放到与Nesbox.swf同级目录（即 GameData.init() 拼接baseUrl + '/' + module的位置）；
3. 嵌入页面传参：flashvars中写system: 'pce'，url指向 ROM 地址即可。

⚠️ 如果你还想支持「用户上传本地 ROM」流程，需要在 GameData.parseOwnRomName() 的Modules映射表中注册新扩展名：

const Modules:Object = { 'nes':'nes.swf', 'smc':'snes.swf', 'gen':'sega.swf', 'gb':'gb.swf', 'pce':'pce.swf' // ← 新增一行 };

同时把.pce加入 Nesbox.initOwnRomMode() 中的 ROM 文件过滤器，用户上传时才能选择到该格式。

三、新增一种游戏模式：从 Base 类出发

Nesbox 内置了五种模式，代码一一对应：

模式类	玩法	对应播放器
Single.as	单人游玩	CorePlayerSingle.as
Network.as	双人联网对战	CorePlayerNetwork.as
Walk.as	剧情解说模式	CorePlayerWalk.as
Contest.as	通关竞速	CorePlayerContest.as
OwnServer.as	自建服务器房间	CorePlayerOwnServer.as

新增一个模式（例如「四人合作模式」），标准步骤如下：

步骤 1：创建模式类mode/Coop.as

继承 Base.as。Base已为你处理了所有通用逻辑：

• 设置持久化（Settings.as）与后端 API（Api.as）
• 底部动作栏（Actions.as）的滑入滑出动画
• 全屏/交互全屏切换（FullscreenMessage.as）
• 快捷键热区：F2上传、F5读档、F8存档、F11全屏（定义在 Base.as 的HotkeyCode常量区）

在构造函数中组装三件套，参照 Single.as 的写法：

coop = new CorePlayerCoop(gameData.core, this); // 播放器 actions = new Actions(this, ActionsMode.Coop); // 动作栏 setup = SetupBuilder.Make(this, gameData); // 按键设置面板

然后覆写init()（把子对象 addChild 进来）和start()（调用coop.initSingleEmulation(...)启动模拟）。

步骤 2：创建播放器core/CorePlayerCoop.as

继承 CorePlayerBase.as，重点实现输入采集。最简单的单人玩法可以直接抄 CorePlayerSingle.as 的模式：监听ENTER_FRAME未暂停时执行emulate(inputFlags)，监听KEY_DOWN/KEY_UP调用onKey()。

如果是联网模式，还需实现 ICorePlayerHandler.as 的sendInput() / sendDummy()，把本地输入经 NetworkSession.as 与远端输入合并后再喂给内核。

步骤 3：注册路由，让入口认识新模式

模式选择与路由集中在 Nesbox.as，需要动三处：

1. 在 GameData.as 顶部常量区新增动作常量，如Coop = 'coop'；
2. 在onLoadRom()的switch(gameData.action)分支中新增case GameData.Coop: startCoopMode();；
3. 在selectMode()的菜单callbacks中加一项coop:startCoopMode，并补一行菜单文案。

最后在 ActionsMode.as 中为新模式定义动作按钮集（静音、存档、全屏等图标的排布），模式 UI 即完整可用。

四、扩展前的准备：工程与依赖清单 ✅

• 项目文件：Nesbox.as3proj 是 FlashDevelop 工程配置，添加新源文件时会自动纳入编译；
• 库依赖（位于 lib/）：
  • fzip.swc— ROM 为 zip 包时自动解压（见 GameData.loadRom()）；
  • as3corelib.swc— PNG 编码等工具，截图功能依赖它；
  • as3crypto.swc— 加密相关能力；
• 国际化：新文案需先在 Locale.as 声明属性，再在 en.json 提供英文值，其他语言包同名 JSON 会自动加载；
• JS 桥接：页面尺寸调整、登录弹窗等通过 JSProxy.as 与宿主页面通信，新增模式若需要页面级交互可在此扩展。

常见坑提示：内核 SWF 必须暴露ICoreModule公开接口，否则Loader加载后的强制转型会失败；画面宽高由内核的getWidth()/getHeight()决定，写死在 Variables.as 中供全屏计算使用，务必与实际分辨率一致。

五、关键文件速查表

扩展目标	先看这些文件
写新主机内核	ICoreModule.as、IGamepadModule.as、CorePlayerBase.as
内核接线/参数	GameData.as、Nesbox.as
写新游戏模式	Base.as、Single.as、CorePlayerSingle.as
模式路由与菜单	Nesbox.as 中onLoadRom()与selectMode()
UI 与动作栏	Actions.as、ActionsMode.as、Setup.as
存档与后端	Api.as、Settings.as

掌握「内核实现ICoreModule+ 模式继承Base」这两条主线，你就可以为 Nesbox 接入任何新主机、创造任何新玩法——这正是这套 Flash 时代插件化架构留给今天的最大价值。

【免费下载链接】emulatorEmulator of NES, Super Nintendo, Sega Mega Drive, GameBoy video consoles项目地址: https://gitcode.com/gh_mirrors/em/emulator