game-lab-kit

game-lab-kit 是一個 TypeScript monorepo，用來整理可被多個小遊戲作品重複使用的共用遊戲架構。

這個專案的重點不是放進所有遊戲，也不是綁定某一個遊戲引擎，而是把遊戲邏輯、資料合約、網路抽象、素材 manifest，以及遊戲引擎 adapter 的邊界整理清楚。

專案目標

• 建立引擎無關的共用遊戲邏輯。
• 讓多個作品集遊戲可以共用基礎工具與資料合約。
• 練習 TypeScript package / monorepo 架構設計。
• 為未來 HTTP API、WebSocket、mock data、後端服務串接預留邊界。
• 讓不同遊戲可以自由選擇 Phaser、Cocos、Unity、Unreal 或其他引擎。

Repository 策略

game-lab-kit      = 共用遊戲架構與 base library
game repositories = 每款獨立的小遊戲作品
my_portfolio      = 個人網站與作品集展示入口

game-lab-kit 不負責收納所有遊戲本體。每款遊戲應該是獨立 repo，只引用自己需要的共用 package。

目前結構

game-lab-kit/
├─ packages/
│  ├─ core/
│  ├─ contracts/
│  ├─ net/
│  ├─ asset-manifest/
│  └─ engine-adapter-contracts/
├─ docs/
├─ package.json
├─ pnpm-workspace.yaml
└─ tsconfig.base.json

Packages

@andylin-builds/core

引擎無關的遊戲邏輯工具。

目前包含：

• direction / feature layout selection
• position expression resolver
• layout expression resolver
• layout pipeline helper

未來可再擴充：

• finite state machine
• state helpers
• random utilities
• math helpers
• game loop abstractions
• result parser

@andylin-builds/contracts

共用資料合約。

目前包含：

• API success / error response types
• API response union type

未來可再擴充：

• API DTO
• schema
• HTTP request types
• WebSocket event types
• mock data contracts

更多設計說明可參考：

docs/contracts.md

@andylin-builds/net

網路與資料來源抽象。

目前包含：

• HTTP method type
• HTTP request options type
• HTTP transport interface
• Mock HTTP transport
• Fetch HTTP transport
• HTTP client helper

未來可再擴充：

• WebSocket transport
• network errors

更多設計說明可參考：

docs/net.md

@andylin-builds/asset-manifest

共用素材 manifest 的型別與工具。

這個 package 不負責存放大量實際素材，而是定義素材描述格式與載入時需要的 metadata。

目前包含：

• image / audio / font / spritesheet asset 型別
• asset manifest 型別
• defineAssetManifest helper

更多設計說明可參考：

docs/asset-manifest.md

@andylin-builds/engine-adapter-contracts

遊戲引擎 adapter 的介面定義。

這個 package 只定義遊戲邏輯希望引擎提供什麼能力，不安裝也不依賴 Phaser、Cocos、Unity、Unreal 或其他引擎。

目前包含：

• Asset loader adapter interface

未來可能包含：

• AudioAdapter
• InputAdapter
• SceneAdapter
• TickerAdapter
• TweenAdapter

依賴規則

core                         不依賴任何 game engine
contracts                    不依賴任何 game engine
net                          可依賴 contracts，但不依賴 game engine
asset-manifest               不依賴任何 game engine
engine-adapter-contracts     只放 interface，不依賴實際 game engine
game repositories            自己安裝 Phaser / Cocos / Unity / Unreal 等實際引擎

核心原則：

Game logic / API contract 不依賴遊戲引擎。
Phaser、Cocos、Unity、Unreal 只是不同的 engine adapter。

為什麼目前不放 engine-phaser

第一版不把 Phaser adapter 放進 game-lab-kit。

原因：

• 避免共用架構過早綁定 Phaser。
• 避免 game-lab-kit 安裝各種遊戲引擎依賴而變肥。
• 目前 adapter 重複還沒有出現，不需要為了架構而架構。

建議做法是先把 Phaser 實作放在單一遊戲 repo：

slot-demo-phaser/
├─ src/
│  ├─ domain/
│  ├─ application/
│  ├─ engine-phaser/
│  └─ presentation/
└─ package.json

等多款 Phaser 遊戲開始出現重複 adapter 程式碼，再考慮抽成獨立 repo：

game-lab-engine-phaser/
├─ src/audio/
├─ src/assets/
├─ src/input/
├─ src/scene/
└─ package.json

開發指令

安裝依賴：

pnpm install

build 所有 packages：

pnpm build

測試所有 packages：

pnpm test

typecheck 所有 packages：

pnpm typecheck

build 單一 package：

pnpm --filter @andylin-builds/core build

測試單一 package：

pnpm --filter @andylin-builds/core test

更多 core 測試策略與測試檔說明可參考：

docs/core-testing.md

單一遊戲 repo 如何引用

本機開發初期可以用 file: 引用：

{
  "dependencies": {
    "@andylin-builds/core": "file:../game-lab-kit/packages/core",
    "@andylin-builds/contracts": "file:../game-lab-kit/packages/contracts",
    "@andylin-builds/net": "file:../game-lab-kit/packages/net",
    "@andylin-builds/asset-manifest": "file:../game-lab-kit/packages/asset-manifest",
    "@andylin-builds/engine-adapter-contracts": "file:../game-lab-kit/packages/engine-adapter-contracts"
  }
}

未來如果發布到 npm 或 GitHub Packages，可以改成版本號：

{
  "dependencies": {
    "@andylin-builds/core": "^0.1.0",
    "@andylin-builds/contracts": "^0.1.0",
    "@andylin-builds/net": "^0.1.0",
    "@andylin-builds/asset-manifest": "^0.1.0",
    "@andylin-builds/engine-adapter-contracts": "^0.1.0"
  }
}

目前狀態

目前已完成：

• pnpm workspace 初始化
• TypeScript 共用設定
• 5 個 workspace packages 的最小 package 結構
• 所有 packages 可執行 pnpm build
• 所有目前測試可執行 pnpm test
• root .gitignore
• @andylin-builds/core 的方向版型解析、座標表達式解析、版型欄位解析與版型解析流程 helper
• core resolver 測試與說明文件
• @andylin-builds/asset-manifest 的第一版素材 manifest 型別、defineAssetManifest helper、測試與說明文件
• @andylin-builds/contracts 的第一版 API 回應合約型別與說明文件
• @andylin-builds/net 的第一版 HTTP transport interface、MockHttpTransport、FetchHttpTransport、HttpClient、baseUrl、query params、array / nested object query params、Content-Type 預設值、HttpClient default headers、HttpClient baseUrl、測試與說明文件
• @andylin-builds/engine-adapter-contracts 的第一個 AssetLoaderAdapter contract、progress / error / complete callback 型別、LoadedAssetRegistry、測試與說明文件