Kenji Engine

🚀 弦司遊戲引擎（Kenji Engine）

首款原生 AI 遊戲引擎。用自然語言構建遊戲，藉助 AI 生成遊戲資源，一鍵完成部署。

弦司遊戲引擎是酷梓琪（Kuuzuki）生態下的遊戲開發利器，它是一款完整的遊戲引擎，內置 MCP 服務器，支持 AI 輔助遊戲開發。你可以使用自然語言創建遊戲，利用 AI 生成像素藝術資源，並自動部署到 itch.io 平臺。

🚀 快速開始

前提條件

• Bun - JavaScript 運行時和包管理器
• 酷梓琪（Kuuzuki） - 用於提升開發體驗的 AI 助手

安裝步驟

1. 克隆倉庫：

git clone <repository-url> kenji-ge
cd kenji-ge

2. 安裝依賴：

bun install

3. 構建所有包：

bun run build

4. 使用 bun link 全局安裝 CLI 工具：
   • 選項 A：自動設置（推薦）：

# 運行設置腳本
./scripts/setup-global.sh

此腳本會自動構建所有包並鏈接所有命令。 - 選項 B：手動設置 - 僅主命令：

# 從根目錄執行
bun run build:packages
bun link

這樣你就可以使用帶有交互式菜單的 kenji-engine 命令。 - 選項 C：手動設置 - 單獨工具：

# 先構建包
bun run build:packages

# 安裝 TUI 編輯器（包含交互式菜單）
cd packages/tui-editor && bun link && cd ../..

# 安裝基本 CLI
cd packages/cli && bun link && cd ../..

這樣你就可以使用帶有交互式菜單的 kenji-engine 命令。

交互式菜單

鏈接完成後，你可以在任何位置使用交互式菜單：

kenji-ge

這將顯示一個美觀的菜單，提供以下選項：

• 🆕 創建新項目 - 通過模板交互式創建項目
• 🎯 打開 TUI 編輯器 - 啟動基於終端的可視化編輯器
• 🔨 構建項目 - 為生產環境編譯你的遊戲
• 🚀 部署項目 - 部署到 itch.io
• ❓ 顯示幫助 - 查看所有可用命令

該菜單會自動檢測當前目錄中的現有遊戲項目，並提供相應的上下文選項。

鏈接後可用的命令

運行 bun link 後，你可以全局使用以下命令：

• 主命令：
  • kenji-ge - 交互式菜單（推薦）
• TUI 編輯器命令：
  • kenji-editor - 帶有交互式菜單的 TUI 編輯器
  • kenji-editor create <name> - 創建新項目
  • kenji-editor start - 啟動 TUI 編輯器
  • kenji-editor build - 構建項目
  • kenji-editor deploy - 部署到 itch.io

注意：基本 CLI 也提供 kenji-engine 命令，但推薦使用主交互式版本以獲得最佳體驗。

創建你的第一個遊戲

1. 創建一個新的乒乓球遊戲：

kenji-ge create my-pong-game --template pong
cd my-pong-game

2. 安裝依賴：

bun install

3. 開始開發：

bun run dev

4. 在瀏覽器中打開： 在瀏覽器中打開 index.html 即可查看你的遊戲！

使用酷梓琪進行 AI 輔助開發

1. 啟動弦司的 MCP 服務器並連接酷梓琪：

cd my-pong-game
kenji mcp  # 啟動 MCP 服務器
kuuzuki    # 將 AI 助手連接到弦司

2. 使用自然語言命令：
   • "為球拍和球生成像素藝術精靈"
   • "當球擊中球拍時讓球移動得更快"
   • "當球擊中某物時添加粒子效果"
   • "創建一個道具系統"
   • "將遊戲部署到 itch.io"

✨ 主要特性

🎮 核心遊戲引擎

• 實體組件系統（ECS） - 靈活的遊戲對象架構
• 內置組件 - Transform2D、Velocity2D、Sprite2D、Collider2D
• 內置系統 - 移動、渲染、碰撞檢測
• Canvas2D 渲染器 - 像素級完美的 2D 渲染
• 輸入管理 - 鍵盤和鼠標輸入處理
• 音頻系統 - 集成 Web Audio API
• 資源管理 - 圖像和畫布資源加載

🎨 像素藝術生成

• 程序生成精靈 - 按需生成遊戲資源
• 多種風格 - 復古、現代和簡約風格
• 特定遊戲生成器 - 乒乓球、打磚塊等
• 零資源要求 - 無需外部藝術資源

🤖 原生 AI 開發

• 內置 MCP 服務器 - 直接集成酷梓琪 AI 助手
• 自然語言編碼 - 例如 "讓球更快"、"添加粒子效果"
• AI 資源生成 - 使用 AI 生成精靈、聲音和動畫
• 智能代碼生成 - AI 創建遊戲系統、組件和邏輯
• 智能部署 - AI 處理 itch.io 發佈和優化

🛠️ 開發工具

• CLI 工具 - 用於項目管理的命令行界面
• Bun 運行時 - 構建和工具鏈速度提升 10 - 100 倍
• TypeScript - 嚴格類型和現代 ES 模塊
• 熱重載 - 快速開發迭代

🚀 部署

• Butler 集成 - 自動部署到 itch.io
• Web 導出 - HTML5 遊戲打包
• 構建管道 - 優化生產構建

🤖 弦司的獨特之處

首款原生 AI 遊戲引擎

與傳統引擎（如 Unity、Godot、Phaser）不同，弦司遊戲引擎從底層開始就為 AI 輔助開發而設計：

• 自然語言編程：例如 "讓球更快"、"添加粒子效果"
• 內置 MCP 服務器：直接集成酷梓琪 AI 助手
• AI 資源生成：使用 AI 生成精靈、聲音和動畫
• 智能代碼生成：AI 創建遊戲系統和組件
• 智能部署：AI 處理優化和發佈

適合現代開發者

• 100% TypeScript：類型安全的遊戲開發
• Bun 驅動：閃電般快速的構建和運行時
• ECS 架構：可擴展、可維護的遊戲代碼
• 零配置：開箱即用

AI 輔助工作流

# 傳統遊戲開發
1. 手動編寫代碼
2. 使用外部工具創建資源
3. 手動調試和測試
4. 手動部署

# 弦司遊戲引擎 + 酷梓琪工作流
1. "創建一個乒乓球遊戲"           # AI 生成完整遊戲
2. "讓球拍發光"                   # AI 添加視覺效果
3. "添加音效"                     # AI 生成並集成音頻
4. "部署遊戲到 itch.io"           # AI 處理發佈

📦 安裝指南

1. 克隆倉庫：

git clone <repository-url> kenji-ge
cd kenji-ge

2. 安裝依賴：

bun install

3. 構建所有包：

bun run build

4. 使用 bun link 全局安裝 CLI 工具：
   • 選項 A：自動設置（推薦）：

# 運行設置腳本
./scripts/setup-global.sh

- **選項 B：手動設置 - 僅主命令**：

# 從根目錄執行
bun run build:packages
bun link

- **選項 C：手動設置 - 單獨工具**：

# 先構建包
bun run build:packages

# 安裝 TUI 編輯器（包含交互式菜單）
cd packages/tui-editor && bun link && cd ../..

# 安裝基本 CLI
cd packages/cli && bun link && cd ../..

💻 使用示例

基礎用法

// 創建遊戲引擎實例
const engine = new GameEngine({
  canvas: HTMLCanvasElement,
  mode: "2d" | "3d",
  targetFPS: number,
  debug: boolean,
});

// 初始化引擎
await engine.initialize();
// 啟動引擎
engine.start();

高級用法

// 創建實體並添加組件
const entity = new Entity()
  .addComponent(new Transform2D(x, y))
  .addComponent(new Velocity2D(vx, vy))
  .addComponent(new Sprite2D(texture));

// 將實體添加到遊戲世界
engine.world.addEntity(entity);

📚 詳細文檔

項目結構

kenji-ge/
├── packages/
│   ├── core/                    # ECS 引擎核心
│   │   ├── src/
│   │   │   ├── ecs/             # 實體、組件、系統、世界
│   │   │   ├── rendering/       # Canvas2D 渲染器
│   │   │   ├── input/           # 輸入管理
│   │   │   ├── audio/           # 音頻系統
│   │   │   ├── components/      # 內置組件
│   │   │   ├── systems/         # 內置系統
│   │   │   └── utils/           # 實用工具
│   │   └── package.json
│   ├── pixel-art-generator/     # 資源生成
│   │   ├── src/
│   │   │   ├── generators/      # 特定遊戲生成器
│   │   │   └── PixelArtGenerator.ts
│   │   └── package.json
│   ├── mcp-server/             # AI 集成
│   │   ├── src/
│   │   │   ├── server.ts        # MCP 服務器
│   │   │   └── GameProjectManager.ts
│   │   └── package.json
│   ├── butler-deploy/          # 部署工具
│   │   └── src/
│   └── cli/                    # 命令行工具
│       └── src/
├── package.json                # 工作區配置
├── bunfig.toml                 # Bun 配置
└── .mcp.json                   # MCP 服務器配置

遊戲模板

空模板

包含引擎初始化的基本遊戲設置。

乒乓球模板

經典乒乓球遊戲，包含：

• 兩個球拍
• 具有物理效果的球
• 生成的像素藝術資源

打磚塊模板（即將推出）

打磚塊遊戲，包含：

• 球拍和球
• 可破壞的磚塊
• 道具

API 參考

核心類

GameEngine

const engine = new GameEngine({
  canvas: HTMLCanvasElement,
  mode: "2d" | "3d",
  targetFPS: number,
  debug: boolean,
});

await engine.initialize();
engine.start();

Entity

const entity = new Entity()
  .addComponent(new Transform2D(x, y))
  .addComponent(new Velocity2D(vx, vy))
  .addComponent(new Sprite2D(texture));

engine.world.addEntity(entity);

PixelArtGenerator

const generator = new PixelArtGenerator();
const sprite = await generator.generateSprite({
  type: "paddle",
  width: 32,
  height: 8,
  colors: ["#FFFFFF"],
  style: "retro",
});

🔧 技術細節

開發

構建

bun run build          # 構建所有包
bun run dev            # 開發模式，監聽文件變化
bun run clean          # 清理構建產物

測試

bun test               # 運行測試

MCP 服務器

bun run mcp            # 啟動 MCP 服務器以進行 AI 集成

部署

Web 構建

kenji-ge build my-game --target web

部署到 itch.io

kenji-ge deploy my-game --itch-user username --itch-game game-slug

🤝 貢獻指南

1. 分叉倉庫
2. 創建功能分支
3. 進行更改
4. 如有必要，添加測試
5. 提交拉取請求

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🗺️ 路線圖

階段 1（當前）

• ✅ 核心 ECS 引擎
• ✅ 使用 Canvas2D 進行 2D 渲染
• ✅ 像素藝術生成
• ✅ MCP 服務器集成
• ✅ CLI 工具
• ✅ 乒乓球模板

階段 2 - 增強 AI 功能

• [ ] 高級 AI 代碼生成（完整遊戲系統）
• [ ] AI 驅動的調試和優化
• [ ] 自然語言資源修改
• [ ] AI 生成的音效和音樂
• [ ] 打磚塊和平臺遊戲模板
• [ ] 社區 AI 模型集成

階段 3 - 高級引擎功能

• [ ] 使用 Three.js + AI 輔助進行 3D 渲染
• [ ] 具有 AI 匹配的多人網絡
• [ ] 帶有 AI 建議的可視化編輯器
• [ ] 使用 AI 分析進行性能優化
• [ ] 跨平臺部署（移動、桌面）
• [ ] AI 驅動的遊戲平衡和測試

🌟 弦司生態系統

弦司 是更大的酷梓琪 AI 開發生態系統的一部分：

• 酷梓琪 - 用於開發的 AI 助手
• 弦司 - 原生 AI 遊戲引擎
• MCP 集成 - 無縫的 AI 輔助開發
• 社區模板 - AI 生成的遊戲模板和資源

為何選擇弦司？

🤝 支持與社區

• 📖 文檔
• 💬 Discord 社區
• 🐛 問題跟蹤
• 📧 郵件支持
• 🎮 即時演示 - 體驗用弦司構建的乒乓球遊戲！

🎮 由酷梓琪團隊用心打造
弦司：AI 與遊戲開發的完美結合