fcdev 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (294) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +82 -2
  3. package/bin/fcdev.mjs +17 -0
  4. package/package.json +38 -4
  5. package/src/api/header-parser.mjs +78 -0
  6. package/src/api/index.mjs +128 -0
  7. package/src/build/bank-link-config.mjs +74 -0
  8. package/src/build/build-plan.mjs +92 -0
  9. package/src/build/dependency-file.mjs +24 -0
  10. package/src/build/disk-builder.mjs +36 -0
  11. package/src/build/index.mjs +32 -0
  12. package/src/build/program-builder.mjs +212 -0
  13. package/src/build/source-collector.mjs +54 -0
  14. package/src/build/tool-arguments.mjs +83 -0
  15. package/src/cli/args-parser.mjs +84 -0
  16. package/src/cli/commands/api-command.mjs +62 -0
  17. package/src/cli/commands/build-command.mjs +34 -0
  18. package/src/cli/commands/debug-command.mjs +70 -0
  19. package/src/cli/commands/disasm-command.mjs +65 -0
  20. package/src/cli/commands/disk-command.mjs +34 -0
  21. package/src/cli/commands/info-command.mjs +33 -0
  22. package/src/cli/commands/project-info.mjs +57 -0
  23. package/src/cli/commands/run-command.mjs +68 -0
  24. package/src/cli/commands/sync-command.mjs +85 -0
  25. package/src/cli/index.mjs +103 -0
  26. package/src/config/config-loader.mjs +132 -0
  27. package/src/config/index.mjs +9 -0
  28. package/src/disasm/analysis.mjs +97 -0
  29. package/src/disasm/cdl.mjs +35 -0
  30. package/src/disasm/disassembler.mjs +114 -0
  31. package/src/disasm/index.mjs +16 -0
  32. package/src/disasm/info-writer.mjs +72 -0
  33. package/src/disasm/loaders.mjs +69 -0
  34. package/src/disasm/opcode-table.mjs +268 -0
  35. package/src/disasm/roundtrip.mjs +69 -0
  36. package/src/disasm/symbols.mjs +30 -0
  37. package/src/disasm/trace.mjs +25 -0
  38. package/src/emulator/debug-client.mjs +125 -0
  39. package/src/emulator/emulator-launcher.mjs +80 -0
  40. package/src/emulator/emulator-locator.mjs +62 -0
  41. package/src/emulator/index.mjs +11 -0
  42. package/src/packagers/fat-floppy.mjs +22 -0
  43. package/src/packagers/fat12-image.mjs +245 -0
  44. package/src/packagers/flat-binary.mjs +53 -0
  45. package/src/packagers/index.mjs +54 -0
  46. package/src/packagers/ines.mjs +38 -0
  47. package/src/shared/errors.mjs +25 -0
  48. package/src/shared/fs-utils.mjs +66 -0
  49. package/src/shared/index.mjs +11 -0
  50. package/src/shared/process.mjs +50 -0
  51. package/src/targets/index.mjs +17 -0
  52. package/src/targets/name-rules.mjs +33 -0
  53. package/src/targets/target-registry.mjs +225 -0
  54. package/src/toolchain/index.mjs +16 -0
  55. package/src/toolchain/toolchain-locator.mjs +104 -0
  56. package/targets/nes/asminc/fcnes.inc +16 -0
  57. package/targets/nes/chr/ascii-8x8.chr +0 -0
  58. package/targets/nes/chr/font8x8_basic.h +152 -0
  59. package/targets/nes/include/fcnes.h +45 -0
  60. package/targets/nes/lib/fcnes.lib +0 -0
  61. package/targets/nes/lib/nes-font.o +0 -0
  62. package/targets/nes/lib-build.json +9 -0
  63. package/targets/nes/src/fcnes.s +91 -0
  64. package/targets/nes/src/nes-font.s +12 -0
  65. package/targets/nes/target.json +27 -0
  66. package/targets/sb2000/api-reference.md +3295 -0
  67. package/targets/sb2000/api-unwrapped.json +36 -0
  68. package/targets/sb2000/asminc/sb2000.inc +418 -0
  69. package/targets/sb2000/include/sb2000-bank.h +74 -0
  70. package/targets/sb2000/include/sb2000-clock.h +68 -0
  71. package/targets/sb2000/include/sb2000-disk.h +141 -0
  72. package/targets/sb2000/include/sb2000-display.h +352 -0
  73. package/targets/sb2000/include/sb2000-file.h +273 -0
  74. package/targets/sb2000/include/sb2000-ime.h +158 -0
  75. package/targets/sb2000/include/sb2000-input.h +192 -0
  76. package/targets/sb2000/include/sb2000-math.h +228 -0
  77. package/targets/sb2000/include/sb2000-memory.h +115 -0
  78. package/targets/sb2000/include/sb2000-printer.h +116 -0
  79. package/targets/sb2000/include/sb2000-sound.h +134 -0
  80. package/targets/sb2000/include/sb2000-symbols.h +776 -0
  81. package/targets/sb2000/include/sb2000-system.h +219 -0
  82. package/targets/sb2000/include/sb2000-text.h +99 -0
  83. package/targets/sb2000/include/sb2000.h +45 -0
  84. package/targets/sb2000/lib/crt0.o +0 -0
  85. package/targets/sb2000/lib/sb2000.lib +0 -0
  86. package/targets/sb2000/lib-build.json +8 -0
  87. package/targets/sb2000/link-banked.cfg +42 -0
  88. package/targets/sb2000/link.cfg +35 -0
  89. package/targets/sb2000/src/crt0.s +122 -0
  90. package/targets/sb2000/src/lib/bank/sb-bank-current.c +18 -0
  91. package/targets/sb2000/src/lib/bank/sb-bank-select.c +21 -0
  92. package/targets/sb2000/src/lib/bank/sbi-bank-trampoline.s +46 -0
  93. package/targets/sb2000/src/lib/clock/sb-clock-get-date.c +17 -0
  94. package/targets/sb2000/src/lib/clock/sb-clock-get-time.c +17 -0
  95. package/targets/sb2000/src/lib/clock/sb-clock-set-date.c +21 -0
  96. package/targets/sb2000/src/lib/clock/sb-clock-set-time.c +17 -0
  97. package/targets/sb2000/src/lib/clock/sbi-date-from-fat.c +20 -0
  98. package/targets/sb2000/src/lib/clock/sbi-date-to-fat.c +24 -0
  99. package/targets/sb2000/src/lib/clock/sbi-time-from-fat.c +20 -0
  100. package/targets/sb2000/src/lib/clock/sbi-time-to-fat.c +19 -0
  101. package/targets/sb2000/src/lib/disk/sb-disk-format-track.c +18 -0
  102. package/targets/sb2000/src/lib/disk/sb-disk-free-bytes.c +38 -0
  103. package/targets/sb2000/src/lib/disk/sb-disk-init.c +16 -0
  104. package/targets/sb2000/src/lib/disk/sb-disk-read-sector.c +24 -0
  105. package/targets/sb2000/src/lib/disk/sb-disk-read-sectors.c +17 -0
  106. package/targets/sb2000/src/lib/disk/sb-disk-scan-track.c +27 -0
  107. package/targets/sb2000/src/lib/disk/sb-disk-start.c +16 -0
  108. package/targets/sb2000/src/lib/disk/sb-disk-stop.c +16 -0
  109. package/targets/sb2000/src/lib/disk/sb-disk-write-sector.c +19 -0
  110. package/targets/sb2000/src/lib/disk/sb-disk-write-sectors.c +17 -0
  111. package/targets/sb2000/src/lib/disk/sbi-disk-batch.c +23 -0
  112. package/targets/sb2000/src/lib/disk/sbi-disk-call.c +17 -0
  113. package/targets/sb2000/src/lib/disk/sbi-disk-set-position.c +18 -0
  114. package/targets/sb2000/src/lib/display/sb-cell-address.c +20 -0
  115. package/targets/sb2000/src/lib/display/sb-cells-copy.c +27 -0
  116. package/targets/sb2000/src/lib/display/sb-cells-fill.c +25 -0
  117. package/targets/sb2000/src/lib/display/sb-cells-rect.c +20 -0
  118. package/targets/sb2000/src/lib/display/sb-display-mode.c +16 -0
  119. package/targets/sb2000/src/lib/display/sb-glyph-address.c +28 -0
  120. package/targets/sb2000/src/lib/display/sb-image-fill-rect.c +26 -0
  121. package/targets/sb2000/src/lib/display/sb-image-load-raw.c +22 -0
  122. package/targets/sb2000/src/lib/display/sb-image-show-full.c +20 -0
  123. package/targets/sb2000/src/lib/display/sb-image-show.c +25 -0
  124. package/targets/sb2000/src/lib/display/sb-image-unpack-map.c +28 -0
  125. package/targets/sb2000/src/lib/display/sb-image-unpack-tiles.c +20 -0
  126. package/targets/sb2000/src/lib/display/sb-image-unpack-to-memory.c +22 -0
  127. package/targets/sb2000/src/lib/display/sb-palette-write.c +20 -0
  128. package/targets/sb2000/src/lib/display/sb-screen-clear.c +19 -0
  129. package/targets/sb2000/src/lib/display/sb-screen-flush.c +16 -0
  130. package/targets/sb2000/src/lib/display/sb-text-draw.c +22 -0
  131. package/targets/sb2000/src/lib/display/sb-text-field-ascii.c +25 -0
  132. package/targets/sb2000/src/lib/display/sb-text-field.c +25 -0
  133. package/targets/sb2000/src/lib/display/sb-text-to-memory.c +27 -0
  134. package/targets/sb2000/src/lib/display/sb-vram-bank.c +17 -0
  135. package/targets/sb2000/src/lib/display/sb-vram-fill.c +21 -0
  136. package/targets/sb2000/src/lib/display/sb-vram-load.c +21 -0
  137. package/targets/sb2000/src/lib/display/sb-window-compact.c +16 -0
  138. package/targets/sb2000/src/lib/display/sb-window-init.c +16 -0
  139. package/targets/sb2000/src/lib/display/sb-window-restore.c +17 -0
  140. package/targets/sb2000/src/lib/display/sb-window-save.c +21 -0
  141. package/targets/sb2000/src/lib/file/sb-dir-change.c +21 -0
  142. package/targets/sb2000/src/lib/file/sb-dir-current.c +27 -0
  143. package/targets/sb2000/src/lib/file/sb-dir-make.c +21 -0
  144. package/targets/sb2000/src/lib/file/sb-dir-open.c +61 -0
  145. package/targets/sb2000/src/lib/file/sb-dir-read.c +87 -0
  146. package/targets/sb2000/src/lib/file/sb-dir-remove.c +21 -0
  147. package/targets/sb2000/src/lib/file/sb-file-close.c +21 -0
  148. package/targets/sb2000/src/lib/file/sb-file-delete.c +21 -0
  149. package/targets/sb2000/src/lib/file/sb-file-get-attr.c +25 -0
  150. package/targets/sb2000/src/lib/file/sb-file-get-date.c +25 -0
  151. package/targets/sb2000/src/lib/file/sb-file-get-time.c +25 -0
  152. package/targets/sb2000/src/lib/file/sb-file-load.c +50 -0
  153. package/targets/sb2000/src/lib/file/sb-file-open.c +26 -0
  154. package/targets/sb2000/src/lib/file/sb-file-read.c +52 -0
  155. package/targets/sb2000/src/lib/file/sb-file-rename.c +30 -0
  156. package/targets/sb2000/src/lib/file/sb-file-save.c +31 -0
  157. package/targets/sb2000/src/lib/file/sb-file-set-attr.c +22 -0
  158. package/targets/sb2000/src/lib/file/sb-file-set-date.c +25 -0
  159. package/targets/sb2000/src/lib/file/sb-file-set-time.c +22 -0
  160. package/targets/sb2000/src/lib/file/sb-file-size.c +27 -0
  161. package/targets/sb2000/src/lib/file/sb-file-write-all.c +32 -0
  162. package/targets/sb2000/src/lib/file/sb-file-write.c +60 -0
  163. package/targets/sb2000/src/lib/file/sbi-dir-state.c +15 -0
  164. package/targets/sb2000/src/lib/file/sbi-dos-call.c +17 -0
  165. package/targets/sb2000/src/lib/file/sbi-load-sector.c +18 -0
  166. package/targets/sb2000/src/lib/file/sbi-select-handle.c +20 -0
  167. package/targets/sb2000/src/lib/file/sbi-set-path.c +26 -0
  168. package/targets/sb2000/src/lib/ime/sb-ime-get-method.c +17 -0
  169. package/targets/sb2000/src/lib/ime/sb-ime-get-state.c +18 -0
  170. package/targets/sb2000/src/lib/ime/sb-ime-hex.c +20 -0
  171. package/targets/sb2000/src/lib/ime/sb-ime-init.c +26 -0
  172. package/targets/sb2000/src/lib/ime/sb-ime-key-wait.c +19 -0
  173. package/targets/sb2000/src/lib/ime/sb-ime-key.c +19 -0
  174. package/targets/sb2000/src/lib/ime/sb-ime-parse.c +23 -0
  175. package/targets/sb2000/src/lib/ime/sb-ime-resume.c +16 -0
  176. package/targets/sb2000/src/lib/ime/sb-ime-select.c +19 -0
  177. package/targets/sb2000/src/lib/ime/sb-ime-set-state.c +18 -0
  178. package/targets/sb2000/src/lib/ime/sb-ime-set-width.c +16 -0
  179. package/targets/sb2000/src/lib/ime/sb-ime-suspend.c +16 -0
  180. package/targets/sb2000/src/lib/input/sb-break-disable.c +16 -0
  181. package/targets/sb2000/src/lib/input/sb-break-enable.c +16 -0
  182. package/targets/sb2000/src/lib/input/sb-key-count.c +17 -0
  183. package/targets/sb2000/src/lib/input/sb-key-flush.c +16 -0
  184. package/targets/sb2000/src/lib/input/sb-key-init.c +16 -0
  185. package/targets/sb2000/src/lib/input/sb-key-modifiers.c +16 -0
  186. package/targets/sb2000/src/lib/input/sb-key-poll.c +17 -0
  187. package/targets/sb2000/src/lib/input/sb-key-wait.c +17 -0
  188. package/targets/sb2000/src/lib/input/sb-keyboard-reset.c +17 -0
  189. package/targets/sb2000/src/lib/input/sb-mouse-buttons.c +21 -0
  190. package/targets/sb2000/src/lib/input/sb-mouse-position.c +18 -0
  191. package/targets/sb2000/src/lib/input/sb-mouse-reset.c +17 -0
  192. package/targets/sb2000/src/lib/input/sb-mouse-set-double-click.c +17 -0
  193. package/targets/sb2000/src/lib/input/sb-mouse-set-limits.c +26 -0
  194. package/targets/sb2000/src/lib/input/sb-mouse-set-position.c +18 -0
  195. package/targets/sb2000/src/lib/input/sb-pad-init.c +17 -0
  196. package/targets/sb2000/src/lib/input/sb-pad-poll.c +17 -0
  197. package/targets/sb2000/src/lib/input/sb-pad-state.c +16 -0
  198. package/targets/sb2000/src/lib/input/sb-pad-wait.c +17 -0
  199. package/targets/sb2000/src/lib/math/sb-float-add.c +19 -0
  200. package/targets/sb2000/src/lib/math/sb-float-div.c +19 -0
  201. package/targets/sb2000/src/lib/math/sb-float-from-text.c +18 -0
  202. package/targets/sb2000/src/lib/math/sb-float-mul.c +19 -0
  203. package/targets/sb2000/src/lib/math/sb-float-sub.c +19 -0
  204. package/targets/sb2000/src/lib/math/sb-float-to-text.c +19 -0
  205. package/targets/sb2000/src/lib/math/sb-int24-add.c +21 -0
  206. package/targets/sb2000/src/lib/math/sb-int24-div.c +26 -0
  207. package/targets/sb2000/src/lib/math/sb-int24-mul.c +20 -0
  208. package/targets/sb2000/src/lib/math/sb-int24-sub.c +21 -0
  209. package/targets/sb2000/src/lib/math/sb-int40-from-text.c +19 -0
  210. package/targets/sb2000/src/lib/math/sb-int40-to-text.c +27 -0
  211. package/targets/sb2000/src/lib/math/sb-line-step.c +21 -0
  212. package/targets/sb2000/src/lib/math/sb-math-div16.c +27 -0
  213. package/targets/sb2000/src/lib/math/sb-math-time-text.c +21 -0
  214. package/targets/sb2000/src/lib/math/sb-random-next.c +20 -0
  215. package/targets/sb2000/src/lib/math/sb-random-seed.c +19 -0
  216. package/targets/sb2000/src/lib/math/sb-random-warm-up.c +16 -0
  217. package/targets/sb2000/src/lib/math/sbi-peek.c +20 -0
  218. package/targets/sb2000/src/lib/math/sbi-poke.c +20 -0
  219. package/targets/sb2000/src/lib/memory/sb-address-to-far.c +20 -0
  220. package/targets/sb2000/src/lib/memory/sb-far-read-byte.c +17 -0
  221. package/targets/sb2000/src/lib/memory/sb-far-read.c +36 -0
  222. package/targets/sb2000/src/lib/memory/sb-far-write-byte.c +17 -0
  223. package/targets/sb2000/src/lib/memory/sb-far-write.c +36 -0
  224. package/targets/sb2000/src/lib/memory/sb-page-alloc.c +19 -0
  225. package/targets/sb2000/src/lib/memory/sb-page-free.c +19 -0
  226. package/targets/sb2000/src/lib/memory/sb-page-largest-free.c +17 -0
  227. package/targets/sb2000/src/lib/memory/sb-window-map-group.c +17 -0
  228. package/targets/sb2000/src/lib/memory/sb-window-map.c +18 -0
  229. package/targets/sb2000/src/lib/memory/sbi-far-copy-in.s +17 -0
  230. package/targets/sb2000/src/lib/memory/sbi-far-copy-out.s +17 -0
  231. package/targets/sb2000/src/lib/memory/sbi-far-read-byte.s +19 -0
  232. package/targets/sb2000/src/lib/memory/sbi-far-write-byte.s +17 -0
  233. package/targets/sb2000/src/lib/printer/sb-printer-carriage-return.c +16 -0
  234. package/targets/sb2000/src/lib/printer/sb-printer-feed.c +17 -0
  235. package/targets/sb2000/src/lib/printer/sb-printer-graphics-mode.c +16 -0
  236. package/targets/sb2000/src/lib/printer/sb-printer-home.c +16 -0
  237. package/targets/sb2000/src/lib/printer/sb-printer-init-port.c +16 -0
  238. package/targets/sb2000/src/lib/printer/sb-printer-page-left.c +16 -0
  239. package/targets/sb2000/src/lib/printer/sb-printer-page-length.c +17 -0
  240. package/targets/sb2000/src/lib/printer/sb-printer-position.c +18 -0
  241. package/targets/sb2000/src/lib/printer/sb-printer-reset.c +16 -0
  242. package/targets/sb2000/src/lib/printer/sb-printer-send-byte.c +18 -0
  243. package/targets/sb2000/src/lib/printer/sb-printer-text.c +29 -0
  244. package/targets/sb2000/src/lib/sb-internal.h +111 -0
  245. package/targets/sb2000/src/lib/sound/sb-sound-effect-from.c +19 -0
  246. package/targets/sb2000/src/lib/sound/sb-sound-play-from.c +18 -0
  247. package/targets/sb2000/src/lib/sound/sb-sound-play-wav-from.c +18 -0
  248. package/targets/sb2000/src/lib/sound/sb-sound-play-wav.c +16 -0
  249. package/targets/sb2000/src/lib/sound/sb-sound-repeat-wav-from.c +19 -0
  250. package/targets/sb2000/src/lib/sound/sb-sound-status.c +17 -0
  251. package/targets/sb2000/src/lib/sound/sb-sound-stop.c +16 -0
  252. package/targets/sb2000/src/lib/sound/sb-sound-tempo.c +17 -0
  253. package/targets/sb2000/src/lib/sound/sb-sound-transpose.c +17 -0
  254. package/targets/sb2000/src/lib/sound/sb-speech-off.c +16 -0
  255. package/targets/sb2000/src/lib/sound/sb-speech-send-entry-from.c +21 -0
  256. package/targets/sb2000/src/lib/sound/sb-speech-send-from.c +19 -0
  257. package/targets/sb2000/src/lib/sound/sb-speech-send.c +16 -0
  258. package/targets/sb2000/src/lib/system/sb-call-banked.c +19 -0
  259. package/targets/sb2000/src/lib/system/sb-context-restore.c +16 -0
  260. package/targets/sb2000/src/lib/system/sb-context-save.c +19 -0
  261. package/targets/sb2000/src/lib/system/sb-display-off.c +16 -0
  262. package/targets/sb2000/src/lib/system/sb-display-on.c +16 -0
  263. package/targets/sb2000/src/lib/system/sb-display-option.c +18 -0
  264. package/targets/sb2000/src/lib/system/sb-exec.c +22 -0
  265. package/targets/sb2000/src/lib/system/sb-irq-enable.c +19 -0
  266. package/targets/sb2000/src/lib/system/sb-irq-hook-reset.c +20 -0
  267. package/targets/sb2000/src/lib/system/sb-irq-hook-set.c +39 -0
  268. package/targets/sb2000/src/lib/system/sb-irq-mask.c +19 -0
  269. package/targets/sb2000/src/lib/system/sb-jump-banked.s +25 -0
  270. package/targets/sb2000/src/lib/system/sb-nmi-disable.c +16 -0
  271. package/targets/sb2000/src/lib/system/sb-nmi-enable.c +16 -0
  272. package/targets/sb2000/src/lib/system/sb-nmi-hook-reset.c +20 -0
  273. package/targets/sb2000/src/lib/system/sb-nmi-hook-set.c +33 -0
  274. package/targets/sb2000/src/lib/system/sb-nmi-service.c +19 -0
  275. package/targets/sb2000/src/lib/system/sb-stack-pointer.s +18 -0
  276. package/targets/sb2000/src/lib/system/sb-system-init.c +16 -0
  277. package/targets/sb2000/src/lib/system/sb-system-state.c +20 -0
  278. package/targets/sb2000/src/lib/system/sb-wait-frames.s +19 -0
  279. package/targets/sb2000/src/lib/system/sbi-exec-run.s +43 -0
  280. package/targets/sb2000/src/lib/system/sbi-interrupts-off.s +19 -0
  281. package/targets/sb2000/src/lib/system/sbi-interrupts-restore.s +17 -0
  282. package/targets/sb2000/src/lib/text/sb-beep.c +16 -0
  283. package/targets/sb2000/src/lib/text/sb-cursor-column.c +16 -0
  284. package/targets/sb2000/src/lib/text/sb-cursor-left.c +16 -0
  285. package/targets/sb2000/src/lib/text/sb-cursor-right.c +16 -0
  286. package/targets/sb2000/src/lib/text/sb-cursor-row.c +16 -0
  287. package/targets/sb2000/src/lib/text/sb-cursor-set-column.c +18 -0
  288. package/targets/sb2000/src/lib/text/sb-cursor-up.c +16 -0
  289. package/targets/sb2000/src/lib/text/sb-print-hex.c +22 -0
  290. package/targets/sb2000/src/lib/text/sb-print-uint.c +25 -0
  291. package/targets/sb2000/src/lib/text/sb-print.c +35 -0
  292. package/targets/sb2000/src/lib/text/sb-putc.c +26 -0
  293. package/targets/sb2000/src/sb2000.s +64 -0
  294. package/targets/sb2000/target.json +42 -0
@@ -0,0 +1,268 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:opcode-table.mjs
3
+ // 说明:6502 官方指令表:每个操作码的助记符、字节数与流程类别,非法操作码为 null。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:数据取自 cc65 的 da65 指令表(cc65/src/da65/opc6502.c);流程类别由助记符推出。
8
+ // ------------------------------------------------------------------------
9
+
10
+ /** 流程类别:next 顺序执行;branch 条件分支;jump 绝对跳转;jump-indirect 间接跳转;call 子程序调用;return 返回;stop 中断指令 */
11
+ export const OPCODES = [
12
+ ['brk', 1, 'stop'], // $00
13
+ ['ora', 2, 'next'], // $01
14
+ null, // $02
15
+ null, // $03
16
+ null, // $04
17
+ ['ora', 2, 'next'], // $05
18
+ ['asl', 2, 'next'], // $06
19
+ null, // $07
20
+ ['php', 1, 'next'], // $08
21
+ ['ora', 2, 'next'], // $09
22
+ ['asl', 1, 'next'], // $0a
23
+ null, // $0b
24
+ null, // $0c
25
+ ['ora', 3, 'next'], // $0d
26
+ ['asl', 3, 'next'], // $0e
27
+ null, // $0f
28
+ ['bpl', 2, 'branch'], // $10
29
+ ['ora', 2, 'next'], // $11
30
+ null, // $12
31
+ null, // $13
32
+ null, // $14
33
+ ['ora', 2, 'next'], // $15
34
+ ['asl', 2, 'next'], // $16
35
+ null, // $17
36
+ ['clc', 1, 'next'], // $18
37
+ ['ora', 3, 'next'], // $19
38
+ null, // $1a
39
+ null, // $1b
40
+ null, // $1c
41
+ ['ora', 3, 'next'], // $1d
42
+ ['asl', 3, 'next'], // $1e
43
+ null, // $1f
44
+ ['jsr', 3, 'call'], // $20
45
+ ['and', 2, 'next'], // $21
46
+ null, // $22
47
+ null, // $23
48
+ ['bit', 2, 'next'], // $24
49
+ ['and', 2, 'next'], // $25
50
+ ['rol', 2, 'next'], // $26
51
+ null, // $27
52
+ ['plp', 1, 'next'], // $28
53
+ ['and', 2, 'next'], // $29
54
+ ['rol', 1, 'next'], // $2a
55
+ null, // $2b
56
+ ['bit', 3, 'next'], // $2c
57
+ ['and', 3, 'next'], // $2d
58
+ ['rol', 3, 'next'], // $2e
59
+ null, // $2f
60
+ ['bmi', 2, 'branch'], // $30
61
+ ['and', 2, 'next'], // $31
62
+ null, // $32
63
+ null, // $33
64
+ null, // $34
65
+ ['and', 2, 'next'], // $35
66
+ ['rol', 2, 'next'], // $36
67
+ null, // $37
68
+ ['sec', 1, 'next'], // $38
69
+ ['and', 3, 'next'], // $39
70
+ null, // $3a
71
+ null, // $3b
72
+ null, // $3c
73
+ ['and', 3, 'next'], // $3d
74
+ ['rol', 3, 'next'], // $3e
75
+ null, // $3f
76
+ ['rti', 1, 'return'], // $40
77
+ ['eor', 2, 'next'], // $41
78
+ null, // $42
79
+ null, // $43
80
+ null, // $44
81
+ ['eor', 2, 'next'], // $45
82
+ ['lsr', 2, 'next'], // $46
83
+ null, // $47
84
+ ['pha', 1, 'next'], // $48
85
+ ['eor', 2, 'next'], // $49
86
+ ['lsr', 1, 'next'], // $4a
87
+ null, // $4b
88
+ ['jmp', 3, 'jump'], // $4c
89
+ ['eor', 3, 'next'], // $4d
90
+ ['lsr', 3, 'next'], // $4e
91
+ null, // $4f
92
+ ['bvc', 2, 'branch'], // $50
93
+ ['eor', 2, 'next'], // $51
94
+ null, // $52
95
+ null, // $53
96
+ null, // $54
97
+ ['eor', 2, 'next'], // $55
98
+ ['lsr', 2, 'next'], // $56
99
+ null, // $57
100
+ ['cli', 1, 'next'], // $58
101
+ ['eor', 3, 'next'], // $59
102
+ null, // $5a
103
+ null, // $5b
104
+ null, // $5c
105
+ ['eor', 3, 'next'], // $5d
106
+ ['lsr', 3, 'next'], // $5e
107
+ null, // $5f
108
+ ['rts', 1, 'return'], // $60
109
+ ['adc', 2, 'next'], // $61
110
+ null, // $62
111
+ null, // $63
112
+ null, // $64
113
+ ['adc', 2, 'next'], // $65
114
+ ['ror', 2, 'next'], // $66
115
+ null, // $67
116
+ ['pla', 1, 'next'], // $68
117
+ ['adc', 2, 'next'], // $69
118
+ ['ror', 1, 'next'], // $6a
119
+ null, // $6b
120
+ ['jmp', 3, 'jump-indirect'], // $6c
121
+ ['adc', 3, 'next'], // $6d
122
+ ['ror', 3, 'next'], // $6e
123
+ null, // $6f
124
+ ['bvs', 2, 'branch'], // $70
125
+ ['adc', 2, 'next'], // $71
126
+ null, // $72
127
+ null, // $73
128
+ null, // $74
129
+ ['adc', 2, 'next'], // $75
130
+ ['ror', 2, 'next'], // $76
131
+ null, // $77
132
+ ['sei', 1, 'next'], // $78
133
+ ['adc', 3, 'next'], // $79
134
+ null, // $7a
135
+ null, // $7b
136
+ null, // $7c
137
+ ['adc', 3, 'next'], // $7d
138
+ ['ror', 3, 'next'], // $7e
139
+ null, // $7f
140
+ null, // $80
141
+ ['sta', 2, 'next'], // $81
142
+ null, // $82
143
+ null, // $83
144
+ ['sty', 2, 'next'], // $84
145
+ ['sta', 2, 'next'], // $85
146
+ ['stx', 2, 'next'], // $86
147
+ null, // $87
148
+ ['dey', 1, 'next'], // $88
149
+ null, // $89
150
+ ['txa', 1, 'next'], // $8a
151
+ null, // $8b
152
+ ['sty', 3, 'next'], // $8c
153
+ ['sta', 3, 'next'], // $8d
154
+ ['stx', 3, 'next'], // $8e
155
+ null, // $8f
156
+ ['bcc', 2, 'branch'], // $90
157
+ ['sta', 2, 'next'], // $91
158
+ null, // $92
159
+ null, // $93
160
+ ['sty', 2, 'next'], // $94
161
+ ['sta', 2, 'next'], // $95
162
+ ['stx', 2, 'next'], // $96
163
+ null, // $97
164
+ ['tya', 1, 'next'], // $98
165
+ ['sta', 3, 'next'], // $99
166
+ ['txs', 1, 'next'], // $9a
167
+ null, // $9b
168
+ null, // $9c
169
+ ['sta', 3, 'next'], // $9d
170
+ null, // $9e
171
+ null, // $9f
172
+ ['ldy', 2, 'next'], // $a0
173
+ ['lda', 2, 'next'], // $a1
174
+ ['ldx', 2, 'next'], // $a2
175
+ null, // $a3
176
+ ['ldy', 2, 'next'], // $a4
177
+ ['lda', 2, 'next'], // $a5
178
+ ['ldx', 2, 'next'], // $a6
179
+ null, // $a7
180
+ ['tay', 1, 'next'], // $a8
181
+ ['lda', 2, 'next'], // $a9
182
+ ['tax', 1, 'next'], // $aa
183
+ null, // $ab
184
+ ['ldy', 3, 'next'], // $ac
185
+ ['lda', 3, 'next'], // $ad
186
+ ['ldx', 3, 'next'], // $ae
187
+ null, // $af
188
+ ['bcs', 2, 'branch'], // $b0
189
+ ['lda', 2, 'next'], // $b1
190
+ null, // $b2
191
+ null, // $b3
192
+ ['ldy', 2, 'next'], // $b4
193
+ ['lda', 2, 'next'], // $b5
194
+ ['ldx', 2, 'next'], // $b6
195
+ null, // $b7
196
+ ['clv', 1, 'next'], // $b8
197
+ ['lda', 3, 'next'], // $b9
198
+ ['tsx', 1, 'next'], // $ba
199
+ null, // $bb
200
+ ['ldy', 3, 'next'], // $bc
201
+ ['lda', 3, 'next'], // $bd
202
+ ['ldx', 3, 'next'], // $be
203
+ null, // $bf
204
+ ['cpy', 2, 'next'], // $c0
205
+ ['cmp', 2, 'next'], // $c1
206
+ null, // $c2
207
+ null, // $c3
208
+ ['cpy', 2, 'next'], // $c4
209
+ ['cmp', 2, 'next'], // $c5
210
+ ['dec', 2, 'next'], // $c6
211
+ null, // $c7
212
+ ['iny', 1, 'next'], // $c8
213
+ ['cmp', 2, 'next'], // $c9
214
+ ['dex', 1, 'next'], // $ca
215
+ null, // $cb
216
+ ['cpy', 3, 'next'], // $cc
217
+ ['cmp', 3, 'next'], // $cd
218
+ ['dec', 3, 'next'], // $ce
219
+ null, // $cf
220
+ ['bne', 2, 'branch'], // $d0
221
+ ['cmp', 2, 'next'], // $d1
222
+ null, // $d2
223
+ null, // $d3
224
+ null, // $d4
225
+ ['cmp', 2, 'next'], // $d5
226
+ ['dec', 2, 'next'], // $d6
227
+ null, // $d7
228
+ ['cld', 1, 'next'], // $d8
229
+ ['cmp', 3, 'next'], // $d9
230
+ null, // $da
231
+ null, // $db
232
+ null, // $dc
233
+ ['cmp', 3, 'next'], // $dd
234
+ ['dec', 3, 'next'], // $de
235
+ null, // $df
236
+ ['cpx', 2, 'next'], // $e0
237
+ ['sbc', 2, 'next'], // $e1
238
+ null, // $e2
239
+ null, // $e3
240
+ ['cpx', 2, 'next'], // $e4
241
+ ['sbc', 2, 'next'], // $e5
242
+ ['inc', 2, 'next'], // $e6
243
+ null, // $e7
244
+ ['inx', 1, 'next'], // $e8
245
+ ['sbc', 2, 'next'], // $e9
246
+ ['nop', 1, 'next'], // $ea
247
+ null, // $eb
248
+ ['cpx', 3, 'next'], // $ec
249
+ ['sbc', 3, 'next'], // $ed
250
+ ['inc', 3, 'next'], // $ee
251
+ null, // $ef
252
+ ['beq', 2, 'branch'], // $f0
253
+ ['sbc', 2, 'next'], // $f1
254
+ null, // $f2
255
+ null, // $f3
256
+ null, // $f4
257
+ ['sbc', 2, 'next'], // $f5
258
+ ['inc', 2, 'next'], // $f6
259
+ null, // $f7
260
+ ['sed', 1, 'next'], // $f8
261
+ ['sbc', 3, 'next'], // $f9
262
+ null, // $fa
263
+ null, // $fb
264
+ null, // $fc
265
+ ['sbc', 3, 'next'], // $fd
266
+ ['inc', 3, 'next'], // $fe
267
+ null, // $ff
268
+ ];
@@ -0,0 +1,69 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:roundtrip.mjs
3
+ // 说明:回读校验:把反汇编出的 ca65 源码重新汇编、链接,与原映像逐字节比较。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:链接配置只放一个从映像起始地址开始、大小恰好等于映像的内存区与一个 CODE 段;不一致时报告第一个不同的偏移与地址。
8
+ // ------------------------------------------------------------------------
9
+ import { readFileSync, writeFileSync } from 'node:fs';
10
+ import path from 'node:path';
11
+ import { FcdevError } from '../shared/index.mjs';
12
+ import { runTool } from '../toolchain/index.mjs';
13
+
14
+ /**
15
+ * 生成回读用的链接配置。
16
+ * @param {number} base 起始地址
17
+ * @param {number} size 映像大小
18
+ * @returns {string} ld65 配置内容
19
+ */
20
+ export function renderRoundtripConfig(base, size) {
21
+ return `MEMORY { ROM: file = %O, start = $${base.toString(16).toUpperCase()}, size = $${size.toString(16).toUpperCase()}; }
22
+ SEGMENTS { CODE: load = ROM, type = ro; }
23
+ `;
24
+ }
25
+
26
+ /**
27
+ * 找出两段字节的第一个差异。
28
+ * @param {Buffer} expected 原映像
29
+ * @param {Buffer} actual 回读得到的映像
30
+ * @returns {number} 第一个不同的偏移;完全相同时为 -1
31
+ */
32
+ export function findFirstDifference(expected, actual) {
33
+ const common = Math.min(expected.length, actual.length);
34
+ for (let offset = 0; offset < common; offset += 1) {
35
+ if (expected[offset] !== actual[offset]) return offset;
36
+ }
37
+ return expected.length === actual.length ? -1 : common;
38
+ }
39
+
40
+ /**
41
+ * 运行一个工具,失败时抛出带输出的错误。
42
+ * @param {import('../toolchain/index.mjs').Toolchain} toolchain 工具链
43
+ * @param {string} tool 工具名
44
+ * @param {string[]} args 参数
45
+ * @param {string} failure 失败说明
46
+ * @returns {Promise<void>}
47
+ * @throws {FcdevError} 工具退出码非零
48
+ */
49
+ async function runOrThrow(toolchain, tool, args, failure) {
50
+ const result = await runTool(toolchain, tool, args);
51
+ if (result.code !== 0) throw new FcdevError(failure, { code: 'DISASM_ROUNDTRIP_FAILED', hint: `${result.stdout}${result.stderr}`.trim() });
52
+ }
53
+
54
+ /**
55
+ * 重新汇编反汇编出的源码并与原映像比较。
56
+ * @param {{toolchain: import('../toolchain/index.mjs').Toolchain, sourceFile: string, expected: Buffer, base: number, workDir: string, name: string}} input 工具链、源码、原映像、起始地址、工作目录与文件名前缀
57
+ * @returns {Promise<{ok: boolean, firstDifference: number}>} 是否一致,以及第一个不同的偏移(一致时为 -1)
58
+ * @throws {FcdevError} 汇编或链接失败
59
+ */
60
+ export async function verifyRoundtrip({ toolchain, sourceFile, expected, base, workDir, name }) {
61
+ const objectFile = path.join(workDir, `${name}.roundtrip.o`);
62
+ const configFile = path.join(workDir, `${name}.roundtrip.cfg`);
63
+ const outputFile = path.join(workDir, `${name}.roundtrip.bin`);
64
+ writeFileSync(configFile, renderRoundtripConfig(base, expected.length));
65
+ await runOrThrow(toolchain, 'ca65', [sourceFile, '-o', objectFile], `重新汇编 ${path.basename(sourceFile)} 失败`);
66
+ await runOrThrow(toolchain, 'ld65', ['-C', configFile, '-o', outputFile, objectFile], '重新链接失败');
67
+ const firstDifference = findFirstDifference(expected, readFileSync(outputFile));
68
+ return { ok: firstDifference === -1, firstDifference };
69
+ }
@@ -0,0 +1,30 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:symbols.mjs
3
+ // 说明:读取用户提供的符号文件:每行“名字 = 地址”或“名字 地址”,用于给地址起名字。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:地址按十六进制,可带 $ 或 0x 前缀;以 ; 或 # 开头的行是注释,空行忽略。
8
+ // ------------------------------------------------------------------------
9
+ import { FcdevError } from '../shared/index.mjs';
10
+
11
+ /** 一行符号:名字、可选的等号、地址 */
12
+ const SYMBOL_LINE = /^([A-Za-z_][A-Za-z0-9_]*)\s*(?:=|\s)\s*(?:\$|0[xX])?([0-9A-Fa-f]{1,4})\s*(?:[;#].*)?$/;
13
+
14
+ /**
15
+ * 解析符号文件。
16
+ * @param {string} text 文件内容
17
+ * @returns {{name: string, address: number}[]} 符号列表,按文件里的顺序
18
+ * @throws {FcdevError} 某一行格式不对
19
+ */
20
+ export function parseSymbols(text) {
21
+ const symbols = [];
22
+ text.split(/\r?\n/).forEach((rawLine, index) => {
23
+ const line = rawLine.trim();
24
+ if (line === '' || line.startsWith(';') || line.startsWith('#')) return;
25
+ const match = SYMBOL_LINE.exec(line);
26
+ if (!match) throw new FcdevError(`符号文件第 ${index + 1} 行格式不对:${line}`, { code: 'DISASM_SYMBOL_INVALID', hint: '写成“名字 = $地址”或“名字 地址”' });
27
+ symbols.push({ name: match[1], address: Number.parseInt(match[2], 16) });
28
+ });
29
+ return symbols;
30
+ }
@@ -0,0 +1,25 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:trace.mjs
3
+ // 说明:读取模拟器 trace 命令记录的指令轨迹:每行以 T 开头,第二列是执行到的指令地址。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:轨迹里的每个地址都是被真实执行过的指令开头,比 CDL 的“代码字节”更精确;用作追踪代码的入口。
8
+ // ------------------------------------------------------------------------
9
+
10
+ /** 轨迹的一行:T、四位十六进制的指令地址,后面是物理地址、字节、寄存器 */
11
+ const TRACE_LINE = /^T ([0-9A-Fa-f]{4}) /;
12
+
13
+ /**
14
+ * 取出轨迹里被执行过的指令地址。
15
+ * @param {string} text 轨迹文件内容
16
+ * @returns {number[]} 不重复的地址,按首次出现的顺序
17
+ */
18
+ export function parseTrace(text) {
19
+ const seen = new Set();
20
+ for (const line of text.split('\n')) {
21
+ const match = TRACE_LINE.exec(line);
22
+ if (match) seen.add(Number.parseInt(match[1], 16));
23
+ }
24
+ return [...seen];
25
+ }
@@ -0,0 +1,125 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:debug-client.mjs
3
+ // 说明:模拟器调试服务的客户端:连接本机端口,发送一行命令,读取以单独的“.”行结束的应答。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:协议见 virtuanes/README.md;服务只监听 127.0.0.1,一次只处理一条命令。
8
+ // ------------------------------------------------------------------------
9
+ import net from 'node:net';
10
+ import { FcdevError } from '../shared/index.mjs';
11
+
12
+ /** fcdev 的调试服务默认端口 */
13
+ export const DEFAULT_DEBUG_PORT = 5699;
14
+
15
+ /** 连接调试服务的超时,单位毫秒 */
16
+ const CONNECT_TIMEOUT_MS = 5_000;
17
+
18
+ /** 一条命令默认的应答超时,单位毫秒 */
19
+ const COMMAND_TIMEOUT_MS = 30_000;
20
+
21
+ /**
22
+ * @typedef {object} DebugReply
23
+ * @property {boolean} ok 应答首行以 OK 开头
24
+ * @property {string} head 应答首行
25
+ * @property {string[]} lines 首行之后的各行
26
+ */
27
+
28
+ /**
29
+ * 解析不含结尾“.”行的应答文本。
30
+ * @param {string} text 应答文本
31
+ * @returns {DebugReply} 解析结果
32
+ */
33
+ export function parseReply(text) {
34
+ const lines = text.split('\n').filter((line) => line.length > 0);
35
+ const head = lines[0] ?? '';
36
+ return { ok: head.startsWith('OK'), head, lines: lines.slice(1) };
37
+ }
38
+
39
+ /** 调试服务客户端 */
40
+ export class DebugClient {
41
+ #socket;
42
+ #buffer = '';
43
+ #waiter = null;
44
+
45
+ /**
46
+ * @param {net.Socket} socket 已连接的套接字
47
+ */
48
+ constructor(socket) {
49
+ this.#socket = socket;
50
+ socket.setEncoding('utf8');
51
+ socket.on('data', (chunk) => {
52
+ this.#buffer += chunk;
53
+ this.#deliver();
54
+ });
55
+ socket.on('close', () => {
56
+ this.#waiter?.reject(new FcdevError('调试连接已关闭', { code: 'DEBUG_CONNECTION_CLOSED' }));
57
+ this.#waiter = null;
58
+ });
59
+ }
60
+
61
+ /**
62
+ * 连接本机调试服务。
63
+ * @param {{port?: number, timeoutMs?: number}} [options] 端口与连接超时
64
+ * @returns {Promise<DebugClient>} 客户端
65
+ * @throws {FcdevError} 连接失败或超时
66
+ */
67
+ static connect({ port = DEFAULT_DEBUG_PORT, timeoutMs = CONNECT_TIMEOUT_MS } = {}) {
68
+ return new Promise((resolve, reject) => {
69
+ const socket = net.connect({ host: '127.0.0.1', port });
70
+ const timer = setTimeout(() => {
71
+ socket.destroy();
72
+ reject(new FcdevError(`连接调试服务(端口 ${port})超时`, { code: 'DEBUG_CONNECT_FAILED' }));
73
+ }, timeoutMs);
74
+ socket.once('connect', () => {
75
+ clearTimeout(timer);
76
+ resolve(new DebugClient(socket));
77
+ });
78
+ socket.once('error', (error) => {
79
+ clearTimeout(timer);
80
+ reject(new FcdevError(`无法连接调试服务(端口 ${port})`, {
81
+ code: 'DEBUG_CONNECT_FAILED',
82
+ hint: '先用 fcdev run --debug 启动模拟器,或检查端口是否一致',
83
+ cause: error,
84
+ }));
85
+ });
86
+ });
87
+ }
88
+
89
+ /** 如果缓冲区里已经有完整应答,交给等待者 */
90
+ #deliver() {
91
+ if (!this.#waiter) return;
92
+ const end = this.#buffer.indexOf('\n.\n');
93
+ if (end < 0) return;
94
+ const reply = parseReply(this.#buffer.slice(0, end + 1));
95
+ this.#buffer = this.#buffer.slice(end + 3);
96
+ const { resolve, timer } = this.#waiter;
97
+ clearTimeout(timer);
98
+ this.#waiter = null;
99
+ resolve(reply);
100
+ }
101
+
102
+ /**
103
+ * 发送一条命令并等待应答;应答为 ERR 时不抛错,由调用者看 ok。
104
+ * @param {string} command 命令文本,不含换行
105
+ * @param {{timeoutMs?: number}} [options] 应答超时
106
+ * @returns {Promise<DebugReply>} 应答
107
+ * @throws {FcdevError} 上一条命令未返回、连接关闭或超时
108
+ */
109
+ send(command, { timeoutMs = COMMAND_TIMEOUT_MS } = {}) {
110
+ if (this.#waiter) throw new FcdevError('上一条调试命令尚未返回', { code: 'DEBUG_BUSY' });
111
+ return new Promise((resolve, reject) => {
112
+ const timer = setTimeout(() => {
113
+ this.#waiter = null;
114
+ reject(new FcdevError(`调试命令“${command}”超过 ${timeoutMs} 毫秒没有应答`, { code: 'DEBUG_TIMEOUT' }));
115
+ }, timeoutMs);
116
+ this.#waiter = { resolve, reject, timer };
117
+ this.#socket.write(`${command}\n`);
118
+ });
119
+ }
120
+
121
+ /** 关闭连接 */
122
+ close() {
123
+ this.#socket.end();
124
+ }
125
+ }
@@ -0,0 +1,80 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:emulator-launcher.mjs
3
+ // 说明:启动模拟器:自由运行模式直接打开窗口,调试模式设置调试端口并等待服务就绪。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:模拟器进程与命令行脱离,命令行退出后窗口保持打开;调试模式下模拟器只在收到 run 命令时才运行。
8
+ // ------------------------------------------------------------------------
9
+ import { spawn } from 'node:child_process';
10
+ import { existsSync } from 'node:fs';
11
+ import net from 'node:net';
12
+ import path from 'node:path';
13
+ import { setTimeout as delay } from 'node:timers/promises';
14
+ import { FcdevError } from '../shared/index.mjs';
15
+ import { DEFAULT_DEBUG_PORT, DebugClient } from './debug-client.mjs';
16
+
17
+ /** 等待调试服务就绪的上限,单位毫秒 */
18
+ const READY_TIMEOUT_MS = 30_000;
19
+
20
+ /** 轮询调试服务的间隔,单位毫秒 */
21
+ const READY_POLL_MS = 300;
22
+
23
+ /**
24
+ * 确认本机端口空闲。端口被占用时模拟器的调试服务会静默启动失败,客户端反而可能连到别的模拟器。
25
+ * @param {number} port 端口
26
+ * @returns {Promise<void>}
27
+ * @throws {FcdevError} 端口已被占用
28
+ */
29
+ export function assertPortFree(port) {
30
+ return new Promise((resolve, reject) => {
31
+ const server = net.createServer();
32
+ server.once('error', (error) => reject(new FcdevError(`端口 ${port} 已被占用`, {
33
+ code: 'EMULATOR_PORT_BUSY',
34
+ hint: '用 --port 换一个端口,或关闭占用它的模拟器',
35
+ cause: error,
36
+ })));
37
+ server.listen(port, '127.0.0.1', () => server.close(() => resolve()));
38
+ });
39
+ }
40
+
41
+ /**
42
+ * 启动模拟器。
43
+ * @param {{executable: string, romFile: string, debug?: boolean, port?: number, readyTimeoutMs?: number}} input 模拟器程序、要加载的文件、是否调试模式与端口
44
+ * @returns {Promise<{pid: number|undefined, client: DebugClient|null}>} 进程号;调试模式下还有已连接的客户端,调用者负责关闭
45
+ * @throws {FcdevError} 文件不存在、无法启动,或调试服务没有在时限内就绪
46
+ */
47
+ export async function launchEmulator({ executable, romFile, debug = false, port = DEFAULT_DEBUG_PORT, readyTimeoutMs = READY_TIMEOUT_MS }) {
48
+ if (!existsSync(romFile)) throw new FcdevError(`找不到要加载的文件:${romFile}`, { code: 'EMULATOR_FILE_MISSING' });
49
+ if (debug) await assertPortFree(port);
50
+ const env = { ...process.env };
51
+ if (debug) env.FCDEV_DEBUG_PORT = String(port);
52
+ else delete env.FCDEV_DEBUG_PORT;
53
+
54
+ const child = spawn(executable, [romFile], { cwd: path.dirname(executable), env, stdio: 'ignore', detached: true });
55
+ const failure = new Promise((_, reject) => {
56
+ child.once('error', (error) => reject(new FcdevError(`无法启动模拟器 ${executable}`, { code: 'EMULATOR_START_FAILED', cause: error })));
57
+ });
58
+ child.unref();
59
+ if (!debug) {
60
+ // 给启动失败留出报错的机会,再返回
61
+ await Promise.race([failure, delay(300)]);
62
+ return { pid: child.pid, client: null };
63
+ }
64
+
65
+ const deadline = Date.now() + readyTimeoutMs;
66
+ while (Date.now() < deadline) {
67
+ try {
68
+ const client = await Promise.race([DebugClient.connect({ port, timeoutMs: 1000 }), failure]);
69
+ const status = await client.send('status');
70
+ if (status.head.includes('running=1')) return { pid: child.pid, client };
71
+ client.close();
72
+ } catch (error) {
73
+ if (error.code === 'EMULATOR_START_FAILED') throw error;
74
+ // 服务尚未就绪,稍后重试
75
+ }
76
+ await delay(READY_POLL_MS);
77
+ }
78
+ child.kill();
79
+ throw new FcdevError(`等待模拟器的调试服务(端口 ${port})就绪超时`, { code: 'EMULATOR_NOT_READY', hint: '检查端口是否被占用,或先关闭已打开的模拟器' });
80
+ }
@@ -0,0 +1,62 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:emulator-locator.mjs
3
+ // 说明:定位模拟器程序:配置项、环境变量、平台包,按顺序查找。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:模拟器只有 Windows 版;其他系统明确报错,不影响构建。
8
+ // ------------------------------------------------------------------------
9
+ import { existsSync } from 'node:fs';
10
+ import { createRequire } from 'node:module';
11
+ import path from 'node:path';
12
+ import { FcdevError } from '../shared/index.mjs';
13
+
14
+ /** 环境变量:自备模拟器的路径 */
15
+ export const EMULATOR_ENV_NAME = 'FCDEV_EMULATOR';
16
+
17
+ /** 平台包里模拟器程序的相对路径 */
18
+ const PACKAGE_EXECUTABLE = path.join('bin', 'VirtuaNES.exe');
19
+
20
+ /**
21
+ * 模拟器平台包的名称,放在 @rujianjs 作用域下。
22
+ * @param {string} [platform] 系统,默认当前系统
23
+ * @param {string} [arch] 架构,默认当前架构
24
+ * @returns {string} 包名
25
+ */
26
+ export function getEmulatorPackageName(platform = process.platform, arch = process.arch) {
27
+ return `@rujianjs/fcdev-emulator-${platform}-${arch}`;
28
+ }
29
+
30
+ /**
31
+ * 按顺序定位模拟器:配置项 emulator、环境变量、平台包。
32
+ * @param {{configured?: string, env?: NodeJS.ProcessEnv, platform?: string}} [options] configured 为配置里的绝对路径
33
+ * @returns {{executable: string, source: string}} 模拟器程序与来源
34
+ * @throws {FcdevError} 系统不支持,或都找不到
35
+ */
36
+ export function locateEmulator({ configured, env = process.env, platform = process.platform } = {}) {
37
+ const explicit = configured ? { executable: configured, source: 'config' } : env[EMULATOR_ENV_NAME] ? { executable: path.resolve(env[EMULATOR_ENV_NAME]), source: 'env' } : null;
38
+ if (explicit) {
39
+ if (!existsSync(explicit.executable)) {
40
+ throw new FcdevError(`找不到模拟器:${explicit.executable}`, { code: 'EMULATOR_NOT_FOUND' });
41
+ }
42
+ return explicit;
43
+ }
44
+ if (platform !== 'win32') {
45
+ throw new FcdevError('模拟器只支持 Windows', {
46
+ code: 'EMULATOR_UNSUPPORTED',
47
+ hint: `其他系统可用 ${EMULATOR_ENV_NAME} 或 fcdev.json 的 emulator 指定自备的模拟器;构建不受影响`,
48
+ });
49
+ }
50
+ const packageName = getEmulatorPackageName(platform);
51
+ try {
52
+ const packageJson = createRequire(import.meta.url).resolve(`${packageName}/package.json`);
53
+ const executable = path.join(path.dirname(packageJson), PACKAGE_EXECUTABLE);
54
+ if (existsSync(executable)) return { executable, source: 'package' };
55
+ } catch {
56
+ // 平台包没有安装,落到下面统一的报错
57
+ }
58
+ throw new FcdevError('找不到模拟器', {
59
+ code: 'EMULATOR_NOT_FOUND',
60
+ hint: `任选一种:安装平台包 ${packageName};设置环境变量 ${EMULATOR_ENV_NAME} 指向模拟器程序;在 fcdev.json 里用 emulator 指定`,
61
+ });
62
+ }
@@ -0,0 +1,11 @@
1
+ // ------------------------------------------------------------------------
2
+ // 名称:index.mjs
3
+ // 说明:emulator 目录的对外入口:定位模拟器、启动模拟器、调试服务客户端。
4
+ // 作者:sungbin
5
+ // 邮箱:sungbin@3578.cn
6
+ // 日期:2026-11-10
7
+ // 备注:无
8
+ // ------------------------------------------------------------------------
9
+ export { DEFAULT_DEBUG_PORT, DebugClient, parseReply } from './debug-client.mjs';
10
+ export { assertPortFree, launchEmulator } from './emulator-launcher.mjs';
11
+ export { EMULATOR_ENV_NAME, getEmulatorPackageName, locateEmulator } from './emulator-locator.mjs';