<?xml version="1.0" encoding="utf-8"?><?xml-stylesheet type="text/xsl" href="rss.xsl"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
    <channel>
        <title>WhereQ Blog</title>
        <link>https://whereq.github.io/zh-CN/blog</link>
        <description>WhereQ Blog</description>
        <lastBuildDate>Thu, 19 Nov 2026 00:00:00 GMT</lastBuildDate>
        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
        <generator>https://github.com/jpmonette/feed</generator>
        <language>zh-CN</language>
        <item>
            <title><![CDATA[WhereQ-DOSBox 的中断地图：模拟器里每一个 INT 都在干什么]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN</guid>
            <pubDate>Thu, 19 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="所有-dos-程序唯一都认同的那一个接口">所有 DOS 程序唯一都认同的那一个接口<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E6%89%80%E6%9C%89-dos-%E7%A8%8B%E5%BA%8F%E5%94%AF%E4%B8%80%E9%83%BD%E8%AE%A4%E5%90%8C%E7%9A%84%E9%82%A3%E4%B8%80%E4%B8%AA%E6%8E%A5%E5%8F%A3" class="hash-link" aria-label="所有 DOS 程序唯一都认同的那一个接口的直接链接" title="所有 DOS 程序唯一都认同的那一个接口的直接链接" translate="no">​</a></h2>
<p>有一件事是我没料到自己会在意，然后一旦在意就停不下来的。</p>
<p>1987 年的 DOS 游戏并不知道显卡是什么。它不知道鼠标存在，也不知道键盘有个缓冲区。它只认一件事：往栈里推一个数，执行 <code>INT</code>，机器就会回答。<code>INT 10h</code>，机器把一个字符画到屏幕上。<code>INT 16h</code>，机器交出一个按键。<code>INT 33h</code>，机器告诉你鼠标在哪、哪些按钮按着。</p>
<p>契约就这么多。1991 到 1994 年的每一个游戏都是照着它写的，而且它从来没有变过。</p>
<p>为了写这篇文章，我把 DOSBox 的中断层认真读了一遍。它是整个模拟器里建得最用心的部分之一——同时也是这个移植版被迫想得最多的部分之一，因为触摸屏不是鼠标，手机也不是 PC。</p>
<p>所以，地图在这里。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="地图">地图<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E5%9C%B0%E5%9B%BE" class="hash-link" aria-label="地图的直接链接" title="地图的直接链接" translate="no">​</a></h2>
<table><thead><tr><th>向量</th><th>服务</th><th>用途</th></tr></thead><tbody><tr><td><strong>10h</strong></td><td>视频 BIOS</td><td>文本与图形输出、光标、调色板、VESA/VBE</td></tr><tr><td><strong>13h</strong></td><td>磁盘 BIOS</td><td>对磁盘镜像做扇区读写</td></tr><tr><td><strong>16h</strong></td><td>键盘 BIOS</td><td>从 BIOS 键盘缓冲区取按键</td></tr><tr><td><strong>21h</strong></td><td>DOS</td><td>DOS API：文件、目录、内存、程序</td></tr><tr><td><strong>29h</strong></td><td>快速控制台</td><td>完全不走 DOS 层的字符输出</td></tr><tr><td><strong>2Ah</strong></td><td>网络重定向器</td><td>「有没有网络协议栈？」</td></tr><tr><td><strong>2Eh</strong></td><td>DOS shell</td><td>模拟器自己的命令行</td></tr><tr><td><strong>2Fh</strong></td><td>多路复用</td><td>XMS、CD-ROM 等扩展的派发口</td></tr><tr><td><strong>33h</strong></td><td>鼠标</td><td>DOS 鼠标驱动</td></tr><tr><td><strong>67h</strong></td><td>EMS</td><td>扩展内存，以及 VCPI</td></tr><tr><td><strong>74h</strong></td><td>PS/2 鼠标</td><td>IRQ 12，鼠标的硬件向量</td></tr><tr><td><strong>41h / 46h</strong></td><td>磁盘参数表</td><td>磁盘的几何参数</td></tr><tr><td><strong>1Fh / 43h / 44h</strong></td><td>字体</td><td>8×8 字模块</td></tr><tr><td><strong>4Bh</strong></td><td>虚拟 DMA</td><td>VDMA 通道 API</td></tr><tr><td><strong>73h</strong></td><td>IPX ESR</td><td>Novell 网络事件服务例程</td></tr></tbody></table>
<p>硬件那一侧有个容易搞混的点：<strong>IRQ 号不是向量号</strong>。两片 8259 各自有一个向量基址——主片 <code>0x08</code>，从片 <code>0x70</code>——向量是在中断被响应的那一刻才算出来的：</p>
<table><thead><tr><th>IRQ</th><th>向量</th><th>设备</th></tr></thead><tbody><tr><td>0</td><td>08h</td><td>PIT 定时器</td></tr><tr><td>1</td><td>09h</td><td>键盘</td></tr><tr><td>2</td><td>0Ah</td><td>到从片 PIC 的级联</td></tr><tr><td>6</td><td>0Eh</td><td>PCjr 键盘</td></tr><tr><td>8</td><td>70h</td><td>实时时钟</td></tr><tr><td>12</td><td>74h</td><td>PS/2 鼠标</td></tr><tr><td>3、4、5、7、10、11</td><td>0Bh、0Ch、0Dh、0Fh、72h、73h</td><td>其余全部——被屏蔽并记录在案</td></tr></tbody></table>
<p>每个向量下面的功能码表，仓库里有一份完整版：<strong><a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/INTERRUPTS.md" target="_blank" rel="noopener noreferrer" class="">docs/INTERRUPTS.md</a></strong>。这篇文章讲的是它背后的故事。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="int-10h-的一次调用怎么变成了一个-c-函数">INT 10h 的一次调用，怎么变成了一个 C 函数<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#int-10h-%E7%9A%84%E4%B8%80%E6%AC%A1%E8%B0%83%E7%94%A8%E6%80%8E%E4%B9%88%E5%8F%98%E6%88%90%E4%BA%86%E4%B8%80%E4%B8%AA-c-%E5%87%BD%E6%95%B0" class="hash-link" aria-label="INT 10h 的一次调用，怎么变成了一个 C 函数的直接链接" title="INT 10h 的一次调用，怎么变成了一个 C 函数的直接链接" translate="no">​</a></h2>
<p>DOSBox 里没有一张集中的中断表。服务安装自己的方式，和真 BIOS 一模一样：写<strong>中断向量表</strong>，让向量指向一段桩代码。</p>
<p><code>INT n</code> 执行 <code>0xCD</code> 这条指令，落进 <code>CPU_Interrupt()</code>，CPU 压入标志、CS 和 EIP，关掉中断标志，再从 IVT 的 <code>base + (n &lt;&lt; 2)</code> 处读出新的 <code>CS:IP</code>。这是货真价实的 8086 流程，DOSBox 一步步照做——来宾的栈上得到的六个字节，和真硬件上完全一样。</p>
<p>向量指向的并不是处理程序，而是一段<strong>桩</strong>：几字节手工拼出来的 16 位实模式代码，形状由一个回调类型决定。DOSBox 的巧思是一字节的合成操作码——<code>FE 38</code>——CPU 解释器认得它，把它变成一次对已注册 C 函数的调用。</p>
<p>这些桩不是装饰，它们的形状就是行为本身：</p>
<ul>
<li class=""><strong>INT 16h 会空转。</strong> 桩是 <code>IRET</code>，然后十二个 <code>NOP</code>，再跳回回调。缓冲区里没有按键时，处理程序给 <code>IP</code> 加一，正好落回那串 <code>NOP</code> 上。于是来宾就在<strong>实模式里空转</strong>，直到 IRQ 1 送来一个按键——和真硬件一模一样。</li>
<li class=""><strong>INT 21h 要交税。</strong> 它的桩里含一条 <code>loop</code> 指令：模拟出来的 DOS 服务开销，一次调用几百个周期，8086 上本来也要花掉的。</li>
<li class=""><strong>INT 13h 用 BIOS 的方式报错。</strong> 桩的结尾是 <code>IRET</code>，然后 <code>INT 0Eh</code>，再 <code>IRET</code>——就是经典的「用 AL=0 调 INT 0Eh」磁盘错误约定。</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="int-33h以及为什么点击必须是按住">INT 33h，以及为什么「点击」必须是「按住」<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#int-33h%E4%BB%A5%E5%8F%8A%E4%B8%BA%E4%BB%80%E4%B9%88%E7%82%B9%E5%87%BB%E5%BF%85%E9%A1%BB%E6%98%AF%E6%8C%89%E4%BD%8F" class="hash-link" aria-label="INT 33h，以及为什么「点击」必须是「按住」的直接链接" title="INT 33h，以及为什么「点击」必须是「按住」的直接链接" translate="no">​</a></h2>
<p>鼠标是最有意思的一个，也是这个移植版改动最多的一个。</p>
<p><code>INT 33h</code> 是一个对 <code>AX</code> 的 <code>switch</code>，实现了 35 个功能码。这里真正要紧的是两个：<strong>AX=03h</strong>，返回光标位置和按键状态；<strong>AX=0Ch</strong>，登记游戏自己的事件回调。</p>
<p>关于 AX=03h，有一点是我读到代码才真正明白的。<code>mouse.buttons</code> 是一个<strong>电平</strong>，不是边沿。<code>Mouse_ButtonPressed()</code> 置位，<code>Mouse_ButtonReleased()</code> 清位，AX=03h 把这个掩码原样交回去：</p>
<div class="language-c codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-c codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token keyword" style="color:rgb(86, 156, 214)">case</span><span class="token plain"> </span><span class="token number" style="color:rgb(181, 206, 168)">0x03</span><span class="token operator" style="color:rgb(212, 212, 212)">:</span><span class="token plain">	</span><span class="token comment" style="color:rgb(106, 153, 85)">/* Return Position and Button Status */</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">    reg_bx</span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain">mouse</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">buttons</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">    reg_cx</span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain">POS_X</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">    reg_dx</span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain">POS_Y</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">    </span><span class="token keyword" style="color:rgb(86, 156, 214)">break</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><br></div></code></pre></div></div>
<p>每帧轮询 AX=03h 的游戏，问的是「这个按钮<strong>现在</strong>按着吗」，而不是「刚才有没有点一下」。</p>
<p>就这一个事实，决定了整个触摸层的设计。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="从一根手指到一只-dos-鼠标">从一根手指到一只 DOS 鼠标<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E4%BB%8E%E4%B8%80%E6%A0%B9%E6%89%8B%E6%8C%87%E5%88%B0%E4%B8%80%E5%8F%AA-dos-%E9%BC%A0%E6%A0%87" class="hash-link" aria-label="从一根手指到一只 DOS 鼠标的直接链接" title="从一根手指到一只 DOS 鼠标的直接链接" translate="no">​</a></h2>
<p>这个移植版的第一版做法很直白：手指按下就是 press，手指抬起就是 release，敲一下算一次点击。</p>
<p>这是错的。而且错在一种只有游戏才会暴露的地方。三国志英杰传的战斗界面读的是<strong>实时</strong>按键状态。如果按下和抬起落在它两次轮询之间，游戏根本看不见这次点击。光标动了，敲击等于没发生，玩家只会觉得这个应用坏了。</p>
<p>所以现在手指在玻璃上按多久，按钮就按住多久：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">  SDL_FINGERDOWN        →  Mouse_ButtonPressed(0)   // 左键，按住</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  SDL_FINGERMOTION      →  移动光标，按键仍然按着</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  SDL_FINGERUP          →  Mouse_ButtonReleased(0)</span><br></div></code></pre></div></div>
<p>敲一下于是变成一次真正的「按住再松开」的点击。拖动也变成真正的拖动——因为光标是在按键按着的时候移动的。</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n7-pads-letters.png" alt="STARFALL 跑在手机上，画面两侧是两块掌机式键盘区：左边是方向键和半边 QWERTY，右边是动作键和另外半边字母。" width="900"></p>
<p align="center"><sub>画面两侧的两块键盘区。整块屏幕就是那只鼠标。</sub></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="吞掉每一次点击的那个陷阱">吞掉每一次点击的那个陷阱<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E5%90%9E%E6%8E%89%E6%AF%8F%E4%B8%80%E6%AC%A1%E7%82%B9%E5%87%BB%E7%9A%84%E9%82%A3%E4%B8%AA%E9%99%B7%E9%98%B1" class="hash-link" aria-label="吞掉每一次点击的那个陷阱的直接链接" title="吞掉每一次点击的那个陷阱的直接链接" translate="no">​</a></h3>
<p>还有第二个 bug，而且更古怪。DOSBox 在全屏时会「捕获鼠标」，这会置上 <code>sdl.mouse.locked</code>。这个标志一置上，<code>Mouse_CursorMoved()</code> 就<strong>忽略绝对位置</strong>，只累加相对位移。</p>
<p>在桌面上这是对的——被捕获的鼠标本来就是相对设备。可手机上根本没有鼠标可捕获，后果就是每一次敲击都被忽略，光标卡在屏幕正中。</p>
<p>修之前和修之后的实测：</p>
<table><thead><tr><th></th><th>点 (700, 300)</th><th>点 (1500, 800)</th><th>点 (1000, 500)</th></tr></thead><tbody><tr><td>之前</td><td>320, 100</td><td>320, 100</td><td>320, 100</td></tr><tr><td>之后</td><td>97, 55</td><td>453, 148</td><td>231, 92</td></tr></tbody></table>
<p>数字是精确的：<code>0.153 × 80 × 8 = 97</code>——DOS 文本屏 80 × 25 个字符格，每格 8 像素。原本永远落在同一个错误格子上的点击，现在落在你真正按下的地方。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="右键">右键<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E5%8F%B3%E9%94%AE" class="hash-link" aria-label="右键的直接链接" title="右键的直接链接" translate="no">​</a></h3>
<p>DOS 鼠标有两个按钮，触摸屏只有一个。而绝大多数 DOS 游戏里右键是<em>取消</em>或<em>返回</em>，所以丢掉右键就是丢掉了一整类交互。</p>
<p>这里没有长按手势，也没有上下文菜单。右键由两个机制送出，而且两个都是<strong>按住</strong>式按钮，和左键完全一样：</p>
<ul>
<li class="">画面上的<strong>第二根手指</strong>。左键会先松开，所以两个按钮不会重叠；右键一直按到那根手指抬起。</li>
<li class="">屏幕上的 <strong><code>RMB</code> 键</strong>，在左边那块、紧挨 <code>Tab</code>。它通过 JNI 桥往 DOSBox 的事件队列里推一个真正的 <code>SDL_BUTTON_RIGHT</code> 的 <code>SDL_MOUSEBUTTONDOWN</code>，事件走的路径和普通鼠标点击一模一样。</li>
</ul>
<p>第二个机制有意思的地方在于，它压根不是一个手势——它是<strong>另一个事件类型</strong>，被塞进模拟器本来就在读的那个队列。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="驱动的状态住在来宾内存之外">驱动的状态住在来宾内存之外<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E9%A9%B1%E5%8A%A8%E7%9A%84%E7%8A%B6%E6%80%81%E4%BD%8F%E5%9C%A8%E6%9D%A5%E5%AE%BE%E5%86%85%E5%AD%98%E4%B9%8B%E5%A4%96" class="hash-link" aria-label="驱动的状态住在来宾内存之外的直接链接" title="驱动的状态住在来宾内存之外的直接链接" translate="no">​</a></h2>
<p>这是我把存档格式重写了两次的那个 bug 的根子。</p>
<p>INT 33h 驱动的状态住在一个<strong>宿主的文件内静态结构体</strong>里，不在模拟出来的内存中。其中有三样东西，来宾在读档之后没法自己重建：</p>
<ul>
<li class="">游戏用 <strong>AX=0Ch</strong> 登记的事件回调——段、偏移和事件掩码；</li>
<li class=""><strong>AX=09h</strong> 定义的图形光标和它的热点；</li>
<li class="">光标范围、位置、可见性和灵敏度。</li>
</ul>
<p>少了第一样，症状精确得让人难受：<strong>光标还在动</strong>——那是 DOSBox 在画——<strong>但游戏的点击送不到游戏里</strong>。对话框的<em>确认</em>按钮就是没反应。模拟器看起来活蹦乱跳，游戏却是聋的。</p>
<p>少了第二样，光标退回默认的白色方块、热点归零，于是<strong>看得见的光标和真正的点击点对不上</strong>，敲击会落在目标的偏上偏左。</p>
<p>所以鼠标驱动必须成为存档的一部分。第一次尝试存了整个结构体。</p>
<p><strong>结果把游戏卡死了。</strong> 三国志英杰传在读档时挂起，而且过一分钟就再也不响应点击——事件队列在一个卡住的 <code>in_UIR</code> 标志后面堆满了。把过期的队列和过期的 <code>in_UIR</code> 喂回中断处理程序，就是把垃圾喂给了游戏自己的回调。</p>
<p>修法是搞懂两种状态的分别：</p>
<blockquote>
<p><strong>配置值得保存，运行期状态是毒药。</strong></p>
</blockquote>
<p>最终形态存的是一个专门的 <code>MouseStateBlock</code>，只放来宾重建不了的东西——回调三元组、光标范围与位置、热点、光标掩码、灵敏度。读档时则把<strong>所有易失的部分重置</strong>：事件队列、按键与点击计数器、重入标志、光标绘制的背景缓冲。</p>
<p>还有一条规则，这是「宿主指针」规则的小号版本：结构体里有两个指向光标位图的<strong>宿主指针</strong>。它们从不写进文件，而是在读档后根据保存的光标类型<strong>重新推导</strong>：用户自定义的图形光标用恢复出来的掩码，其余一律用内置箭头。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="同一条规则往下一层pic">同一条规则，往下一层：PIC<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E5%90%8C%E4%B8%80%E6%9D%A1%E8%A7%84%E5%88%99%E5%BE%80%E4%B8%8B%E4%B8%80%E5%B1%82pic" class="hash-link" aria-label="同一条规则，往下一层：PIC的直接链接" title="同一条规则，往下一层：PIC的直接链接" translate="no">​</a></h2>
<p>中断控制器是同一个形状的问题，而这个移植版得出了同一个答案。</p>
<p>存档是机器的快照，而机器包含它的中断子系统。<code>PIC_SaveState</code> 和 <code>PIC_LoadState</code> 会把两个控制器结构体写进去——然后加载器<strong>故意不把全部都恢复</strong>：</p>
<div class="language-c codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-c codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">	</span><span class="token comment" style="color:rgb(106, 153, 85)">/* Keep the game's interrupt MASK and configuration, but drop any stale</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">	 * pending/in-service state: a restored in-service bit would block all</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">	 * lower-priority IRQs (so the RTC that drives INT 15h/86h, and thus sound</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">	 * timing, would stall), and a stale request bit would fire a spurious IRQ.</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">	 * At the top-of-main-loop restore point no IRQ is genuinely mid-service. */</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">	pics</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">i</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">imrr </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">~</span><span class="token plain">pics</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">i</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">imr</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">	pics</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">i</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">irr </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token number" style="color:rgb(181, 206, 168)">0</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">	pics</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">i</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">isr </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token number" style="color:rgb(181, 206, 168)">0</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><br></div></code></pre></div></div>
<p>掩码是<em>配置</em>——来宾自己决定要哪些中断，它要留下来。在服务位和请求位是<em>瞬态</em>——一个残留的在服务位会卡死整个优先级链，一个残留的请求位会打出一次莫名的中断。</p>
<p>保留配置，丢掉运行期状态。同一句话，在两个不同的子系统里说了两遍，而两次都是靠撞墙撞出来的。</p>
<p>格式版本也随着设计在动：<strong>8</strong> 是「整个鼠标驱动状态」，<strong>9</strong> 是「精简成回调 + 范围 + 位置」，<strong>10</strong> 是「光标形状、热点和其余配置」。含义变了的格式必须把版本号喊出来，这样旧的存档会被<strong>拒绝</strong>，而不是被误读。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="这个移植版没有改的东西">这个移植版没有改的东西<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E8%BF%99%E4%B8%AA%E7%A7%BB%E6%A4%8D%E7%89%88%E6%B2%A1%E6%9C%89%E6%94%B9%E7%9A%84%E4%B8%9C%E8%A5%BF" class="hash-link" aria-label="这个移植版没有改的东西的直接链接" title="这个移植版没有改的东西的直接链接" translate="no">​</a></h2>
<p>这个答案更让人意外，也更值得直说：<strong>BIOS 中断层是上游代码。</strong></p>
<p><code>src/ints/</code> 下的每一个文件自导入以来都没动过，只有一个例外。<code>mouse.cpp</code> 有五个导入之后的提交；而 <code>int10.cpp</code> 及其八个兄弟、<code>bios.cpp</code>、<code>bios_disk.cpp</code>、<code>bios_keyboard.cpp</code>、<code>ems.cpp</code>、<code>xms.cpp</code> 一个都没有。</p>
<p>DOS 层也一样。<code>src/dos/dos.cpp</code>——整个 INT 21h 处理程序——以及 <code>dos_misc.cpp</code>、<code>dos_classes.cpp</code>、<code>dos_memory.cpp</code> 与导入的源码逐字节相同。这个移植版对它的<strong>唯一</strong>侵入是一行，而且和中断没有关系：</p>
<div class="language-c codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-c codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token function" style="color:rgb(220, 220, 170)">SegSet16</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">ds</span><span class="token punctuation" style="color:rgb(212, 212, 212)">,</span><span class="token plain">pspseg</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token function" style="color:rgb(220, 220, 170)">SegSet16</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">es</span><span class="token punctuation" style="color:rgb(212, 212, 212)">,</span><span class="token plain">pspseg</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token comment" style="color:rgb(106, 153, 85)">/* WhereQ: a guest program has taken over the machine, so the boot</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)"> * is over and a save-state request may be serviced. The shell</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)"> * itself never reaches its prompt in this case (it is blocked</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)"> * inside the program it started), so this is the only place where</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)"> * the save-state module learns that the guest is running. */</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token function" style="color:rgb(220, 220, 170)">SAVESTATE_GuestReady</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><br></div></code></pre></div></div>
<p>连包启动器都是走的标准路径。每个游戏会生成一个 <code>RUN.BAT</code>，被追加到模拟器的 <code>[autoexec]</code> 里；来宾随后用 <code>INT 21h AH=4Bh</code> 去 exec 它，再 <code>AH=4Bh</code> 跑游戏自己的 <code>PLAY.BAT</code>，最后 <code>AH=4Ch</code> 退出。这个移植版没有新增任何启动器 API——它只是挑了一个文件名，剩下的交给 DOS。</p>
<p>整个移植版大致就是这个形状：真正有意思的工作几乎从不在 BIOS 层，而在<strong>它上面那一层</strong>——把一根手指变成一只鼠标，把一次轻触变成一个按住不松的按钮，把一个游戏变成存档能带走的东西。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="自己看一遍">自己看一遍<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E8%87%AA%E5%B7%B1%E7%9C%8B%E4%B8%80%E9%81%8D" class="hash-link" aria-label="自己看一遍的直接链接" title="自己看一遍的直接链接" translate="no">​</a></h2>
<p>看这一层工作，最省事的办法是打开 <code>MOUSE</code> 日志分组，在 <code>dosbox.conf</code> 里：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">[log]</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">logfile=/sdcard/dosbox.log</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">mouse=true</span><br></div></code></pre></div></div>
<p>Android 应用不带 <code>[log]</code> 段，所以默认是关的。打开之后，驱动<strong>没有实现</strong>的每一次 INT 33h 调用都会被报出来：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">Mouse Function 0018 not implemented!</span><br></div></code></pre></div></div>
<p>这等于直接读出了游戏在要什么、驱动又没回答什么。再往前一个函数的地方，有一行被注释掉的日志，会打印<strong>每一次</strong> INT 33h 调用的 AX、BX、CX 和光标位置——对想读这份代码的人来说，这是这个树里最值得解开的一行。</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong>——源码、完整的中断地图 <a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/INTERRUPTS.md" target="_blank" rel="noopener noreferrer" class=""><code>docs/INTERRUPTS.md</code></a>，以及背后的技术参考。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="致谢-dosbox">致谢 DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts-CN#%E8%87%B4%E8%B0%A2-dosbox" class="hash-link" aria-label="致谢 DOSBox的直接链接" title="致谢 DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> 写成——一群志愿者把 1994 年的一套操作系统改造到此后世界造出的每一台机器上都能跑，包括那些当时还不存在的机器。他们让它活过了三十年，并免费交给任何想要的人。WhereQ-DOSBox 只是建在他们工作之上的一层薄薄的壳。原创力、手艺和慷慨完全属于他们。</p>
<p>这个移植版基于 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 做的 DOSBox r4305 的 Emscripten 版，它又来自 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 最早那次用 Emscripten 编译 DOSBox 的尝试，并且踩着 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 的 Emscripten 工作一路往前。窗口、音频和触摸输入则由 <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> 的 SDL2 库承担。</p>
<p><strong>DOSBox 是 DOSBox 项目的商标</strong>；这个移植版与 DOSBox 团队没有任何隶属或背书关系。</p>
<hr>
<p><em>模拟器就是一台由「对还没人问过的问题的回答」造出来的机器。真正有意思的工作，在于决定那个问题从一根拇指上传来时，回答应该是什么。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>dos</category>
            <category>中断</category>
            <category>x86</category>
            <category>android</category>
            <category>模拟器</category>
            <category>复古</category>
            <category>开源</category>
            <category>whereq</category>
            <category>存档</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox interrupts: the map of every INT in the emulator]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts</guid>
            <pubDate>Thu, 19 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-one-interface-every-dos-program-agrees-on">The one interface every DOS program agrees on<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#the-one-interface-every-dos-program-agrees-on" class="hash-link" aria-label="The one interface every DOS program agrees on的直接链接" title="The one interface every DOS program agrees on的直接链接" translate="no">​</a></h2>
<p>Here is something I did not expect to care about, and then could not stop caring about.</p>
<p>A DOS game from 1987 does not know what a graphics card is. It does not know that a mouse exists, or that a keyboard has a buffer. It knows exactly one thing: it can ask the machine a question by <strong>pushing a number onto the stack and executing <code>INT</code></strong>. <code>INT 10h</code> and the machine will put a character on the screen. <code>INT 16h</code> and the machine will hand over a keystroke. <code>INT 33h</code> and the machine will tell it where the mouse is and which buttons are down.</p>
<p>That is the whole contract. Every game from 1991 to 1994 is written against it, and it never changed.</p>
<p>I have been reading DOSBox's interrupt layer properly for this article, and it turns out to be one of the most carefully built parts of the emulator — and one of the parts this port has had to think about hardest, because a touch screen is not a mouse and a phone is not a PC.</p>
<p>So here is the map.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-map">The map<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#the-map" class="hash-link" aria-label="The map的直接链接" title="The map的直接链接" translate="no">​</a></h2>
<table><thead><tr><th>Vector</th><th>Service</th><th>What it is for</th></tr></thead><tbody><tr><td><strong>10h</strong></td><td>Video BIOS</td><td>text and graphics output, the cursor, the palette, VESA/VBE</td></tr><tr><td><strong>13h</strong></td><td>Disk BIOS</td><td>sector reads and writes against the disk images</td></tr><tr><td><strong>16h</strong></td><td>Keyboard BIOS</td><td>keystrokes out of the BIOS keyboard buffer</td></tr><tr><td><strong>21h</strong></td><td>DOS</td><td>the DOS API: files, directories, memory, programs</td></tr><tr><td><strong>29h</strong></td><td>Fast console</td><td>character output with no DOS overhead at all</td></tr><tr><td><strong>2Ah</strong></td><td>Network redirector</td><td>"is there a network stack?"</td></tr><tr><td><strong>2Eh</strong></td><td>DOS shell</td><td>the emulator's own command shell</td></tr><tr><td><strong>2Fh</strong></td><td>Multiplex</td><td>the dispatcher for XMS, CD-ROM and other extensions</td></tr><tr><td><strong>33h</strong></td><td>Mouse</td><td>the DOS mouse driver</td></tr><tr><td><strong>67h</strong></td><td>EMS</td><td>expanded memory, and VCPI</td></tr><tr><td><strong>74h</strong></td><td>PS/2 mouse</td><td>IRQ 12, the mouse's hardware vector</td></tr><tr><td><strong>41h / 46h</strong></td><td>Disk parameter tables</td><td>the geometry of the disks</td></tr><tr><td><strong>1Fh / 43h / 44h</strong></td><td>Fonts</td><td>the 8×8 character blocks</td></tr><tr><td><strong>4Bh</strong></td><td>Virtual DMA</td><td>the VDMA channel API</td></tr><tr><td><strong>73h</strong></td><td>IPX ESR</td><td>the Novell network event service routine</td></tr></tbody></table>
<p>And the hardware side, where an IRQ number is <em>not</em> a vector number. The two 8259s have a vector base — <code>0x08</code> for the master, <code>0x70</code> for the slave — and the vector is computed when the interrupt is taken:</p>
<table><thead><tr><th>IRQ</th><th>Vector</th><th>Device</th></tr></thead><tbody><tr><td>0</td><td>08h</td><td>the PIT timer</td></tr><tr><td>1</td><td>09h</td><td>the keyboard</td></tr><tr><td>2</td><td>0Ah</td><td>the cascade to the slave PIC</td></tr><tr><td>6</td><td>0Eh</td><td>the PCjr keyboard</td></tr><tr><td>8</td><td>70h</td><td>the real-time clock</td></tr><tr><td>12</td><td>74h</td><td>the PS/2 mouse</td></tr><tr><td>3, 4, 5, 7, 10, 11</td><td>0Bh, 0Ch, 0Dh, 0Fh, 72h, 73h</td><td>everything else — masked and recorded</td></tr></tbody></table>
<p>The full map, with the function-code tables underneath each vector, is in the repository as <strong><a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/INTERRUPTS.md" target="_blank" rel="noopener noreferrer" class="">docs/INTERRUPTS.md</a></strong>. This article is the story behind it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-a-call-to-int-10h-becomes-a-c-function">How a call to INT 10h becomes a C function<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#how-a-call-to-int-10h-becomes-a-c-function" class="hash-link" aria-label="How a call to INT 10h becomes a C function的直接链接" title="How a call to INT 10h becomes a C function的直接链接" translate="no">​</a></h2>
<p>There is no central interrupt table in DOSBox. A service installs itself the way a real BIOS does: it writes the <strong>interrupt vector table</strong>, and the vector points at a stub.</p>
<p><code>INT n</code> executes opcode <code>0xCD</code>, lands in <code>CPU_Interrupt()</code>, and the CPU pushes flags, CS and EIP, clears the interrupt flag, and reads the new <code>CS:IP</code> out of the IVT at <code>base + (n &lt;&lt; 2)</code>. That is the real 8086 sequence, and DOSBox runs it for real — the guest's stack gets the same six bytes it would on hardware.</p>
<p>What the vector points at is not a handler but a <strong>stub</strong>: a few bytes of hand-assembled real-mode code whose shape is decided by a callback type. DOSBox's trick is a synthetic one-byte opcode — <code>FE 38</code> — that the CPU interpreter recognises and turns into a call to a registered C function.</p>
<p>The stubs are not decoration. Their shape is the behaviour:</p>
<ul>
<li class=""><strong>INT 16h spins.</strong> The stub is <code>IRET</code>, then twelve <code>NOP</code>s, then a jump back into the callback. When no key is buffered the handler adds one to <code>IP</code>, which lands it back on the NOP sled. The guest therefore <em>spins in real mode</em> until IRQ 1 delivers a key — exactly what real hardware does.</li>
<li class=""><strong>INT 21h pays a tax.</strong> Its stub contains a <code>loop</code> instruction: the emulated DOS service overhead, a few hundred cycles per call that a real 8086 would have spent.</li>
<li class=""><strong>INT 13h reports errors the BIOS way.</strong> Its stub ends with <code>IRET</code>, then <code>INT 0Eh</code>, then <code>IRET</code> — the classic "call INT 0Eh with AL=0" disk-error convention.</li>
</ul>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="int-33h-and-why-a-click-has-to-be-a-held-button">INT 33h, and why a click has to be a held button<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#int-33h-and-why-a-click-has-to-be-a-held-button" class="hash-link" aria-label="INT 33h, and why a click has to be a held button的直接链接" title="INT 33h, and why a click has to be a held button的直接链接" translate="no">​</a></h2>
<p>The mouse is the interesting one, and it is the one this port changed.</p>
<p><code>INT 33h</code> is a <code>switch</code> on <code>AX</code> with 35 implemented function codes. The two that matter here are <strong>AX=03h</strong>, which returns the cursor position and the button state, and <strong>AX=0Ch</strong>, which registers the game's event callback.</p>
<p>Here is the thing about AX=03h that I did not appreciate until I read the code. <code>mouse.buttons</code> is a <strong>level</strong>, not an edge. <code>Mouse_ButtonPressed()</code> sets a bit; <code>Mouse_ButtonReleased()</code> clears it; AX=03h hands the mask straight back:</p>
<div class="language-c codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-c codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token keyword" style="color:rgb(86, 156, 214)">case</span><span class="token plain"> </span><span class="token number" style="color:rgb(181, 206, 168)">0x03</span><span class="token operator" style="color:rgb(212, 212, 212)">:</span><span class="token plain">	</span><span class="token comment" style="color:rgb(106, 153, 85)">/* Return Position and Button Status */</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">    reg_bx</span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain">mouse</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">buttons</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">    reg_cx</span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain">POS_X</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">    reg_dx</span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain">POS_Y</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">    </span><span class="token keyword" style="color:rgb(86, 156, 214)">break</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><br></div></code></pre></div></div>
<p>A game that polls AX=03h every frame is asking <em>"is the button down right now?"</em> — not <em>"did a click happen?"</em>.</p>
<p>And that single fact determined the design of the touch layer.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="from-a-finger-to-a-dos-mouse">From a finger to a DOS mouse<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#from-a-finger-to-a-dos-mouse" class="hash-link" aria-label="From a finger to a DOS mouse的直接链接" title="From a finger to a DOS mouse的直接链接" translate="no">​</a></h2>
<p>The first version of this port did the obvious thing: a finger down was a press, a finger up was a release. A tap was a click.</p>
<p>That is wrong, and it was wrong in a way that only showed up in games. 三国志英杰传's battle UI reads the live button state. If the press and the release land between two of its polls, the game never sees the click. The cursor moves, the tap registers as nothing, and the player concludes the app is broken.</p>
<p>So the finger now holds the button down for exactly as long as it is on the glass:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">  SDL_FINGERDOWN        →  Mouse_ButtonPressed(0)   // LEFT, held</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  SDL_FINGERMOTION      →  move the cursor, button still held</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  SDL_FINGERUP          →  Mouse_ButtonReleased(0)</span><br></div></code></pre></div></div>
<p>A tap becomes a real held-then-released click. A drag becomes a real drag, because the cursor moves while the button is down.</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n7-pads-letters.png" alt="STARFALL running on the phone with the two console pads either side of the picture: the left pad carries the arrow keys and half a QWERTY, the right pad the action keys and the other half." width="900"></p>
<p align="center"><sub>The two pads, either side of the picture. The whole screen is the mouse.</sub></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-trap-that-ate-every-tap">The trap that ate every tap<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#the-trap-that-ate-every-tap" class="hash-link" aria-label="The trap that ate every tap的直接链接" title="The trap that ate every tap的直接链接" translate="no">​</a></h3>
<p>There was a second bug, and it was stranger. DOSBox captures the mouse when it goes fullscreen, which sets <code>sdl.mouse.locked</code>. With that flag set, <code>Mouse_CursorMoved()</code> <strong>ignores the absolute position</strong> and only accumulates relative movement.</p>
<p>On a desktop that is correct — a captured mouse is a relative device. On a phone there is no mouse to capture, and the consequence was that every tap was ignored and the cursor sat in the middle of the screen.</p>
<p>The measurement, before and after:</p>
<table><thead><tr><th></th><th>tap (700, 300)</th><th>tap (1500, 800)</th><th>tap (1000, 500)</th></tr></thead><tbody><tr><td>before</td><td>320, 100</td><td>320, 100</td><td>320, 100</td></tr><tr><td>after</td><td>97, 55</td><td>453, 148</td><td>231, 92</td></tr></tbody></table>
<p>The numbers are exact. <code>0.153 × 80 × 8 = 97</code> — the DOS text screen's 80 × 25 cells at 8 pixels each. A tap that was always landing on the same wrong cell now lands where you touched.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-right-button">The right button<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#the-right-button" class="hash-link" aria-label="The right button的直接链接" title="The right button的直接链接" translate="no">​</a></h3>
<p>A DOS mouse has two buttons. A touchscreen has one. And in most DOS games the right button is <em>cancel</em> or <em>back</em>, so losing it loses a whole category of interaction.</p>
<p>There is no long-press gesture and no context menu. Two mechanisms deliver it, and both are <strong>held</strong> buttons, exactly like the left one:</p>
<ul>
<li class=""><strong>A second finger</strong> on the picture. The left button is released first, so the two never overlap, and the right button is held until that finger lifts.</li>
<li class=""><strong>The on-screen <code>RMB</code> key</strong>, next to <code>Tab</code> on the left pad. It pushes a real <code>SDL_MOUSEBUTTONDOWN</code> for <code>SDL_BUTTON_RIGHT</code> into DOSBox's event queue through the JNI bridge, and the event flows through the same path as a mouse click.</li>
</ul>
<p>The second one is the interesting one, because it is not a gesture at all. It is a <em>different event type</em> injected into the queue the emulator already reads.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-drivers-state-lives-outside-the-guests-memory">The driver's state lives outside the guest's memory<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#the-drivers-state-lives-outside-the-guests-memory" class="hash-link" aria-label="The driver's state lives outside the guest's memory的直接链接" title="The driver's state lives outside the guest's memory的直接链接" translate="no">​</a></h2>
<p>Here is the bug that made me rewrite the save-state format twice.</p>
<p>The INT 33h driver's state lives in a <strong>host file-static struct</strong>, not in the emulated memory. Three pieces of it cannot be rebuilt by the guest after a restore:</p>
<ul>
<li class="">the event callback the game registered with <strong>AX=0Ch</strong> — the segment, the offset and the event mask;</li>
<li class="">the graphics cursor and its hotspot, from <strong>AX=09h</strong>;</li>
<li class="">the cursor range, the position, the visibility, the sensitivity.</li>
</ul>
<p>Without the first, the symptom is precise and nasty: <strong>the cursor still moves</strong> — DOSBox draws it — <strong>but the game's clicks stop reaching the game.</strong> A dialog's <em>confirm</em> button simply does nothing. The emulator looks alive; the game is deaf.</p>
<p>Without the second, the cursor reverts to the default white block drawn with a zero hotspot, so the <em>visible</em> cursor no longer lines up with the real click point, and taps land up and to the left of the target.</p>
<p>So the mouse driver had to become part of the save state. The first attempt saved the whole struct.</p>
<p><strong>That wedged the games.</strong> 三国志英杰传 hung on load, and stopped responding to clicks after a minute once the event queue filled behind a stuck re-entrancy flag. Feeding a stale event queue and a stale <code>in_UIR</code> back into the interrupt handler fed garbage into the game's own callback.</p>
<p>The fix was to learn the difference between two kinds of state:</p>
<blockquote>
<p><strong>Configuration is worth saving. Run-time state is poison.</strong></p>
</blockquote>
<p>The final form saves a dedicated <code>MouseStateBlock</code> holding only what the guest cannot rebuild — the callback triple, the cursor range and position, the hotspot, the cursor masks, the sensitivity. And on load it <strong>resets</strong> everything volatile: the event queue, the button and click counters, the re-entrancy flag, the cursor-draw backing store.</p>
<p>One more rule, and it is the host-pointer rule in miniature. The struct holds two <strong>host pointers</strong> — to the cursor bitmaps. They are never written to disk. They are <em>re-derived</em> from the saved cursor type after a load: a user-defined graphics cursor uses the restored masks, anything else uses the built-in arrow.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-same-rule-one-layer-down-the-pic">The same rule, one layer down: the PIC<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#the-same-rule-one-layer-down-the-pic" class="hash-link" aria-label="The same rule, one layer down: the PIC的直接链接" title="The same rule, one layer down: the PIC的直接链接" translate="no">​</a></h2>
<p>The interrupt controller has the same shape of problem, and the port reached the same answer.</p>
<p>A save state is a snapshot of a machine, and the machine includes its interrupt subsystem. <code>PIC_SaveState</code> and <code>PIC_LoadState</code> write the two controller structs — and then the loader deliberately does <em>not</em> restore all of it:</p>
<div class="language-c codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-c codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">	</span><span class="token comment" style="color:rgb(106, 153, 85)">/* Keep the game's interrupt MASK and configuration, but drop any stale</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">	 * pending/in-service state: a restored in-service bit would block all</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">	 * lower-priority IRQs (so the RTC that drives INT 15h/86h, and thus sound</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">	 * timing, would stall), and a stale request bit would fire a spurious IRQ.</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">	 * At the top-of-main-loop restore point no IRQ is genuinely mid-service. */</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">	pics</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">i</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">imrr </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token operator" style="color:rgb(212, 212, 212)">~</span><span class="token plain">pics</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">i</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">imr</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">	pics</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">i</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">irr </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token number" style="color:rgb(181, 206, 168)">0</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">	pics</span><span class="token punctuation" style="color:rgb(212, 212, 212)">[</span><span class="token plain">i</span><span class="token punctuation" style="color:rgb(212, 212, 212)">]</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token plain">isr </span><span class="token operator" style="color:rgb(212, 212, 212)">=</span><span class="token plain"> </span><span class="token number" style="color:rgb(181, 206, 168)">0</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><br></div></code></pre></div></div>
<p>The mask is the <em>configuration</em> — the guest's own decision about which interrupts it wants, and it survives. The in-service and request registers are <em>transient</em> — a leftover in-service bit wedges the priority chain, and a leftover request fires a spurious IRQ.</p>
<p>Keep the configuration. Drop the run-time state. The same sentence, twice, in two different subsystems, and both times it was learned by breaking it.</p>
<p>The format version moved as the design moved: <strong>8</strong> was "the whole mouse driver state", <strong>9</strong> was "slimmed to callback + range + position", <strong>10</strong> is "cursor shape, hotspot and the rest of the configuration". A format that changes meaning must change its version loudly, so that an older save is <em>refused</em> rather than misread.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-this-port-did-not-change">What this port did not change<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#what-this-port-did-not-change" class="hash-link" aria-label="What this port did not change的直接链接" title="What this port did not change的直接链接" translate="no">​</a></h2>
<p>The more surprising answer, and the one worth stating plainly: <strong>the BIOS interrupt layer is upstream code.</strong></p>
<p>Every file in <code>src/ints/</code> is untouched since the import, with one exception. <code>mouse.cpp</code> has five post-import commits; <code>int10.cpp</code> and its eight siblings, <code>bios.cpp</code>, <code>bios_disk.cpp</code>, <code>bios_keyboard.cpp</code>, <code>ems.cpp</code> and <code>xms.cpp</code> have none.</p>
<p>The same is true of the DOS layer. <code>src/dos/dos.cpp</code> — the whole INT 21h handler — <code>dos_misc.cpp</code>, <code>dos_classes.cpp</code> and <code>dos_memory.cpp</code> are byte-identical to the imported sources. The port's <strong>single</strong> intrusion into it is one line, and it is not about interrupts at all:</p>
<div class="language-c codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-c codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token function" style="color:rgb(220, 220, 170)">SegSet16</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">ds</span><span class="token punctuation" style="color:rgb(212, 212, 212)">,</span><span class="token plain">pspseg</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token function" style="color:rgb(220, 220, 170)">SegSet16</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">es</span><span class="token punctuation" style="color:rgb(212, 212, 212)">,</span><span class="token plain">pspseg</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token comment" style="color:rgb(106, 153, 85)">/* WhereQ: a guest program has taken over the machine, so the boot</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)"> * is over and a save-state request may be serviced. The shell</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)"> * itself never reaches its prompt in this case (it is blocked</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)"> * inside the program it started), so this is the only place where</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)"> * the save-state module learns that the guest is running. */</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token function" style="color:rgb(220, 220, 170)">SAVESTATE_GuestReady</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">;</span><br></div></code></pre></div></div>
<p>Even the bundle launcher rides the stock path. Each game gets a generated <code>RUN.BAT</code> that is appended to the emulator's <code>[autoexec]</code>; the guest then does <code>INT 21h AH=4Bh</code> to exec it, <code>AH=4Bh</code> again for the game's own <code>PLAY.BAT</code>, and <code>AH=4Ch</code> to exit. The port did not add a launcher API. It chose a filename and let DOS do the rest.</p>
<p>That is the shape of the whole port: the interesting work is almost never in the BIOS layer. It is in <strong>what sits above it</strong> — turning a finger into a mouse, a tap into a held button, and a game into something a save state can carry.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="watching-it-yourself">Watching it yourself<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#watching-it-yourself" class="hash-link" aria-label="Watching it yourself的直接链接" title="Watching it yourself的直接链接" translate="no">​</a></h2>
<p>The cheapest way to see this layer work is the <code>MOUSE</code> log group, enabled from <code>dosbox.conf</code>:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">[log]</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">logfile=/sdcard/dosbox.log</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">mouse=true</span><br></div></code></pre></div></div>
<p>The Android app ships no <code>[log]</code> section, so it is off by default. Once it is on, every INT 33h call that the driver does <em>not</em> implement is reported:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">Mouse Function 0018 not implemented!</span><br></div></code></pre></div></div>
<p>which is a direct read-out of what a game is asking for and what the driver does not answer. There is a commented-out line one function away that would print the AX, BX, CX and cursor position of <em>every</em> INT 33h call — the single most useful change a developer could make to this tree.</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — the source, the full interrupt map at <a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/INTERRUPTS.md" target="_blank" rel="noopener noreferrer" class=""><code>docs/INTERRUPTS.md</code></a>, and the technical reference behind it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Interrupts#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They kept it alive for three decades and gave it away to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which grew out of <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. The SDL2 library by <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> carries the window, the audio and the touch input.</p>
<p><strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>An emulator is a machine made of answers to questions nobody has asked yet. The interesting work is in deciding what the answer should be when the question arrives from a thumb.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>dos</category>
            <category>interrupts</category>
            <category>x86</category>
            <category>android</category>
            <category>emulator</category>
            <category>retro</category>
            <category>open-source</category>
            <category>whereq</category>
            <category>savestate</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.13：读档之后，存档还记得自己是什么时候存的]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN</guid>
            <pubDate>Wed, 18 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="刚刚">「刚刚」<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN#%E5%88%9A%E5%88%9A" class="hash-link" aria-label="「刚刚」的直接链接" title="「刚刚」的直接链接" translate="no">​</a></h2>
<p>午饭之后你回来接着打。点那个写着「五小时前」的档位。游戏原样回来了——那只大家伙、血条、你当时站着的那个房间，都在你离开时的样子。</p>
<p>然后档位上写着的是「<strong>刚刚</strong>」。</p>
<p>存档还是你存的那一份，游戏还是你走时的那一刻。只有时间在说谎，而且它撒的方向刚好是让这个应用显得不可信：它唯一该记住的事，它自己没记住。</p>
<p>1.0.0.13 的全部内容就是这个。这是我发过的最小的一版，修复也只有三行。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-save-states.jpg" alt="WhereQ-DOSBox 里 whereq-demo-bundle 的存档面板：档位 1 写着 2 hours ago，旁边是 Save 和 Load 两个按钮，档位 2 和档位 3 是空的。" width="900"></p>
<p align="center"><sub>存档面板。每个档位旁边的那一行字，就是这一版唯一要修的东西。</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="先说前提存档已经搬到应用外面了">先说前提：存档已经搬到应用外面了<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN#%E5%85%88%E8%AF%B4%E5%89%8D%E6%8F%90%E5%AD%98%E6%A1%A3%E5%B7%B2%E7%BB%8F%E6%90%AC%E5%88%B0%E5%BA%94%E7%94%A8%E5%A4%96%E9%9D%A2%E4%BA%86" class="hash-link" aria-label="先说前提：存档已经搬到应用外面了的直接链接" title="先说前提：存档已经搬到应用外面了的直接链接" translate="no">​</a></h2>
<p>这个 bug 得先说清楚存档放在哪儿才讲得通，因为 1.0.0.12 把它们搬走了，而那一版在这里一直没发过文章。简单交代一下。</p>
<p>在那之前，存档是应用私有目录里的一个文件。卸载应用——或者手机丢了、换手机了——所有存档跟着一起没。现在应用可以自己留一份在你手上的地方：在手机上选一个文件夹（<strong>Config → Saves folder</strong>，或者第一次存档之后弹出来的那个邀请），之后每个档位都会镜像到那里，压成 gzip，就放在游戏旁边。</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">  应用                              你选的那个文件夹</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  ──────                          ────────────────────</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  存档   ── gzip ──▶                STARFALL/</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                    slot1.gz</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                    slot2.gz</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                    bundle.zip      (游戏本身)</span><br></div></code></pre></div></div>
<p>于是重装、换手机、或者手滑删了应用，东西都能回来：游戏按名字 offer 给你恢复，它们的存档已经在那里了。同名的两个压缩包会按名字区分——<em>game</em> 和 <em>game (2)</em>——所以它们的存档不会混到同一个地方。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-files-panel.jpg" alt="WhereQ-DOSBox 的 Files 面板：Install a bundle 按钮、Install all bundles from a folder 按钮，以及 Ultima8 和 whereq-demo-bundle 两个游戏，每个都有 Play、Launch 和 Remove。" width="900"></p>
<p align="center"><sub>Files 面板：游戏列表，以及设置存档目录的 <b>Config</b> 按钮。</sub></p>
<p>而这次搬家，恰恰就是 bug 的来处。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="错在哪一行">错在哪一行<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN#%E9%94%99%E5%9C%A8%E5%93%AA%E4%B8%80%E8%A1%8C" class="hash-link" aria-label="错在哪一行的直接链接" title="错在哪一行的直接链接" translate="no">​</a></h2>
<p>本地那份档位不见了的时候——重装了、换手机了——应用会从镜像里把它重建出来。文件是新写出来的，于是带上了写的那一刻的时间戳。</p>
<p>启动器读的就是这个文件上的时间。于是五小时前存的档位，从镜像里恢复出来，就成了「刚刚」。</p>
<p>快照本身一点问题都没有，而且从来就没问题过：机器、声音芯片、DOS 文件句柄，全都原样回来了。错的只有那个标签。可这反而更糟，因为一个错的标签会让你开始怀疑底下的东西——你会怀疑这次恢复到底忠实不忠实，其实恢复完美无缺，撒谎的是日期。</p>
<p>修法是把时间跟着一块带过去。镜像知道这个档位究竟是什么时候存的，重建出来的本地文件现在拿到的就是这个时间，而不是当前时间：</p>
<div class="language-kotlin codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-kotlin codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">// Keep the original SAVE time: restoring rewrites the local file, so</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token comment" style="color:rgb(106, 153, 85)">// without this the slot would show "just now" after every load.</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token keyword" style="color:rgb(86, 156, 214)">if</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">ok</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token plain"> doc</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token function" style="color:rgb(220, 220, 170)">lastModified</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token function" style="color:rgb(220, 220, 170)">takeIf</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">{</span><span class="token plain"> it </span><span class="token operator" style="color:rgb(212, 212, 212)">&gt;</span><span class="token plain"> </span><span class="token number" style="color:rgb(181, 206, 168)">0L</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">}</span><span class="token operator" style="color:rgb(212, 212, 212)">?</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token function" style="color:rgb(220, 220, 170)">let</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">{</span><span class="token plain"> local</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token function" style="color:rgb(220, 220, 170)">setLastModified</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">it</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">}</span><br></div></code></pre></div></div>
<p>一行活儿，一行代码，档位于是又变回「5 小时前」。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="手机上的名字">手机上的名字<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN#%E6%89%8B%E6%9C%BA%E4%B8%8A%E7%9A%84%E5%90%8D%E5%AD%97" class="hash-link" aria-label="手机上的名字的直接链接" title="手机上的名字的直接链接" translate="no">​</a></h2>
<p>启动器名字、通知和桌面图标现在都带着这个项目自己的名字和标记：<strong>WhereQ-DOSBox</strong>。</p>
<p>包名是 <code>com.whereq.dosbox</code>，下载文件名是 <code>whereq-dosbox-1.0.0.13.apk</code>，所以这一版可以直接覆盖安装上一版——包名一样、签名密钥一样，不用先卸载。你的游戏和存档原地不动。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="你的存档还是读得出来">你的存档还是读得出来<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN#%E4%BD%A0%E7%9A%84%E5%AD%98%E6%A1%A3%E8%BF%98%E6%98%AF%E8%AF%BB%E5%BE%97%E5%87%BA%E6%9D%A5" class="hash-link" aria-label="你的存档还是读得出来的直接链接" title="你的存档还是读得出来的直接链接" translate="no">​</a></h2>
<p><strong>存档格式什么都没改。</strong> 修的是启动器，不是快照，所以之前各版本写下的存档都照常读得出来——文件布局仍然是版本 10，和当初把鼠标块精简成稳定配置之后那一版一样。</p>
<p>这比听起来更重要：一次悄悄改掉格式的发布，会留下一批再也打不开的存档。老实做法是——格式真变了就大声改，带版本号地改。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="拿去用">拿去用<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN#%E6%8B%BF%E5%8E%BB%E7%94%A8" class="hash-link" aria-label="拿去用的直接链接" title="拿去用的直接链接" translate="no">​</a></h2>
<p>发布版 APK 用发布密钥签名，可以直接覆盖安装上一版：</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.13</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">whereq-dosbox-1.0.0.13.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">size:   16 482 792 bytes</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: 98243e5577276d31f89adc1ac776bfc4242fdc0ff43f877bc36797c138cffa94</span><br></div></code></pre></div></div>
<p>它跑在 <strong>arm64-v8a、armeabi-v7a 和 x86_64</strong> 设备上，要求 Android 5.0 及以上，完全离线，不需要账号，没有任何追踪。项目采用 GPL-2.0 许可，DOSBox 核心连同它的 <code>AUTHORS</code>、<code>ChangeLog</code>、<code>COPYING</code> 和逐文件头注释一起嵌入。</p>
<p>再说一遍：<strong>这篇文章不是文档。</strong> 文档是仓库本身，而且现在是一份参考文档，不再是一堆笔记。请去读那份，而不是信我的一面之词。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="谢谢-dosbox">谢谢 DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13-CN#%E8%B0%A2%E8%B0%A2-dosbox" class="hash-link" aria-label="谢谢 DOSBox的直接链接" title="谢谢 DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> 写成——一群志愿者把 1994 年的一套操作系统改造到此后世界造出的每一台机器上都能跑，包括那些当时还不存在的机器。他们让它活过了三十年，并免费交给任何想要的人。WhereQ-DOSBox 只是建在他们工作之上的一层薄薄的壳。原创力、手艺和慷慨完全属于他们。</p>
<p>这个移植基于 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 做的 DOSBox r4305 的 Emscripten 版，它又来自 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 最早那次用 Emscripten 编译 DOSBox 的尝试，并且踩着 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 的 Emscripten 工作一路往前。窗口、音频和触摸输入则由 <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> 的 SDL2 库承担。</p>
<p><strong>DOSBox 是 DOSBox 项目的商标</strong>；这个移植与 DOSBox 团队没有任何隶属或背书关系。</p>
<hr>
<p><em>一个会谎报自己年龄的存档只是个小谎，而小谎正是工具失去信任的方式。如果你发现「继续」下面那个档位这一周一直写着「刚刚」——这一版就是你要的那一版。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>模拟器</category>
            <category>发布</category>
            <category>怀旧</category>
            <category>开源</category>
            <category>whereq</category>
            <category>存档</category>
            <category>存档目录</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.13: a restored save keeps the time it was made]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13</guid>
            <pubDate>Wed, 18 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="just-now">"Just now"<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13#just-now" class="hash-link" aria-label="&quot;Just now&quot;的直接链接" title="&quot;Just now&quot;的直接链接" translate="no">​</a></h2>
<p>You come back to the game after lunch. You tap the slot that said you saved it five hours ago. The game loads exactly where you left it — the boss, the health bar, the room you were in.</p>
<p>And the slot now says <em>"just now"</em>.</p>
<p>The save is the save you made. The game is the game you left. Only the timestamp lies, and it lies in the direction that makes the app feel like it cannot be trusted with the one thing it is supposed to remember.</p>
<p>That is the whole of 1.0.0.13. It is the smallest release I have shipped and the only one where the fix is three lines long.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-save-states.jpg" alt="The save-state sheet of WhereQ-DOSBox for the game whereq-demo-bundle: slot 1 says 2 hours ago and has Save and Load buttons, slots 2 and 3 are empty." width="900"></p>
<p align="center"><sub>The save-state sheet. The line next to each slot is the only thing this
release is about.</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="first-the-ground-moved-the-saves-live-outside-the-app-now">First, the ground moved: the saves live outside the app now<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13#first-the-ground-moved-the-saves-live-outside-the-app-now" class="hash-link" aria-label="First, the ground moved: the saves live outside the app now的直接链接" title="First, the ground moved: the saves live outside the app now的直接链接" translate="no">​</a></h2>
<p>The bug only makes sense once you know where the saves live, because 1.0.0.12 moved them and that release never got a post here. So, briefly.</p>
<p>Until then, a save state was a file in the app's own private storage. Uninstall the app — or lose the phone, or switch phones — and every save goes with it. The app can now keep a copy somewhere that is yours: pick a folder on the phone (<strong>Config → Saves folder</strong>, or the offer that appears after your first save), and every slot is mirrored there, gzipped, next to the game itself.</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">  the app                          the folder you picked</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  ──────                          ────────────────────</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  the slot   ── gzip ──▶             STARFALL/</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                     slot1.gz</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                     slot2.gz</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                     bundle.zip      (the game)</span><br></div></code></pre></div></div>
<p>So a reinstall, a new phone, or an app deleted by accident all come back: the games are offered for restore by name, and their save states are already there. Two archives with the same file name are told apart by name — <em>game</em> and <em>game (2)</em> — so their saves never end up in the same place.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-files-panel.jpg" alt="The Files panel of WhereQ-DOSBox: an Install a bundle button, an Install all bundles from a folder button, and the games Ultima8 and whereq-demo-bundle, each with Play, Launch and Remove." width="900"></p>
<p align="center"><sub>The Files panel: the games, and the <b>Config</b> button where the saves
folder is set.</sub></p>
<p>And that move is exactly where the bug comes from.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-line-that-was-wrong">The line that was wrong<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13#the-line-that-was-wrong" class="hash-link" aria-label="The line that was wrong的直接链接" title="The line that was wrong的直接链接" translate="no">​</a></h2>
<p>When the local copy of a slot is gone — a reinstall, a new phone — the app rebuilds it from the mirror. It writes the file, and a written file has a fresh timestamp: the moment of the write.</p>
<p>The launcher reads the time off that file. So a slot made five hours ago, restored from the mirror, came back labelled <em>"just now"</em>.</p>
<p>The snapshot itself was fine, and it was always fine: the machine, the sound chips, the DOS file handles, all of it came back exactly. Only the label was wrong. Which is worse in a way, because a wrong label makes you doubt the thing underneath it — you start wondering whether the restore was faithful, when the restore was perfect and the date was a lie.</p>
<p>The fix is to carry the time across with the state. The mirror knows when the slot was really saved; the rebuilt local file now gets that timestamp instead of the current one:</p>
<div class="language-kotlin codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-kotlin codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token comment" style="color:rgb(106, 153, 85)">// Keep the original SAVE time: restoring rewrites the local file, so</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token comment" style="color:rgb(106, 153, 85)">// without this the slot would show "just now" after every load.</span><span class="token plain"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token keyword" style="color:rgb(86, 156, 214)">if</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">ok</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token plain"> doc</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token function" style="color:rgb(220, 220, 170)">lastModified</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token function" style="color:rgb(220, 220, 170)">takeIf</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">{</span><span class="token plain"> it </span><span class="token operator" style="color:rgb(212, 212, 212)">&gt;</span><span class="token plain"> </span><span class="token number" style="color:rgb(181, 206, 168)">0L</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">}</span><span class="token operator" style="color:rgb(212, 212, 212)">?</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token function" style="color:rgb(220, 220, 170)">let</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">{</span><span class="token plain"> local</span><span class="token punctuation" style="color:rgb(212, 212, 212)">.</span><span class="token function" style="color:rgb(220, 220, 170)">setLastModified</span><span class="token punctuation" style="color:rgb(212, 212, 212)">(</span><span class="token plain">it</span><span class="token punctuation" style="color:rgb(212, 212, 212)">)</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(212, 212, 212)">}</span><br></div></code></pre></div></div>
<p>One line of work for one line of code, and the slot says <em>"5 hours ago"</em> again.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-name-on-the-phone">The name on the phone<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13#the-name-on-the-phone" class="hash-link" aria-label="The name on the phone的直接链接" title="The name on the phone的直接链接" translate="no">​</a></h2>
<p>The launcher name, the notification and the launcher icons carry the project's own name and mark: <strong>WhereQ-DOSBox</strong>.</p>
<p>The package is <code>com.whereq.dosbox</code> and the download is <code>whereq-dosbox-1.0.0.13.apk</code>, so this release installs over the previous one in place — same package, same signing key, no uninstalling first. Your games and your saves stay where they are.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="your-save-states-still-load">Your save states still load<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13#your-save-states-still-load" class="hash-link" aria-label="Your save states still load的直接链接" title="Your save states still load的直接链接" translate="no">​</a></h2>
<p><strong>Nothing about the save format changed.</strong> The fix is in the launcher, not in the snapshot, so every save state written by the earlier releases loads normally — the file layout is still version 10, the same one that has been in use since the mouse block was slimmed down.</p>
<p>That matters more than it sounds: a release that quietly changes the format would leave a generation of slots unopenable, and the honest thing is to change the format loudly, with a version bump, when it really changes.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="get-it">Get it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13#get-it" class="hash-link" aria-label="Get it的直接链接" title="Get it的直接链接" translate="no">​</a></h2>
<p>The release APK is signed with the release key, so it installs over the previous version in place:</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.13</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">whereq-dosbox-1.0.0.13.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">size:   16 482 792 bytes</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: 98243e5577276d31f89adc1ac776bfc4242fdc0ff43f877bc36797c138cffa94</span><br></div></code></pre></div></div>
<p>It runs on <strong>arm64-v8a, armeabi-v7a and x86_64</strong> devices, Android 5.0 and newer, entirely offline, with no account and no tracking. The project is GPL-2.0, and the DOSBox core is embedded with its <code>AUTHORS</code>, <code>ChangeLog</code>, <code>COPYING</code> and per-file headers intact.</p>
<p>Again, <strong>this post is not the documentation.</strong> The documentation is the repository, and it is a single reference document rather than a folder of notes. Please read that rather than take my word for it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.13#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They kept it alive for three decades and gave it away to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which grew out of <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. The SDL2 library by <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> carries the window, the audio and the touch input.</p>
<p><strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>A save state that lies about its own age is a small lie, and small lies are how a tool stops being trusted. If the slot under the "Resume" button has been saying "just now" all week — this is the release you want.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>emulator</category>
            <category>release</category>
            <category>retro</category>
            <category>open-source</category>
            <category>whereq</category>
            <category>savestate</category>
            <category>saves</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 使用指南：五分钟把 DOS 游戏装进手机]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN</guid>
            <pubDate>Wed, 18 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[{`]]></description>
            <content:encoded><![CDATA[<style>
/* The phone screenshots come in two shapes: 2400x1080 (landscape) and
 1080x2400 (portrait). Left at the full 715px column width, a portrait
 shot rendered 715x1588 - taller than the viewport - and the guide ran to
 roughly 24000px. Cap every screenshot in a 560px box instead, so both
 orientations stay legible and the article stops being a scroll marathon.
 The width cap stays relative, so the images still fit on a phone. */
.markdown img[src*='docs/screenshots/'] {
max-width: min(560px, 100%);
max-height: 560px;
width: auto;
height: auto;
}
</style>
<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="一份我想要却找不到的指南">一份我想要却找不到的指南<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E4%B8%80%E4%BB%BD%E6%88%91%E6%83%B3%E8%A6%81%E5%8D%B4%E6%89%BE%E4%B8%8D%E5%88%B0%E7%9A%84%E6%8C%87%E5%8D%97" class="hash-link" aria-label="一份我想要却找不到的指南的直接链接" title="一份我想要却找不到的指南的直接链接" translate="no">​</a></h2>
<p>在自己的手机上试用这个应用时，我注意到一件事：我读过的每一份 DOSBox 指南，作者都默认你已经知道 <code>.zip</code> 包是什么。他们直接从有意思的部分讲起——声音芯片、存档格式、JIT——然后假定你从 1994 年起就一直在用 DOS。</p>
<p>对大多数拿着手机的人来说，这个假定是错的。把老游戏搬上现代手机，难的从来不是模拟器，而是最初那五分钟：怎么把游戏<strong>弄进手机</strong>，而且是应用能启动的形状。</p>
<p>所以我干脆写了一份我想要的那一份。七个步骤，每一步都配一张真机截图，不假设你见过命令行。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="五分钟版本">五分钟版本<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E4%BA%94%E5%88%86%E9%92%9F%E7%89%88%E6%9C%AC" class="hash-link" aria-label="五分钟版本的直接链接" title="五分钟版本的直接链接" translate="no">​</a></h2>
<ol>
<li class="">安装应用（APK 在<a href="https://github.com/whereq/whereq-dosbox/releases" target="_blank" rel="noopener noreferrer" class="">发布页</a>）。</li>
<li class="">打开它，落到 <strong>Files</strong> 面板，里面是空的。</li>
<li class="">按 <strong>+ Install a bundle (.zip)</strong>，选一个 <code>.zip</code> 游戏文件。</li>
<li class="">按 <strong>Play</strong>，游戏就开始了。</li>
<li class="">随时按左上角的 <strong>File</strong> 回到列表。</li>
</ol>
<p>就这么多。下面全是这五步背后的细节——想弄明白在做什么就读，想直接玩就跳过。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="开始之前">开始之前<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E5%BC%80%E5%A7%8B%E4%B9%8B%E5%89%8D" class="hash-link" aria-label="开始之前的直接链接" title="开始之前的直接链接" translate="no">​</a></h2>
<table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>手机</td><td>Android 5.0 及以上，手机平板都行</td></tr><tr><td>空间</td><td>应用大约 60 MB，再加上游戏本身的大小</td></tr><tr><td>网络</td><td>应用和游戏都在手机上之后，不需要网络</td></tr><tr><td>账号</td><td>不需要</td></tr></tbody></table>
<p>你还需要<strong>一个游戏</strong>，单个 <code>.zip</code> 文件。这里说的「游戏」不是把你自己的文件打个 ZIP——往下看<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E6%B8%B8%E6%88%8F%E4%BB%8E%E5%93%AA%E6%9D%A5" class="">游戏从哪来？</a>。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第-1-步--安装应用">第 1 步 —— 安装应用<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E7%AC%AC-1-%E6%AD%A5--%E5%AE%89%E8%A3%85%E5%BA%94%E7%94%A8" class="hash-link" aria-label="第 1 步 —— 安装应用的直接链接" title="第 1 步 —— 安装应用的直接链接" translate="no">​</a></h2>
<p>应用不在源码仓库里。它由发布流水线构建，发布在<a href="https://github.com/whereq/whereq-dosbox/releases" target="_blank" rel="noopener noreferrer" class="">发布页</a>上，文件名是 <code>whereq-dosbox-&lt;version&gt;.apk</code>，旁边还有一个 <code>.sha256</code> 文件写着校验和。</p>
<p>把 <code>.apk</code> 拷到手机上——数据线、云盘、文件传输，随你——然后在手机上点它。Android 会问要不要允许这个应用安装，允许就行。</p>
<p>应用会出现在你的主屏幕上，就是那个 <strong><code>&gt;_</code> 标记</strong>：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-20-launcher-home-icon.png" alt="Android 主屏幕上的 WhereQ-DOSBox 图标，一个深色方块，中间是 >_ 提示符。" width="900"></p>
<p align="center"><sub>主屏幕上的 WhereQ-DOSBox 图标。</sub></p>
<p>应用列表里的名字、通知里的名字、Android 展示应用信息时写的名字，都写着 <strong>WhereQ-DOSBox</strong>：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-21-app-info.png" alt="WhereQ-DOSBox 的 Android 应用信息页：应用名、版本 1.0.0.13 和应用图标。" width="900"></p>
<p align="center"><sub>WhereQ-DOSBox 的 Android 应用信息页。</sub></p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第-2-步--安装游戏">第 2 步 —— 安装游戏<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E7%AC%AC-2-%E6%AD%A5--%E5%AE%89%E8%A3%85%E6%B8%B8%E6%88%8F" class="hash-link" aria-label="第 2 步 —— 安装游戏的直接链接" title="第 2 步 —— 安装游戏的直接链接" translate="no">​</a></h2>
<p>打开应用。你会落到 <strong>Files</strong> 面板——列出已安装内容的那个界面：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-01-files-panel-empty.png" alt="全新安装后空白的 WhereQ-DOSBox Files 面板，顶部是 Install a bundle (.zip) 按钮，下面是 Install all bundles from a folder 按钮。" width="900"></p>
<p align="center"><sub>全新安装后空白的 Files 面板。</sub></p>
<p>两种把游戏放进去的办法，都在面板顶部：</p>
<table><thead><tr><th>按钮</th><th>作用</th></tr></thead><tbody><tr><td><strong>+ Install a bundle (.zip)</strong></td><td>从手机里选一个 <code>.zip</code></td></tr><tr><td><strong>Install all bundles from a folder</strong></td><td>把某一个文件夹里的所有 <code>.zip</code> 一次解开</td></tr></tbody></table>
<p>按 <strong>+ Install a bundle (.zip)</strong>，系统的文件选择器会打开。选你的游戏 <code>.zip</code>——通常在 <strong>Downloads</strong> 里——应用会解开它并登记好。面板上就列出它了：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-02-files-panel.png" alt="Files 面板里有两个已安装的游戏，starfall-v2 和 F1，每个都带 Play、States、Launch 和 Remove 按钮。" width="900"></p>
<p align="center"><sub>Files 面板里有两个已安装的游戏。</sub></p>
<p>列表里每个游戏有四个按钮：</p>
<table><thead><tr><th>按钮</th><th>作用</th></tr></thead><tbody><tr><td><strong>Play</strong></td><td>从头开始运行游戏</td></tr><tr><td><strong>States</strong></td><td>为这个游戏存档、读档</td></tr><tr><td><strong>Launch…</strong></td><td>换一段程序来跑，或者在游戏前加载驱动文件</td></tr><tr><td><strong>Remove</strong></td><td>从应用里卸载这个游戏</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="游戏从哪来">游戏从哪来？<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E6%B8%B8%E6%88%8F%E4%BB%8E%E5%93%AA%E6%9D%A5" class="hash-link" aria-label="游戏从哪来？的直接链接" title="游戏从哪来？的直接链接" translate="no">​</a></h3>
<p>这里的游戏是一个形状固定的 <code>.zip</code>：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">  the bundle</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  ─────────</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  PLAY.BAT          the entry point - the app runs this</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  &lt;the game files&gt;  whatever the game needs</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  __meta.json       the name the app shows in the list</span><br></div></code></pre></div></div>
<p>就这些。仓库里附送了一个，你可以照着看形状、马上试起来：<a href="https://github.com/whereq/whereq-dosbox/tree/main/examples/game-bundle" target="_blank" rel="noopener noreferrer" class=""><code>examples/game-bundle</code></a>——就是 <strong>STARFALL</strong> 演示版。把那个文件夹里的 <code>whereq-demo-bundle.zip</code> 拷到手机上装上就行。</p>
<p>至于真正的游戏：还在托管这些废弃 DOS 游戏的站点，一般都直接给 <code>.zip</code>。如果某个游戏的压缩包里只有游戏文件、没有 <code>PLAY.BAT</code>，应用是起不来的——自己写一个 <code>PLAY.BAT</code> 去运行游戏的可执行文件，再把文件夹压一次。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第-3-步--开始玩">第 3 步 —— 开始玩<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E7%AC%AC-3-%E6%AD%A5--%E5%BC%80%E5%A7%8B%E7%8E%A9" class="hash-link" aria-label="第 3 步 —— 开始玩的直接链接" title="第 3 步 —— 开始玩的直接链接" translate="no">​</a></h2>
<p>按 <strong>Play</strong>。</p>
<p>模拟器会重启应用并引导游戏启动，你落到 DOS 提示符：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-03-dos-boot-prompt.png" alt="DOSBox 欢迎画面和 C:\> 提示符，下方是屏幕键盘。" width="900"></p>
<p align="center"><sub>DOSBox 欢迎画面和 <code>C:\&gt;</code> 提示符，下方是屏幕键盘。</sub></p>
<p>输入游戏的名字，按 <strong>Enter</strong>。从这一刻起就是真正的游戏了——真正的键盘，真正的声音，真正的鼠标。</p>
<p>这是一款 1994 年的 DOS 游戏跑在手机上的样子：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-04-game-f1-menu.png" alt="Formula 1（Domark，1994）跑在手机上，四周是屏幕键盘。" width="900"></p>
<p align="center"><sub>Formula 1（Domark，1994）跑在手机上，四周是屏幕键盘。</sub></p>
<p>这是 STARFALL 演示版：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-05-game-starfall-title.png" alt="STARFALL 的标题画面。" width="900"></p>
<p align="center"><sub>STARFALL 的标题画面。</sub></p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-06-game-starfall-play.png" alt="STARFALL 正在游戏中，画面两侧是两块键盘区。" width="900"></p>
<p align="center"><sub>STARFALL 正在游戏中，画面两侧是两块键盘区。</sub></p>
<p>第一次运行游戏时，Android 可能会问要不要允许这个应用发通知。它用通知来提醒你「游戏还在后台」。答哪边都行——拒绝只是少一条提醒：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-19-notification-permission.png" alt="Android 的通知权限对话框：Allow WhereQ-DOSBox to send you notifications?" width="900"></p>
<p align="center"><sub>Android 的通知权限对话框。</sub></p>
<p>游戏在跑的时候，按左上角的 <strong>File</strong> 会把 Files 面板拉到上层，面板上会给正在跑的那个游戏显示一行 <strong>Resume</strong>：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-02b-files-panel-resume.png" alt="游戏运行中拉出的 Files 面板，列表上方有一行 Resume F1。" width="900"></p>
<p align="center"><sub>游戏运行中拉出的 Files 面板，列表上方有 <b>Resume F1</b>。</sub></p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第-4-步--键盘和鼠标">第 4 步 —— 键盘和鼠标<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E7%AC%AC-4-%E6%AD%A5--%E9%94%AE%E7%9B%98%E5%92%8C%E9%BC%A0%E6%A0%87" class="hash-link" aria-label="第 4 步 —— 键盘和鼠标的直接链接" title="第 4 步 —— 键盘和鼠标的直接链接" translate="no">​</a></h2>
<p>不用外接实体键盘，因为屏幕键盘<strong>就是</strong>键盘。横屏时画面两侧会出现两块键盘区，像掌机那样摆：左边是方向键组成的十字键加半边 QWERTY，右边是动作键（Alt、Ctrl、Shift、Space、Enter）和另外半边字母。</p>
<p>两个键可以切换键盘区显示的内容：</p>
<table><thead><tr><th>键</th><th>显示</th></tr></thead><tbody><tr><td><strong>#+=</strong></td><td>标点层</td></tr><tr><td><strong>Fn</strong></td><td>F1–F12、Ins/Del、Home/End、PgUp/PgDn、Caps、PrtSc、Pause</td></tr></tbody></table>
<p>切换之后，那个键会亮着。</p>
<p><strong>修饰键有两种用法。</strong> <em>点一下</em> Ctrl、Alt 或 Shift，它会保持按下状态等你按下一个键——先 Ctrl 再 C。<em>按住</em>它，它的表现就和一个真正的键一样：手指按着多久它就保持多久，游戏里那些开火键、侧移键正是这么用的，另一只拇指同时操控方向。</p>
<p><strong>鼠标就是屏幕本身。</strong> 你的手指就是鼠标：拖动是移动指针，点一下是点击，屏幕上的 <strong>RMB</strong> 键（左边那块，紧挨 <strong>Tab</strong>）是鼠标右键——在大多数 DOS 游戏里那代表<em>取消</em>或<em>返回</em>。在画面上<strong>按住第二根手指</strong>也是同一个意思，而且是在那根手指自己的位置上。</p>
<p>把手机转成竖屏，两块键盘区会折成底部的一条，适合画面高比宽大的游戏。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第-5-步--存档">第 5 步 —— 存档<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E7%AC%AC-5-%E6%AD%A5--%E5%AD%98%E6%A1%A3" class="hash-link" aria-label="第 5 步 —— 存档的直接链接" title="第 5 步 —— 存档的直接链接" translate="no">​</a></h2>
<p><strong>存档</strong>是把整台机器冻住：CPU、内存、显存、声卡芯片、打开着的 DOS 文件句柄，全都冻住。读档之后，游戏正好停在你离开时的样子——哪怕中间应用被关掉过。</p>
<p>按 <strong>File</strong>，再按游戏旁边的 <strong>States</strong>：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-07-save-states-empty.png" alt="Save states 面板，三个空档位。" width="900"></p>
<p align="center"><sub>Save states 面板，三个空档位。</sub></p>
<p>一共有三个档位。按 <strong>Save</strong> 把当前游戏冻进档位 1，面板会告诉你是什么时候存的：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-13-save-states-slot.png" alt="Save states 面板里已存的档位：档位 1 写着两分钟前，带 Save 和 Load 按钮。" width="900"></p>
<p align="center"><sub>已存的档位——档位 1，两分钟前。</sub></p>
<p>关掉面板，Files 面板会为这个游戏保留一行 <strong>Resume</strong>，写明是哪个档位、什么时候存的：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-10-files-panel-resume-slot.png" alt="Files 面板上有一行绿色的 Resume starfall-v2 - slot 1 - just now。" width="900"></p>
<p align="center"><sub><b>Resume starfall-v2 · slot 1 · just now</b>。</sub></p>
<p><strong>Load</strong> 把游戏放回去。档位能撑过退出应用，也能撑过手机重启。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第-6-步--让存档更安全">第 6 步 —— 让存档更安全<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E7%AC%AC-6-%E6%AD%A5--%E8%AE%A9%E5%AD%98%E6%A1%A3%E6%9B%B4%E5%AE%89%E5%85%A8" class="hash-link" aria-label="第 6 步 —— 让存档更安全的直接链接" title="第 6 步 —— 让存档更安全的直接链接" translate="no">​</a></h2>
<p>存档默认放在应用自己的私有存储里。卸载应用时 Android 会把它删掉——手机丢了、换手机了，也一样。你的游戏和你的存档跟着一起没。</p>
<p>所以应用会问你一次：要不要在你自己掌管的地方再留一份：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-08-saves-offer.png" alt="Keep your saves safe 提示，首次存档后出现，带 Choose folder 按钮。" width="900"></p>
<p align="center"><sub>首次存档后出现的 <b>Keep your saves safe</b> 提示。</sub></p>
<p>应用自己的对话框里也是同一套说法，随时可以打开看：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-14-saves-folder-unset.png" alt="Saves folder 对话框，尚未设置任何文件夹，带 Choose folder 和 Close 按钮。" width="900"></p>
<p align="center"><sub>Saves folder 对话框，尚未设置任何文件夹。</sub></p>
<p>按 <strong>Choose folder</strong>，系统会问要不要允许这个应用访问手机上的某个文件夹：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-09-folder-permission.png" alt="Android 的文件夹访问授权对话框，带 Use this folder 和 Allow 按钮。" width="900"></p>
<p align="center"><sub>系统对文件夹的授权对话框。</sub></p>
<p>选好文件夹，按 <strong>USE THIS FOLDER</strong>，再按 <strong>ALLOW</strong>。从这以后每个档位都会压缩一份镜像到那个文件夹里，就放在游戏旁边。</p>
<p>你随时可以在 <strong>Config → Saves folder</strong> 下查看或更换这个文件夹：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-11-settings-dialog.png" alt="WhereQ-DOSBox 的设置对话框。" width="900"></p>
<p align="center"><sub>设置对话框。</sub></p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-12-saves-folder-dialog.png" alt="Saves folder 对话框，已经设置好文件夹。" width="900"></p>
<p align="center"><sub>Saves folder 对话框，已经设置好文件夹。</sub></p>
<p>两点提醒：</p>
<ul>
<li class="">Android 不允许应用直接占用整个 <strong>Download</strong> 文件夹，那个权限太宽了。挑别的文件夹就行——<strong>Documents</strong> 完全可以。</li>
<li class="">你只需要回答这一次，应用不会再问。</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第-7-步--重装之后或者换了新手机">第 7 步 —— 重装之后，或者换了新手机<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E7%AC%AC-7-%E6%AD%A5--%E9%87%8D%E8%A3%85%E4%B9%8B%E5%90%8E%E6%88%96%E8%80%85%E6%8D%A2%E4%BA%86%E6%96%B0%E6%89%8B%E6%9C%BA" class="hash-link" aria-label="第 7 步 —— 重装之后，或者换了新手机的直接链接" title="第 7 步 —— 重装之后，或者换了新手机的直接链接" translate="no">​</a></h2>
<p>这就是那个文件夹的用处。</p>
<p>把应用卸载，重新装上，选同一个文件夹。应用会进去一看，你的游戏还在——它们从来就不在应用里面：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-15-durable-folder-contents.png" alt="应用卸载之后，手机上那个文件夹里的内容：游戏包和已保存的档位。" width="900"></p>
<p align="center"><sub>应用卸载之后，手机上那个文件夹里的内容。</sub></p>
<p>应用会认出那些没被安装的游戏，问你要不要把它们带回来：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-16-restore-games-offer.png" alt="Restore games 提示，询问是否把未安装的游戏带回来。" width="900"></p>
<p align="center"><sub><b>Restore games</b> 提示。</sub></p>
<p>按 <strong>Restore</strong>，它们连名字带存档一起回来：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-17-games-restored.png" alt="Files 面板里恢复出来的两个游戏，存档也在。" width="900"></p>
<p align="center"><sub>恢复出来的两个游戏，存档也在。</sub></p>
<p>而存档仍然记得自己是什么时候存的：</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-18-save-states-restored-slot.png" alt="恢复出来的存档档位，仍然写着三分钟前。" width="900"></p>
<p align="center"><sub>恢复出来的档位，仍然写着三分钟前。</sub></p>
<p>最后这一行就是整个功能的意义所在。三分钟前存的存档，就写着三分钟前——哪怕它是从文件夹里重新装回一个新装的版本。</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="东西都放在哪里">东西都放在哪里<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E4%B8%9C%E8%A5%BF%E9%83%BD%E6%94%BE%E5%9C%A8%E5%93%AA%E9%87%8C" class="hash-link" aria-label="东西都放在哪里的直接链接" title="东西都放在哪里的直接链接" translate="no">​</a></h2>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">  inside the app                    the folder you picked</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  ────────────                      ───────────────────</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  the games                         &lt;your folder&gt;/</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  the save-state slots                &lt;game name&gt;/</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                       slot1.gz</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                       slot2.gz</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                       bundle.zip</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  gone when the app is removed     stays until you delete it</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="出问题了怎么办">出问题了怎么办<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E5%87%BA%E9%97%AE%E9%A2%98%E4%BA%86%E6%80%8E%E4%B9%88%E5%8A%9E" class="hash-link" aria-label="出问题了怎么办的直接链接" title="出问题了怎么办的直接链接" translate="no">​</a></h2>
<table><thead><tr><th>你看到的</th><th>意味着</th><th>怎么办</th></tr></thead><tbody><tr><td><em>「That save file is damaged」</em></td><td>这个档位是旧版本写的</td><td>存档格式升过版本号，太旧的档位会被拒绝而不是读错。重新存一个新档位。</td></tr><tr><td>游戏起不来</td><td>包里没有 <code>PLAY.BAT</code>，或者入口指错了</td><td>打开那个 <code>.zip</code>，确认 <code>PLAY.BAT</code> 能运行游戏的可执行文件</td></tr><tr><td>按 <strong>Play</strong> 没动静</td><td>模拟器正在重启来引导游戏</td><td>等几秒——进程是故意重启的，游戏会在新进程里起来</td></tr><tr><td>键盘挡住了画面</td><td>两块键盘区占了画面两侧</td><td>把手机转成竖屏，键盘会折成底部一条</td></tr><tr><td>鼠标点不动</td><td>游戏要的是「按住」状态</td><td>拖动用来移动；右键用屏幕上的 <strong>RMB</strong> 键，或者在画面上按住第二根手指</td></tr><tr><td><strong>Download</strong> 文件夹选不了</td><td>Android 不允许应用占用整个 Download</td><td>换一个文件夹，比如 <strong>Documents</strong></td></tr><tr><td>弹出通知授权</td><td>应用想发「回到游戏」的通知</td><td>允许或拒绝都行——拒绝只是少这条通知</td></tr><tr><td>游戏很卡</td><td>模拟器跑的是当年的硬件，不是快机器</td><td>这是 1994 年那台机器本来的速度，不是手机慢</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="接下来">接下来<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E6%8E%A5%E4%B8%8B%E6%9D%A5" class="hash-link" aria-label="接下来的直接链接" title="接下来的直接链接" translate="no">​</a></h2>
<p>这篇就是指南。仓库里存着同一份文档，以及它背后的一切：</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong>——源码、示例包、问题追踪，指南本身在 <a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/USER-GUIDE.md" target="_blank" rel="noopener noreferrer" class=""><code>docs/USER-GUIDE.md</code></a>。</p>
<p>**<a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/TECHNICAL-REFERENCE.md" target="_blank" rel="noopener noreferrer" class="">技术参考</a>**是长文——原生构建怎么做、存档机制怎么把整台机器拍下来、FM 芯片怎么被精确还原、包怎么变成一个跑起来的 DOS 程序、屏幕键盘怎么把按键送进模拟器、以及构建流水线。它是写给工程师看的，不是给拿着手机的人看的。</p>
<p>**<a href="https://github.com/whereq/whereq-dosbox/releases" target="_blank" rel="noopener noreferrer" class="">发布页</a>**上有 APK 和它的校验和。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="致谢-dosbox">致谢 DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide-CN#%E8%87%B4%E8%B0%A2-dosbox" class="hash-link" aria-label="致谢 DOSBox的直接链接" title="致谢 DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> 写成——一群志愿者把 1994 年的一套操作系统改造到此后世界造出的每一台机器上都能跑，包括那些当时还不存在的机器。他们让它活过了三十年，并免费交给任何想要的人。WhereQ-DOSBox 只是建在他们工作之上的一层薄薄的壳。原创力、手艺和慷慨完全属于他们。</p>
<p>这个移植基于 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 做的 DOSBox r4305 的 Emscripten 版，它又来自 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 最早那次用 Emscripten 编译 DOSBox 的尝试，并且踩着 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 的 Emscripten 工作一路往前。窗口、音频和触摸输入则由 <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> 的 SDL2 库承担。</p>
<p><strong>DOSBox 是 DOSBox 项目的商标</strong>；这个移植与 DOSBox 团队没有任何隶属或背书关系。</p>
<hr>
<p><em>上面每一张截图都是真机，跑的是正式签名的 APK。这里没有任何一张是效果图。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>模拟器</category>
            <category>指南</category>
            <category>复古</category>
            <category>开源</category>
            <category>whereq</category>
            <category>存档</category>
            <category>保存</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox user guide: put a DOS game on your phone in five minutes]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide</guid>
            <pubDate>Wed, 18 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[{`]]></description>
            <content:encoded><![CDATA[<style>
/* The phone screenshots come in two shapes: 2400x1080 (landscape) and
 1080x2400 (portrait). Left at the full 715px column width, a portrait
 shot rendered 715x1588 - taller than the viewport - and the guide ran to
 roughly 24000px. Cap every screenshot in a 560px box instead, so both
 orientations stay legible and the article stops being a scroll marathon.
 The width cap stays relative, so the images still fit on a phone. */
.markdown img[src*='docs/screenshots/'] {
max-width: min(560px, 100%);
max-height: 560px;
width: auto;
height: auto;
}
</style>
<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-guide-i-wanted-and-could-not-find">The guide I wanted and could not find<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#the-guide-i-wanted-and-could-not-find" class="hash-link" aria-label="The guide I wanted and could not find的直接链接" title="The guide I wanted and could not find的直接链接" translate="no">​</a></h2>
<p>Here is a thing I noticed while I was testing the app on my own phone. Every DOSBox guide I have ever read was written by somebody who already knew what a <code>.zip</code> bundle was. They start at the interesting part — the sound chips, the save-state format, the JIT — and assume you have been running DOS since 1994.</p>
<p>That assumption is wrong for most people holding a phone. The hardest part of putting an old game on a modern phone is not the emulator. It is the first five minutes: getting the game <em>onto</em> the phone at all, in a shape the app can start.</p>
<p>So I wrote the guide I wanted instead. Seven steps, one screenshot of every screen, and no assumption that you have ever seen a command prompt.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-five-minute-version">The five-minute version<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#the-five-minute-version" class="hash-link" aria-label="The five-minute version的直接链接" title="The five-minute version的直接链接" translate="no">​</a></h2>
<ol>
<li class="">Install the app. The APK is on the <a href="https://github.com/whereq/whereq-dosbox/releases" target="_blank" rel="noopener noreferrer" class="">releases page</a>.</li>
<li class="">Open it. You land on the <strong>Files</strong> panel, and it is empty.</li>
<li class="">Press <strong>+ Install a bundle (.zip)</strong> and pick a <code>.zip</code> game file.</li>
<li class="">Press <strong>Play</strong>. The game starts.</li>
<li class="">Press <strong>File</strong> (top left) whenever you want to come back to the list.</li>
</ol>
<p>That is the whole thing. Everything below is the detail behind those five steps — read it if you want to understand what you are doing, skip it if you just want to play.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="before-you-start">Before you start<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#before-you-start" class="hash-link" aria-label="Before you start的直接链接" title="Before you start的直接链接" translate="no">​</a></h2>
<table><thead><tr><th></th><th></th></tr></thead><tbody><tr><td>Phone</td><td>Android 5.0 or newer, any phone or tablet</td></tr><tr><td>Space</td><td>about 60 MB for the app, plus the size of the game</td></tr><tr><td>Network</td><td>none needed once the app and the game are on the phone</td></tr><tr><td>Account</td><td>none</td></tr></tbody></table>
<p>You also need <strong>a game</strong>, as a single <code>.zip</code> file. A game for this app is not the same thing as a ZIP of your own files — see <a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#where-do-i-get-a-game" class="">Where do I get a game?</a> below.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-1--install-the-app">Step 1 — Install the app<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#step-1--install-the-app" class="hash-link" aria-label="Step 1 — Install the app的直接链接" title="Step 1 — Install the app的直接链接" translate="no">​</a></h2>
<p>The app is not in the source repository. It is built by the release pipeline and published on the <a href="https://github.com/whereq/whereq-dosbox/releases" target="_blank" rel="noopener noreferrer" class="">releases page</a> as <code>whereq-dosbox-&lt;version&gt;.apk</code>, with a <code>.sha256</code> file next to it carrying the checksum.</p>
<p>Copy the <code>.apk</code> to your phone — cable, cloud drive, a file-sharing app, whatever is at hand — then tap it on the phone. Android asks whether to allow installing from that app; allow it, and the install goes through.</p>
<p>The app appears on your home screen as the <strong><code>&gt;_</code> mark</strong>:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-20-launcher-home-icon.png" alt="An Android home screen with the WhereQ-DOSBox icon, a dark square carrying the >_ prompt mark." width="900"></p>
<p align="center"><sub>The WhereQ-DOSBox icon on the home screen.</sub></p>
<p>The name in the app list, the notification, and the screen Android shows for the app all read <strong>WhereQ-DOSBox</strong>:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-21-app-info.png" alt="The Android App info page for WhereQ-DOSBox: the app name, version 1.0.0.13, and the app icon." width="900"></p>
<p align="center"><sub>The Android App info page for WhereQ-DOSBox.</sub></p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-2--install-a-game">Step 2 — Install a game<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#step-2--install-a-game" class="hash-link" aria-label="Step 2 — Install a game的直接链接" title="Step 2 — Install a game的直接链接" translate="no">​</a></h2>
<p>Open the app. You land in the <strong>Files</strong> panel — the screen that lists what you have installed:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-01-files-panel-empty.png" alt="The Files panel of WhereQ-DOSBox on a fresh install, empty, with an Install a bundle (.zip) button at the top and the Install all bundles from a folder button below it." width="900"></p>
<p align="center"><sub>The Files panel on a fresh install, with no games yet.</sub></p>
<p>Two ways to get a game in, both at the top of the panel:</p>
<table><thead><tr><th>button</th><th>what it does</th></tr></thead><tbody><tr><td><strong>+ Install a bundle (.zip)</strong></td><td>pick one <code>.zip</code> from your phone</td></tr><tr><td><strong>Install all bundles from a folder</strong></td><td>unpack every <code>.zip</code> in one folder at once</td></tr></tbody></table>
<p>Press <strong>+ Install a bundle (.zip)</strong>, and the system's file picker opens. Pick your game's <code>.zip</code> — usually in <strong>Downloads</strong> — and the app unpacks it and registers it. The panel then lists it:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-02-files-panel.png" alt="The Files panel with two games installed, starfall-v2 and F1, each with Play, States, Launch and Remove buttons." width="900"></p>
<p align="center"><sub>The Files panel with two games installed.</sub></p>
<p>Each game in the list has four buttons:</p>
<table><thead><tr><th>button</th><th>what it does</th></tr></thead><tbody><tr><td><strong>Play</strong></td><td>start the game from the beginning</td></tr><tr><td><strong>States</strong></td><td>save and load save states for this game</td></tr><tr><td><strong>Launch…</strong></td><td>run a different program, or add driver files, before the game</td></tr><tr><td><strong>Remove</strong></td><td>uninstall this game from the app</td></tr></tbody></table>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-do-i-get-a-game">Where do I get a game?<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#where-do-i-get-a-game" class="hash-link" aria-label="Where do I get a game?的直接链接" title="Where do I get a game?的直接链接" translate="no">​</a></h3>
<p>A game for this app is a <code>.zip</code> with a small, fixed shape:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">  the bundle</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  ─────────</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  PLAY.BAT          the entry point - the app runs this</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  &lt;the game files&gt;  whatever the game needs</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  __meta.json       the name the app shows in the list</span><br></div></code></pre></div></div>
<p>That is it. The repository ships one, so you can see the shape and try the app immediately: <a href="https://github.com/whereq/whereq-dosbox/tree/main/examples/game-bundle" target="_blank" rel="noopener noreferrer" class=""><code>examples/game-bundle</code></a> — the <strong>STARFALL</strong> demo. Copy <code>whereq-demo-bundle.zip</code> from that folder to your phone and install it.</p>
<p>For real games: sites that still host abandonware DOS games generally offer them as a <code>.zip</code>. If a game's archive contains the game files but no <code>PLAY.BAT</code>, the app cannot start it — make a <code>PLAY.BAT</code> that runs the game's executable, and zip the folder again.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-3--play-the-game">Step 3 — Play the game<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#step-3--play-the-game" class="hash-link" aria-label="Step 3 — Play the game的直接链接" title="Step 3 — Play the game的直接链接" translate="no">​</a></h2>
<p>Press <strong>Play</strong>.</p>
<p>The emulator restarts the app and boots the game, and you land at a DOS prompt:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-03-dos-boot-prompt.png" alt="The DOSBox welcome banner and the C:\> prompt, with the on-screen keyboard below it." width="900"></p>
<p align="center"><sub>The DOSBox welcome banner and the <code>C:\&gt;</code> prompt, with the on-screen
keyboard below it.</sub></p>
<p>Type the game's name and press <strong>Enter</strong>. From then on it is the real game — the real keyboard, the real sound, the real mouse.</p>
<p>Here is a real 1994 DOS game running on a phone:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-04-game-f1-menu.png" alt="Formula 1 (Domark, 1994) running on the phone, with the on-screen keyboard around it." width="900"></p>
<p align="center"><sub>Formula 1 (Domark, 1994) running on the phone, with the on-screen keyboard
around it.</sub></p>
<p>And here is the STARFALL demo:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-05-game-starfall-title.png" alt="The STARFALL title screen." width="900"></p>
<p align="center"><sub>The STARFALL title screen.</sub></p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-06-game-starfall-play.png" alt="STARFALL being played, with the two keyboard pads beside the picture." width="900"></p>
<p align="center"><sub>STARFALL being played, with the two keyboard pads beside the picture.</sub></p>
<p>The first time a game runs, Android may ask whether the app may send you notifications. It uses them for a "back to the game" reminder when you leave the app. Answer either way — declining only means you lose that reminder:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-19-notification-permission.png" alt="The Android notification permission prompt: Allow WhereQ-DOSBox to send you notifications?" width="900"></p>
<p align="center"><sub>The Android notification permission prompt.</sub></p>
<p>When a game is running, the <strong>File</strong> key (top left) brings the Files panel back over it, and the panel shows a <strong>Resume</strong> line for the game that is running right now:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-02b-files-panel-resume.png" alt="The Files panel over a running game, with a Resume F1 line above the list." width="900"></p>
<p align="center"><sub>The Files panel over a running game, with <b>Resume F1</b> above the list.</sub></p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-4--the-keyboard-and-the-mouse">Step 4 — The keyboard and the mouse<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#step-4--the-keyboard-and-the-mouse" class="hash-link" aria-label="Step 4 — The keyboard and the mouse的直接链接" title="Step 4 — The keyboard and the mouse的直接链接" translate="no">​</a></h2>
<p>There is no physical keyboard in the way, because the screen keyboard <em>is</em> the keyboard. In landscape you get two pads beside the picture, the way a handheld console is built: the <strong>left pad</strong> has the arrow keys as a D-pad and the left half of a split QWERTY, the right pad has the action keys (Alt, Ctrl, Shift, Space, Enter) and the right half of the alphabet.</p>
<p>Two keys change what the pads show:</p>
<table><thead><tr><th>key</th><th>shows</th></tr></thead><tbody><tr><td><strong>#+=</strong></td><td>the punctuation layer</td></tr><tr><td><strong>Fn</strong></td><td>F1–F12, Ins/Del, Home/End, PgUp/PgDn, Caps, PrtSc, Pause</td></tr></tbody></table>
<p>The switched key lights up while its layer is on.</p>
<p><strong>Modifiers work two ways.</strong> <em>Tap</em> Ctrl, Alt or Shift and it stays armed for the next key — Ctrl, then C. <em>Hold</em> it and it behaves like a real key for as long as your finger is down, which is what a game expects of its fire and strafe keys while the other thumb steers.</p>
<p><strong>The mouse is the screen.</strong> Your finger is the mouse: drag to move the pointer, tap to click, and the on-screen <strong>RMB</strong> key (on the left pad, next to <strong>Tab</strong>) is the right mouse button — in most DOS games that is <em>cancel</em> or <em>back</em>. A <strong>second finger</strong> on the picture does the same, at that finger's own position.</p>
<p>Turn the phone to portrait and the pads fold into a single strip along the bottom, for the games that are taller than they are wide.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-5--save-a-state">Step 5 — Save a state<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#step-5--save-a-state" class="hash-link" aria-label="Step 5 — Save a state的直接链接" title="Step 5 — Save a state的直接链接" translate="no">​</a></h2>
<p>A <strong>save state</strong> is the whole machine frozen: the CPU, the memory, the video memory, the sound chips, the open DOS file handles. Load it and the game is exactly where you left it — even if the app was closed in between.</p>
<p>Press <strong>File</strong>, then <strong>States</strong> next to the game:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-07-save-states-empty.png" alt="The Save states sheet, with three empty slots." width="900"></p>
<p align="center"><sub>The Save states sheet, with three empty slots.</sub></p>
<p>There are three slots. Press <strong>Save</strong> to freeze the game into slot 1, and the sheet shows when you did it:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-13-save-states-slot.png" alt="The Save states sheet with a saved slot: Slot 1 says two minutes ago and has Save and Load buttons." width="900"></p>
<p align="center"><sub>The sheet with a saved slot — Slot 1, two minutes ago.</sub></p>
<p>Close the sheet and the Files panel carries a <strong>Resume</strong> line for the game, naming the slot and the moment it was made:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-10-files-panel-resume-slot.png" alt="The Files panel with a green Resume starfall-v2 - slot 1 - just now line above the list." width="900"></p>
<p align="center"><sub>The Files panel with <b>Resume starfall-v2 · slot 1 · just now</b>.</sub></p>
<p><strong>Load</strong> puts the game back. A slot survives quitting the app and rebooting the phone.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-6--keep-your-saves-safe">Step 6 — Keep your saves safe<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#step-6--keep-your-saves-safe" class="hash-link" aria-label="Step 6 — Keep your saves safe的直接链接" title="Step 6 — Keep your saves safe的直接链接" translate="no">​</a></h2>
<p>A save state normally lives inside the app's own private storage. Android deletes that when you uninstall the app — and when you lose the phone, or switch phones. Your games and your saves go with it.</p>
<p>So the app asks, once, whether you want a second copy somewhere that is yours:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-08-saves-offer.png" alt="The Keep your saves safe prompt, offering a Choose folder button, shown after the first save." width="900"></p>
<p align="center"><sub>The <b>Keep your saves safe</b> prompt, after the first save.</sub></p>
<p>The app says the same thing in its own dialog, which you can open at any time:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-14-saves-folder-unset.png" alt="The Saves folder dialog with no folder set yet, with Choose folder and Close buttons." width="900"></p>
<p align="center"><sub>The Saves folder dialog, with no folder set yet.</sub></p>
<p>Press <strong>Choose folder</strong>, and the system asks you to allow the app into a folder on your phone:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-09-folder-permission.png" alt="The Android system permission dialog for the folder, with Use this folder and Allow buttons." width="900"></p>
<p align="center"><sub>The system permission dialog for the folder.</sub></p>
<p>Pick a folder, press <strong>USE THIS FOLDER</strong>, and press <strong>ALLOW</strong>. From then on every slot is mirrored into that folder, compressed, next to the game itself.</p>
<p>You can see, and change, the folder at any time under <strong>Config → Saves folder</strong>:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-11-settings-dialog.png" alt="The Settings dialog of WhereQ-DOSBox." width="900"></p>
<p align="center"><sub>The Settings dialog.</sub></p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-12-saves-folder-dialog.png" alt="The Saves folder dialog, with a folder set." width="900"></p>
<p align="center"><sub>The Saves folder dialog, with a folder set.</sub></p>
<p>Two notes:</p>
<ul>
<li class="">Android refuses to let an app take the <strong>Download</strong> folder itself, because that would be too broad a permission. Pick any other folder — <strong>Documents</strong> is fine.</li>
<li class="">You only have to answer this once. The app does not ask again.</li>
</ul>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="step-7--after-a-reinstall-or-on-a-new-phone">Step 7 — After a reinstall, or on a new phone<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#step-7--after-a-reinstall-or-on-a-new-phone" class="hash-link" aria-label="Step 7 — After a reinstall, or on a new phone的直接链接" title="Step 7 — After a reinstall, or on a new phone的直接链接" translate="no">​</a></h2>
<p>This is what the folder is for.</p>
<p>Uninstall the app, install it again, and choose the same folder. The app looks inside it and finds your games — they are still there, because they were never inside the app:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-15-durable-folder-contents.png" alt="The durable folder on the phone after the app was uninstalled, holding the game bundles and the saved slots." width="900"></p>
<p align="center"><sub>The folder on the phone after the app was uninstalled.</sub></p>
<p>The app notices the games that are not installed and offers to bring them back:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-16-restore-games-offer.png" alt="The Restore games prompt, offering to bring the games that are not installed back." width="900"></p>
<p align="center"><sub>The <b>Restore games</b> prompt.</sub></p>
<p>Press <strong>Restore</strong>, and they come back with their names and their saves:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-17-games-restored.png" alt="Two restored games in the Files panel, with their saves ready." width="900"></p>
<p align="center"><sub>Restored two games, with their saves ready.</sub></p>
<p>And the save state still knows when it was made:</p>
<p align="center"><img src="https://raw.githubusercontent.com/whereq/whereq-dosbox/main/docs/screenshots/android-n8-18-save-states-restored-slot.png" alt="The restored save-state slot, still saying three minutes ago." width="900"></p>
<p align="center"><sub>The restored slot, still saying three minutes ago.</sub></p>
<p>That last line is the point of the whole feature. A save that was made three minutes ago says <em>three minutes ago</em>, even after it was rebuilt from the folder on a fresh install.</p>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-everything-lives">Where everything lives<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#where-everything-lives" class="hash-link" aria-label="Where everything lives的直接链接" title="Where everything lives的直接链接" translate="no">​</a></h2>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">  inside the app                    the folder you picked</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  ────────────                      ───────────────────</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  the games                         &lt;your folder&gt;/</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  the save-state slots                &lt;game name&gt;/</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                       slot1.gz</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                       slot2.gz</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">                                       bundle.zip</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">  gone when the app is removed     stays until you delete it</span><br></div></code></pre></div></div>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="if-something-goes-wrong">If something goes wrong<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#if-something-goes-wrong" class="hash-link" aria-label="If something goes wrong的直接链接" title="If something goes wrong的直接链接" translate="no">​</a></h2>
<table><thead><tr><th>what you see</th><th>what it means</th><th>what to do</th></tr></thead><tbody><tr><td><em>"That save file is damaged"</em></td><td>the slot was written by an older version</td><td>the save format grew a version; older slots are refused rather than misread. Start a new slot.</td></tr><tr><td>The game does not start</td><td>the bundle has no <code>PLAY.BAT</code>, or the entry point is wrong</td><td>open the <code>.zip</code> and check that <code>PLAY.BAT</code> runs the game's executable</td></tr><tr><td>Nothing happens when you tap <strong>Play</strong></td><td>the emulator is restarting to boot the game</td><td>wait a few seconds — the process restarts on purpose, and the game starts in the new process</td></tr><tr><td>The keyboard is in the way</td><td>the pads take the sides of the screen</td><td>turn the phone to portrait for a single strip along the bottom</td></tr><tr><td>The mouse does not click</td><td>the game wants the mouse <em>held</em></td><td>drag for movement; the on-screen <strong>RMB</strong> key, or a second finger on the picture, is the right button</td></tr><tr><td>You cannot pick the <strong>Download</strong> folder</td><td>Android will not grant an app the whole Download folder</td><td>pick another folder, such as <strong>Documents</strong></td></tr><tr><td>You get a notification prompt</td><td>the app wants to show the "back to the game" notification</td><td>allow it or decline it — you can decline, you just lose that notification</td></tr><tr><td>The game is slow</td><td>the emulator runs the original hardware, not a fast one</td><td>it is what the 1994 machine did. It is not the phone being slow.</td></tr></tbody></table>
<hr>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="where-to-go-next">Where to go next<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#where-to-go-next" class="hash-link" aria-label="Where to go next的直接链接" title="Where to go next的直接链接" translate="no">​</a></h2>
<p>This post is the guide. The repository holds the same document, plus everything behind it:</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — the source, the example bundle, the issues, and the guide itself at <a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/USER-GUIDE.md" target="_blank" rel="noopener noreferrer" class=""><code>docs/USER-GUIDE.md</code></a>.</p>
<p>The <strong><a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/TECHNICAL-REFERENCE.md" target="_blank" rel="noopener noreferrer" class="">technical reference</a></strong> is the long one — how the native build works, how the save-state machine takes a snapshot of the whole machine, the exact FM snapshot, the bundle launcher, the on-screen keyboard, the build pipeline. It is written for engineers, not for phone holders.</p>
<p>The <strong><a href="https://github.com/whereq/whereq-dosbox/releases" target="_blank" rel="noopener noreferrer" class="">releases page</a></strong> carries the APK and its checksum.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-User-Guide#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They kept it alive for three decades and gave it away to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which grew out of <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. The SDL2 library by <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> carries the window, the audio and the touch input.</p>
<p><strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>Every screenshot above is a real phone, running the release-signed APK. Nothing here is a mock-up.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>emulator</category>
            <category>guide</category>
            <category>retro</category>
            <category>open-source</category>
            <category>whereq</category>
            <category>savestate</category>
            <category>saves</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.10：声音也活过了存档]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN</guid>
            <pubDate>Tue, 17 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="那段留在后面的音乐">那段留在后面的音乐<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E9%82%A3%E6%AE%B5%E7%95%99%E5%9C%A8%E5%90%8E%E9%9D%A2%E7%9A%84%E9%9F%B3%E4%B9%90" class="hash-link" aria-label="那段留在后面的音乐的直接链接" title="那段留在后面的音乐的直接链接" translate="no">​</a></h2>
<p>你在 boss 打到一半的时候按了存档。音乐正响，那只大家伙正在做一件让人难受的事，你把手机放下，去回一条消息。</p>
<p>两分钟后你回来，读档。</p>
<p>战斗和你离开时一模一样——怪物、血条、它的坐标，样样都对。可音乐完全不在同一条时间线上：它从来没有跟机器一起被冻住，于是一切都倒回去了，它还在往前放。而 PC 喇叭那头的哔哔声还在后台嗡嗡地响，谁也不理。</p>
<p>那是 1.0.0.9。存档做得很好，好到只差一样东西：声音。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="存档存的是一台机器不是一块屏幕">存档存的是一台机器，不是一块屏幕<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E5%AD%98%E6%A1%A3%E5%AD%98%E7%9A%84%E6%98%AF%E4%B8%80%E5%8F%B0%E6%9C%BA%E5%99%A8%E4%B8%8D%E6%98%AF%E4%B8%80%E5%9D%97%E5%B1%8F%E5%B9%95" class="hash-link" aria-label="存档存的是一台机器，不是一块屏幕的直接链接" title="存档存的是一台机器，不是一块屏幕的直接链接" translate="no">​</a></h2>
<p>存档本来应该存下整台机器：CPU、内存、显存、打开的 DOS 文件句柄、硬件定时器。少了机器的任何一个部件，读回来就只是一台略有不同的机器——而这一次，你听得出来。</p>
<p>FM 芯片根本不在快照里。不是存得不准、不是存得不全——是压根没有。</p>
<p>这比听上去更糟，因为游戏冻住的时候芯片并不会跟着停。游戏运行中读档，模拟器会把它知道的一切倒回去：怪物、血条、那只大家伙的坐标、DOS 文件句柄、定时器。芯片不在它知道的那一串里，于是它继续放下去。你眼前是一场被倒带的战斗，耳朵里却是没有倒带的音乐。</p>
<p>如果这份存档是被恢复进一个全新的进程里——也就是关掉应用之后再按<strong>继续</strong>时发生的事——那芯片是崭新的、空白、哑的，音乐直接就没了。</p>
<p>PC 喇叭坏得又是第三种方式。它<strong>确实</strong>在快照里，可它是个实时输出设备，它排队的延迟和定时器索引被按着<strong>当前</strong>时钟恢复，而不是被保存时的那台机器的时钟——于是混音器继续发出一个客人根本没要求过的蜂鸣。它带着嗡声回来了。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="精确在这里是什么意思">「精确」在这里是什么意思<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E7%B2%BE%E7%A1%AE%E5%9C%A8%E8%BF%99%E9%87%8C%E6%98%AF%E4%BB%80%E4%B9%88%E6%84%8F%E6%80%9D" class="hash-link" aria-label="「精确」在这里是什么意思的直接链接" title="「精确」在这里是什么意思的直接链接" translate="no">​</a></h2>
<p>修法是把芯片本身整个存下来，而不是存它的摘要。OPL 的状态是<strong>一个</strong>大约五千字节的结构体：每个运算单元的包络、波形相位、LFO 计数器、反馈历史。它被写进状态文件、再读回来，于是下一个采样点从上一个采样点停下的地方接着走。</p>
<p>还有一种更省事的做法，值得说清楚它为什么不够用。这个移植留着芯片的 512 个寄存器——驱动把音色写进去的那些——读档时可以重放它们。这能把音色完美地重建出来。但驱动在一首曲子的开头把音色编好，之后只发「按下」和「松开」；在这中间发生的一切都活在<strong>芯片内部</strong>，没有任何一个寄存器记录得了。于是重放寄存器就等于把每一个音符都从攻击段重新触发。音回来了，却回错了：它从头开始，而不是从原来的地方接着走。</p>
<p>所以寄存器重放还在，作为那些无法快照自己的 OPL 模型的兜底。但它现在只是兜底，不再是主方案。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="我是怎么验的">我是怎么验的<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E6%88%91%E6%98%AF%E6%80%8E%E4%B9%88%E9%AA%8C%E7%9A%84" class="hash-link" aria-label="我是怎么验的的直接链接" title="我是怎么验的的直接链接" translate="no">​</a></h2>
<p>我让自己相信这件事成立的方式，是我希望自己被说服的方式：写一个测试程序，在 FM 芯片上编出<strong>一个持续的长音</strong>，然后等一个按键。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-opl-test.png" alt="WhereQ-DOSBox 在安卓手机横屏下运行 OPL 测试包：上方是 DOSBox 欢迎画面，下方终端里显示 OPL test: one sustained tone on the FM chip. Save a state, wait, load it - the tone must not restart. 以及 The tone is playing. Press any key to stop it." width="900"></p>
<p align="center"><sub>OPL 测试包：一个持续的长音，以及一行提示——存一个档，等一等，再读回来。</sub></p>
<p>这个测试包就在仓库里，你也可以自己跑。屏幕上就写着它是什么：<em>"The tone is playing. Press any key to stop it."</em></p>
<p>然后这个移植在存档时把芯片的状态打进日志，读档时再打一遍，两边必须对得上——同样的包络、同样的波形相位、同样的 LFO 计数器、同样的寄存器内容。</p>
<p>这是相隔两分钟真实芯片时间的存档日志和读档日志：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">savestate: OPL chip saved:    ... phase=d96f49ac ... active=36 lfo=000b228c opl3=0</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">savestate: OPL module saved:  exact=1 mode=2 regs=62/512 r20=31 r23=31 r40=3f ...</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">savestate: OPL chip restored: ... phase=d96f49ac ... active=36 lfo=000b228c opl3=0</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">savestate: OPL module restored: exact=1 mode=2 regs=62/512 r20=31 r23=31 r40=3f ...</span><br></div></code></pre></div></div>
<p>一模一样。音从攻击段中间接上，继续响。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="有件事你得知道">有件事你得知道<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E6%9C%89%E4%BB%B6%E4%BA%8B%E4%BD%A0%E5%BE%97%E7%9F%A5%E9%81%93" class="hash-link" aria-label="有件事你得知道的直接链接" title="有件事你得知道的直接链接" translate="no">​</a></h2>
<p><strong>1.0.0.9 写下的存档，1.0.0.10 读不了了。</strong></p>
<p>声音芯片进了快照之后，状态文件多了一个版本号，读档端现在会<strong>拒绝</strong>旧存档，而不是硬把它读错。这才是诚实的做法——一个能读、但声音读错的存档，比一个直接说「不行」的存档更糟糕。</p>
<p>如果你手上有 1.0.0.9 留下的存档在意，升级之前先读出来。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="一个一直按着的键">一个一直按着的键<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E4%B8%80%E4%B8%AA%E4%B8%80%E7%9B%B4%E6%8C%89%E7%9D%80%E7%9A%84%E9%94%AE" class="hash-link" aria-label="一个一直按着的键的直接链接" title="一个一直按着的键的直接链接" translate="no">​</a></h2>
<p>按着某个键的时候转屏，那个键会永远按在 DOSBox 里。旋转之后布局要重建，而重建出来的布局没有告诉模拟器「手指已经抬起来了」，于是那个键一直按着，DOSBox 就一直重复它。</p>
<p>现在，布局重建时，所有处于按下状态的键都会被释放。</p>
<p>还有另一半。<strong>Ctrl</strong> 同时出现在两个地方——手柄区和折叠面板上——而代码默认它上面永远只有一根手指，于是在一处松开会把另一处也取消掉。现在它会数手指。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="塞得下的启动器">塞得下的启动器<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E5%A1%9E%E5%BE%97%E4%B8%8B%E7%9A%84%E5%90%AF%E5%8A%A8%E5%99%A8" class="hash-link" aria-label="塞得下的启动器的直接链接" title="塞得下的启动器的直接链接" translate="no">​</a></h2>
<p><strong>Files</strong> 面板现在会量一量自己有多少空间，再据此限制游戏列表的数量。以前装到第三个游戏，按钮会被挤出面板底边——掉下去就再也捞不回来了。</p>
<p>这是这一版里最小的改动，也是我最恼火它没在前三个版本里就发生的一个。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="桌面版又能链接了">桌面版又能链接了<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E6%A1%8C%E9%9D%A2%E7%89%88%E5%8F%88%E8%83%BD%E9%93%BE%E6%8E%A5%E4%BA%86" class="hash-link" aria-label="桌面版又能链接了的直接链接" title="桌面版又能链接了的直接链接" translate="no">​</a></h2>
<p>存档相关的代码从来没被加进 autotools 的构建里，所以那个桌面基线——也就是那个能在笔记本上几秒钟编完、用来盯着模拟器内核别走偏的构建——从 1.0.0.8 引入存档开始就链接不过了。</p>
<p>我为这件事蒙了整整两个版本，因为我忙着发安卓版，一直没顾上。</p>
<p>原因有四条，彼此独立，但其实是同一类：构建里漏了一个源文件、少了一个头文件、一个函数本来该被条件编译掉、以及同一个静态库被连着列了两次——那是一个循环依赖，换个顺序才会暴露。</p>
<p>现在基线又能编译链接，也能跑。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="一份文档而不是一本流水账">一份文档，而不是一本流水账<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E4%B8%80%E4%BB%BD%E6%96%87%E6%A1%A3%E8%80%8C%E4%B8%8D%E6%98%AF%E4%B8%80%E6%9C%AC%E6%B5%81%E6%B0%B4%E8%B4%A6" class="hash-link" aria-label="一份文档，而不是一本流水账的直接链接" title="一份文档，而不是一本流水账的直接链接" translate="no">​</a></h2>
<p>仓库过去有一个 <code>porting/</code> 目录：一份移植日志、一些跑分笔记、一份键盘设计说明，还有一个日志文件。还在写移植的时候它们很有用；写完之后就没用了，因为那是<strong>按时间顺序记下来的东西</strong>——你得先知道事情发生的先后，才知道现在哪一条是真的。</p>
<p>现在只剩<strong>一份</strong>参考文档：<a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/TECHNICAL-REFERENCE.md" target="_blank" rel="noopener noreferrer" class=""><code>docs/TECHNICAL-REFERENCE.md</code></a>。整个实现都在这一个地方——原生构建和 ABI 矩阵、存档机制和它的文件格式、精确的 FM 快照、快照里的 DOS 层、启动器、屏幕键盘、吞吐跑分、还有哪些东西没被拍进去，以及这个移植拍下的每一张截图，都带着源码引用。</p>
<p>流水账没有消失，它变成了章节。历史仍然在 git log 里，那本来就是历史该待的地方。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="安卓移植结束了">安卓移植结束了<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E5%AE%89%E5%8D%93%E7%A7%BB%E6%A4%8D%E7%BB%93%E6%9D%9F%E4%BA%86" class="hash-link" aria-label="安卓移植结束了的直接链接" title="安卓移植结束了的直接链接" translate="no">​</a></h2>
<p>这一版带了一个不是版本号的标签：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">milestone/android-migration-complete</span><br></div></code></pre></div></div>
<p>它是带注释的，曾经指向这一版的提交（这个标记后来移到了 v1.0.0.13），而且<strong>故意</strong>落在发布脚本能理解的 <code>vX.Y.Z.A</code> 格式之外，所以脚本永远不会再把它当成一次发布捡起来。</p>
<p>它标记的是一个阶段，不是一个版本。安卓移植已经完成：模拟器核心能为三个 ABI 编译，应用层在真机上跑得动，存档装得下整台机器——包括声音——桌面基线也能链接了。接下来是<strong>维护</strong>：修 bug 和打磨文档。没有新功能的计划。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="拿去用">拿去用<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E6%8B%BF%E5%8E%BB%E7%94%A8" class="hash-link" aria-label="拿去用的直接链接" title="拿去用的直接链接" translate="no">​</a></h2>
<p>发布版 APK 就在仓库里，用发布密钥签名，可以直接覆盖安装 1.0.0.9：</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.10</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">downloads/whereq-dosbox-1.0.0.10.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: 80bdce1b4bdeba809159310441e450e704f6c322e2a3ff98bcc822ed50077018</span><br></div></code></pre></div></div>
<p>GitHub Release 上另有一份由流水线在干净机器上构建的产物，旁边带着它自己的 SHA-256 文件。</p>
<p>它跑在 <strong>arm64-v8a、armeabi-v7a 和 x86_64</strong> 设备上，要求 Android 5.0 及以上，完全离线，不需要账号，没有任何追踪。项目采用 GPL-2.0 许可，DOSBox 核心连同它的 <code>AUTHORS</code>、<code>ChangeLog</code>、<code>COPYING</code> 和逐文件头注释一起嵌入。</p>
<p>再说一遍：<strong>这篇文章不是文档。</strong> 文档是仓库本身，而且现在是一份参考文档，不再是一堆笔记。请去读那份，而不是信我的一面之词。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="谢谢-dosbox">谢谢 DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10-CN#%E8%B0%A2%E8%B0%A2-dosbox" class="hash-link" aria-label="谢谢 DOSBox的直接链接" title="谢谢 DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> 写成——一群志愿者把 1994 年的一套操作系统改造到此后世界造出的每一台机器上都能跑，包括那些当时还不存在的机器。他们让它活过了三十年，并免费交给任何想要的人。WhereQ-DOSBox 只是建在他们工作之上的一层薄薄的壳。原创力、手艺和慷慨完全属于他们。</p>
<p>这个移植基于 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 做的 DOSBox r4305 的 Emscripten 版，它又来自 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 最早那次用 Emscripten 编译 DOSBox 的尝试，并且踩着 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 的 Emscripten 工作一路往前。窗口、音频和触摸输入则由 <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> 的 SDL2 库承担。</p>
<p><strong>DOSBox 是 DOSBox 项目的商标</strong>；这个移植与 DOSBox 团队没有任何隶属或背书关系。</p>
<hr>
<p><em>一个听不见的存档只能算半个存档。正是这件事让我给一颗声音芯片写了个测试程序。如果你的存档读回来时音乐对不上——或者干脆没了——这一版就是你要的那一版。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>模拟器</category>
            <category>发布</category>
            <category>怀旧</category>
            <category>开源</category>
            <category>whereq</category>
            <category>存档</category>
            <category>声音</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.10: the sound survives the save state]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10</guid>
            <pubDate>Tue, 17 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-music-that-stayed-behind">The music that stayed behind<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#the-music-that-stayed-behind" class="hash-link" aria-label="The music that stayed behind的直接链接" title="The music that stayed behind的直接链接" translate="no">​</a></h2>
<p>You freeze a game in the middle of a fight. The music is loud, the boss is doing something unpleasant, and you put the phone down to answer a message.</p>
<p>You come back two minutes later and load the state.</p>
<p>The fight is exactly where you left it — the sprites, the health bar, the position of the boss, all of it. The music, though, is somewhere else entirely: it was never frozen with the rest of the machine, so it carried on playing while everything else went back. And the beeping that was coming out of the PC speaker is still going on in the background, droning at nobody.</p>
<p>That was 1.0.0.9. The snapshot was very good, and it was missing the sound.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-save-state-is-a-machine-not-a-screen">A save state is a machine, not a screen<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#a-save-state-is-a-machine-not-a-screen" class="hash-link" aria-label="A save state is a machine, not a screen的直接链接" title="A save state is a machine, not a screen的直接链接" translate="no">​</a></h2>
<p>A save state is supposed to be the whole machine: the CPU, the memory, the video memory, the open DOS file handles, the hardware timers. If one part of the machine is missing from the snapshot, the machine you come back to is a slightly different machine, and you can hear it.</p>
<p>The FM chip was not in the snapshot. Not badly, not approximately — not at all.</p>
<p>That is worse than it sounds, because the chip does not stop while the game is frozen. Load a state while the game is running and the emulator rewinds everything it knows about: the sprites, the health bar, the boss's coordinates, the DOS file handles, the timers. The chip is not among the things it knows, so it keeps playing. You are looking at a fight that has been rewound, and listening to music that has not.</p>
<p>And if the state is restored into a fresh process — which is what the <strong>Resume</strong> button does after the app has been closed — the chip is new, blank and silent, and the music is simply gone.</p>
<p>The PC speaker was a third kind of broken. It <em>was</em> in the snapshot, but it is a real-time output device, and its queued delays and its timer indices were restored against the current clock rather than the saved one — so the mixer carried on emitting a beep the guest had never asked for. It came back droning.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-exactly-means-here">What "exactly" means here<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#what-exactly-means-here" class="hash-link" aria-label="What &quot;exactly&quot; means here的直接链接" title="What &quot;exactly&quot; means here的直接链接" translate="no">​</a></h2>
<p>The fix is to snapshot the chip itself — the whole thing, not a summary of it. The OPL's state is a single struct of about five kilobytes: the envelope of every operator, the wave phase, the LFO counters, the feedback history. It is written into the state file and read back, so the next sample continues from where the last one stopped.</p>
<p>There is a cheaper version of this, and it is worth explaining why it is not enough. The port keeps a copy of the chip's 512 registers — the ones the driver wrote its instruments into — and a restore can replay them. That rebuilds the instruments perfectly. But a driver programs its instruments once at the start of a song and then only says <em>key on</em> and <em>key off</em>; everything that happens in between lives <strong>inside</strong> the chip, where no register records it. Replaying the registers therefore re-triggers every note from its attack. The tone comes back — but it comes back wrong: it starts again instead of continuing where it was.</p>
<p>So the register replay is still here, as the fallback for the OPL models that cannot snapshot themselves. But it is a fallback now, not the plan.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="how-i-checked-it">How I checked it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#how-i-checked-it" class="hash-link" aria-label="How I checked it的直接链接" title="How I checked it的直接链接" translate="no">​</a></h2>
<p>The way I convinced myself this works is the way I would want to be convinced: I wrote a test program that programs <strong>one sustained tone</strong> on the FM chip and then waits for a key.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-opl-test.png" alt="WhereQ-DOSBox on an Android phone running the OPL test bundle: the DOSBox welcome screen at the top, and in the terminal the lines OPL test: one sustained tone on the FM chip. Save a state, wait, load it - the tone must not restart. and The tone is playing. Press any key to stop it." width="900"></p>
<p align="center"><sub>The OPL test bundle: one sustained tone, and an instruction to save a
state, wait, and load it again.</sub></p>
<p>The bundle is in the repository, so you can run it yourself. It says what it is on the screen: <em>"The tone is playing. Press any key to stop it."</em></p>
<p>Then the port writes the chip's state to the log when it saves, and writes it again when it loads, and the two have to match — same envelope, same wave phase, same LFO counter, same register contents.</p>
<p>Here they are, two minutes of live chip time apart:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">savestate: OPL chip saved:    ... phase=d96f49ac ... active=36 lfo=000b228c opl3=0</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">savestate: OPL module saved:  exact=1 mode=2 regs=62/512 r20=31 r23=31 r40=3f ...</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">savestate: OPL chip restored: ... phase=d96f49ac ... active=36 lfo=000b228c opl3=0</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">savestate: OPL module restored: exact=1 mode=2 regs=62/512 r20=31 r23=31 r40=3f ...</span><br></div></code></pre></div></div>
<p>Identical. The tone picked up in the middle of its attack and carried on.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="one-consequence-you-should-know-about">One consequence you should know about<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#one-consequence-you-should-know-about" class="hash-link" aria-label="One consequence you should know about的直接链接" title="One consequence you should know about的直接链接" translate="no">​</a></h2>
<p><strong>Save states written by 1.0.0.9 cannot be loaded by 1.0.0.10.</strong></p>
<p>The state file grew a version when the sound chips became part of the snapshot, and the loader now <em>refuses</em> an older state rather than misreading it. That is the honest behaviour — a state that loads but plays the wrong sound is worse than a state that says no.</p>
<p>If you have save states from 1.0.0.9 that you care about, load them before you update.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-key-that-stayed-down">A key that stayed down<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#a-key-that-stayed-down" class="hash-link" aria-label="A key that stayed down的直接链接" title="A key that stayed down的直接链接" translate="no">​</a></h2>
<p>Rotating the phone while a key was held left that key pressed in DOSBox for ever. The layout is rebuilt on a rotation, and the rebuilt layout did not tell the emulator that the finger had come up — so the key stayed down, and DOSBox went on repeating it.</p>
<p>Now every key that is down is released when the layout is rebuilt.</p>
<p>There was a second half to it. <strong>Ctrl</strong> is shown in two places at once — on the pad and on the fold-up panel — and the code assumed there was only ever one finger on it, so releasing it in one place cancelled it in the other. It now counts the fingers.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-launcher-that-fits">The launcher that fits<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#the-launcher-that-fits" class="hash-link" aria-label="The launcher that fits的直接链接" title="The launcher that fits的直接链接" translate="no">​</a></h2>
<p>The <strong>Files</strong> panel measures the space it has and caps the game list to it. A third game used to push the buttons off the bottom edge of the panel, where nothing could bring them back.</p>
<p>This is the smallest change in the release and the one I am most annoyed did not happen in the first three.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-desktop-build-links-again">The desktop build links again<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#the-desktop-build-links-again" class="hash-link" aria-label="The desktop build links again的直接链接" title="The desktop build links again的直接链接" translate="no">​</a></h2>
<p>The save-state code was never added to the autotools build, so the desktop baseline — the build that keeps the emulator core honest, the one that compiles on a laptop in seconds — had stopped linking. It had been broken since the save states went in, in 1.0.0.8, and I did not notice for two releases because I was busy shipping the Android one.</p>
<p>There were four separate reasons, and they are all of the same kind: a source file missing from the build, a missing include, a function that should have been compiled out, and the same archive listed twice in a row, which is a circular dependency that only shows up in a particular order.</p>
<p>The baseline compiles and links again, and it runs.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="one-document-instead-of-a-diary">One document instead of a diary<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#one-document-instead-of-a-diary" class="hash-link" aria-label="One document instead of a diary的直接链接" title="One document instead of a diary的直接链接" translate="no">​</a></h2>
<p>The repository used to carry a <code>porting/</code> folder: a porting log, some bench notes, a design note for the keyboard, and a log file. It was useful while the port was being written and it had stopped being useful the moment it was finished, because it was a <em>chronicle</em> — you had to know the order of things to know what was true now.</p>
<p>There is now <strong>one</strong> reference document: <a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/TECHNICAL-REFERENCE.md" target="_blank" rel="noopener noreferrer" class=""><code>docs/TECHNICAL-REFERENCE.md</code></a>. It is the whole implementation in one place — the native build and the ABI matrix, the save-state machine and its file format, the exact FM snapshot, the DOS layer inside the snapshot, the bundle launcher, the on-screen keyboard, the throughput benchmark, what is still not captured, and every screenshot the port produced, with the source references inline.</p>
<p>The diary did not disappear; it became chapters. The history is still in the git log, where history belongs.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-android-migration-is-over">The Android migration is over<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#the-android-migration-is-over" class="hash-link" aria-label="The Android migration is over的直接链接" title="The Android migration is over的直接链接" translate="no">​</a></h2>
<p>This release carries a tag that is not a release:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">milestone/android-migration-complete</span><br></div></code></pre></div></div>
<p>It is annotated, it pointed at this release's commit — the marker has since moved on to v1.0.0.13 — and it deliberately sits <strong>outside</strong> the <code>vX.Y.Z.A</code> scheme the release script understands, so the script will never pick it up and try to release it again.</p>
<p>It marks a phase, not a version. The Android migration is done: the emulator core builds for three ABIs, the app layer works on a real device, save states carry the whole machine including the sound, and the desktop baseline links. What comes after this is <strong>maintenance</strong> — bug fixes and documentation polish. No new features are planned.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="get-it">Get it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#get-it" class="hash-link" aria-label="Get it的直接链接" title="Get it的直接链接" translate="no">​</a></h2>
<p>The release APK is in the repository, signed with the release key, so it installs over 1.0.0.9 in place:</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.10</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">downloads/whereq-dosbox-1.0.0.10.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: 80bdce1b4bdeba809159310441e450e704f6c322e2a3ff98bcc822ed50077018</span><br></div></code></pre></div></div>
<p>The GitHub Release carries its own asset, built by the pipeline on a clean runner, with its own SHA-256 file next to it.</p>
<p>It runs on <strong>arm64-v8a, armeabi-v7a and x86_64</strong> devices, Android 5.0 and newer, entirely offline, with no account and no tracking. The project is GPL-2.0, and the DOSBox core is embedded with its <code>AUTHORS</code>, <code>ChangeLog</code>, <code>COPYING</code> and per-file headers intact.</p>
<p>Again, <strong>this post is not the documentation.</strong> The documentation is the repository, and it is now a single reference document rather than a folder of notes. Please read that rather than take my word for it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.10#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They kept it alive for three decades and gave it away to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which grew out of <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. The SDL2 library by <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> carries the window, the audio and the touch input.</p>
<p><strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>A save state that cannot hear is only half a save state. That is what made me write a test program for a sound chip. If your states came back with the music out of sync — or gone entirely — this is the release you want.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>emulator</category>
            <category>release</category>
            <category>retro</category>
            <category>open-source</category>
            <category>whereq</category>
            <category>savestate</category>
            <category>sound</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox：昨日的计算世界，今日的掌上体验，明日的无限可能]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN</guid>
            <pubDate>Tue, 17 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<p>还记得那个没有应用商店、没有触摸屏、没有云账号的年代吗？但我们依然可以为了玩一款游戏，心甘情愿地耗上整个周末。😂</p>
<p>那时候，我们敲着 <code>C:\GAMES\DOOM.EXE</code>，就觉得自己已经是计算机专家了。</p>
<p>其实，DOS 从未真正离开。它只是在等待一台更小的电脑。</p>
<p>今天，我们希望通过 <strong>WhereQ-DOSBox</strong>，让这段经典的计算机世界在 Android 手机上继续延续。</p>
<p>它不是运行在浏览器里的 DOS 模拟器，也不是连接到某台老电脑的远程桌面。它是一个原生 Android 应用，真正的 DOSBox 模拟器核心以原生动态库的形式集成在 APK 内部。</p>
<p>而它背后，还有不少值得分享的东西。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="眼见为实">眼见为实<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E7%9C%BC%E8%A7%81%E4%B8%BA%E5%AE%9E" class="hash-link" aria-label="眼见为实的直接链接" title="眼见为实的直接链接" translate="no">​</a></h2>
<div style="position:relative;width:100%;padding-bottom:56.25%;height:0;overflow:hidden;border-radius:2px"><iframe src="https://www.youtube-nocookie.com/embed/IttWMbYYQeI" title="WhereQ-DOSBox 运行在安卓手机上——屏幕上是一个 DOS 游戏，音乐垫在下面" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen=""></iframe></div>
<p align="center"><sub>手机上的 WhereQ-DOSBox：中间跑着 FIFA 96，左右两条黑边里是两块手柄区，
底下垫着 1990 年世界杯的那首歌。屏幕上的一切都是真正的 DOSBox 核心，
以原生动态库的形式跑在 APK 内部。</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="不只是运行-dos-游戏">不只是运行 DOS 游戏<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E4%B8%8D%E5%8F%AA%E6%98%AF%E8%BF%90%E8%A1%8C-dos-%E6%B8%B8%E6%88%8F" class="hash-link" aria-label="不只是运行 DOS 游戏的直接链接" title="不只是运行 DOS 游戏的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="原生-android-架构">原生 Android 架构<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E5%8E%9F%E7%94%9F-android-%E6%9E%B6%E6%9E%84" class="hash-link" aria-label="原生 Android 架构的直接链接" title="原生 Android 架构的直接链接" translate="no">​</a></h3>
<p>基于 DOSBox r4305 和 SDL2，通过 Android NDK 与 CMake 集成构建。原生支持 ARM64、ARMv7 和 x86_64 架构。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="智能-cpu-执行机制">智能 CPU 执行机制<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E6%99%BA%E8%83%BD-cpu-%E6%89%A7%E8%A1%8C%E6%9C%BA%E5%88%B6" class="hash-link" aria-label="智能 CPU 执行机制的直接链接" title="智能 CPU 执行机制的直接链接" translate="no">​</a></h3>
<p>通过 <code>core=auto</code> 配置，普通实模式程序自动使用解释执行，而进入保护模式的程序则切换到动态重编译（JIT）执行。DOS/4GW 程序也在我们的兼容性探索范围之内。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="真正理解手机操作的键盘">真正理解手机操作的键盘<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E7%9C%9F%E6%AD%A3%E7%90%86%E8%A7%A3%E6%89%8B%E6%9C%BA%E6%93%8D%E4%BD%9C%E7%9A%84%E9%94%AE%E7%9B%98" class="hash-link" aria-label="真正理解手机操作的键盘的直接链接" title="真正理解手机操作的键盘的直接链接" translate="no">​</a></h3>
<p>DOS 游戏是为键盘设计的，而不是为手指设计的。我们没有简单地把一块桌面键盘缩小后塞进手机屏幕。</p>
<p>横屏模式下，4:3 的 DOS 显示区域保持在屏幕中央，常用控制按键则充分利用左右两侧的黑边区域。竖屏模式则采用紧凑的底部键盘布局。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="你的-dos-环境你的程序">你的 DOS 环境，你的程序<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E4%BD%A0%E7%9A%84-dos-%E7%8E%AF%E5%A2%83%E4%BD%A0%E7%9A%84%E7%A8%8B%E5%BA%8F" class="hash-link" aria-label="你的 DOS 环境，你的程序的直接链接" title="你的 DOS 环境，你的程序的直接链接" translate="no">​</a></h3>
<p>支持导入 ZIP 游戏包、从文件夹批量安装，也可以直接通过 Android 文件管理器打开 ZIP 文件。</p>
<p>还有一个值得强调的细节：ZIP 包里不一定非得是游戏。</p>
<p>它可以是 DOS 工具、文本界面应用，或者几乎任何兼容的 DOS 程序。</p>
<p>无需申请多余的存储权限。通过 Android 系统文件选择器，应用只访问你主动选择的文件。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="一个叫-starfall-的小游戏">一个叫 STARFALL 的小游戏<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E4%B8%80%E4%B8%AA%E5%8F%AB-starfall-%E7%9A%84%E5%B0%8F%E6%B8%B8%E6%88%8F" class="hash-link" aria-label="一个叫 STARFALL 的小游戏的直接链接" title="一个叫 STARFALL 的小游戏的直接链接" translate="no">​</a></h3>
<p>我们还用汇编语言开发了一款非常小巧的 16 位 DOS 街机游戏。</p>
<p>大约 5 KB。一个 COM 可执行文件。不需要运行时环境，也没有任何外部依赖库。</p>
<p>它涵盖了 VGA 图形显示、BIOS 键盘输入和 PC Speaker 蜂鸣器音频。</p>
<p>有时候，证明一个完整模拟器能够正常工作的最好方式，就是准备一个比社交媒体头像还小的游戏。😂</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="而对于开发者来说还有另一段故事">而对于开发者来说，还有另一段故事<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E8%80%8C%E5%AF%B9%E4%BA%8E%E5%BC%80%E5%8F%91%E8%80%85%E6%9D%A5%E8%AF%B4%E8%BF%98%E6%9C%89%E5%8F%A6%E4%B8%80%E6%AE%B5%E6%95%85%E4%BA%8B" class="hash-link" aria-label="而对于开发者来说，还有另一段故事的直接链接" title="而对于开发者来说，还有另一段故事的直接链接" translate="no">​</a></h2>
<p>我们不想只交付一个 APK，然后把所有实现细节都藏起来。</p>
<p>项目同时提供：</p>
<ul>
<li class="">可复现的 Android NDK/CMake 构建流程。</li>
<li class="">用于开发和测试的 Linux 桌面基准环境。</li>
<li class="">CPU 核心性能基准测试工具。</li>
<li class="">无 Root 开发工具链 —— 不需要 root，也不需要 sudo。</li>
<li class="">移植说明、性能测试文档，以及完整的源代码。</li>
<li class="">GNU GPL-2.0 开源协议，延续 DOSBox 的开源传承。</li>
</ul>
<p>Android 平台相关的修改尽可能保持精简和局部化，让上游 DOSBox 的核心实现尽可能保持原貌。</p>
<p>整个实现都写在一处地方 —— 那份<a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/TECHNICAL-REFERENCE.md" target="_blank" rel="noopener noreferrer" class="">技术参考文档</a> —— 配着图表、源码引用和实测数据。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="为什么要做这个项目">为什么要做这个项目？<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E4%B8%BA%E4%BB%80%E4%B9%88%E8%A6%81%E5%81%9A%E8%BF%99%E4%B8%AA%E9%A1%B9%E7%9B%AE" class="hash-link" aria-label="为什么要做这个项目？的直接链接" title="为什么要做这个项目？的直接链接" translate="no">​</a></h2>
<p>技术一直在进步，但这不应该意味着过去的一切都变得无法访问。</p>
<p>还有成千上万款经典 DOS 游戏、教育软件、商业工具和各种应用程序，值得继续被使用、被发现、被保存。</p>
<p>我们认为，数字遗产保护不应该只局限于博物馆、虚拟机或者复古硬件收藏爱好者。</p>
<p>有时候，保护经典其实很简单：让旧的东西能够在新的设备上继续运行。</p>
<p>现在，你口袋里的手机也可以打开一个 DOS 命令提示符。</p>
<p>而某个 90 年代的计算机爱好者，可能正在疑惑：为什么运行一个 5 KB 的游戏，竟然需要 8 个 CPU 核心？😁</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="这是一个里程碑不是终点">这是一个里程碑，不是终点<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E8%BF%99%E6%98%AF%E4%B8%80%E4%B8%AA%E9%87%8C%E7%A8%8B%E7%A2%91%E4%B8%8D%E6%98%AF%E7%BB%88%E7%82%B9" class="hash-link" aria-label="这是一个里程碑，不是终点的直接链接" title="这是一个里程碑，不是终点的直接链接" translate="no">​</a></h2>
<p>安卓移植阶段已经完成，这个项目带上了一个标注它的标签：</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">milestone/android-migration-complete</span><br></div></code></pre></div></div>
<p>模拟器核心能为三个 ABI 编译，应用层在真机上跑得动，存档能装下整台机器——包括声音芯片——桌面基线也能正常链接。接下来进入<strong>维护阶段</strong>：修 bug、打磨文档，不再增加新功能。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="拿去用">拿去用<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E6%8B%BF%E5%8E%BB%E7%94%A8" class="hash-link" aria-label="拿去用的直接链接" title="拿去用的直接链接" translate="no">​</a></h2>
<p><strong>WhereQ-DOSBox 是一个开源项目，而这段旅程还在继续。</strong></p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong></p>
<p>如果你也曾经经历过 DOS 时代，我们很想听听你的想法：</p>
<blockquote>
<p><strong>如果可以让一款经典 DOS 游戏或应用重新焕发生命，你最想让哪一个回来？</strong></p>
</blockquote>
<p>即使那些老电脑早已不在，也让它们曾经创造的精彩继续运行下去。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="谢谢-dosbox">谢谢 DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone-CN#%E8%B0%A2%E8%B0%A2-dosbox" class="hash-link" aria-label="谢谢 DOSBox的直接链接" title="谢谢 DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> 写成——一群志愿者把 1994 年的一套操作系统改造到此后世界造出的每一台机器上都能跑，包括那些当时还不存在的机器。他们让它活过了三十年，并免费交给任何想要的人。WhereQ-DOSBox 只是建在他们工作之上的一层薄薄的壳。原创力、手艺和慷慨完全属于他们。</p>
<p>这个移植基于 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 做的 DOSBox r4305 的 Emscripten 版，它又来自 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 最早那次用 Emscripten 编译 DOSBox 的尝试，并且踩着 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 的 Emscripten 工作一路往前。窗口、音频和触摸输入则由 <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> 的 SDL2 库承担。</p>
<p><strong>DOSBox 是 DOSBox 项目的商标</strong>；这个移植与 DOSBox 团队没有任何隶属或背书关系。</p>
<hr>
<p><em>你口袋里的手机能打开一个 DOS 提示符。整个想法就是这一句话，只是做出来比应该花的时间更久。如果你记得某个值得再跑一次的 DOS 程序，告诉我们是哪一个 —— 也许我们会把它做出来。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>模拟器</category>
            <category>里程碑</category>
            <category>怀旧</category>
            <category>开源</category>
            <category>whereq</category>
            <category>数字遗产保护</category>
            <category>游戏</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox: Yesterday's Computing. Today's Pocket. Tomorrow's Possibilities.]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone</guid>
            <pubDate>Tue, 17 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<p>Remember when computers had no app stores, no touchscreens, no cloud accounts, and somehow we still managed to spend entire weekends playing games? 😂</p>
<p>We used to type commands like <code>C:\GAMES\DOOM.EXE</code> and consider ourselves computer experts.</p>
<p>Well, DOS never really left. It was just waiting for a smaller computer.</p>
<p>Today, we're taking a meaningful step in bringing that world to Android with WhereQ-DOSBox.</p>
<p>Not a DOS emulator running inside a browser. Not a remote desktop connecting to an old PC. It's a native Android application with the actual DOSBox emulator core running as a native library inside the APK.</p>
<p>And there's quite a bit more behind it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="watch-it-running">Watch it running<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#watch-it-running" class="hash-link" aria-label="Watch it running的直接链接" title="Watch it running的直接链接" translate="no">​</a></h2>
<div style="position:relative;width:100%;padding-bottom:56.25%;height:0;overflow:hidden;border-radius:2px"><iframe src="https://www.youtube-nocookie.com/embed/IttWMbYYQeI" title="WhereQ-DOSBox running on an Android phone — a DOS game on screen, with music under it" style="position:absolute;top:0;left:0;width:100%;height:100%;border:0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen=""></iframe></div>
<p align="center"><sub>WhereQ-DOSBox on a phone: FIFA 96 in the middle, the two console pads
in the letterbox bars either side, and the 1990 World Cup song under it.
Everything on screen is the real DOSBox core, running as a native library
inside the APK.</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="more-than-just-running-dos-games">More than just running DOS games<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#more-than-just-running-dos-games" class="hash-link" aria-label="More than just running DOS games的直接链接" title="More than just running DOS games的直接链接" translate="no">​</a></h2>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="native-android-architecture">Native Android architecture<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#native-android-architecture" class="hash-link" aria-label="Native Android architecture的直接链接" title="Native Android architecture的直接链接" translate="no">​</a></h3>
<p>DOSBox r4305 with SDL2, integrated through Android NDK and CMake. Native execution across ARM64, ARMv7 and x86_64.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="intelligent-cpu-execution">Intelligent CPU execution<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#intelligent-cpu-execution" class="hash-link" aria-label="Intelligent CPU execution的直接链接" title="Intelligent CPU execution的直接链接" translate="no">​</a></h3>
<p>The <code>core=auto</code> configuration automatically uses the interpreter for real-mode applications and switches to dynamic recompilation (JIT) for protected-mode applications. DOS/4GW programs are part of the compatibility journey.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-keyboard-that-understands-mobile">A keyboard that understands mobile<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#a-keyboard-that-understands-mobile" class="hash-link" aria-label="A keyboard that understands mobile的直接链接" title="A keyboard that understands mobile的直接链接" translate="no">​</a></h3>
<p>DOS games were designed for keyboards, not thumbs. We didn't simply shrink a desktop keyboard onto a phone.</p>
<p>The 4:3 DOS display stays in the middle, while frequently used controls occupy the left and right letterbox areas in landscape mode. Portrait mode gets a compact bottom keyboard.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="your-dos-environment-your-programs">Your DOS environment, your programs<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#your-dos-environment-your-programs" class="hash-link" aria-label="Your DOS environment, your programs的直接链接" title="Your DOS environment, your programs的直接链接" translate="no">​</a></h3>
<p>Import ZIP bundles, install multiple bundles from a folder, or open ZIP files directly from Android's file manager.</p>
<p>And here's an important distinction: a bundle doesn't have to contain a game. It can be a DOS utility, a text-mode application, or practically any compatible DOS program.</p>
<p>No unnecessary storage permissions. Android's system file picker provides access only to the files you select.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-little-game-called-starfall">A little game called STARFALL<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#a-little-game-called-starfall" class="hash-link" aria-label="A little game called STARFALL的直接链接" title="A little game called STARFALL的直接链接" translate="no">​</a></h3>
<p>We also built a tiny 16-bit DOS arcade game in assembly.</p>
<p>Approximately 5 KB. One COM executable. No runtime. No external libraries.</p>
<p>It exercises VGA graphics, BIOS keyboard input and PC speaker audio.</p>
<p>Sometimes the best way to demonstrate an entire emulator is with a game smaller than the average social media profile picture. 😂</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="and-for-developers-theres-another-story">And for developers, there's another story<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#and-for-developers-theres-another-story" class="hash-link" aria-label="And for developers, there's another story的直接链接" title="And for developers, there's another story的直接链接" translate="no">​</a></h2>
<p>We didn't want to deliver just an APK and hide everything else.</p>
<p>The project includes:</p>
<ul>
<li class="">A reproducible NDK/CMake Android build.</li>
<li class="">A desktop Linux baseline for development and testing.</li>
<li class="">CPU-core benchmarking tools.</li>
<li class="">A rootless development toolchain — no root, no sudo required.</li>
<li class="">Porting notes and benchmark documentation, plus the complete source code.</li>
<li class="">GNU GPL-2.0 licensing, preserving the open-source lineage of DOSBox.</li>
</ul>
<p>The Android-specific changes are kept relatively small and localized, leaving the upstream DOSBox implementation largely intact.</p>
<p>The whole implementation is written up in one place — the <a href="https://github.com/whereq/whereq-dosbox/blob/main/docs/TECHNICAL-REFERENCE.md" target="_blank" rel="noopener noreferrer" class="">technical reference</a> — with the diagrams, the source references and the measured numbers.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-build-this">Why build this?<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#why-build-this" class="hash-link" aria-label="Why build this?的直接链接" title="Why build this?的直接链接" translate="no">​</a></h2>
<p>Technology moves forward, but that shouldn't mean everything behind us becomes inaccessible.</p>
<p>There are thousands of classic DOS games, educational programs, business utilities and pieces of software that deserve to remain usable and discoverable.</p>
<p>We believe preservation shouldn't be limited to museums, virtual machines or vintage hardware collectors.</p>
<p>Sometimes, preservation simply means making something old work on something new.</p>
<p>A phone in your pocket can now open a DOS prompt.</p>
<p>And somewhere, a 1990s computer enthusiast is probably wondering why we need 8 CPU cores to run a 5 KB game. 😁</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-milestone-not-an-ending">A milestone, not an ending<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#a-milestone-not-an-ending" class="hash-link" aria-label="A milestone, not an ending的直接链接" title="A milestone, not an ending的直接链接" translate="no">​</a></h2>
<p>The Android migration is finished, and the project carries a tag that says so:</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">milestone/android-migration-complete</span><br></div></code></pre></div></div>
<p>The emulator core builds for three ABIs, the app layer works on a real device, save states carry the whole machine — the sound chips included — and the desktop baseline links. What comes next is <strong>maintenance</strong>: bug fixes and documentation polish, no new features.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="get-it">Get it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#get-it" class="hash-link" aria-label="Get it的直接链接" title="Get it的直接链接" translate="no">​</a></h2>
<p>WhereQ-DOSBox is open source, and the journey is ongoing.</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong></p>
<p>If you grew up with DOS, we'd love to hear from you:</p>
<blockquote>
<p>What's the one DOS application or game you would bring back to life first?</p>
</blockquote>
<p>Let's keep the old machines running, even when the machines themselves are no longer around.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Milestone#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They kept it alive for three decades and gave it away to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which grew out of <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. The SDL2 library by <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> carries the window, the audio and the touch input.</p>
<p><strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>A phone in your pocket can open a DOS prompt. That is the whole idea, and it took longer than it should have. If you remember a DOS program that deserves another run, tell us which one — we might build it.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>emulator</category>
            <category>milestone</category>
            <category>retro</category>
            <category>open-source</category>
            <category>whereq</category>
            <category>preservation</category>
            <category>gaming</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.8：保存整台机器，让「继续」真的能继续]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN</guid>
            <pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="一个会骗人的按钮">一个会骗人的按钮<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN#%E4%B8%80%E4%B8%AA%E4%BC%9A%E9%AA%97%E4%BA%BA%E7%9A%84%E6%8C%89%E9%92%AE" class="hash-link" aria-label="一个会骗人的按钮的直接链接" title="一个会骗人的按钮的直接链接" translate="no">​</a></h2>
<p>两个版本之前，我给启动器加了一个 <strong>Resume</strong> 按钮。它看上去就是个承诺：按一下，回到你刚才在玩的那局游戏。</p>
<p>结果不是。它每次都把上一款游戏从头开始。</p>
<p>我自己一直没发现，因为我桌上的模拟器进程还活着——游戏其实从没停过，自然也就没什么好「恢复」的。后来有位用户在手机上按了那个按钮，丢掉了一个小时的进度，直截了当地告诉我：<em>你这个 Resume 其实是重开。</em></p>
<p>他没说错。而修它并不是改一行代码就行的——要做的是给整台机器拍一张快照。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="认真做的话存档是什么">认真做的话，存档是什么<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN#%E8%AE%A4%E7%9C%9F%E5%81%9A%E7%9A%84%E8%AF%9D%E5%AD%98%E6%A1%A3%E6%98%AF%E4%BB%80%E4%B9%88" class="hash-link" aria-label="认真做的话，存档是什么的直接链接" title="认真做的话，存档是什么的直接链接" translate="no">​</a></h2>
<p>DOS 游戏自己通常有存档。有的游戏有，很多没有；有的只把进度写在当前目录里，然后指望你自己找到菜单走回去。</p>
<p><strong>存档点</strong>（save state）是另一回事：它是被冻住的整台机器。</p>
<p>不是游戏，而是机器。带着寄存器的 CPU、DOS 内存、显存、硬件定时器，以及程序当时正打开的那些文件。是所有让这一局成为「此刻这一局」的东西——所以读档回来是回到同一个瞬间，而不是回到附近。</p>
<p>DOSBox r4305 本身没有存档点，所以我在这个移植里写了一个。每个游戏有 <strong>三个槽位</strong>，以文件形式存在应用的私有目录里，因此退出应用、重启手机、升级 APK 都丢不掉。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-save-states.jpg" alt="WhereQ-DOSBox 的存档对话框：正在运行的游戏有三个槽位，第一个是两小时前存的，每个槽位都有 Save 和 Load 按钮" width="900"></p>
<p align="center"><sub>每个游戏三个槽位。Save 冻住正在运行的机器，Load 把它放回去。槽位是手机
上的文件，退出应用也不会丢。</sub></p>
<p>这里有个细节我啃了两天，值得写下来，因为它是「存档能用」和「存档会把游戏搞崩」的分界线。</p>
<p>快照必须在<strong>安全点</strong>上拍：客机程序得真的在跑，画面得已经稳定，而且 CPU 不能正站在一个挂着 <code>IRET</code> 的中断回调里。位置选错了，读档就会落进 BIOS 调用的半截里——那种损坏看起来像游戏坏了，而不是像存档坏了。</p>
<p>而且它必须把 <strong>DOS 层</strong>一起拍下来，不只是 CPU。开着 <code>SOUND\MUSIC.FLX</code> 的游戏，指望回来时那个文件还开着。不把文件句柄放进快照，Ultima VIII 每次读档后一秒左右就会走进自己的 extender，然后以 <code>DOS Error=0006 (invalid handle)</code> 中止。放进去之后，那十六个句柄都回来了，音乐也还在响。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="于是继续终于真的是继续">于是「继续」终于真的是继续<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN#%E4%BA%8E%E6%98%AF%E7%BB%A7%E7%BB%AD%E7%BB%88%E4%BA%8E%E7%9C%9F%E7%9A%84%E6%98%AF%E7%BB%A7%E7%BB%AD" class="hash-link" aria-label="于是「继续」终于真的是继续的直接链接" title="于是「继续」终于真的是继续的直接链接" translate="no">​</a></h2>
<p>这个按钮现在会读回你上次玩的那个游戏的最新槽位，而且会告诉你它要干什么：<em>Resume whereq-demo-bundle · slot 1 · just now</em>。如果一个槽位都没存，它就照旧从头开始。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-resume.jpg" alt="WhereQ-DOSBox 存档之后的文件面板：绿色的 Resume 按钮显示 Resume whereq-demo-bundle，slot 1，just now，底部状态栏写着 Saved to slot 1" width="900"></p>
<p align="center"><sub>Saved to slot 1——Resume 按钮已经知道了一切：哪个游戏、哪个槽位、多久之前
存的。</sub></p>
<p>这不是一个「复制文件」的按钮。应用会先把自己的进程拆掉，干净地启动一个什么都没排队的模拟器，等画面稳定下来，然后才把机器恢复进去。早了那么一瞬间——比如手机还在转屏——就会恢复进一个马上就要被丢弃的渲染器里，屏幕一片黑。这条我也追了一阵。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="说不清楚的那部分">说不清楚的那部分<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN#%E8%AF%B4%E4%B8%8D%E6%B8%85%E6%A5%9A%E7%9A%84%E9%82%A3%E9%83%A8%E5%88%86" class="hash-link" aria-label="说不清楚的那部分的直接链接" title="说不清楚的那部分的直接链接" translate="no">​</a></h2>
<p><strong>有些老 DOS 程序确实过不了读档这一关。</strong> Ultima VIII 的 extender 仍然会在读档后一秒左右中止：<code>Exit to error: RET from illegal descriptor type 13</code>。</p>
<p>这不是应用的问题，也不是「继续」这条路的问题：手动打开面板读同一个槽位，结果完全一样。快照目前还没装下的，是 DOS/4GW 游戏真正依赖的那部分宿主状态——声卡和它的 DMA、EMS 与 XMS 的句柄表、VCPI 的 PIC 向量重映射、鼠标、RTC，以及 PIC 的事件队列。这是还没做完的里程碑，移植日志里写的也是同样的话。</p>
<p>在那之前：STARFALL 存读都完全正常；Ultima VIII 这类游戏可以存、可以读，但它的 extender 读到之后不太高兴。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="游戏现在也能在后台活着了">游戏现在也能在后台活着了<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN#%E6%B8%B8%E6%88%8F%E7%8E%B0%E5%9C%A8%E4%B9%9F%E8%83%BD%E5%9C%A8%E5%90%8E%E5%8F%B0%E6%B4%BB%E7%9D%80%E4%BA%86" class="hash-link" aria-label="游戏现在也能在后台活着了的直接链接" title="游戏现在也能在后台活着了的直接链接" translate="no">​</a></h2>
<p>另一件我原本想当然的事，是以为离开应用就等于离开游戏。Android 上不是这样：系统随时可以回收一个后台应用的进程，而 DOSBox 把整台机器都放在内存里——于是游戏就那么没了，连个提示都没有。</p>
<p>现在只要游戏在跑，就有一条常驻通知把进程保住。切到别的应用去，晚点再回来，游戏还在你离开的那一帧——不用存档，不用重载。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-screenshot-phone.jpg" alt="WhereQ-DOSBox 在安卓手机横屏下的运行画面：中间的 DOSBox 欢迎画面和已挂载的 C 盘，左右黑边上是屏幕键盘，方向键排成倒 T 形" width="900"></p>
<p align="center"><sub>手机上的实际画面。四个方向键现在是真键盘上的倒 T 形——上键在最上面，左右并排，
下键在最下面——手指靠形状就能找对方向。</sub></p>
<p>最后这条改动很小，但我挺喜欢。方向键原本是一根竖排的队列，这和它要代替的那块键盘完全不像：手指必须先「知道」四个键分别是哪一个。现在拇指直接读形状就行。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="拿去用">拿去用<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN#%E6%8B%BF%E5%8E%BB%E7%94%A8" class="hash-link" aria-label="拿去用的直接链接" title="拿去用的直接链接" translate="no">​</a></h2>
<p>发布版 APK 就在仓库里，用发布密钥签名，可以直接覆盖安装 1.0.0.7：</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.8</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">downloads/whereq-dosbox-1.0.0.8.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: ed17f39bddeb9e871485df390f772f19c5a43abdbf3b5845c7abd4afbb602ca3</span><br></div></code></pre></div></div>
<p>它跑在 <strong>arm64-v8a、armeabi-v7a 和 x86_64</strong> 设备上，要求 Android 5.0 及以上，完全离线，不需要账号，没有任何追踪。项目采用 GPL-2.0 许可，DOSBox 核心连同它的 <code>AUTHORS</code>、<code>ChangeLog</code>、<code>COPYING</code> 和逐文件头注释一起嵌入。</p>
<p>再说一遍：<strong>这篇文章不是文档。</strong> 文档是仓库本身：构建指南、移植日志（里面有一节专门讲快照到底怎么拍的，以及为什么必须等安全点）、性能测试笔记，以及这个移植的每一行代码。请去读那些，而不是信我的一面之词。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="谢谢-dosbox">谢谢 DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8-CN#%E8%B0%A2%E8%B0%A2-dosbox" class="hash-link" aria-label="谢谢 DOSBox的直接链接" title="谢谢 DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> 写成——一群志愿者把 1994 年的一套操作系统改造到此后世界造出的每一台机器上都能跑，包括那些当时还不存在的机器。他们让它活过了三十年，并免费交给任何想要的人。WhereQ-DOSBox 只是建在他们工作之上的一层薄薄的壳。原创力、手艺和慷慨完全属于他们。</p>
<p>这个移植基于 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 做的 DOSBox r4305 的 Emscripten 版，它又来自 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 最早那次用 Emscripten 编译 DOSBox 的尝试，并且踩着 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 的 Emscripten 工作一路往前。窗口、音频和触摸输入则由 <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> 的 SDL2 库承担。</p>
<p><strong>DOSBox 是 DOSBox 项目的商标</strong>；这个移植与 DOSBox 团队没有任何隶属或背书关系。</p>
<hr>
<p><em>如果你按下「继续」，游戏真的回到了离开时的样子——或者没有，而存档点正是你放弃的地方——请告诉我。我一直在记一份名单，那是最有用的一种反馈。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>模拟器</category>
            <category>发布</category>
            <category>怀旧</category>
            <category>开源</category>
            <category>whereq</category>
            <category>存档</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.8: save the whole machine, and a Resume button that resumes]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8</guid>
            <pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-button-that-lied">The button that lied<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8#the-button-that-lied" class="hash-link" aria-label="The button that lied的直接链接" title="The button that lied的直接链接" translate="no">​</a></h2>
<p>Two releases ago I gave the launcher a <strong>Resume</strong> button. It looked like a promise: press it, and you are back in the game you were playing.</p>
<p>It was not. It started the last game from the beginning, every time.</p>
<p>I did not notice it myself, because on my desk the emulator process was still alive — the game had never really stopped, so there was nothing to resume. Then somebody on a phone pressed the button, lost an hour of progress, and told me plainly: <em>the Resume button restarts the game.</em></p>
<p>They were right, and the fix was not a one-liner. It took a whole-machine snapshot.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-a-save-state-is-when-you-are-serious-about-it">What a save state is, when you are serious about it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8#what-a-save-state-is-when-you-are-serious-about-it" class="hash-link" aria-label="What a save state is, when you are serious about it的直接链接" title="What a save state is, when you are serious about it的直接链接" translate="no">​</a></h2>
<p>A DOS game has its own save files. Some games have them; many do not; the ones that do usually save somewhere in the current directory and expect you to find your way back through a menu.</p>
<p>A <strong>save state</strong> is a different thing: it is the entire machine, frozen.</p>
<p>Not the game — the machine. The CPU with its registers, the DOS memory, the video memory, the hardware timers, the files the program had open. Everything that made the game <em>that game at that moment</em>, so that restoring it puts you back in the same instant rather than near it.</p>
<p>DOSBox r4305 has no save state at all, so I wrote one into the port. Every game gets <strong>three slots</strong>, written as files in the app's private directory, which means they survive quitting the app, rebooting the phone, and updating the APK.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-save-states.jpg" alt="The save states dialog of WhereQ-DOSBox: three slots for the running game, the first one saved two hours ago, each with a Save and a Load button" width="900"></p>
<p align="center"><sub>Three slots per game. Save freezes the running machine, Load puts it
back. The slots are files on the phone — they survive quitting the
app.</sub></p>
<p>There is a subtlety that cost me two days and is worth writing down, because it is the difference between a snapshot that works and one that crashes the game.</p>
<p>The snapshot has to be taken at a <strong>safe point</strong>: the guest program must actually be running, the picture must have settled, and the CPU must not be standing inside an interrupt callback with an <code>IRET</code> pending. Take it in the wrong place and you restore into the middle of a BIOS call — the kind of corruption that looks like a broken game rather than a broken save.</p>
<p>And it has to capture the <strong>DOS layer</strong>, not just the CPU. A game that has <code>SOUND\MUSIC.FLX</code> open expects that file to still be open when it comes back. Without the file handles in the snapshot, Ultima VIII walked into its own extender and aborted with <code>DOS Error=0006 (invalid handle)</code> a second after every restore. With them, the sixteen handles come back and the music keeps playing.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="so-now-resume-means-resume">So now Resume means resume<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8#so-now-resume-means-resume" class="hash-link" aria-label="So now Resume means resume的直接链接" title="So now Resume means resume的直接链接" translate="no">​</a></h2>
<p>The button restores the newest slot of the last game you played, and it tells you what it is about to do: <em>Resume whereq-demo-bundle · slot 1 · just now</em>. With no slot saved, it starts the game from the beginning, exactly as before.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-resume.jpg" alt="The Files panel of WhereQ-DOSBox after a save: a green Resume button reading Resume whereq-demo-bundle, slot 1, just now, and the status line Saved to slot 1" width="900"></p>
<p align="center"><sub>Saved to slot 1 — and the Resume button already knows: the game, the
slot, and how long ago it was written.</sub></p>
<p>Under the hood this is not a button that copies a file. The app tears its own process down, boots a clean emulator with nothing queued, waits for the picture to settle, and only then restores the machine into it. A restore that happens a fraction of a second too early — while the phone is still rotating the screen — restores into a renderer that is about to be thrown away, and you get a black screen. I chased that one for a while too.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-honest-part">The honest part<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8#the-honest-part" class="hash-link" aria-label="The honest part的直接链接" title="The honest part的直接链接" translate="no">​</a></h2>
<p><strong>Some old DOS programs do not survive a restore.</strong> Ultima VIII's extender still aborts about a second after the load, with <code>Exit to error: RET from illegal descriptor type 13</code>.</p>
<p>That is not the app, and it is not the Resume path: loading the same slot by hand, with the panel open, does exactly the same thing. What the snapshot does not capture yet is the rest of the host state a DOS/4GW game leans on — the sound chips and their DMA, the EMS and XMS handle tables, the VCPI PIC vector remapping, the mouse, the RTC, and the PIC event queue. It is milestone work that is not finished, and the porting log says so in the same words.</p>
<p>Until it is: STARFALL saves and resumes perfectly, and a game like Ultima VIII can be saved and restored, but its extender does not like what it finds.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-game-keeps-running-now-too">The game keeps running now, too<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8#the-game-keeps-running-now-too" class="hash-link" aria-label="The game keeps running now, too的直接链接" title="The game keeps running now, too的直接链接" translate="no">​</a></h2>
<p>The other thing I got wrong was assuming that leaving the app would leave the game alone. On Android it does not: the OS is free to reclaim the process of a backgrounded app, and DOSBox keeps the whole machine in RAM — so the game was simply gone, with no warning.</p>
<p>While a game is running, a small ongoing notification now holds the process. Switch to another app, come back later, and the game is exactly where you left it — no save, no reload, just the frame you walked away from.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-screenshot-phone.jpg" alt="WhereQ-DOSBox running on an Android phone in landscape: the DOSBox welcome screen and a mounted C drive in the middle, the on-screen keyboard in the letterbox bars on the left and right, the arrow keys in an inverted T" width="900"></p>
<p align="center"><sub>The app on a phone. The four arrows now sit in the inverted T of a real
keyboard — up on top, left and right side by side, down below — so the
thumb finds the direction by shape alone.</sub></p>
<p>That last change is small and I am fond of it. The arrows used to be a single vertical column, which is nothing like the keyboard they stand in for: the finger had to <em>know</em> which of the four was which. Now the thumb reads the shape.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="get-it">Get it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8#get-it" class="hash-link" aria-label="Get it的直接链接" title="Get it的直接链接" translate="no">​</a></h2>
<p>The release APK is in the repository, signed with the release key, so it installs over 1.0.0.7 in place:</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.8</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">downloads/whereq-dosbox-1.0.0.8.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: ed17f39bddeb9e871485df390f772f19c5a43abdbf3b5845c7abd4afbb602ca3</span><br></div></code></pre></div></div>
<p>It runs on <strong>arm64-v8a, armeabi-v7a and x86_64</strong> devices, Android 5.0 and newer, entirely offline, with no account and no tracking. The project is GPL-2.0, and the DOSBox core is embedded with its <code>AUTHORS</code>, <code>ChangeLog</code>, <code>COPYING</code> and per-file headers intact.</p>
<p>Again, <strong>this post is not the documentation.</strong> The documentation is the repository: the build guide, the porting log — including the section that explains exactly how a snapshot is taken and why it has to wait for a safe point — the benchmark notes, and every line of the port. Please read those rather than take my word for it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.8#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They kept it alive for three decades and gave it away to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which grew out of <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. The SDL2 library by <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> carries the window, the audio and the touch input.</p>
<p><strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>If you press Resume and your game comes back exactly where you left it — or if it does not, and the save state is where you give up on it — tell me. I am keeping a list, and it is the most useful thing anyone can send me.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>emulator</category>
            <category>release</category>
            <category>retro</category>
            <category>open-source</category>
            <category>whereq</category>
            <category>save-states</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.9：把键盘改造成掌机]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN</guid>
            <pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="一个戴着键盘外形的妥协">一个戴着键盘外形的妥协<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#%E4%B8%80%E4%B8%AA%E6%88%B4%E7%9D%80%E9%94%AE%E7%9B%98%E5%A4%96%E5%BD%A2%E7%9A%84%E5%A6%A5%E5%8D%8F" class="hash-link" aria-label="一个戴着键盘外形的妥协的直接链接" title="一个戴着键盘外形的妥协的直接链接" translate="no">​</a></h2>
<p>DOS 的画面是 4:3，手机横过来是 20:9。多出来的那部分就是左右两条黑边，前两个版本里，键盘就住在那两条黑边上。</p>
<p>那两条黑边并不算糟。方向键排成真键盘上的倒 T 形，修饰键和编辑键在另一侧，画面占住了整个屏幕中间。用起来是没问题的。</p>
<p>但对一个想模拟的东西来说，那是错的形状。DOS 游戏是左手拇指管方向、右手拇指管按键的，而这些键全都不在拇指习惯待的地方。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="掌机是怎么做的">掌机是怎么做的<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#%E6%8E%8C%E6%9C%BA%E6%98%AF%E6%80%8E%E4%B9%88%E5%81%9A%E7%9A%84" class="hash-link" aria-label="掌机是怎么做的的直接链接" title="掌机是怎么做的的直接链接" translate="no">​</a></h2>
<p>掌机的做法是：屏幕放中间，操作键分到两只手上——一边一个——而且绝不让按键盖到画面上。</p>
<p>1.0.0.9 就是照着这个来的。那两条黑边不再是「能塞多少塞多少」的两列键，而是<strong>两块手柄区</strong>，画面依然完整地留在中间。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-keyboard-pads.png" alt="WhereQ-DOSBox 在安卓手机横屏下的运行画面：中间是 DOSBox 欢迎画面，左边手柄区顶部是 File、Esc、Tab，下面是数字 1 到 5、左半边 QWERTY 和排成十字的方向键；右边手柄区顶部是 #+=、Fn 和退格，下面是右半边 QWERTY 以及 Alt、Ctrl、Shift、Space、Enter" width="900"></p>
<p align="center"><sub>左手那半负责方向键和左半边键盘，右手那半负责动作键和右半边。画面留在中间，
没有一个键画在它上面。</sub></p>
<p><strong>左半边</strong>是负责转向的那只手：四个方向键做成<strong>十字键</strong>——上键在最上面，左右并排，下键在最下面，手指靠形状就能读出方向——再往上是劈成两半的 QWERTY 的左半边，最顶上一排是 <strong>File</strong>、<strong>Esc</strong> 和 <strong>Tab</strong>。</p>
<p><strong>右半边</strong>是负责操作的那只手：拇指下面是 <strong>Alt</strong>、<strong>Ctrl</strong>、<strong>Shift</strong>、<strong>Space</strong> 和 <strong>Enter</strong>，往上是 QWERTY 的右半边，最顶上一排是 <strong>#+=</strong>、<strong>Fn</strong> 和退格。</p>
<p>QWERTY 是「劈开」的，不是「缩小」的。左边是 <code>12345 qwert asdfg zxcvb</code>，右边是 <code>67890 yuiop hjkl: nm./\</code>——每一半都是正常尺寸的真键，而不是把整块键盘缩小后的玩具。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="三层一个键一层">三层，一个键一层<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#%E4%B8%89%E5%B1%82%E4%B8%80%E4%B8%AA%E9%94%AE%E4%B8%80%E5%B1%82" class="hash-link" aria-label="三层，一个键一层的直接链接" title="三层，一个键一层的直接链接" translate="no">​</a></h2>
<p>键盘劈成两半只解决了一半问题；另一半是键不够用的时候怎么办。这里的答案是<strong>一层一个键</strong>，就放在右半边最上面那一排。</p>
<p><strong>#+=</strong> 把两半同时换成标点。切到这一层时，这个键会亮成蓝色，并且变成 <em>abc</em>——因为按下它就是回到字母层。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-keyboard-symbols.png" alt="WhereQ-DOSBox 切到标点层：右上角的 #+= 键亮成蓝色并显示 abc，左右两块手柄区显示标点符号——左边是 ! @ # $ %，右边是 ^ &amp; * ( )" width="900"></p>
<p align="center"><sub>标点层。每个带 Shift 的字符就在它对应的不带 Shift 的键正下方，被切走的那个键会亮起来。</sub></p>
<p><strong>Fn</strong> 换来功能键：左边是 F1 到 F12，右边是 Ins / Del、Home / End、PgUp / PgDn、Caps、PrtSc 和 Pause。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-keyboard-functions.png" alt="WhereQ-DOSBox 切到功能层：Fn 键亮成蓝色，左半边是 F1 到 F12，右半边是 Ins、Home、PgUp、Del、End、PgDn、Caps、PrtSc 和 Pause" width="900"></p>
<p align="center"><sub>功能层——整个 F 排和编辑键，一个字母键都不用让出来。</sub></p>
<p>而右半边的字母层本身就已经带着 <code>: . / \</code>，所以敲一条 DOS 路径根本不需要切层：<code>C:\GAMES\DUNE\SETUP.EXE</code> 只是一串字母加标点，在同一层上顺序按下去就行。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ctrlalt-和-shift按游戏想要的方式来">Ctrl、Alt 和 Shift，按游戏想要的方式来<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#ctrlalt-%E5%92%8C-shift%E6%8C%89%E6%B8%B8%E6%88%8F%E6%83%B3%E8%A6%81%E7%9A%84%E6%96%B9%E5%BC%8F%E6%9D%A5" class="hash-link" aria-label="Ctrl、Alt 和 Shift，按游戏想要的方式来的直接链接" title="Ctrl、Alt 和 Shift，按游戏想要的方式来的直接链接" translate="no">​</a></h2>
<p>修饰键是我想得最久的一部分，因为两种游戏对 Ctrl 的要求是不一样的。</p>
<p><strong>点一下</strong> Ctrl、Alt 或 Shift 会让它<strong>待命</strong>：接下来按的那个键会被修饰，然后修饰键自己松开。Ctrl、然后 C——文本编辑器和 DOS 命令行要的就是这个。</p>
<p><strong>按住</strong>则是一直按着，直到你松手，和真键盘一样。这正是游戏对开火键和移动键的期待：右拇指按住 Ctrl，左拇指在十字键上走，游戏两个都收得到。</p>
<p>旧键盘只能做前一种。新的手柄区两种都能做，因为修饰键无非就是一个「处于按下状态」的键。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="布局跟着屏幕走">布局跟着屏幕走<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#%E5%B8%83%E5%B1%80%E8%B7%9F%E7%9D%80%E5%B1%8F%E5%B9%95%E8%B5%B0" class="hash-link" aria-label="布局跟着屏幕走的直接链接" title="布局跟着屏幕走的直接链接" translate="no">​</a></h2>
<p>不是每部手机都能腾出 20:9 那么宽的黑边，所以键盘会按黑边的宽度挑自己的形态：宽度够（至少 116 dp）就用完整的两块手柄区，差一点就退回到每侧一列键加上可折叠的 QWERTY 面板，竖屏则是贴底边的一条窄条。</p>
<p>下面这部分我并不满意。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-keyboard-pads-18x9.png" alt="WhereQ-DOSBox 在 18:9 屏幕下的运行画面：还是同样的两块手柄区，但字母键明显更小，画面占比更大" width="900"></p>
<p align="center"><sub>同一套布局在 18:9 屏幕上。手柄区照样放得下，但字母键明显小了——大约 24 dp 宽，
而 20:9 屏上是 33 dp。</sub></p>
<p>在 20:9 屏上，字母键的宽度是 <strong>32.8 dp</strong>。到了 18:9 屏——很多手机就是这个比例——黑边变窄，同一套布局下字母键只剩 <strong>23.6 dp</strong>，大约是屏幕宽度的 2.9 %，而正常手机键盘的一个键差不多是这个的两倍。十字键和动作键不受影响，挤小的只有字母。</p>
<p>这个数是量出来的，不是我猜的：两种宽度都在模拟器上跑过、也都实际敲过字，三层布局在两种宽度下的截图都在仓库里。我没有做的是<strong>在真正的 18:9 手机上试</strong>——这台设备上没有的读者如果愿意替我补上这一课，我很想听。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="底下什么都没变">底下什么都没变<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#%E5%BA%95%E4%B8%8B%E4%BB%80%E4%B9%88%E9%83%BD%E6%B2%A1%E5%8F%98" class="hash-link" aria-label="底下什么都没变的直接链接" title="底下什么都没变的直接链接" translate="no">​</a></h2>
<p>这一版全是应用层的工作。SDL 的 surface 依然是全屏，键盘只画在画面两侧的黑边里，<strong><code>libdosbox.so</code> 和 1.0.0.8 发出来的是同一个库</strong>——同样的原生核心，同样的编译参数。</p>
<p>有时候，描述一个大改动最诚实的方式，是说清楚<strong>什么没有</strong>变。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="流水线现在会自己出版本">流水线现在会自己出版本<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#%E6%B5%81%E6%B0%B4%E7%BA%BF%E7%8E%B0%E5%9C%A8%E4%BC%9A%E8%87%AA%E5%B7%B1%E5%87%BA%E7%89%88%E6%9C%AC" class="hash-link" aria-label="流水线现在会自己出版本的直接链接" title="流水线现在会自己出版本的直接链接" translate="no">​</a></h2>
<p>这个仓库第一次有了 CI 流水线。每次推送和每个 PR，<code>ci.yml</code> 都会把模拟器从源码编译三个 ABI——SDL2 加整个 DOSBox 核心，编译三遍——再在上面打包出应用，并检查三个原生库确实都进了 APK。</p>
<p>遇到 <code>v*</code> 标签时，<code>release.yml</code> 会编译发布版 APK、用发布密钥签名、比对证书指纹，然后把它连同 SHA-256 一起发成 GitHub Release。</p>
<p>密钥本身放在仓库的 secrets 里——keystore 用 base64 编码，密码和别名放在旁边——绝不进代码库。流水线会拒绝发布证书对不上的构建：换了密钥签出来的 APK 装不上旧版本，而让用户在自己的手机上发现这件事，不是发现的好地方。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="拿去用">拿去用<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#%E6%8B%BF%E5%8E%BB%E7%94%A8" class="hash-link" aria-label="拿去用的直接链接" title="拿去用的直接链接" translate="no">​</a></h2>
<p>发布版 APK 就在仓库里，用发布密钥签名，可以直接覆盖安装 1.0.0.8：</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.9</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">downloads/whereq-dosbox-1.0.0.9.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: cd6d0bdafd0f84c7324936c89a6cab14ed87a21e4211ed8909078b4a7a51ac02</span><br></div></code></pre></div></div>
<p>它跑在 <strong>arm64-v8a、armeabi-v7a 和 x86_64</strong> 设备上，要求 Android 5.0 及以上，完全离线，不需要账号，没有任何追踪。项目采用 GPL-2.0 许可，DOSBox 核心连同它的 <code>AUTHORS</code>、<code>ChangeLog</code>、<code>COPYING</code> 和逐文件头注释一起嵌入。</p>
<p>再说一遍：<strong>这篇文章不是文档。</strong> 文档是仓库本身：构建指南、移植日志（里面有一节专门讲那三条宽度规则和量出来的键宽）、键盘本身的设计笔记，以及这个移植的每一行代码。请去读那些，而不是信我的一面之词。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="谢谢-dosbox">谢谢 DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9-CN#%E8%B0%A2%E8%B0%A2-dosbox" class="hash-link" aria-label="谢谢 DOSBox的直接链接" title="谢谢 DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> 写成——一群志愿者把 1994 年的一套操作系统改造到此后世界造出的每一台机器上都能跑，包括那些当时还不存在的机器。他们让它活过了三十年，并免费交给任何想要的人。WhereQ-DOSBox 只是建在他们工作之上的一层薄薄的壳。原创力、手艺和慷慨完全属于他们。</p>
<p>这个移植基于 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 做的 DOSBox r4305 的 Emscripten 版，它又来自 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 最早那次用 Emscripten 编译 DOSBox 的尝试，并且踩着 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 的 Emscripten 工作一路往前。窗口、音频和触摸输入则由 <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> 的 SDL2 库承担。</p>
<p><strong>DOSBox 是 DOSBox 项目的商标</strong>；这个移植与 DOSBox 团队没有任何隶属或背书关系。</p>
<hr>
<p><em>如果你手上的手机屏幕比较窄、觉得字母键太小——请告诉我。这一版里唯一一件我希望在发布前就见到真机的事情，与其我自己发现，不如你来告诉我。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>模拟器</category>
            <category>发布</category>
            <category>怀旧</category>
            <category>开源</category>
            <category>whereq</category>
            <category>键盘</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.9: the keyboard becomes a handheld console]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9</guid>
            <pubDate>Mon, 16 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-compromise-wearing-the-shape-of-a-keyboard">A compromise, wearing the shape of a keyboard<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#a-compromise-wearing-the-shape-of-a-keyboard" class="hash-link" aria-label="A compromise, wearing the shape of a keyboard的直接链接" title="A compromise, wearing the shape of a keyboard的直接链接" translate="no">​</a></h2>
<p>The DOS picture is 4:3. A phone in landscape is 20:9. The difference is two black bars, one on each side of the picture, and for two releases those bars were where the keys lived.</p>
<p>They were not bad bars. The arrows went into the inverted T of a real keyboard, the modifiers and the editing keys into the other side, and the picture kept the whole middle of the screen. It worked.</p>
<p>It was also the wrong shape for the thing it was standing in for. A DOS game is played with the left thumb on the arrows and the right thumb on the keys, and every one of those keys was a long way from where a thumb expects it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-a-handheld-console-does">What a handheld console does<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#what-a-handheld-console-does" class="hash-link" aria-label="What a handheld console does的直接链接" title="What a handheld console does的直接链接" translate="no">​</a></h2>
<p>A handheld console puts the screen in the middle and the controls in your hands — one hand on each side — and it never lets the controls sit on top of the picture.</p>
<p>That is the whole idea behind 1.0.0.9. The bars are no longer two columns of whatever fitted; they are <strong>two pads</strong>, and the picture sits untouched in the middle.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-keyboard-pads.png" alt="WhereQ-DOSBox in landscape on an Android phone: the DOSBox welcome screen in the middle, a left pad with File, Esc and Tab on top, the digits 1 to 5, the left half of a QWERTY and the arrow keys as a D-pad, and a right pad with #+=, Fn and Backspace on top, the right half of a QWERTY and the action keys Alt, Ctrl, Shift, Space and Enter" width="900"></p>
<p align="center"><sub>The left pad carries the arrows and the left half of the keyboard, the
right pad the action keys and the right half. The picture keeps the middle,
and nothing is drawn over it.</sub></p>
<p>The <strong>left pad</strong> is the thumb that steers: the four arrows as a <strong>D-pad</strong> — up on top, left and right side by side, down below, so the finger reads the direction by shape alone — and above them the left half of a split QWERTY, with <strong>File</strong>, <strong>Esc</strong> and <strong>Tab</strong> along the top.</p>
<p>The <strong>right pad</strong> is the thumb that acts: <strong>Alt</strong>, <strong>Ctrl</strong>, <strong>Shift</strong>, <strong>Space</strong> and <strong>Enter</strong> under the right thumb, the right half of the QWERTY above them, and <strong>#+=</strong>, <strong>Fn</strong> and Backspace along the top.</p>
<p>The QWERTY is split rather than shrunk. <code>12345 qwert asdfg zxcvb</code> on the left, <code>67890 yuiop hjkl: nm./\</code> on the right — each half is a real key size, not a miniature of the whole thing.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="three-layers-one-key-each">Three layers, one key each<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#three-layers-one-key-each" class="hash-link" aria-label="Three layers, one key each的直接链接" title="Three layers, one key each的直接链接" translate="no">​</a></h2>
<p>A split keyboard is only half the story; the other half is what you do when you run out of keys. The answer here is <strong>one key per layer</strong>, in the top row of the right pad.</p>
<p><strong>#+=</strong> swaps both halves for the punctuation. The key lights up blue while its layer is on, and turns into <em>abc</em>, because that is what pressing it brings you back to.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-keyboard-symbols.png" alt="WhereQ-DOSBox with the symbol layer switched on: the #+= key at the top right is lit blue and reads abc, and both pads show punctuation — ! @ # $ % on the left and ^ &amp; * ( ) on the right" width="900"></p>
<p align="center"><sub>The punctuation layer. Every shifted character sits directly below its
unshifted key, and the switched key is lit.</sub></p>
<p><strong>Fn</strong> brings up the functions: F1 to F12 on the left, and Ins / Del, Home / End, PgUp / PgDn, Caps, PrtSc and Pause on the right.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-keyboard-functions.png" alt="WhereQ-DOSBox with the function layer switched on: the Fn key is lit blue, the left pad shows F1 to F12 and the right pad shows Ins, Home, PgUp, Del, End, PgDn, Caps, PrtSc and Pause" width="900"></p>
<p align="center"><sub>The function layer — the whole F-row and the editing keys, without
stealing a single key from the letters.</sub></p>
<p>And because the letter layer of the right half already carries <code>: . / \</code>, typing a DOS path needs no layer switch at all: <code>C:\GAMES\DUNE\SETUP.EXE</code> is just letters and punctuation, in that order, on one layer.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="ctrl-alt-and-shift-the-way-a-game-wants-them">Ctrl, Alt and Shift, the way a game wants them<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#ctrl-alt-and-shift-the-way-a-game-wants-them" class="hash-link" aria-label="Ctrl, Alt and Shift, the way a game wants them的直接链接" title="Ctrl, Alt and Shift, the way a game wants them的直接链接" translate="no">​</a></h2>
<p>The modifiers were the part I had to think about longest, because two different games want two different things from Ctrl.</p>
<p>A <em>tap</em> on Ctrl, Alt or Shift <strong>arms</strong> it: the next key you press is modified, and the modifier releases itself. Ctrl, then C — that is what a text editor or a DOS shell wants.</p>
<p>A <em>hold</em> keeps it pressed for as long as your finger is down, like a real key. That is what a game wants from its fire and strafe keys: hold Ctrl on the right thumb while the left thumb walks the D-pad, and the game sees both at once.</p>
<p>The old keyboard could only do the first one. The new pads do both, because a modifier is just a key that is down.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-layout-follows-the-screen">The layout follows the screen<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#the-layout-follows-the-screen" class="hash-link" aria-label="The layout follows the screen的直接链接" title="The layout follows the screen的直接链接" translate="no">​</a></h2>
<p>Not every phone has 20:9 of letterbox to work with, so the keyboard picks its shape from the width of the bar: the full pads when there is room for them (at least 116 dp), a single key column per side with the fold-up QWERTY when there is less, and a slim strip along the bottom in portrait.</p>
<p>Here is the part I am not happy about.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-keyboard-pads-18x9.png" alt="WhereQ-DOSBox on an 18:9 display: the same two pads, but the letter keys are noticeably smaller and the picture is proportionally larger" width="900"></p>
<p align="center"><sub>The same layout on an 18:9 screen. The pads still fit, but the letters
are small — about 24 dp wide, against 33 dp on a 20:9 screen.</sub></p>
<p>On a 20:9 screen the letter keys come out at <strong>32.8 dp</strong> wide. On an 18:9 screen — the shape of a lot of phones — the bars are narrower and the same layout leaves the letters at <strong>23.6 dp</strong>, about 2.9 % of the screen width, where a normal phone keyboard key is roughly twice that. The D-pad and the action keys keep their full size; it is the letters that get tight.</p>
<p>I measured it rather than guessed: both widths were run on the emulator and typed into, and the screenshots of all three layers at both widths are in the repository. What I have <em>not</em> done is try it on a physical 18:9 phone, and that is the gap I would want a reader with such a phone to close for me.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="nothing-underneath-changed">Nothing underneath changed<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#nothing-underneath-changed" class="hash-link" aria-label="Nothing underneath changed的直接链接" title="Nothing underneath changed的直接链接" translate="no">​</a></h2>
<p>The whole release is app-layer work. The SDL surface stays full-screen, the keyboard only ever draws in the bars beside the picture, and <strong><code>libdosbox.so</code> is the same library 1.0.0.8 shipped</strong> — byte for byte the same native core, recompiled with the same flags.</p>
<p>Sometimes the honest way to describe a big change is to say what did <em>not</em> change.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-pipeline-builds-the-releases-now">The pipeline builds the releases now<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#the-pipeline-builds-the-releases-now" class="hash-link" aria-label="The pipeline builds the releases now的直接链接" title="The pipeline builds the releases now的直接链接" translate="no">​</a></h2>
<p>The repository has a CI pipeline for the first time. On every push and every pull request, <code>ci.yml</code> builds the emulator from source for all three ABIs — SDL2 and the whole DOSBox core, three times — and packages an app on top of them, checking that all three native libraries really made it into the APK.</p>
<p>On a <code>v*</code> tag, <code>release.yml</code> builds the release APK, signs it with the release key, checks the certificate against the known fingerprint, and publishes it as a GitHub Release with its SHA-256.</p>
<p>The key itself lives in the repository's secrets — the keystore base64-encoded, the store password and the alias beside it — and never in the tree. The pipeline refuses to publish if the certificate is not the one every previous release was signed with, because an APK signed with a different key cannot be installed over the old one, and finding that out on a user's phone is not a good place to find it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="get-it">Get it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#get-it" class="hash-link" aria-label="Get it的直接链接" title="Get it的直接链接" translate="no">​</a></h2>
<p>The release APK is in the repository, signed with the release key, so it installs over 1.0.0.8 in place:</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.9</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">downloads/whereq-dosbox-1.0.0.9.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: cd6d0bdafd0f84c7324936c89a6cab14ed87a21e4211ed8909078b4a7a51ac02</span><br></div></code></pre></div></div>
<p>It runs on <strong>arm64-v8a, armeabi-v7a and x86_64</strong> devices, Android 5.0 and newer, entirely offline, with no account and no tracking. The project is GPL-2.0, and the DOSBox core is embedded with its <code>AUTHORS</code>, <code>ChangeLog</code>, <code>COPYING</code> and per-file headers intact.</p>
<p>Again, <strong>this post is not the documentation.</strong> The documentation is the repository: the build guide, the porting log — including the section that explains the three width rules and the measured key sizes — the design notes of the keyboard itself, and every line of the port. Please read those rather than take my word for it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.9#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They kept it alive for three decades and gave it away to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which grew out of <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. The SDL2 library by <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> carries the window, the audio and the touch input.</p>
<p><strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>If you have a phone with a narrow screen and the letters feel too small — tell me. That is the one thing in this release I would like to have seen on real hardware before shipping it, and I would rather hear it from you than find it out myself.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>emulator</category>
            <category>release</category>
            <category>retro</category>
            <category>open-source</category>
            <category>whereq</category>
            <category>keyboard</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.7：跑自己的 DOS 游戏、真正的 JIT，以及一个塞得进手机的启动器]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN</guid>
            <pubDate>Fri, 13 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="模拟器是最简单的那一环">模拟器是最简单的那一环<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E6%A8%A1%E6%8B%9F%E5%99%A8%E6%98%AF%E6%9C%80%E7%AE%80%E5%8D%95%E7%9A%84%E9%82%A3%E4%B8%80%E7%8E%AF" class="hash-link" aria-label="模拟器是最简单的那一环的直接链接" title="模拟器是最简单的那一环的直接链接" translate="no">​</a></h2>
<p>昨天，我把 WhereQ-DOSBox 放到了外面——DOSBox 的原生 Android 移植版，模拟器核心以真正的 <code>libdosbox.so</code> 跑在 APK 里面。</p>
<p>那篇发布公告许下了一个愿：<strong>你自己的 DOS 游戏，跑在你口袋里那台真正的机器上。</strong></p>
<p>这种愿望，要是只做到“能启动、能看到 <code>C:\&gt;</code> 提示符”，很便宜。可一旦有人真的<strong>拿去用</strong>，模拟器反而成了整个问题里最小的一块。</p>
<p>所以从 v1.0.0.2 到 v1.0.0.7，这六个版本真正修掉的东西，是这些。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第一件事游戏怎么进到手机里">第一件事：游戏怎么进到手机里？<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E7%AC%AC%E4%B8%80%E4%BB%B6%E4%BA%8B%E6%B8%B8%E6%88%8F%E6%80%8E%E4%B9%88%E8%BF%9B%E5%88%B0%E6%89%8B%E6%9C%BA%E9%87%8C" class="hash-link" aria-label="第一件事：游戏怎么进到手机里？的直接链接" title="第一件事：游戏怎么进到手机里？的直接链接" translate="no">​</a></h2>
<p>这是第一道墙。DOSBox 起来了，然后你面对着一个空空的驱动器。你的游戏躺在某个 1997 年的 <code>.zip</code> 里，而手机上的文件管理器不会替你把 DOS 目录树解开。</p>
<p>于是 App 里长出了一个<strong>启动器</strong>。一个 <code>.zip</code> 就是一个<strong>套装（bundle）</strong>：任意一个 DOS 程序，解压一次，放进挂载好的 C: 盘的 <code>C:\GAMES\&lt;n&gt;</code>，再配一个把它启动起来的 <code>RUN.BAT</code>。三种进法，一种权限都不用申请：</p>
<ul>
<li class="">系统文件选择器，装单个 <code>.zip</code>；</li>
<li class="">系统文件夹选择器，把一个文件夹里的 <code>.zip</code> 一次性全解开；</li>
<li class="">以及<strong>用 WhereQ-DOSBox 打开</strong>——在文件管理器里点一下，套装自己就装好了。</li>
</ul>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-files-panel.jpg" alt="WhereQ-DOSBox 的 Files 面板，列着已安装的 Ultima8 和 whereq-demo-bundle 两个套装，每个都有 Play、Launch 和 Remove，上方是 Install a bundle 按钮" width="900"></p>
<p align="center"><sub>Files 面板。两个套装，点一下就能开玩；还有一个永远有效的逃生通道
（<strong>Exit to prompt</strong>）——哪怕游戏已经卡死或者黑屏了，它也管用。</sub></p>
<p>有一个细节比看上去费事：DOSBox 是在挂载驱动器的那一刻缓存目录列表的。之后才装进去的套装，<strong>不在</strong>那份缓存里；于是会去枚举自己文件的安装程序，什么也找不到。所以启动器每开一个游戏，都会让模拟器重启进一个干净的进程、重新挂载一次 C: 盘。多花一秒，但这正是“装上了”和“真的能跑”的区别。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第二件事那个按钮的名字起错了">第二件事：那个按钮的名字起错了<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E7%AC%AC%E4%BA%8C%E4%BB%B6%E4%BA%8B%E9%82%A3%E4%B8%AA%E6%8C%89%E9%92%AE%E7%9A%84%E5%90%8D%E5%AD%97%E8%B5%B7%E9%94%99%E4%BA%86" class="hash-link" aria-label="第二件事：那个按钮的名字起错了的直接链接" title="第二件事：那个按钮的名字起错了的直接链接" translate="no">​</a></h2>
<p>启动器刚来的时候，按钮叫 <strong>Games</strong>——因为我想当然地以为大家只想要游戏。但那个名字是错的：启动器打开的并不是游戏，而是套装；一个套装可以装着任何 DOS 程序——一个工具、一个文本界面的程序、一个 demo、一集你一直想打完的 shareware。</p>
<p>所以按钮现在叫 <strong>File</strong>——DOS 时代的老叫法——面板也改成了 <strong>Files</strong>：<em>Install a bundle (.zip)</em>、<em>No bundles installed yet.</em>、<em>Start file…</em>。</p>
<p>这是件小事。但正是这种小事，把一个演示变成一个工具。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="第三件事键盘塞不进屏幕">第三件事：键盘塞不进屏幕<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E7%AC%AC%E4%B8%89%E4%BB%B6%E4%BA%8B%E9%94%AE%E7%9B%98%E5%A1%9E%E4%B8%8D%E8%BF%9B%E5%B1%8F%E5%B9%95" class="hash-link" aria-label="第三件事：键盘塞不进屏幕的直接链接" title="第三件事：键盘塞不进屏幕的直接链接" translate="no">​</a></h2>
<p>屏幕键盘原本是 21 个等宽的键。横屏的时候，这比手机还宽——最后一个键被切掉，<strong>根本按不到</strong>。现在这些键改成按权重分配，整条键盘永远正好铺满屏幕宽度。</p>
<p>接着键盘条本身又成了问题：它吃掉了三分之一的屏幕。DOS 画面是 4:3 的，横屏两侧本来就有黑边——于是那些常驻按键现在直接住进了这两条黑边里，变成左右两列。左边是 Ctrl、Alt、Shift 这些修饰键，右边是 <strong>File</strong>、<strong>Ent</strong>、<strong>Space</strong> 和方向键，整块屏幕中间完整地留给 DOS。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-starfall.jpg" alt="STARFALL 在横屏手机上运行：DOS 画面在正中，屏幕键盘分列在左右两侧的黑边里" width="900"></p>
<p align="center"><sub>示例套装 STARFALL 跑在新布局里：游戏在中间，按键在两侧的黑边里。</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="更重的一件事jit和那些需要它的游戏">更重的一件事：JIT，和那些需要它的游戏<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E6%9B%B4%E9%87%8D%E7%9A%84%E4%B8%80%E4%BB%B6%E4%BA%8Bjit%E5%92%8C%E9%82%A3%E4%BA%9B%E9%9C%80%E8%A6%81%E5%AE%83%E7%9A%84%E6%B8%B8%E6%88%8F" class="hash-link" aria-label="更重的一件事：JIT，和那些需要它的游戏的直接链接" title="更重的一件事：JIT，和那些需要它的游戏的直接链接" translate="no">​</a></h2>
<p>实模式的 DOS 程序用解释器跑得非常好——DOSBox 本来就是这么写的，对任何 8 位、16 位的程序来说解释器都够快。</p>
<p>保护模式程序是另一回事。DOS/4GW 扩展程序、保护模式游戏：那是一套不同的 CPU 模型，而解释器只能一条指令一条指令地走。<strong>Ultima VIII</strong> 就是一个 DOS/4GW 保护模式游戏——而保护模式代码，正是重编译核心存在的理由。</p>
<p>DOSBox 自带一个 JIT——重编译核心，在运行时直接生成机器码。上游是靠 GCC 插件来编译它的，而 NDK 的 clang 做不到；Android 又禁止让可写的内存可执行，而原版的代码缓存正是这么干的。</p>
<p>这两个问题最后都有解。可移植的代码生成器（arm64、armv7、x86_64）不需要插件，直接往一块缓冲区里生成机器码；那块缓冲区改用匿名 <code>PROT_EXEC</code> 映射，而不是可写的堆内存，来获得可执行权限。现在这个 JIT 已经编进了三个 Android ABI 的 <code>libdosbox.so</code>。</p>
<p>而随包发布的配置是 <code>core=auto</code>：</p>
<ul>
<li class="">一直待在实模式的程序跑<strong>解释器</strong>，跟以前一模一样——JIT 根本不会启动，代码缓存连分配都不会发生；</li>
<li class="">一旦切换到保护模式的程序，在第一次模式切换的那一刻交给<strong>重编译核心</strong>。</li>
</ul>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-screenshot-phone.jpg" alt="WhereQ-DOSBox 横屏运行在 Android 手机上：正中是 DOSBox 欢迎画面和已挂载的 C: 盘，屏幕键盘分列在左右两侧的黑边里" width="900"></p>
<p align="center"><sub>欢迎画面和已挂载的 C: 盘，按键在两侧黑边里。中间跑的是货真价实的 DOSBox 核心，
不是一个仿写的实现。</sub></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="关于-apk-体积我得说实话">关于 APK 体积，我得说实话<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E5%85%B3%E4%BA%8E-apk-%E4%BD%93%E7%A7%AF%E6%88%91%E5%BE%97%E8%AF%B4%E5%AE%9E%E8%AF%9D" class="hash-link" aria-label="关于 APK 体积，我得说实话的直接链接" title="关于 APK 体积，我得说实话的直接链接" translate="no">​</a></h3>
<p>第一篇公告里说 APK 大约 <strong>5.3 MB</strong>。现在大约 <strong>15.5 MB</strong>——与其让你下载时才发现，不如我先解释清楚。</p>
<p>两个原因，都是故意的。原生库在 APK 里是<strong>不压缩</strong>存放的，这样 Android 可以直接从 APK 里映射它们，而不用每次安装都复制到磁盘——差别的大头在这儿。另外 App 层现在是 Kotlin + AndroidX，带来了大约 4.5 MB 的 dex。</p>
<p>这笔交换是：下载大一点，换来更快的安装，以及一台更像机器的机器。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="我写进文档却没做出来的那个设置">我写进文档、却没做出来的那个设置<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E6%88%91%E5%86%99%E8%BF%9B%E6%96%87%E6%A1%A3%E5%8D%B4%E6%B2%A1%E5%81%9A%E5%87%BA%E6%9D%A5%E7%9A%84%E9%82%A3%E4%B8%AA%E8%AE%BE%E7%BD%AE" class="hash-link" aria-label="我写进文档、却没做出来的那个设置的直接链接" title="我写进文档、却没做出来的那个设置的直接链接" translate="no">​</a></h2>
<p>v1.0.0.6 里，我在文档里、在这个仓库里写过这么一句：<em>“如果 JIT 的代码缓存分配不出来，就把 <code>core=normal</code> 写进 <code>dosbox.conf</code> 作为退路。”</em></p>
<p>然后我自己照着这句话试了一遍。<code>dosbox.conf</code> 每次启动都会从随包的模板重新生成——这是故意的，这样模板一改，已经装在手机上的版本也能拿到。而这意味着<strong>手工改过的 <code>dosbox.conf</code> 会在下次启动时被覆盖</strong>。何况那个文件本来就在 App 的私有目录里，任何文件管理器都够不着。</p>
<p><strong>我文档里写的那个退路，其实根本够不着。</strong> 确实有那么一小撮老 DOS 程序在重编译核心上会出毛病，而我当时没给它们留任何出路。</p>
<p>所以 Files 面板现在多了一个 <strong>Config</strong> 按钮：</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-cpu-core.jpg" alt="WhereQ-DOSBox 的 CPU core 对话框，提供 Auto、Normal、Dynamic、Simple、Prefetch 五个选项，当前选中 Auto" width="900"></p>
<p align="center"><sub>CPU core 现在可以在 App 里选：Auto（默认）、Normal、Dynamic、Simple、Prefetch。
DOSBox 是启动时决定用哪个核心的，所以 App 会问你要不要重启。</sub></p>
<p>这个选择会被存下来，写进生成出来的配置文件，重启之后还在，App 升级之后也还在。一个小对话框，换来一句终于能兑现的承诺。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="还改了什么">还改了什么<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E8%BF%98%E6%94%B9%E4%BA%86%E4%BB%80%E4%B9%88" class="hash-link" aria-label="还改了什么的直接链接" title="还改了什么的直接链接" translate="no">​</a></h2>
<p>App 层从 Java 换成了 Kotlin——同样的八个类，重写了一遍——<strong>Gradle 现在是正式的构建方式</strong>。发布脚本学会了更新 Android manifest，也不再把整个工作树一股脑塞进发布提交里。模拟器脚本改用真实 GPU，而不是那个会把屏幕画成碎片的软件光栅器。</p>
<p>还有 <strong>STARFALL</strong>——那个示例套装——已经进了仓库：一个用 16 位 DOS 汇编写的迷你街机游戏，一个大约 5 KB 的 <code>.COM</code>，没有运行时、没有依赖，并且以可以直接安装的 <code>.zip</code> 形式提交了。它的存在是为了让新用户不用先去找一个游戏，就能把整条流程走一遍：装套装、按 Play、看游戏跑起来。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="拿去用">拿去用<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E6%8B%BF%E5%8E%BB%E7%94%A8" class="hash-link" aria-label="拿去用的直接链接" title="拿去用的直接链接" translate="no">​</a></h2>
<p>发布版 APK 就在仓库里，用发布密钥签名，所以后来的版本可以直接覆盖安装：</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> —— tag <strong>v1.0.0.7</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">downloads/whereq-dosbox-1.0.0.7.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: 2e97f12f3901acbdc23f62395316df25aa51f4a081d941a950b2d7dfa36910a1</span><br></div></code></pre></div></div>
<p>支持 <strong>arm64-v8a、armeabi-v7a 和 x86_64</strong> 设备，Android 5.0 及以上，全程离线，不要账号，不做任何追踪。</p>
<p>这是一个 GPL-2.0 的项目，DOSBox 核心以 <code>AUTHORS</code>、<code>ChangeLog</code>、<code>COPYING</code> 和逐文件头部的形式完整嵌入。整个移植只动了核心里寥寥几处——SDL 的视频与触摸路径、鼠标映射、JIT 代码缓存的 Android 分支，还有两处只为消掉编译器警告而做的改动。其余全部是上游代码。</p>
<p>再说一遍：<strong>这篇文章不是文档。</strong> 文档就是仓库本身——构建指南、移植记录、性能测试报告，以及移植部分的每一行代码。请你自己去读，而不是听我在这儿说。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="谢谢dosbox">谢谢，DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7-CN#%E8%B0%A2%E8%B0%A2dosbox" class="hash-link" aria-label="谢谢，DOSBox的直接链接" title="谢谢，DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 是由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox 团队</a> 写出来的——一群志愿者，把一个 1994 年的操作系统做到了此后世界上每一台机器上都能跑，包括那些当时还不存在的机器。他们让它活过了三十年，并免费送给每一个想要它的人。WhereQ-DOSBox 只是叠在他们工作之上的一层薄壳。原创、手艺和慷慨，全部属于他们。</p>
<p>这个移植建立在 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong> 之上——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 用 Emscripten 做的 DOSBox r4305 版本；而 Em-DOSBox 本身，起源于 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 第一次尝试用 Emscripten 编译 DOSBox，后来又搭上了 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 在 Emscripten 上的工作。窗口、音频和触摸输入则由 <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> 的 SDL2 库承担。</p>
<p><strong>DOSBox 是 DOSBox 项目的商标</strong>；本移植与 DOSBox 团队无隶属关系，也未获其背书。</p>
<hr>
<p><em>如果你自己的某个游戏现在能在手机上跑起来了——或者跑不起来，而你在那个 CPU core 对话框前放弃了——都请告诉我。我一直在记一份清单，那是我收到的最有用的东西。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>模拟器</category>
            <category>发布</category>
            <category>怀旧</category>
            <category>开源</category>
            <category>whereq</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox 1.0.0.7: your own DOS games, a real JIT, and a launcher that fits on a phone]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7</guid>
            <pubDate>Fri, 13 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-emulator-was-the-easy-part">The emulator was the easy part<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#the-emulator-was-the-easy-part" class="hash-link" aria-label="The emulator was the easy part的直接链接" title="The emulator was the easy part的直接链接" translate="no">​</a></h2>
<p>Yesterday I put WhereQ-DOSBox out into the world: a native Android port of DOSBox, the emulator core running as a real <code>libdosbox.so</code> inside an APK.</p>
<p>The announcement made a promise: <em>your own DOS games, on the actual machine in your pocket.</em></p>
<p>A promise like that is cheap to make with an emulator that boots to a <code>C:\&gt;</code> prompt. It gets expensive the moment someone tries to actually <strong>use</strong> it — because then the emulator is the smallest part of the problem.</p>
<p>So here is what six releases, v1.0.0.2 through v1.0.0.7, actually fixed.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="first-how-do-you-get-your-games-onto-the-phone">First: how do you get your games onto the phone?<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#first-how-do-you-get-your-games-onto-the-phone" class="hash-link" aria-label="First: how do you get your games onto the phone?的直接链接" title="First: how do you get your games onto the phone?的直接链接" translate="no">​</a></h2>
<p>This was the wall. DOSBox boots, and then you are staring at a drive with nothing on it. Your games live in a <code>.zip</code> from somewhere in 1997, and the file manager on your phone is not going to unpack a DOS directory tree for you.</p>
<p>So the app grew a <strong>launcher</strong>. A <code>.zip</code> is a <em>bundle</em>: any DOS program, unpacked once into <code>C:\GAMES\&lt;n&gt;</code> on the mounted C: drive, with a <code>RUN.BAT</code> that starts it. Three ways to get one in, none of which asks for a permission:</p>
<ul>
<li class="">the system file picker, for a single <code>.zip</code>;</li>
<li class="">the system folder picker, which unpacks every <code>.zip</code> in a folder at once;</li>
<li class="">and <strong>Open with WhereQ-DOSBox</strong>, so a bundle you tap in a file manager installs itself.</li>
</ul>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-files-panel.jpg" alt="The Files panel of WhereQ-DOSBox, listing the installed bundles Ultima8 and whereq-demo-bundle, each with Play, Launch and Remove, and the Install a bundle button at the top" width="900"></p>
<p align="center"><sub>The Files panel. Two bundles, one tap to play, and an escape hatch
(<strong>Exit to prompt</strong>) that always works — even when the game has
hung or gone black.</sub></p>
<p>One detail that took more care than it looks: DOSBox caches the directory listing of a drive when it mounts it. A bundle installed afterwards is <em>not</em> in that cache, so an installer that enumerates its own files finds nothing. The launcher therefore restarts the emulator into a clean boot with a freshly mounted C: for every game it starts. It costs a second, and it is the difference between "installed" and "actually runs".</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="then-the-button-was-called-the-wrong-thing">Then: the button was called the wrong thing<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#then-the-button-was-called-the-wrong-thing" class="hash-link" aria-label="Then: the button was called the wrong thing的直接链接" title="Then: the button was called the wrong thing的直接链接" translate="no">​</a></h2>
<p>The launcher arrived as a <strong>Games</strong> button, because that is what I assumed people would want. It was wrong: the launcher does not open games. It opens bundles, and a bundle can hold any DOS program — a utility, a text-mode application, a demo, a shareware episode you always wanted to finish.</p>
<p>So the button is <strong>File</strong> now — the old DOS way — and the panel is <strong>Files</strong>. <em>Install a bundle (.zip)</em>, <em>No bundles installed yet</em>, <em>Start file…</em>. Small thing. It is the kind of small thing that turns a demo into a tool.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="and-the-keyboard-did-not-fit-on-the-screen">And: the keyboard did not fit on the screen<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#and-the-keyboard-did-not-fit-on-the-screen" class="hash-link" aria-label="And: the keyboard did not fit on the screen的直接链接" title="And: the keyboard did not fit on the screen的直接链接" translate="no">​</a></h2>
<p>The on-screen keyboard had 21 keys of a fixed width. In landscape, that is wider than the phone — the last key was cut off and could not be pressed. The keys are weighed now, so the strip always fills the width exactly.</p>
<p>Then the strip itself became the problem: it ate a third of the screen. The DOS picture is 4:3 and letterboxed, so in landscape there are black bars down the left and right — and the always-on keys now live in those bars as two vertical columns. The modifiers on the left, <strong>File</strong>, <strong>Ent</strong>, <strong>Space</strong> and the arrow keys on the right, and the whole middle of the screen stays a DOS screen.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-starfall.jpg" alt="STARFALL running on the phone in landscape, with the DOS picture in the middle and the two on-screen keyboard columns in the letterbox bars at the left and right edges" width="900"></p>
<p align="center"><sub>STARFALL, the example bundle, running in the new layout: the game in the
middle, the keys in the bars on either side of it.</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-bigger-one-a-jit-and-the-games-that-needed-it">The bigger one: a JIT, and the games that needed it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#the-bigger-one-a-jit-and-the-games-that-needed-it" class="hash-link" aria-label="The bigger one: a JIT, and the games that needed it的直接链接" title="The bigger one: a JIT, and the games that needed it的直接链接" translate="no">​</a></h2>
<p>Real-mode DOS programs run perfectly on an interpreter — DOSBox was written that way, and the interpreter is fast enough for anything 8-bit and 16-bit.</p>
<p>Protected-mode programs are a different story. A DOS/4GW extender, a protected-mode game: that is a different CPU model, and the interpreter walks it instruction by instruction. <strong>Ultima VIII</strong> — a DOS/4GW game — is exactly the kind of program the recompiler exists for.</p>
<p>DOSBox has a JIT — a recompiling core that emits machine code at run time. Upstream builds it with a GCC plugin, which the NDK's clang cannot do, and Android forbids making writable memory executable, which is what the stock code cache does.</p>
<p>Both problems turned out to be solvable. The portable code generators (arm64, armv7, x86_64) emit machine code into a buffer with no plugin involved, and the buffer is made executable with an anonymous <code>PROT_EXEC</code> mapping instead of a writable heap block. The JIT is now compiled into <code>libdosbox.so</code> for all three Android ABIs.</p>
<p>And the shipped configuration is <code>core=auto</code>:</p>
<ul>
<li class="">a program that stays in real mode runs on the <strong>interpreter</strong>, exactly as before — the JIT never engages and the code cache is never even allocated;</li>
<li class="">a program that switches into protected mode hands over to the <strong>recompiler</strong> at the first mode switch.</li>
</ul>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-screenshot-phone.jpg" alt="WhereQ-DOSBox running on an Android phone in landscape: the DOSBox welcome screen and a mounted C drive in the middle, the on-screen keyboard in the letterbox bars on the left and right" width="900"></p>
<p align="center"><sub>The welcome screen and a mounted C: drive, with the keyboard in the bars
on either side. The emulator core is the real DOSBox, not a re-implementation
of it.</sub></p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="honest-about-the-apk-size">Honest about the APK size<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#honest-about-the-apk-size" class="hash-link" aria-label="Honest about the APK size的直接链接" title="Honest about the APK size的直接链接" translate="no">​</a></h3>
<p>The first announcement said the APK was about <strong>5.3 MB</strong>. It is now about <strong>15.5 MB</strong>, and I would rather explain that than let you find out from the download.</p>
<p>Two reasons, both on purpose. The native libraries are stored <strong>uncompressed</strong> in the APK, so Android can map them straight out of it instead of copying them to disk on every install — that is most of the difference. And the app layer is now Kotlin with AndroidX, which adds roughly 4.5 MB of dex.</p>
<p>The trade is: a bigger download, in exchange for an install that is faster and a machine that behaves like a machine.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-setting-i-documented-but-did-not-ship">The setting I documented but did not ship<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#the-setting-i-documented-but-did-not-ship" class="hash-link" aria-label="The setting I documented but did not ship的直接链接" title="The setting I documented but did not ship的直接链接" translate="no">​</a></h2>
<p>In v1.0.0.6 I wrote, in the documentation and in this very repository: <em>"If the JIT code cache cannot be allocated, put <code>core=normal</code> in <code>dosbox.conf</code> as the fallback."</em></p>
<p>Then I tried to follow my own advice. <code>dosbox.conf</code> is regenerated from the shipped template on every boot — deliberately, so that a change to the template reaches phones that are already installed. Which means a hand-edited <code>dosbox.conf</code> is overwritten at the next start. And the file lives in the app's private directory anyway, where no file manager can reach it.</p>
<p><strong>The fallback I documented was not reachable.</strong> A handful of old DOS programs do misbehave on the recompiler, and I had given them no way out.</p>
<p>So the Files panel has a <strong>Config</strong> button now:</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-cpu-core.jpg" alt="The CPU core dialog in WhereQ-DOSBox, offering Auto, Normal, Dynamic, Simple and Prefetch, with Auto selected" width="900"></p>
<p align="center"><sub>The CPU core, pickable in the app: Auto (the default), Normal, Dynamic,
Simple, Prefetch. DOSBox chooses its core when it starts, so the app asks
whether to restart.</sub></p>
<p>The choice is stored and written into the generated configuration, so it survives a restart and an app update. One small dialog — and a promise in the documentation that is now true.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="what-else-changed">What else changed<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#what-else-changed" class="hash-link" aria-label="What else changed的直接链接" title="What else changed的直接链接" translate="no">​</a></h2>
<p>The app layer was ported from Java to Kotlin — the same eight classes, rewritten — and <strong>Gradle is now the canonical build</strong>. The release script was taught to update the Android manifest, and it no longer stages the whole working tree into a release commit. The emulator script starts the emulator on the real GPU instead of a software rasterizer that drew the screen in scattered tiles.</p>
<p>And <strong>STARFALL</strong> — the example bundle — is in the tree: a tiny arcade game in 16-bit DOS assembly, one <code>.COM</code> of about 5 KB, no runtime, no libraries, committed as a ready-to-install <code>.zip</code>. It exists so that a new user can see the whole flow — install a bundle, press Play, watch a game run — without having to find a game first.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="get-it">Get it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#get-it" class="hash-link" aria-label="Get it的直接链接" title="Get it的直接链接" translate="no">​</a></h2>
<p>The release APK is in the repository, and it is signed with the release key, so a later version installs over it in place:</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong> — tag <strong>v1.0.0.7</strong></p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">downloads/whereq-dosbox-1.0.0.7.apk</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">sha256: 2e97f12f3901acbdc23f62395316df25aa51f4a081d941a950b2d7dfa36910a1</span><br></div></code></pre></div></div>
<p>It runs on <strong>arm64-v8a, armeabi-v7a and x86_64</strong> devices, Android 5.0 and newer, entirely offline, with no account and no tracking.</p>
<p>The project is GPL-2.0 and the DOSBox core is embedded with its <code>AUTHORS</code>, <code>ChangeLog</code>, <code>COPYING</code> and per-file headers intact. The port touches the core in only a handful of small, local places — the SDL video and touch paths, the mouse mapping, the Android branch of the JIT's code cache, a couple of fixes that only silence the compiler. Everything else is upstream code.</p>
<p>Again, <strong>this post is not the documentation.</strong> The documentation is the repository: the build guide, the porting log, the benchmark notes, and every line of the port. Please read those rather than take my word for it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-1.0.0.7#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They kept it alive for three decades and gave it away to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which grew out of <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. The SDL2 library by <a href="https://github.com/libsdl-org/SDL" target="_blank" rel="noopener noreferrer" class="">Sam Lantinga</a> carries the window, the audio and the touch input.</p>
<p><strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>If a game of yours now runs on your phone — or if it doesn't, and the CPU core dialog is where you give up on it — tell me. I am keeping a list, and it is the most useful thing anyone can send me.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>emulator</category>
            <category>release</category>
            <category>retro</category>
            <category>open-source</category>
            <category>whereq</category>
        </item>
        <item>
            <title><![CDATA[财经今日 开源了：界面、它读的库表结构，以及中间的 API]]></title>
            <link>https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement-CN</guid>
            <pubDate>Thu, 12 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/caijing.svg" alt="财经今日 · CaiJing Today" class="themedComponent_mlkZ themedComponent--light_NVdE" width="180"><img src="https://whereq.github.io/img/apps/caijing.svg" alt="财经今日 · CaiJing Today" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="180"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="一个交易日是六个标签页">一个交易日，是六个标签页<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement-CN#%E4%B8%80%E4%B8%AA%E4%BA%A4%E6%98%93%E6%97%A5%E6%98%AF%E5%85%AD%E4%B8%AA%E6%A0%87%E7%AD%BE%E9%A1%B5" class="hash-link" aria-label="一个交易日，是六个标签页的直接链接" title="一个交易日，是六个标签页的直接链接" translate="no">​</a></h2>
<p>九点二十五，集合竞价结束。九点半，开盘。从这一刻起，接下来四个小时，
市场一直在说话：一次公开市场操作、一个期货点位、一个指数点位、一份征求意见
稿、一份公司公告，再加上一篇分析——而这两者到底差在哪。</p>
<p>这些消息都是真的，也都真实存在。只是它们不在同一个地方。</p>
<p>于是你打开六个标签页：行情快讯、指数页面、板块热力图、日历、公告检索、还有
一个论坛。它们各自的版式、配色、关注点都不一样，而且大多是为别人的问题而
做的。</p>
<p>我一直想要的是一块板子。一屏之内，热榜、7×24 快讯、板块热力、经济日历、个股
热榜同时都在；而且每个面板回答的都是同一个问题：<strong>发生了什么变化，有多重要。</strong></p>
<p><strong>财经今日（CaiJing Today）</strong> 就是这块板子。它以中文为默认界面，因为市场先说
中文；英文放在旁边，一键可切。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="这块板子">这块板子<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement-CN#%E8%BF%99%E5%9D%97%E6%9D%BF%E5%AD%90" class="hash-link" aria-label="这块板子的直接链接" title="这块板子的直接链接" translate="no">​</a></h2>
<p align="center"><img src="https://whereq.github.io/img/apps/caijing-today-live-zh.jpg" alt="财经今日线上运行中的界面（真实数据）——左侧是带热度条的热榜，中间是编辑精选、行情图表和个股热榜，右侧是 7×24 快讯、经济日历和全球市场行情" width="100%"></p>
<p align="center"><sub>这是运行中的站点——<strong>caijing.today</strong>——里面是真实数据。左侧是热榜
TOP 50，配 1 小时 / 24 小时 / 本周 / 本月四档时间窗和热度条；中间是编辑精选、
行情图表和个股热榜；右侧是 7×24 快讯、经济日历和全球市场行情；顶部那条是滚动的
行情带。</sub></p>
<p>打开它，版式是刻意做密的。顶部一条行情带横向滚动。往下是三栏面板，每一个都是
同一套数据库的一个切面，谁也不替谁做总结。</p>
<ul>
<li class=""><strong>热榜 / TOP 50</strong> —— 按热度排序的新闻，右侧可切换时间窗。这里的热度不是编辑
判断，而是由发布时间、该条所挂分析的可信度，以及情绪强度共同算出来的。</li>
<li class=""><strong>7×24 快讯</strong> —— 快讯流。短、带时间戳，有自己的节奏；你读一篇五分钟前打开
的稿子，它也还在旁边走着。</li>
<li class=""><strong>个股热榜</strong> —— 个股热榜，自带一套排序。</li>
<li class=""><strong>分类导航</strong> —— 十二个分类：宏观、股市、美股、债券、外汇、大宗商品、加密、
房产、科技、公司、政策、观点。这不是手工维护的分类表——每一条内容是按它的
信号类型、板块、地域和标签归类的，你也可以手动改。</li>
<li class=""><strong>经济日历</strong> —— 当天的预定数据发布，带重要度。</li>
<li class=""><strong>数据图表 / 行业板块 / 加密市场 / 热搜关键词</strong> —— 走势图、带资金流的板块
热力、加密板块，以及大家正在搜什么。</li>
</ul>
<p>整套界面两种语言，切换按钮在页头。中文不是英文的翻译——中文才是最初的版式，
英文是后来并排加上去的。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/caijing-today-live-zh-light.jpg" alt="财经今日线上运行中的浅色界面——同样的首页，浅色主题" width="100%"></p>
<p align="center"><sub>同一块板子的浅色主题。板子默认是深色的，页头的切换按钮可以换，切换结果会
被记住。</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="技术说明">技术说明<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement-CN#%E6%8A%80%E6%9C%AF%E8%AF%B4%E6%98%8E" class="hash-link" aria-label="技术说明的直接链接" title="技术说明的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>前端</strong> —— React 19、TypeScript、Vite、TanStack Query、i18next。类型严格，
55 个测试。</li>
<li class=""><strong>后端</strong> —— FastAPI、SQLAlchemy 2（asyncpg 异步驱动）、Pydantic。
<strong>只读</strong>：这个服务从不写入它所读的数据库。</li>
<li class=""><strong>数据库</strong> —— PostgreSQL 17。15 张表、2 个视图，以
<a href="https://github.com/whereq/CaiJing-Today/blob/main/docs/SCHEMA.sql" target="_blank" rel="noopener noreferrer" class=""><code>docs/SCHEMA.sql</code></a>
的形式公开。</li>
<li class=""><strong>API</strong> —— <code>/api/v1</code> 下 17 个接口，全部是读。</li>
<li class=""><strong>许可</strong> —— MIT，覆盖整个仓库。</li>
<li class=""><strong>测试</strong> —— 后端 25 个、前端 55 个，CI 里四道关：后端测试、一道把库表契约
真正灌进 PostgreSQL 并和 ORM 映射对账的 schema 检查、前端测试，以及四个镜像
的 Docker 构建。</li>
</ul>
<p><strong>这篇文章不是文档。</strong> 文档是仓库本身：库表契约、安装指南、数据来源的规矩、
测试矩阵。我更希望你直接去读那些，而不是听我一面之词。</p>
<p>👉 <strong><a href="https://github.com/whereq/CaiJing-Today" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/CaiJing-Today</a></strong></p>
<p>跑起来：</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token function" style="color:rgb(220, 220, 170)">git</span><span class="token plain"> clone https://github.com/whereq/CaiJing-Today.git</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token builtin class-name" style="color:rgb(78, 201, 176)">cd</span><span class="token plain"> CaiJing-Today</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token function" style="color:rgb(220, 220, 170)">cp</span><span class="token plain"> docker/.env.example docker/.env</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token function" style="color:rgb(220, 220, 170)">docker</span><span class="token plain"> compose </span><span class="token parameter variable" style="color:rgb(156, 220, 254)">-f</span><span class="token plain"> docker/docker-compose.yml up </span><span class="token parameter variable" style="color:rgb(156, 220, 254)">-d</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(156, 220, 254)">--build</span><br></div></code></pre></div></div>
<p>然后打开 <code>http://localhost:8080</code>。这就是完整的一栈——PostgreSQL 17、库表契约、
演示数据、API 和前端。API 在 <code>http://localhost:8000</code>，交互式文档在 <code>/docs</code>。</p>
<p><strong>构建、测试、运行都不需要任何 key。</strong> <code>docker/.env.example</code> 里的默认值是本地
开发用的凭据，不是密钥；而且不需要身份提供者：浏览是公开的，所以界面停在匿名
模式，登录入口自动隐藏。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="为什么现在把它放出来">为什么现在把它放出来<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement-CN#%E4%B8%BA%E4%BB%80%E4%B9%88%E7%8E%B0%E5%9C%A8%E6%8A%8A%E5%AE%83%E6%94%BE%E5%87%BA%E6%9D%A5" class="hash-link" aria-label="为什么现在把它放出来的直接链接" title="为什么现在把它放出来的直接链接" translate="no">​</a></h2>
<p>因为<strong>采集器</strong>是那部分不开源的，而<strong>库表结构</strong>是开源的。</p>
<p>这个仓库把库表结构当作一份明确的契约公开——15 张表、2 个视图，列的类型、唯一
约束、快照的纪律、时间的 UTC 规矩——再加上一个只读它的 FastAPI 服务。生产环境
里往这些表里灌数据的采集器是另一个组件。</p>
<p>我觉得这个切分才是有用的地方。库表结构不是谁家数据库的导出物，它是<strong>两个允许
由不同的人写的程序之间的约定</strong>。如果你想要自己的采集器——自己的信源、自己的节
奏、自己对「一条新闻」的理解——那就写一个往这些表里插入的组件，API 和界面不
改一行代码就会把它伺服出来。</p>
<p>这就是全部的扩展点，规矩写在
<a href="https://github.com/whereq/CaiJing-Today/blob/main/docs/data-sources.md" target="_blank" rel="noopener noreferrer" class="">docs/data-sources.md</a>里：
<code>published_at</code> 是什么时区、为什么快照表要新增一个 <code>as_of</code> 而不是更新、哪些分
类 id 是合法的、热度分数由什么构成。</p>
<p><strong>有一句必须说清楚的话。</strong> MIT 许可覆盖的是<strong>代码</strong>，它对往数据库里放的数据只
字未提。采集器取回来的标题、行情和公告，权利属于发布它们的那家机构，各有各的
条款；财经通讯社、免费公开数据门户和行情数据商给的授权根本不是一回事。你要是
接了真实数据，守约是你的事，不是这个项目的。</p>
<p>还有关于演示数据，说白了：里面每一行都是编的。标题带【示例】/ <code>[sample]</code> 前缀，
价格是假的，日历条目是占位的，链接用的是保留域名 <code>.invalid</code>，热榜里的代码是
<code>DEMO-001</code> … <code>DEMO-010</code> 而不是真实股票代码。这是有意的——真实代码配一个编出来
的热度，读起来就成了投资建议。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/caijing-today-home.jpg" alt="同一块板子跑在仓库自带的合成演示数据上——每条标题都标着【示例】，个股热榜里的代码全是 DEMO-001 到 DEMO-010" width="100%"></p>
<p align="center"><sub>这就是一份全新 checkout 跑起来的样子：同一块板子，跑在合成演示数据上。每条
标题都标着【示例】，代码全是 DEMO-001 … <code>DEMO-010</code>，里面没有一个数字是真的。
界面和线上一样，默认中文。</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="致谢">致谢<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement-CN#%E8%87%B4%E8%B0%A2" class="hash-link" aria-label="致谢的直接链接" title="致谢的直接链接" translate="no">​</a></h2>
<p>这个应用站在别人的劳动之上，装作不是那样才是不诚实的。</p>
<ul>
<li class=""><strong><a href="https://polygon.io/" target="_blank" rel="noopener noreferrer" class="">Polygon.io</a></strong> —— 行情数据。行情带、指数点位、走势图都
来自它。</li>
<li class=""><strong><a href="https://www.gdeltproject.org/" target="_blank" rel="noopener noreferrer" class="">GDELT</a></strong> —— 全球新闻索引，对应 <code>gdelt</code> 这个
信源 id。</li>
<li class=""><strong><a href="https://www.sec.gov/edgar" target="_blank" rel="noopener noreferrer" class="">SEC EDGAR</a></strong> —— 美国公告索引，对应 <code>sec_edgar</code>
这个信源 id。</li>
<li class=""><strong>东方财富</strong> —— 界面上标注为 <code>akshare_em_global</code> 和 <code>akshare_em_cjzc</code> 的全球
快讯与财经早餐信源。</li>
<li class=""><strong>财经 RSS 聚合</strong> —— <code>rss</code> 这个信源 id 背后的财经 RSS 信息源。</li>
<li class=""><strong><a href="https://react.dev/" target="_blank" rel="noopener noreferrer" class="">React</a></strong>、<strong><a href="https://vite.dev/" target="_blank" rel="noopener noreferrer" class="">Vite</a></strong>、
<strong><a href="https://tanstack.com/query" target="_blank" rel="noopener noreferrer" class="">TanStack Query</a></strong>、
<strong><a href="https://www.i18next.com/" target="_blank" rel="noopener noreferrer" class="">i18next</a></strong>、
<strong><a href="https://fastapi.tiangolo.com/" target="_blank" rel="noopener noreferrer" class="">FastAPI</a></strong>、
<strong><a href="https://www.sqlalchemy.org/" target="_blank" rel="noopener noreferrer" class="">SQLAlchemy</a></strong>、
<strong><a href="https://docs.pydantic.dev/" target="_blank" rel="noopener noreferrer" class="">Pydantic</a></strong>、
<strong><a href="https://www.postgresql.org/" target="_blank" rel="noopener noreferrer" class="">PostgreSQL</a></strong>、
<strong><a href="https://nginx.org/" target="_blank" rel="noopener noreferrer" class="">nginx</a></strong> 和 <strong><a href="https://www.docker.com/" target="_blank" rel="noopener noreferrer" class="">Docker</a></strong> —— 这个
仓库所依赖的技术栈。依赖清单在 <code>NOTICE</code> 里。</li>
</ul>
<p>演示数据集则不归任何人所有——这恰恰是它的意义：它是合成的，它自己写明了这一点，
它的存在只是为了让一份全新的 checkout 起来就有东西可看。</p>
<hr>
<p><em>如果你照着这份契约写了一个采集器——或者把它改成一块服务于别的市场的板子——
我很想听听。</em></p>]]></content:encoded>
            <category>whereq</category>
            <category>开源</category>
            <category>财经</category>
            <category>新闻</category>
            <category>react</category>
            <category>fastapi</category>
            <category>postgresql</category>
            <category>库表结构</category>
        </item>
        <item>
            <title><![CDATA[CaiJing Today is open source — the board, the schema it reads, and the API in between]]></title>
            <link>https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement</link>
            <guid>https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement</guid>
            <pubDate>Thu, 12 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/caijing.svg" alt="CaiJing Today · 财经今日" class="themedComponent_mlkZ themedComponent--light_NVdE" width="180"><img src="https://whereq.github.io/img/apps/caijing.svg" alt="CaiJing Today · 财经今日" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="180"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="a-market-day-is-a-lot-of-tabs">A market day is a lot of tabs<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement#a-market-day-is-a-lot-of-tabs" class="hash-link" aria-label="A market day is a lot of tabs的直接链接" title="A market day is a lot of tabs的直接链接" translate="no">​</a></h2>
<p>At 09:25 the call auction ends. At 09:30 the tape starts, and for the next
four hours the Chinese market talks continuously — a central-bank operation, a
futures point, an index level, a draft regulation, a company filing, an
analyst note about the difference between two of them.</p>
<p>All of it is real, and all of it is somewhere. But it is not in the same place.</p>
<p>So you end up with six tabs open — a wire service, a quote page, a sector
heatmap, a calendar, a filing index, a forum — and the tab bar quietly becomes
the product. Every one of them is a different layout, a different colour
scheme, a different idea of what matters, and most of them are built for
somebody else's question.</p>
<p>I kept wanting a single board. One page where the hot list, the 7×24 newsflash,
sector heat, the economic calendar and the individual-stock hot list are all
visible at once, and where every panel answers the same question: <em>what
changed, and how much does it matter?</em></p>
<p><strong>财经今日 (CaiJing Today)</strong> is that board. It is Chinese-first, because that
is the language the market speaks first, with English one click away.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-board">The board<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement#the-board" class="hash-link" aria-label="The board的直接链接" title="The board的直接链接" translate="no">​</a></h2>
<p align="center"><img src="https://whereq.github.io/img/apps/caijing-today-live-en.jpg" alt="CaiJing Today running at caijing.today with live data — the hot ranking on the left with heat bars, the editorial picks and market charts in the middle, the individual-stock hot list below them, and the live newsflash, economic calendar and global market quotes on the right" width="100%"></p>
<p align="center"><sub>This is the running site — <strong>caijing.today</strong> — with live data.
On the left the TOP 50 hot ranking with its 1-hour / 24-hour / week / month
windows and heat bars. In the middle the editorial picks, the market charts
and the individual-stock hot list. On the right the 7×24 newsflash, the
economic calendar and the global market quotes. The strip across the top
scrolls the live quote tape.</sub></p>
<p>Open it and the shape is deliberately dense. A quote strip scrolls along the
top. Below that, three columns of panels, each one a window onto the same
database, none of them a summary of the others.</p>
<ul>
<li class=""><strong>Hot Ranking (热榜 / TOP 50)</strong> — headlines ranked by heat, with a window
selector. The heat score is not editorial judgement; it is computed from
publication time, the confidence of the analysis attached to the item, and
how strong its sentiment is.</li>
<li class=""><strong>Live Newsflash (7×24 快讯)</strong> — the newsflash. Short, timestamped, and it
keeps its own rhythm while you read, so an article you opened five minutes
ago still has the tape beside it.</li>
<li class=""><strong>Hot Stocks (个股热榜)</strong> — the individual-stock hot list, with its own
ranking.</li>
<li class=""><strong>Categories (分类导航)</strong> — twelve categories: 宏观, 股市, 美股, 债券, 外汇,
大宗商品, 加密, 房产, 科技, 公司, 政策, 观点. They are not a hand-made
taxonomy — each item is classified from its signal type, sectors, region and
tags, and you can disagree with the result by hand.</li>
<li class=""><strong>Economic Calendar (经济日历)</strong> — the day's scheduled releases, with an
importance rating.</li>
<li class=""><strong>Market Data / Trending / Global Markets (数据图表 / 热搜关键词 / 全球市场)</strong> —
the index sparklines, the trending keywords, and the global quote board.</li>
<li class=""><strong>Sector Heat / Crypto Market (行业板块 / 加密市场)</strong> — the sector heatmap with
capital inflow, and the crypto board with coins, chains and TVL.</li>
</ul>
<p>And the whole thing is in two languages, with the toggle in the header. The
Chinese is not a translation of the English — the Chinese is the original
layout, and English was added beside it.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/caijing-today-live-en-light.jpg" alt="CaiJing Today running at caijing.today in light mode — the same home board with a light theme" width="100%"></p>
<p align="center"><sub>The same board in the light theme. The board is dark by default; the
toggle in the header switches it, and the choice is remembered.</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-honest-technical-note">The honest technical note<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement#the-honest-technical-note" class="hash-link" aria-label="The honest technical note的直接链接" title="The honest technical note的直接链接" translate="no">​</a></h2>
<ul>
<li class=""><strong>Frontend</strong> — React 19, TypeScript, Vite, TanStack Query, i18next. Strict
types, and 55 tests.</li>
<li class=""><strong>Backend</strong> — FastAPI, SQLAlchemy 2 over asyncpg, Pydantic. <strong>Read-only</strong>:
the service never writes to the database it reads.</li>
<li class=""><strong>Database</strong> — PostgreSQL 17. Fifteen tables and two views, published as
<a href="https://github.com/whereq/CaiJing-Today/blob/main/docs/SCHEMA.sql" target="_blank" rel="noopener noreferrer" class=""><code>docs/SCHEMA.sql</code></a>.</li>
<li class=""><strong>API</strong> — seventeen endpoints under <code>/api/v1</code>, all of them reads.</li>
<li class=""><strong>Licence</strong> — MIT, for the whole repository.</li>
<li class=""><strong>Tests</strong> — 25 backend, 55 frontend, and four CI gates: the backend suite, a
schema job that applies the contract to a real PostgreSQL and checks the ORM
mirror against it, the frontend suite, and a Docker build of all four images.</li>
</ul>
<p><strong>This post is not the documentation.</strong> The documentation is the repository:
the schema contract, the setup guide, the data-source rules and the test
matrix. I would rather you read those than take my word for it.</p>
<p>👉 <strong><a href="https://github.com/whereq/CaiJing-Today" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/CaiJing-Today</a></strong></p>
<p>To run it:</p>
<div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token function" style="color:rgb(220, 220, 170)">git</span><span class="token plain"> clone https://github.com/whereq/CaiJing-Today.git</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token builtin class-name" style="color:rgb(78, 201, 176)">cd</span><span class="token plain"> CaiJing-Today</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain" style="display:inline-block"></span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token function" style="color:rgb(220, 220, 170)">cp</span><span class="token plain"> docker/.env.example docker/.env</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token function" style="color:rgb(220, 220, 170)">docker</span><span class="token plain"> compose </span><span class="token parameter variable" style="color:rgb(156, 220, 254)">-f</span><span class="token plain"> docker/docker-compose.yml up </span><span class="token parameter variable" style="color:rgb(156, 220, 254)">-d</span><span class="token plain"> </span><span class="token parameter variable" style="color:rgb(156, 220, 254)">--build</span><br></div></code></pre></div></div>
<p>Then open <code>http://localhost:8080</code>. That is the whole stack — PostgreSQL 17,
the schema contract, the demo data, the API and the frontend. The API is on
<code>http://localhost:8000</code>, with interactive documentation at <code>/docs</code>.</p>
<p><strong>You do not need any keys to build, test or run it.</strong> The defaults in
<code>docker/.env.example</code> are local development credentials, not secrets, and the
site works with no identity provider at all: browsing is public, so the UI
stays in anonymous mode and the sign-in control is hidden.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-it-is-in-the-world-now">Why it is in the world now<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement#why-it-is-in-the-world-now" class="hash-link" aria-label="Why it is in the world now的直接链接" title="Why it is in the world now的直接链接" translate="no">​</a></h2>
<p>Because the collector is the part that is <em>not</em> open, and the schema is the
part that is.</p>
<p>This repository ships the schema as an explicit contract — 15 tables, two
views, the column types, the unique constraints, the snapshot discipline, the
UTC rules — and a FastAPI service that reads it and nothing else. The
collector that fills those tables in production is a separate component.</p>
<p>I think that split is the useful bit. The schema is not a dump of somebody
else's database; it is the agreement between two programs that are allowed to
be written by different people. If you want your own collector — your own
sources, your own cadence, your own idea of what a headline is — you write a
component that inserts into those tables, and the API and the interface serve
it with no code changes.</p>
<p>That is the whole extension point, and it is documented in
<a href="https://github.com/whereq/CaiJing-Today/blob/main/docs/data-sources.md" target="_blank" rel="noopener noreferrer" class="">docs/data-sources.md</a>:
what <code>published_at</code> means, why the snapshot tables take a new <code>as_of</code> instead
of an update, which category ids are legal, and what the heat score is made
of.</p>
<p><strong>One warning, because it matters.</strong> The MIT licence covers <strong>the code</strong>. It
says nothing about the data you put into the database. The headlines, quotes
and filings a collector retrieves belong to the organisations that published
them, each under its own terms, and a financial wire, a free public-data
portal and a market-data vendor do not grant the same rights. If you connect
real data, complying with those terms is your job, not this project's.</p>
<p>And to be plain about the demo dataset: every row in it is invented. The
headlines are prefixed 【示例】 / <code>[sample]</code>, the prices are fabricated, the
calendar entries are placeholders, the links use the reserved <code>.invalid</code> TLD,
and the hot-stock list uses <code>DEMO-001</code> … <code>DEMO-010</code> rather than real tickers.
That is deliberate. A real ticker next to a fabricated heat score reads as
investment advice.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/caijing-today-home.jpg" alt="the same home board running on the repository's synthetic demo dataset — every headline marked 【示例】 and every ticker in the hot list reading DEMO-001 to DEMO-010" width="100%"></p>
<p align="center"><sub>This is what a fresh checkout gives you: the same board, running on the
synthetic demo dataset. Every headline is marked 【示例】, every ticker reads
DEMO-001 … DEMO-010, and nothing in it is real. The interface is
Chinese-first, as it is on the live site.</sub></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="credits">Credits<a href="https://whereq.github.io/zh-CN/blog/CaiJing-Today-Open-Source-Announcement#credits" class="hash-link" aria-label="Credits的直接链接" title="Credits的直接链接" translate="no">​</a></h2>
<p>This app stands on the work of other people, and it would be dishonest to
pretend otherwise.</p>
<ul>
<li class=""><strong><a href="https://polygon.io/" target="_blank" rel="noopener noreferrer" class="">Polygon.io</a></strong> — market data. The quote strip, the
index levels, the charts.</li>
<li class=""><strong><a href="https://www.gdeltproject.org/" target="_blank" rel="noopener noreferrer" class="">GDELT</a></strong> — the global news index behind
the <code>gdelt</code> source id.</li>
<li class=""><strong><a href="https://www.sec.gov/edgar" target="_blank" rel="noopener noreferrer" class="">SEC EDGAR</a></strong> — the US filing index behind
the <code>sec_edgar</code> source id.</li>
<li class=""><strong>东方财富 (Eastmoney)</strong> — the 全球快讯 and 财经早餐 feeds the interface
credits as <code>akshare_em_global</code> and <code>akshare_em_cjzc</code>.</li>
<li class=""><strong>财经 RSS 聚合</strong> — the finance RSS feeds behind the <code>rss</code> source id.</li>
<li class=""><strong><a href="https://react.dev/" target="_blank" rel="noopener noreferrer" class="">React</a></strong>, <strong><a href="https://vite.dev/" target="_blank" rel="noopener noreferrer" class="">Vite</a></strong>,
<strong><a href="https://tanstack.com/query" target="_blank" rel="noopener noreferrer" class="">TanStack Query</a></strong>,
<strong><a href="https://www.i18next.com/" target="_blank" rel="noopener noreferrer" class="">i18next</a></strong>,
<strong><a href="https://fastapi.tiangolo.com/" target="_blank" rel="noopener noreferrer" class="">FastAPI</a></strong>,
<strong><a href="https://www.sqlalchemy.org/" target="_blank" rel="noopener noreferrer" class="">SQLAlchemy</a></strong>,
<strong><a href="https://docs.pydantic.dev/" target="_blank" rel="noopener noreferrer" class="">Pydantic</a></strong>,
<strong><a href="https://www.postgresql.org/" target="_blank" rel="noopener noreferrer" class="">PostgreSQL</a></strong>,
<strong><a href="https://nginx.org/" target="_blank" rel="noopener noreferrer" class="">nginx</a></strong> and <strong><a href="https://www.docker.com/" target="_blank" rel="noopener noreferrer" class="">Docker</a></strong> — the
stack this repository is built on. The dependency list is in <code>NOTICE</code>.</li>
</ul>
<p>The demo dataset is also the work of nobody in particular, which is exactly
the point: it is synthetic, it says so, and it exists so that a fresh
checkout has something to show.</p>
<hr>
<p><em>If you write a collector against the schema — or fork the board for a
market this one does not cover — I would genuinely like to hear about it.</em></p>]]></content:encoded>
            <category>whereq</category>
            <category>open-source</category>
            <category>finance</category>
            <category>news</category>
            <category>react</category>
            <category>fastapi</category>
            <category>postgresql</category>
            <category>schema</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox：把 DOS 年代带回手机]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN</guid>
            <pubDate>Thu, 12 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="角落里那台机器">角落里那台机器<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN#%E8%A7%92%E8%90%BD%E9%87%8C%E9%82%A3%E5%8F%B0%E6%9C%BA%E5%99%A8" class="hash-link" aria-label="角落里那台机器的直接链接" title="角落里那台机器的直接链接" translate="no">​</a></h2>
<p>我记得的，是风扇的声音。</p>
<p>不是游戏，不是跟软驱较劲的那几个晚上——是风扇。一台米色的主机蹲在父母客厅的角落，风扇转起来像是它正在想什么事情；旁边是一台带点偏绿、微微凸起的 CRT 显示器，那在当时，已经是一扇<strong>窗</strong>。</p>
<p>那台机器开着的时候，整个房间的温度都不一样。它是家里最吵的东西，而它属于我。</p>
<p>然后，是那个闪烁的光标。</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">C:\&gt;</span><br></div></code></pre></div></div>
<p>这个提示符像是一句邀请。它不自作解释，它只是<strong>等</strong>着。如果你愿意学它的语言——<code>cd</code>、<code>dir</code>、<code>copy</code>、<code>mkdir</code>——它就会老老实实照你说的做。那是我第一次觉得，电脑是一件<strong>工具</strong>，而不只是一个用来消费的家电。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="游戏以及游戏底下的软件">游戏，以及游戏底下的软件<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN#%E6%B8%B8%E6%88%8F%E4%BB%A5%E5%8F%8A%E6%B8%B8%E6%88%8F%E5%BA%95%E4%B8%8B%E7%9A%84%E8%BD%AF%E4%BB%B6" class="hash-link" aria-label="游戏，以及游戏底下的软件的直接链接" title="游戏，以及游戏底下的软件的直接链接" translate="no">​</a></h2>
<p>我玩过的那批游戏，现在说来都算经典了：<strong>Wolfenstein 3D</strong>，软盘被磁头刮花到根本读不出来，我用的是一张有划痕的；<strong>Commander Keen</strong>，一座明显是两个喝多了咖啡的人做的城市；凌晨两点跟朋友用拨号线路联机打 <strong>Liero</strong>；<strong>Prince of Persia</strong>，它教会我必须经常存档，因为我会死很多次；还有 <strong>Duke Nukem</strong> 和初代 <strong>Doom</strong>，以及 shareware 那种特定的魔力——这一集恰好断在你知道下一集会从哪里开始的地方。</p>
<p>但真正改变我人生的，其实不是这些游戏，而是游戏<strong>周围</strong>的软件——以及"它们不过就是磁盘上的文件"这件事。</p>
<p>我写了人生第一个 <code>.BAT</code> 文件。我敲了一条长到需要换行的命令，于是不得不去学"行连接符"。我用文本编辑器打开一个配置文件，改了一行，然后程序的行为就变了。我见过蓝屏，也因此明白：电脑是会坏的；坏是有原因的；我可以去找出那个原因。</p>
<p>然后——那个把我的人生彻底拐向另一个方向、也正是我整个职业生涯起点的瞬间——我意识到：<strong>程序不是魔法，它就是文本。</strong></p>
<blockquote>
<p><strong>我可以打开它、读它、改它、弄坏它，然后重新把它拼回来。</strong></p>
</blockquote>
<p>Turbo Pascal、BASIC、AUTOEXEC.BAT、CONFIG.SYS——它们看起来都是同一个东西换了不同的戏服。那都是某一个人坐下来写下的一串指令，而机器听命了。</p>
<p>这就是<strong>启蒙</strong>。软件从一个黑盒子，变成了一个<strong>你伸得进手去</strong>的东西。此后我做的一切——分布式系统、Kubernetes 集群、AI Agent、包括这个网站——都是从那个瞬间长出来的：<strong>机器不是一个魔法盒子，它是一台你可以读懂的机器。</strong></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="然后整个世界搬进了我们的口袋">然后，整个世界搬进了我们的口袋<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN#%E7%84%B6%E5%90%8E%E6%95%B4%E4%B8%AA%E4%B8%96%E7%95%8C%E6%90%AC%E8%BF%9B%E4%BA%86%E6%88%91%E4%BB%AC%E7%9A%84%E5%8F%A3%E8%A2%8B" class="hash-link" aria-label="然后，整个世界搬进了我们的口袋的直接链接" title="然后，整个世界搬进了我们的口袋的直接链接" translate="no">​</a></h2>
<p>然后，世界有了自己的屏幕。</p>
<p>看看手机变成了什么。它是相机，是钱包，是图书馆，是报纸，是游戏机，是地图，是电话，是银行，是医院，是教室。对今天绝大多数人来说，手机<strong>就是</strong>那台计算机。阅读、工作、游戏、学习、思考，全都发生在它上面。计算的重心，就这样悄无声息地挪了过来。</p>
<p>这也意味着一件有点可悲的事：那个"数以百万计的人通过命令提示符去<strong>驾驭</strong>一台机器"的时代，结束了。DOS 年代不只是"旧"——它更是一扇已经关上的门。那一代人第一次真正接触电脑，是从一个闪烁的光标开始的：它问你，你想做什么？而我们这一代，看到的是一堵墙的矩形，永远不必知道底下是什么。</p>
<p>我并不认为这一定更糟。我不是来说"手机不是一台好电脑"的。但我确实觉得，这让我们失去了一些东西。整整一代人对机器的<strong>主人感</strong>，来自于"你不得不"学会命令行。今天没有人再递给你一个光标了，你拿到的是一屏的应用图标，然后你永远不必知道它们下面是什么。</p>
<p>所以有个问题一直在我脑子里转，简单到有点不好意思问出口：</p>
<blockquote>
<p><strong>为什么不把 DOS 带到手机上去？</strong></p>
</blockquote>
<p>不是为了做个博物馆展品，不是做一个在网页里跑 demo 的怀旧 App。而是做成一个<strong>真的</strong>东西——真家伙，在你自己口袋里那台真正的机器上跑，用你自己的 DOS 游戏和软件，就像当年本该有的样子。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="whereq-dosbox">WhereQ-DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN#whereq-dosbox" class="hash-link" aria-label="WhereQ-DOSBox的直接链接" title="WhereQ-DOSBox的直接链接" translate="no">​</a></h2>
<p>这就是答案。今天，我把它开源了。</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-screenshot-phone.jpg" alt="WhereQ-DOSBox 运行在 Android 手机上 —— DOSBox 欢迎界面、已挂载的驱动器以及屏幕键盘" width="760"></p>
<p align="center"><sub>欢迎界面、已挂载的驱动器，以及屏幕键盘。触摸就是 DOS 鼠标，
按键直接输入到 DOSBox 里。</sub></p>
<p><strong>WhereQ-DOSBox</strong> 是 <strong>DOSBox</strong> 的原生 Android 移植版——模拟器核心以真正的原生库（<code>libdosbox.so</code>）的形式跑在 APK 里面。不是网页，不是 WebView，不是在 JavaScript 里再模拟一遍 x86。在你的手机上，以原生速度运行。</p>
<p>今天就能做到的事情：</p>
<ul>
<li class="">在手机挂载的驱动器上运行你自己的 DOS 软件和游戏。</li>
<li class="">用屏幕键盘打字——按键直接进 DOSBox。</li>
<li class="">把触摸屏当成 DOS 鼠标来用。</li>
<li class="">全程离线，不需要账号，不需要浏览器，也没有任何追踪。</li>
</ul>
<p>APK 大约 <strong>5.3 MB</strong>，支持 <strong>arm64-v8a、armeabi-v7a 和 x86_64</strong> 设备（Android 5.0 及以上）。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="它是开源的--请直接去看">它是开源的 —— 请直接去看<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN#%E5%AE%83%E6%98%AF%E5%BC%80%E6%BA%90%E7%9A%84--%E8%AF%B7%E7%9B%B4%E6%8E%A5%E5%8E%BB%E7%9C%8B" class="hash-link" aria-label="它是开源的 —— 请直接去看的直接链接" title="它是开源的 —— 请直接去看的直接链接" translate="no">​</a></h3>
<p>这是一个 GPL-2.0 的项目。DOSBox 核心以 <code>AUTHORS</code>、<code>ChangeLog</code>、<code>COPYING</code> 和逐文件头部完整的形式嵌入进来，完全符合许可证的要求。整个移植只动了核心里的四个地方，都是很小的局部改动；其余全部是上游代码。</p>
<p>有一点我想说得很坦白：<strong>这篇文章不是文档。</strong> 文档就是仓库本身——构建指南、移植记录、性能测试报告，以及移植部分的每一行代码，全都在公开的地方。我宁愿你自己去读，而不是听我在这儿说。</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong></p>
<p>想自己编译一份：</p>
<div class="language-sh codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-sh codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token function" style="color:rgb(220, 220, 170)">git</span><span class="token plain"> clone git@github.com:whereq/whereq-dosbox.git</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token builtin class-name" style="color:rgb(78, 201, 176)">cd</span><span class="token plain"> whereq-dosbox</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">bin/build.sh all      </span><span class="token comment" style="color:rgb(106, 153, 85)"># bootstrap + native + android + apk</span><br></div></code></pre></div></div>
<p>跑完，<code>whereq-dosbox-debug.apk</code> 就在 <code>build/apk/</code> 里。完整指南——包括发布签名、Gradle 那一套、启动图标——都在 <strong><a href="https://github.com/whereq/whereq-dosbox/blob/main/BUILDING.md" target="_blank" rel="noopener noreferrer" class="">BUILDING.md</a></strong>。</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="我为什么要把它放出来">我为什么要把它放出来<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN#%E6%88%91%E4%B8%BA%E4%BB%80%E4%B9%88%E8%A6%81%E6%8A%8A%E5%AE%83%E6%94%BE%E5%87%BA%E6%9D%A5" class="hash-link" aria-label="我为什么要把它放出来的直接链接" title="我为什么要把它放出来的直接链接" translate="no">​</a></h3>
<p>因为我一直在遇到这样的人：他们记得 DOS 那个年代，<strong>想要</strong>它回来——但已经悄悄地接受了"那是不可能的了"，把它跟米色主机、和 3.5 寸软盘一起归档了。</p>
<p>它没有消失。它只是在等一次移植。</p>
<p>如果这能让某个人重新找回一个晚上的一句 <code>C:\&gt;</code>、一个下午的 Commander Keen，或者让一个从来没有过米色主机的小孩第一次体验到"哦——<strong>原来是这样运作的</strong>"，那这几个月的移植就值了。</p>
<p>如果你也想起了什么，也请一定告诉我。</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="谢谢dosbox">谢谢，DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement-CN#%E8%B0%A2%E8%B0%A2dosbox" class="hash-link" aria-label="谢谢，DOSBox的直接链接" title="谢谢，DOSBox的直接链接" translate="no">​</a></h2>
<p>没有 DOSBox 项目，这一切都不可能。</p>
<p><strong>DOSBox</strong> 是由 <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox 团队</a> 写出来的——一群志愿者，把一个 1994 年的操作系统做到了世界上此后每一台机器上都能跑，包括那些当时还不存在的机器。他们让它兼容了大量 DOS 游戏，三十年里一直维护着它，而且这一切都是免费的、送给任何想要的人的。WhereQ-DOSBox 只是叠在他们工作之上的一层薄薄的壳。原创、手艺和慷慨，全部属于他们。</p>
<p>这个移植建立在 <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong> 之上——<a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a> 用 Emscripten 做的 DOSBox r4305 版本；而 Em-DOSBox 本身，起源于 <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib</a> 第一次尝试用 Emscripten 编译 DOSBox，后来又搭上了 <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a> 在 Emscripten 上的工作。他们每一位，都把"DOS 跑在浏览器里"这件事往前推到了当时没人想得到的地方——而正是这个想法，让"DOS 跑在手机上"变得值得一试。</p>
<p>谢谢你们。全部的功劳都属于你们。<strong>DOSBox 是 DOSBox 项目的商标</strong>；本移植与 DOSBox 团队无隶属关系，也未获其背书。</p>
<hr>
<p><em>如果你还记得某款游戏、某台机器，或者某一个 <code>C:\&gt;</code>——说给我听。我正在把它们收集起来，这会是一份很好的档案。</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>模拟器</category>
            <category>怀旧</category>
            <category>经典游戏</category>
            <category>开源</category>
            <category>whereq</category>
        </item>
        <item>
            <title><![CDATA[WhereQ-DOSBox: bringing the DOS era back to your phone]]></title>
            <link>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement</link>
            <guid>https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement</guid>
            <pubDate>Thu, 12 Nov 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[<ThemedImage]]></description>
            <content:encoded><![CDATA[<figure style="text-align:center;margin:0 0 2rem"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--light_NVdE" width="300"><img src="https://whereq.github.io/img/apps/whereq-dosbox-logo-transparent.png" alt="WhereQ-DOSBox" class="themedComponent_mlkZ themedComponent--dark_xIcU" width="300"></figure>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="the-machine-in-the-corner-of-the-room">The machine in the corner of the room<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement#the-machine-in-the-corner-of-the-room" class="hash-link" aria-label="The machine in the corner of the room的直接链接" title="The machine in the corner of the room的直接链接" translate="no">​</a></h2>
<p>I remember the fan first.</p>
<p>Not the games, not the arguments with the diskette drive — the fan. A beige tower in the corner of my parents' living room, its fan whirring like it was thinking about something, and a green-ish CRT screen that was somehow a <em>window</em>. When that machine was on, the whole room changed temperature. It was the loudest thing in the house, and it was mine.</p>
<p>Then came the blinking cursor.</p>
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token plain">C:\&gt;</span><br></div></code></pre></div></div>
<p>That prompt was an invitation. It didn't explain itself; it waited. And if you were willing to learn its language — <code>cd</code>, <code>dir</code>, <code>copy</code>, <code>mkdir</code> — it would do exactly what you asked. I didn't know it yet, but that was the first time a computer felt like a <em>tool</em> rather than a appliance you consumed.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="games-and-the-software-underneath-them">Games, and the software underneath them<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement#games-and-the-software-underneath-them" class="hash-link" aria-label="Games, and the software underneath them的直接链接" title="Games, and the software underneath them的直接链接" translate="no">​</a></h2>
<p>I played the usual suspects. <strong>Wolfenstein 3D</strong> on a share so smeared the floppy disk never worked. <strong>Commander Keen</strong>, bouncing around a city that was obviously made by two people with a lot of coffee. <strong>Liero</strong> at 2 AM with a friend on a dial-up line. <strong>Prince of Persia</strong>, which taught me to save often because I was going to die a lot. <strong>Duke Nukem</strong> and the original <strong>Doom</strong>, and the specific magic of a shareware episode that ended exactly where the next one would begin.</p>
<p>But the thing that actually changed my life wasn't the games. It was the software <em>around</em> the games — and the fact that it was all just files on a disk.</p>
<p>I wrote my first <code>.BAT</code> file. I typed a command so long I broke the line and had to learn about line continuation. I opened a text editor, changed a line in a configuration file, and something behaved differently. I got a <strong>Blue Screen of Death</strong> and learned that a computer could fail, that failure had causes, and that I could go looking for them.</p>
<p>And then — the moment that turned into a career — I realized that a program was not magic. It was text. <strong>You could open it, read it, change it, break it, and build it back.</strong> Turbo Pascal, BASIC, the autoexec.bat, the config.sys: it all looked like the same thing wearing different costumes. A person had sat down and written instructions, and the machine obeyed.</p>
<p>That was the 启蒙 — the ignition. Software stopped being a black box and became a <em>thing you could touch</em>. Everything I have built since — the distributed systems, the Kubernetes clusters, the AI agents, this website — grew out of that one realization: <strong>a machine is not a magic box, it is a machine you can read.</strong></p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="then-the-world-moved-into-our-pockets">Then the world moved into our pockets<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement#then-the-world-moved-into-our-pockets" class="hash-link" aria-label="Then the world moved into our pockets的直接链接" title="Then the world moved into our pockets的直接链接" translate="no">​</a></h2>
<p>And then the world got a screen of its own.</p>
<p>Look at what a phone became. It is a camera, a wallet, a library, a newspaper, a game console, a map, a telephone, a bank, a hospital, a classroom. For most people alive today, the phone is <em>the</em> computer. It is where they read, work, play, learn, and think. It is where the entire center of gravity of computing moved.</p>
<p>And that means something quietly sad happened: the era where millions of people learned to <em>command</em> a machine is over. The DOS era wasn't just old — it was a way of learning that no longer has a doorway. That generation's first real contact with a computer was a blinking cursor asking what you wanted to do. Ours is a feed.</p>
<p>I don't think that's strictly worse. I'm not here to argue that a phone is a bad computer. But I do think it costs us something. An entire generation's sense of ownership over machines came from <em>having to</em> learn a command line. Nobody hands you a cursor anymore; you get a wall of rectangles and you never have to find out what's underneath.</p>
<p>So the question I kept asking myself was embarrassingly simple:</p>
<blockquote>
<p><strong>Why not bring DOS to the phone?</strong></p>
</blockquote>
<p>Not as a museum exhibit. Not as a nostalgia app that runs one demo in a webview. As a <em>real</em> thing — the genuine article, running on the actual machine in your pocket, with your own DOS games and software, the way it was meant to be used.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="whereq-dosbox">WhereQ-DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement#whereq-dosbox" class="hash-link" aria-label="WhereQ-DOSBox的直接链接" title="WhereQ-DOSBox的直接链接" translate="no">​</a></h2>
<p>This is the answer, and today I'm putting it in the open.</p>
<p align="center"><img src="https://whereq.github.io/img/apps/whereq-dosbox-screenshot-phone.jpg" alt="WhereQ-DOSBox running on an Android phone — the DOSBox welcome screen, a mounted drive and the on-screen keyboard" width="760"></p>
<p align="center"><sub>The welcome screen, a mounted drive, and the on-screen keyboard. Touch moves
the DOS mouse; the keys type straight into DOSBox.</sub></p>
<p><strong>WhereQ-DOSBox</strong> is a native Android port of <strong>DOSBox</strong> — the emulator core runs as a real native library (<code>libdosbox.so</code>) inside an APK. Not a web page, not a WebView, not a JavaScript emulation of an x86 emulation. On your phone, at native speed.</p>
<p>A few things you can do with it today:</p>
<ul>
<li class="">Run your own DOS software and games, from a mounted drive on your phone.</li>
<li class="">Type with the on-screen keyboard — the keys go straight into DOSBox.</li>
<li class="">Use the touchscreen as the DOS mouse.</li>
<li class="">Do all of it offline, with no account, no browser, and no tracking.</li>
</ul>
<p>The APK is about <strong>5.3 MB</strong> and runs on <strong>arm64-v8a, armeabi-v7a and x86_64</strong> devices (Android 5.0 and newer).</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="its-open-source--read-it">It's open source — read it<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement#its-open-source--read-it" class="hash-link" aria-label="It's open source — read it的直接链接" title="It's open source — read it的直接链接" translate="no">​</a></h3>
<p>This is a GPL-2.0 project, and the DOSBox core is embedded with its <code>AUTHORS</code>, <code>ChangeLog</code>, <code>COPYING</code> and per-file headers intact, exactly as the license requires. The port touches the core in only four small, local places; everything else is upstream code.</p>
<p>I want to be honest about something: <strong>this post is not the documentation.</strong> The documentation is the repository — the build guide, the porting log, the benchmark notes, and every line of the port are in the open, and I'd rather you read those than take my word for it.</p>
<p>👉 <strong><a href="https://github.com/whereq/whereq-dosbox" target="_blank" rel="noopener noreferrer" class="">github.com/whereq/whereq-dosbox</a></strong></p>
<p>To build it yourself:</p>
<div class="language-sh codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#9CDCFE;--prism-background-color:#1E1E1E"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-sh codeBlock_bY9V thin-scrollbar" style="color:#9CDCFE;background-color:#1E1E1E"><code class="codeBlockLines_e6Vv"><div class="token-line" style="color:#9CDCFE"><span class="token function" style="color:rgb(220, 220, 170)">git</span><span class="token plain"> clone git@github.com:whereq/whereq-dosbox.git</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain"></span><span class="token builtin class-name" style="color:rgb(78, 201, 176)">cd</span><span class="token plain"> whereq-dosbox</span><br></div><div class="token-line" style="color:#9CDCFE"><span class="token plain">bin/build.sh all      </span><span class="token comment" style="color:rgb(106, 153, 85)"># bootstrap + native + android + apk</span><br></div></code></pre></div></div>
<p>That drops <code>whereq-dosbox-debug.apk</code> into <code>build/apk/</code>. The full guide — release signing, the Gradle path, the launcher icons — is in <strong><a href="https://github.com/whereq/whereq-dosbox/blob/main/BUILDING.md" target="_blank" rel="noopener noreferrer" class="">BUILDING.md</a></strong>.</p>
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="why-im-putting-it-out-there">Why I'm putting it out there<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement#why-im-putting-it-out-there" class="hash-link" aria-label="Why I'm putting it out there的直接链接" title="Why I'm putting it out there的直接链接" translate="no">​</a></h3>
<p>Because I keep meeting people who remember the DOS era, and who <em>want</em> it back — but who had quietly accepted that it was gone, filed away with the beige tower and the 3.5-inch floppies.</p>
<p>It isn't gone. It's just been waiting for a port.</p>
<p>If this brings back one evening of <code>C:\&gt;</code>, one afternoon of Commander Keen, one "oh — <em>that's</em> how it works" moment for somebody who never had a beige tower in the corner — then the months of porting were worth it.</p>
<p>If it brings back a memory for you too, I'd genuinely love to hear about it.</p>
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="thank-you-dosbox">Thank you, DOSBox<a href="https://whereq.github.io/zh-CN/blog/WhereQ-DOSBox-Announcement#thank-you-dosbox" class="hash-link" aria-label="Thank you, DOSBox的直接链接" title="Thank you, DOSBox的直接链接" translate="no">​</a></h2>
<p>None of this is possible without the DOSBox project.</p>
<p><strong>DOSBox</strong> was written by the <a href="https://www.dosbox.com/crew.php" target="_blank" rel="noopener noreferrer" class="">DOSBox Team</a> — a volunteer crew who took an operating system from 1994 and made it runnable on every machine the world has produced since, including the ones that did not exist yet. They made it compatible with a wide variety of DOS games, they kept it alive for three decades, and they did it as a gift to anyone who wanted it. WhereQ-DOSBox is a thin layer on top of their work. The originality, the craft, and the generosity are entirely theirs.</p>
<p>This port is built on <strong><a href="https://github.com/dreamlayers/em-dosbox" target="_blank" rel="noopener noreferrer" class="">Em-DOSBox</a></strong>, the Emscripten build of DOSBox r4305 by <a href="https://github.com/dreamlayers" target="_blank" rel="noopener noreferrer" class="">Boris Gjenero</a>, which itself grew from <a href="https://github.com/CeRiAl" target="_blank" rel="noopener noreferrer" class="">Ismail Khatib's</a> first attempt to compile DOSBox with Emscripten, and rode on the Emscripten work of <a href="https://github.com/kripken/" target="_blank" rel="noopener noreferrer" class="">Alon Zakai</a>. Every one of them pushed the "DOS in a browser" idea further than anyone thought possible — and that idea is exactly what made "DOS on a phone" something worth trying.</p>
<p>Thank you. All of it. <strong>DOSBox is a trademark of the DOSBox project</strong>; this port is not affiliated with or endorsed by the DOSBox team.</p>
<hr>
<p><em>If you remember a specific game, or a specific machine, or a specific <code>C:\&gt;</code> prompt — tell me. I am collecting them, and this is going to be a good archive.</em></p>]]></content:encoded>
            <category>dosbox</category>
            <category>android</category>
            <category>emulator</category>
            <category>retro</category>
            <category>nostalgia</category>
            <category>open-source</category>
            <category>whereq</category>
        </item>
    </channel>
</rss>