NoodleStormno/dsh-plugin-tic80

dsh-plugin-tic80

CI
npm version
license
DeepSeek Harness
GitHub topic

中文文档 | English

dsh-plugin-tic80 是专为 DeepSeek Harness (dsh) 打造的 TIC-80 幻想计算机全功能生态插件。更多相关生态插件请浏览 GitHub 话题：dsh-plugin。

保留 TIC-80 官方控制台的全部功能，并通过 DeepSeek Harness 与大语言模型（LLM）实现自然语言交互对话，让 LLM 能够自主编写 TIC-80 的 代码、音乐（Tracker）、世界地图和精灵（像素艺术），并支持本地原生控制台与 Web 实时热重载（Live Studio）运行与测试。

⚡ 专为极速原型打造 (Rapid Prototyping)

- 🎯 开箱即用的极速游戏原型：专为玩法创意与游戏机制验证设计，输入自然语言需求，秒级生成包含代码、精灵、地图与音效的完整可玩 Demo。
- ⚙️ 顶部配置驱动手感微调：大模型生成代码时严格遵循工程规范，所有核心物理与玩法变量（如 jump 跳跃高度、gravity 重力、speed 移速、friction 摩擦力等）均统一提取在代码脚本最顶部（cfg = { ... }）。无需在复杂的逻辑代码深处翻找，轻松修改并即时调出理想的跳跃手感与操作反馈！
- 🗺️ 所见即所得的关卡设计（WYSIWYG）：告别在代码中硬编码巨型关卡二维数组，直接利用 TIC-80 内置的 Map Editor（地图编辑器，快捷键 F3） 可视化绘制关卡，配合 Sprite Flags（图块碰撞标记）与地图实体解析，真正实现关卡搭建“所见即所得”。

🌟 核心特性

- 🎮 保留 TIC-80 全部特性：
- 240×136 经典复古分辨率，16 色可定制调色盘。
- 完整的双 Bank 架构：Bank 0（256 个背景图块 Tiles）+ Bank 1（256 个前景精灵 Sprites），支持多格精灵（16×16、24×24、32×32）及 8 位精灵碰撞/事件标记（Flags）。
- 240×136 超大世界地图（World Map，共 32,640 单元格）。
- 4 通道音乐音轨跟踪器（Music Tracker，64 个 Pattern，64 首 Track，速度/节拍控制）。
- 64 个内置音效（SFX，30 音符包络、音高琶音、16 种波形合成）。
- 支持 .lua 纯文本卡带格式与官方二进制 .tic ROM 格式双向无损转换。
- 💬 对话式 AI 游戏开发：
- 为 DeepSeek Harness 提供 13 个类型化模型工具（dsh-tools），LLM 可通过对话设计游戏关卡、编写 Lua 逻辑、生成 ASCII 像素画、合成 8-bit 音效并编排复古 BGM。
- 内置智能 Linter 静态分析引擎，实时检测 Lua 语法、TIC() 主循环合规性、512KB 内存限制与越界调用。
- 🚀 内置嵌入式 UI 与实时热重载：
- DSH 内嵌三栏工作台：TIC-80 虚拟游戏机直接潜入 DeepSeek Harness Web 页面（左侧为 DSH 侧边栏，中间栏为 TIC-80 游戏机屏幕，右侧为 AI 对话栏），无需在多个窗口来回切换。
- 官方原生 TIC-80 WebAssembly 引擎与工作台：采用官方原版编译的 TIC-80 WebAssembly 控制台（基于 Emscripten 与 SDL2），100% 保留经典复古 CRT 显示效果、真实命令行 CLI 终端与官方全套内置编辑器（F1 代码编辑器、F2 精灵像素画、F3 世界地图、F4 音效合成器、F5 音乐音轨 Tracker、Ctrl+R 运行游戏、Esc 退出到终端）。
- 实时 WebSocket 热重载：LLM 或用户通过模型工具修改任意代码、精灵、地图或音效后，中间栏 TIC-80 屏幕即时重新载入卡带并无缝生效。
- Native Desktop Runner：无缝对接本地 tic80.exe 桌面版，支持 Headless CLI 测试与全屏运行。
- 📦 多格式导出：
- 一键导出 .lua 源码卡带、.tic 二进制 ROM、单文件独立运行的 .html 网页游戏。
- 🕹️ 内置经典游戏脚手架：
- minimal（极简起步）
- platformer（跳跃重力平台跳跃）
- sokoban（经典推箱子关卡）
- rpg（俯视视角冒险与 NPC 对话）
- shmup（太空弹幕射击与星空特效）

📦 安装与配置

在 DeepSeek Harness 中使用

在你的 dsh 配置文件（例如 cordis.yml 或 cordis.patch.yml）中添加插件：

- id: tic80
name: 'dsh-plugin-tic80'
config:
defaultTemplate: minimal   # 可选: minimal, platformer, sokoban, rpg, shmup
autoRun: true              # 自动启动 Web Live Studio
webStudioPort: 3088        # Web 预览端口
cartFilePath: './cart.lua' # 绑定本地卡带文件自动同步

也可以通过 dsh CLI 启动：

dsh --profile web --patch ./cordis.patch.yml

独立引入开发

npm install dsh-plugin-tic80

import { Context } from '@deepseek-ai/cordis';
import * as Tic80Plugin from 'dsh-plugin-tic80';

const ctx = new Context();
ctx.plugin(Tic80Plugin, {
defaultTemplate: 'platformer',
autoRun: true,
webStudioPort: 3088,
});

🛠️ LLM 模型工具清单 (DSH Tools)

插件在 ctx.tools 注册了 13 个面向大模型的全功能工具：

| 工具名称 | 功能描述 |
| :--- | :--- |
| tic80_init | 从预设模板（minimal/platformer/sokoban/rpg/shmup）初始化卡带项目 |
| tic80_get_cart | 查询当前卡带的代码、精灵列表、地图局部或音效音乐状态 |
| tic80_set_code | 更新卡带游戏逻辑（Lua/JS），附带静态语法校验与热重载 |
| tic80_edit_sprite | 用 ASCII 字符画（如 . 为透明，0-f 为颜色索引）绘制 8×8 或多图块精灵 |
| tic80_batch_sprites | 批量绘制一组精灵动画帧或 Tileset |
| tic80_edit_map | 在 240×136 地图上放置图块、矩形填充或通过 ASCII 布局图快速铺设关卡 |
| tic80_create_sfx | 使用预设（jump/coin/laser/explosion/hit/powerup/blip）或音符包络生成音效 |
| tic80_compose_music | 编写 4 通道复古芯片音乐 Pattern，并编排到 Track 音轨 |
| tic80_set_palette | 切换调色盘（Sweetie-16、PICO-8、DB16、GameBoy、Cyberpunk）或自定义 RGB |
| tic80_validate | 对卡带进行合规性与内存审查，确保能在 TIC-80 环境稳定运行 |
| tic80_run | 启动 Web Live Studio（浏览器热重载）或唤起本地 tic80.exe 运行 |
| tic80_export | 导出为 .lua 源码、.tic 二进制 ROM、或独立单文件 .html |
| tic80_studio_status | 查看当前 Live Studio 运行状态、在线玩家及实时运行日志 |

💡 对话提示词示例

安装插件后，你可以在 DeepSeek Harness 中与 LLM 直接对话：

“帮我做一个推箱子游戏，画一个可爱的金发工人精灵，箱子涂成木纹色，设计 3 关地图，并配上推箱子的音效和过关通关音效。”

LLM 会自动调用：
1. tic80_init({ template: 'sokoban' })
2. tic80_edit_sprite 用 ASCII 绘制人物和箱子。
3. tic80_edit_map 绘制精巧的迷宫关卡。
4. tic80_create_sfx 合成推箱子撞击声与通关特效音。
5. tic80_run({ mode: 'web' }) 打开浏览器并在画布上实时游玩！

🧪 自动化测试

项目内置 100% 覆盖的核心功能与端到端测试：

npm test

包含：
- 卡带文本解析与二进制 .tic 打包测试
- 精灵 ASCII 解析与多格拼接测试
- 地图填充与 ASCII 关卡布局测试
- 音频 SFX 波形与音乐音轨测试
- 静态 Linter 代码审查测试
- 13 个 DSH Tools 完整调用测试
- 本地 tic80.exe --cli 真实加载运行测试

📄 许可证

MIT License © 2026 NoodleStormno