mbackschat/amiga-boing

# amiga-boing  著名的 **Amiga Boing Ball** 演示（Dale Luck / R. J. Mical，1984 CES）—— 一个在洋红色线框房间里弹跳的红白相间球体 —— 以可编译的、带有大量注释的 68000 汇编代码形式呈现，并附带关于其工作原理的深度文档。 这里的源码是 **AMICUS Disk 9 “polite” Boing**（一款 Commodore-Amiga 开发者示例），基于 Harry “Piru” Sintonen 的反汇编进行重建，拆分为可读的文件并添加了注释。它可以通过 `vasm`/`vlink` 编译为 Kickstart 1.x / OCS 可执行文件，并在 FS-UAE 下运行。有关完整的历史和变体渊源，请参阅 [docs/DEMO-BACKGROUND.md](docs/DEMO-BACKGROUND.md)。 ## 快速开始 ``` git submodule update --init # fetch vendor/ (see "vendor/" below) ./scripts/build.sh # assemble + link + stage the uae/ run target ./scripts/run.sh # launch the demo in FS-UAE ``` 关闭 FS-UAE 窗口即可退出。完整细节和各操作系统的注意事项：**[docs/RUNNING.md](docs/RUNNING.md)**。 **前提要求：** `vasmm68k_mot` + `vlink`（VS Code 的 [amiga-assembly](https://marketplace.visualstudio.com/items?itemName=prb28.amiga-assembly) 扩展已内置，或者需在您的 `PATH` 中）；**FS-UAE**；以及 **`vendor/`**（见下文）的内容。 ## `vendor/` — 您必须自行提供的受版权文件 构建过程需要三个不可再分发的第三方受版权组件，因此它们存放在一个独立的**私有** git 子模块（[`amiga-boing-vendor`](https://github.com/mbackschat/amiga-boing-vendor)）中，而不是在本仓库内： ``` vendor/ include/ Amiga 1.3 NDK assembler headers (*.i) © Commodore-Amiga, Inc. libs/ mathtrans.library © Commodore-Amiga + Motorola FFP firmware rom/ kick13.rom (Kickstart 1.3, r34.5) © Commodore / Cloanto (required — native OS) rom/ kick204.rom (Kickstart 2.04, r37.175) © Commodore / Cloanto (optional — default boot ROM when present) ``` 如果您有访问权限，执行 `git submodule update --init` 即可拉取。**如果您没有权限**，请按照该确切的目录结构提供您自己的副本 —— 例如来自 [Cloanto Amiga Forever](https://www.amigaforever.com/) 的 NDK 1.3 includes 和 Kickstart ROM（**必须要有 1.3**，2.04 为可选），以及来自 Workbench 1.3 软盘的 `mathtrans.library`。`scripts/build.sh` 需要 1.3 ROM，并在检测到 2.04 时将其作为默认的启动 ROM；如果有缺失，它会提示您。 ## 目录结构 ``` src/ demo sources (assembled into one binary) boing.s vasm entry point — INCLUDEs the five .s files below startup.s Lattice C c.o startup boilerplate anim.s _Boing audio per-frame + audio.device setup + sample DATA globe.s _init_globe / _draw_globe — sphere math + polygon fill main.s _main, the main loop, physics, palette cycling, globals runtime.s Lattice C runtime + library glue stubs assets/ boing.samples the "BOING!" 8-bit PCM Boing.info Workbench icon uae/ FS-UAE run-target skeleton (config + startup-sequence + UAEquit) vendor/ copyrighted NDK includes / mathtrans.library / Kickstart ROM (private submodule) scripts/ build.sh, run.sh docs/ analysis & reference (see below) specs/ handoff spec for a separate browser-port project archive/ unmodified originals (Sintonen disasm + Maher's C reconstruction) uae/ generated FS-UAE run target (git-ignored; staged by build.sh) build/ assembler output (git-ignored) ``` ## 文档 - **[docs/RUNNING.md](docs/RUNNING.md)** — 构建与运行（macOS / Linux / Windows）、工具链、`vendor/`、常见陷阱。 - **[docs/DEVIATIONS.md](docs/DEVIATIONS.md)** — 本仓库对原始 AMICUS 源码做出的两处刻意修改（自动启动；KS2.0+ 帧率修复），以及如何重新验证。 - **[docs/ANIMATION-DETAILS.md](docs/ANIMATION-DETAILS.md)** — 运动/时序/距离，通过 UAE 录制测量并与源码进行核对（用于重现该动画）。 - **[docs/BOING-ANALYSIS.md](docs/BOING-ANALYSIS.md)** — 针对源码的逐函数分析。 - **[docs/AMIGA-KNOWHOW.md](docs/AMIGA-KNOWHOW.md)** — Amiga 1000 硬件/操作系统参考，范围仅限于本演示所使用的内容。 - **[docs/DEMO-BACKGROUND.md](docs/DEMO-BACKGROUND.md)** — 历史、文化背景、变体渊源。 - **[docs/BOING-AMICUS(S)-VS-MAHER(C).md](docs/BOING-AMICUS%28S%29-VS-MAHER%28C%29.md)** — 与 Jimmy Maher 的 C 语言重制版进行比较。 ## 保真度说明 `src/` 与原始的 AMICUS 反汇编（`archive/boing_original.s`）保持高度一致，只有**两处刻意的偏差**：自动启动（原始版本启动时是暂停的），以及针对 Kickstart 2.0+ 的帧率修复（一个受版本控制的提交块，用于在更高版本的操作系统上保持演示以原生场频 —— 50 Hz PAL / 60 Hz NTSC —— 运行；KS1.x 运行原始代码路径）。第一处只是单个值的翻转；第二处增加了一点代码，因此构建出的结果不再是严格逐字节相同的。它的屏幕处理方式是原始的：球体屏幕在**后台**打开，因此需要向下拖动 CLI/Workbench 屏幕的标题栏才能看到它。完整细节：**[docs/DEVIATIONS.md](docs/DEVIATIONS.md)**；未修改的原始文件位于 `archive/` 中。

标签：68000, Amiga, 图形演示, 复古计算, 安全报告生成, 快速连接, 汇编语言