refactor: convert to monorepo structure with engine package (#4)

Author: hiddentao

.github/workflows/ci.yml

@@ -39,23 +39,17 @@ jobs:
         path: playwright-report/
         retention-days: 30
 
-    - name: Install demo dependencies
-      run: cd demo && bun i
-
     - name: Run linting and type checking
       run: bun run lint
 
-    - name: Run demo linting and type checking
-      run: cd demo && bun run lint
-
     - name: Run tests with coverage
       run: bun run coverage
 
     - name: Build demo
-      run: cd demo && bun run build
+      run: bun run demo:build
 
     - name: Upload coverage to Coveralls
       uses: coverallsapp/github-action@v2
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
-        file: ./lcov.info
+        file: ./packages/core/lcov.info

.github/workflows/deploy-demo.yml

@@ -34,7 +34,7 @@ jobs:
       run: bun run build
 
     - name: Build demo
-      run: cd demo && bun i && bun run build
+      run: bun run demo:build
 
     - name: Setup Pages
       uses: actions/configure-pages@v4
@@ -46,4 +46,4 @@ jobs:
 
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v4
+      uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -11,7 +11,7 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
-    
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -36,10 +36,8 @@ jobs:
       - name: Get changelog for this release
         id: changelog
         run: |
-          # Extract changelog section for this version
           VERSION="${{ steps.tag.outputs.tag }}"
           if [ -f "CHANGELOG.md" ]; then
-            # Get content between this version and next version/end of file
             awk "/^## \[?${VERSION#v}\]?/ {flag=1; next} /^## / && flag {exit} flag" CHANGELOG.md > release_notes.md
             if [ -s release_notes.md ]; then
               echo "HAS_CHANGELOG=true" >> $GITHUB_OUTPUT
@@ -62,4 +60,4 @@ jobs:
           prerelease: false
           generate_release_notes: ${{ steps.changelog.outputs.HAS_CHANGELOG == 'false' }}
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -27,6 +27,7 @@ dist-ssr
 coverage
 lcov.info
 test-results/
+playwright-report/
 
 # Build info
 tsconfig.tsbuildinfo
@@ -40,3 +41,6 @@ tsconfig.declarations.tsbuildinfo
 # Demo build
 demo/dist
 
+# Packages
+packages/*/dist
+packages/*/node_modules

.versionrc.json

@@ -1,59 +1,20 @@
 {
-  "header": "# Changelog\n\nAll notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.\n",
-  "types": [
-    {
-      "type": "feat",
-      "section": "Features"
-    },
-    {
-      "type": "fix",
-      "section": "Bug Fixes"
-    },
-    {
-      "type": "docs",
-      "section": "Documentation"
-    },
-    {
-      "type": "test",
-      "section": "Tests"
-    },
-    {
-      "type": "build",
-      "section": "Build System"
-    },
-    {
-      "type": "ci",
-      "section": "CI/CD"
-    },
-    {
-      "type": "chore",
-      "hidden": true
-    },
-    {
-      "type": "style",
-      "hidden": true
-    },
-    {
-      "type": "refactor",
-      "section": "Code Refactoring"
-    },
-    {
-      "type": "perf",
-      "section": "Performance Improvements"
-    },
-    {
-      "type": "revert",
-      "section": "Reverts"
-    }
+  "packageFiles": [
+    "packages/core/package.json"
+  ],
+  "bumpFiles": [
+    "packages/core/package.json"
   ],
-  "commitUrlFormat": "https://github.com/hiddentao/clockwork-engine/commit/{{hash}}",
-  "compareUrlFormat": "https://github.com/hiddentao/clockwork-engine/compare/{{previousTag}}...{{currentTag}}",
-  "issueUrlFormat": "https://github.com/hiddentao/clockwork-engine/issues/{{id}}",
-  "userUrlFormat": "https://github.com/{{user}}",
-  "releaseCommitMessageFormat": "chore(release): {{currentTag}}",
-  "issuePrefixes": ["#"],
-  "tagPrefix": "v",
-  "scripts": {
-    "prerelease": "bun run lint && bun test && bun run build"
-  }
+  "infile": "CHANGELOG.md",
+  "header": "# Changelog\n\nAll notable changes to this project will be documented in this file.\n",
+  "types": [
+    { "type": "feat", "section": "Features" },
+    { "type": "fix", "section": "Bug Fixes" },
+    { "type": "perf", "section": "Performance" },
+    { "type": "refactor", "section": "Refactoring" },
+    { "type": "docs", "section": "Documentation" },
+    { "type": "test", "section": "Tests" },
+    { "type": "build", "section": "Build System" },
+    { "type": "ci", "section": "CI/CD" }
+  ]
 }

LICENSE.md

@@ -1,6 +1,6 @@
-# MIT License
+MIT License
 
-Copyright (c) 2025 [Ramesh Nair](https://hiddentao.com)
+Copyright (c) 2025 Ramesh Nair
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -4,87 +4,109 @@
 
 [![Build Status](https://img.shields.io/github/actions/workflow/status/hiddentao/clockwork-engine/ci.yml?branch=main)](https://github.com/hiddentao/clockwork-engine/actions)
 [![Coverage Status](https://coveralls.io/repos/github/hiddentao/clockwork-engine/badge.svg?branch=main)](https://coveralls.io/github/hiddentao/clockwork-engine?branch=main)
-[![NPM Version](https://img.shields.io/npm/v/@hiddentao/clockwork-engine.svg)](https://www.npmjs.com/package/@hiddentao/clockwork-engine)
+[![NPM Version](https://img.shields.io/npm/v/@clockwork-engine/core.svg)](https://www.npmjs.com/package/@clockwork-engine/core)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-blue.svg)](https://www.typescriptlang.org/)
 
-**A TypeScript game engine for deterministic, replayable games with built-in recording, replay, and rendering capabilities.**
+**A TypeScript game engine for deterministic, replayable games with platform-agnostic rendering.**
 
-[Documentation](./docs)
+[Documentation](./packages/core/docs)
 
 </div>
 
 ---
 
-## 🎮 Live Demo
+## Live Demo
 
 **[Try the Interactive Demo →](https://hiddentao.github.io/clockwork-engine)**
 
-## ✨ Features
+## Features
 
-- 🎯 **Deterministic Gameplay** - Frame-based updates with seeded PRNG for perfect reproducibility
-- 📹 **Record & Replay** - Built-in recording system for gameplay sessions with frame-accurate playback
-- 🎮 **Game Object System** - Type-safe game entities with automatic grouping and lifecycle management
-- 🎨 **Built-in PIXI.js Renderer** - Built-in [pixi.js](https://pixijs.com/) integration with viewport management, event handling, and rendering abstractions
-- 🏃‍♂️ **High-Performance Collision Detection** - Spatial partitioning with BSP trees for efficient collision queries
-- ⚡ **Event-Driven Architecture** - Flexible event system with custom event sources and managers
-- 🔄 **Universal Serialization** - Automatic serialization for all game data with custom type support
-- ⏱️ **Frame-Based Timers** - Deterministic timing system replacing JavaScript's native timers
-- 🔧 **TypeScript First** - Full type safety with comprehensive interfaces and generics
+- **Deterministic Gameplay** - Frame-based updates with seeded PRNG for perfect reproducibility
+- **Record & Replay** - Built-in recording system for gameplay sessions with frame-accurate playback
+- **Game Object System** - Type-safe game entities with automatic grouping and lifecycle management
+- **Platform-Agnostic Rendering** - Separate rendering implementations (PIXI.js for web, headless for testing)
+- **High-Performance Collision Detection** - Spatial partitioning with BSP trees for efficient collision queries
+- **Event-Driven Architecture** - Flexible event system with custom event sources and managers
+- **Universal Serialization** - Automatic serialization for all game data with custom type support
+- **Frame-Based Timers** - Deterministic timing system replacing JavaScript's native timers
+- **TypeScript First** - Full type safety with comprehensive interfaces and generics
 
-## 🚀 Quick Start
+## Packages
+
+This monorepo contains the following packages:
+
+| Package | Description |
+|---------|-------------|
+| [`@clockwork-engine/core`](./packages/core) | Core engine with game objects, recording/replay, serialization, and platform abstraction |
+| [`@clockwork-engine/platform-web-pixi`](./packages/platform-web-pixi) | Web platform with PIXI.js 2D rendering |
+| [`@clockwork-engine/platform-memory`](./packages/platform-memory) | Headless platform for testing and replay validation |
+
+## Quick Start
 
 ### Installation
 
 ```bash
-npm install @hiddentao/clockwork-engine
-# or
-bun add @hiddentao/clockwork-engine
+# Install core engine and web platform
+bun add @clockwork-engine/core @clockwork-engine/platform-web-pixi
+
+# For testing/headless use
+bun add @clockwork-engine/platform-memory
 ```
 
 ### Basic Usage
 
 ```typescript
-import { GameEngine, GameObject, Vector2D, GameCanvas } from '@hiddentao/clockwork-engine'
+import { GameEngine, GameObject, Vector2D, GameCanvas } from '@clockwork-engine/core'
+import { WebPlatformLayer } from '@clockwork-engine/platform-web-pixi'
 
+// 1. Define your game engine
 class MyGame extends GameEngine {
   setup() {
-    // Initialize your game world
     const player = new Player(new Vector2D(100, 100))
     this.registerGameObject(player)
   }
 }
 
+// 2. Define your game canvas
 class MyGameCanvas extends GameCanvas {
-  protected initializeGameLayers(): void {
+  protected setupRenderers(): void {
     // Set up your game rendering layers
   }
 
   protected render(deltaFrames: number): void {
-    // Custom rendering logic (optional)
+    // Custom rendering logic
   }
 }
 
-const game = new MyGame()
-game.reset("my-seed")
-
-// Create canvas with built-in PIXI.js integration
-const container = document.getElementById('game-container')
-const canvas = await MyGameCanvas.create(container, {
-  width: 800,
-  height: 600,
+// 3. Initialize the platform and canvas
+const container = document.getElementById('game-container')!
+const platform = new WebPlatformLayer(container, {
+  screenWidth: 800,
+  screenHeight: 600,
   worldWidth: 800,
-  worldHeight: 600
+  worldHeight: 600,
 })
+await platform.init()
+
+// 4. Create and initialize the canvas
+const canvas = new MyGameCanvas(
+  { width: 800, height: 600, worldWidth: 800, worldHeight: 600 },
+  platform
+)
+await canvas.initialize()
 
+// 5. Create game engine and connect to canvas
+const game = new MyGame()
+await game.reset({ seed: 'my-seed' })
 canvas.setGameEngine(game)
 game.start()
 ```
 
-## 📚 Documentation
+## Documentation
 
-Comprehensive documentation is available in the [docs](./docs) directory:
+Comprehensive documentation is available in the [docs](./packages/core/docs) directory.
 
-## 🛠️ Development
+## Development
 
 ### Prerequisites
 
@@ -101,7 +123,7 @@ cd clockwork-engine
 # Install dependencies
 bun install
 
-# Build the project
+# Build all packages
 bun run build
 
 # Run in watch mode
@@ -134,9 +156,9 @@ bun run format
 ### Demo Application
 
 ```bash
-# Run the demo (from project root)
+# Run the demo
 cd demo
-bun i 
+bun i
 bun run dev
 ```
 
@@ -173,9 +195,8 @@ The release process will:
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md)
+See [CHANGELOG.md](./CHANGELOG.md)
 
-## 📄 License
+## License
 
 This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
-