# Axial2.5D

**Repository Path**: dreamszhu/Axial2.5D

## Basic Information

- **Project Name**: Axial2.5D
- **Description**: No description available
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Axial2.5D

基于 Canvas 2D API 的 2.5D 等距/二测游戏框架。

A Canvas 2D API isometric/dimetric game framework.

## 🎉 Phase 5 已完成！

**应用代码减少 57%** - 从 ~350 行精简至 ~150 行！

```typescript
const game = new Game({
  width: 800,
  height: 600,
  modules: {
    layerManager: { enabled: true },
    cameraController: { enabled: true, followEntity: 'player' },
    occlusionSystem: { enabled: true },
    effectSystem: { enabled: true },
    uiManager: { enabled: true, autoUpdate: true }
  }
});
```

详见：[docs/PHASE5_COMPLETE.md](./docs/PHASE5_COMPLETE.md)

## 📁 项目结构 Project Structure

```
Axial2.5D/
├── src/                          # 框架源代码 Framework Source
│   ├── core/                     # 核心模块 Core
│   │   ├── Projection.ts         # 投影变换 Projection
│   │   ├── IsoCamera.ts          # 相机系统 Camera
│   │   ├── CanvasRenderer.ts     # 渲染器 Renderer
│   │   ├── Layer.ts              # 图层类 Layer
│   │   ├── LayerManager.ts       # 图层管理器 Layer Manager
│   │   ├── Game.ts               # 游戏主类 Game
│   │   └── types.ts              # 类型定义 Types
│   ├── world/                    # 世界管理 World
│   │   ├── GridSystem.ts         # 网格系统 Grid
│   │   ├── GridLines.ts          # 网格线 Grid Lines
│   │   ├── EntityManager.ts      # 实体管理 Entity
│   │   ├── PathFinder.ts         # 寻路系统 Pathfinding
│   │   ├── IsoPrimitive.ts       # 3D 几何体基类 Primitives
│   │   ├── IsoBox.ts             # 3D 盒子/建筑 Boxes
│   │   └── IsoSprite.ts          # 精灵/角色 Sprites
│   ├── input/                    # 输入处理 Input
│   │   └── InputManager.ts       # 输入管理器 Input
│   ├── ui/                       # UI 系统 UI
│   │   └── UIManager.ts          # UI 管理器 UI Manager
│   ├── debug/                    # 调试工具 Debug
│   │   └── DebugSystem.ts        # 调试系统 Debug
│   ├── scene/                    # 场景管理 Scene
│   │   └── SceneManager.ts       # 场景管理器 Scene Manager
│   ├── resource/                 # 资源管理 Resource
│   │   └── ResourceManager.ts    # 资源管理器 Resource
│   ├── utils/                    # 工具类 Utils
│   │   └── EventBus.ts           # 事件总线 Event Bus
│   └── index.ts                  # 主入口 Entry Point
├── examples/                     # 示例 Examples
│   ├── html/                     # HTML 示例（浏览器运行）
│   │   ├── standalone.html       # 独立演示（无需编译）⭐
│   │   └── framework.html        # 框架示例（使用 API）
│   ├── ts/                       # TypeScript 示例（需要编译）
│   │   ├── demo.ts               # 基础演示
│   │   ├── game-demo.ts          # 完整游戏演示
│   │   └── advanced-demo.ts      # 高级功能演示
│   └── README.md                 # 示例说明
├── public/                       # 静态资源 Static Assets
│   └── assets/                   # 图片/音频等 Assets
├── server/                       # 服务器 Server
│   └── demo-server.js            # HTTP 服务器 HTTP Server
├── tests/                        # 测试 Tests
│   └── index.ts                  # 单元测试 Unit Tests
├── docs/                         # 文档 Documentation
├── dist/                         # 编译输出 Build Output (generated)
├── package.json                  # 项目配置 Package Config
├── tsconfig.json                 # TypeScript 配置 TS Config
└── README.md                     # 项目说明 Documentation
```

## 🚀 快速开始 Quick Start

### 方式 1：开发模式（推荐）Development Mode

```bash
npm install
npm run dev
```

**访问：** 
- Phase 5 示例：http://localhost:3001/examples/html/phase5-demo.html ⭐ **推荐**
- Framework 示例：http://localhost:3001/examples/html/framework.html

**特点：**
- 使用框架 API 编写
- Vite 热重载，开发体验好
- 适合学习和参考框架用法

### 方式 2：独立演示 Standalone Demo

```bash
npm run server
```

**访问：** http://localhost:3000

**特点：**
- 完整功能演示
- 无需编译，直接运行
- 适合快速体验所有功能

### 方式 3：命令行演示 CLI Demo

```bash
npm run demo    # 基础演示
npm run test    # 单元测试
```

## 📖 使用框架 Using the Framework

### 1. 安装 Installation

```bash
npm install axial-2-5d
```

### 2. 基础示例 Basic Example

#### Phase 5 简化版（推荐）

```typescript
import { Game } from 'axial-2-5d';

// 配置化创建游戏（Phase 5）
const game = new Game({
  width: 800,
  height: 600,
  modules: {
    layerManager: { enabled: true, layerCount: 5 },
    cameraController: { enabled: true, followEntity: 'player', smoothness: 0.1 },
    occlusionSystem: { enabled: true },
    effectSystem: { enabled: true },
    uiManager: { enabled: true, autoUpdate: true, logElementId: 'log' }
  }
});

// 初始化地图
game.init({
  width: 12,
  height: 12,
  tileW: 50,
  tileH: 50,
  tiles: []
});

// 访问模块
const { effectSystem, uiManager } = game.modules;

// 使用构建器 API 添加云效果
effectSystem.addClouds(8, { layer: 4, sizeRange: [40, 80] });

// UI 绑定
uiManager.bindText('fps', () => game.stats.fps);
uiManager.bindButton('btnGrid', () => toggleGrid(), { toggle: true });

// 启动游戏
game.start();
```

#### 传统方式（仍支持）

```typescript
import { Game, LayerManager, Projection } from 'axial-2-5d';

// 创建游戏实例
const game = new Game({
  width: 800,
  height: 600,
  projection: {
    type: 'isometric',
    viewAngle: 45
  }
});

// 创建地图
const mapData = {
  width: 12,
  height: 12,
  tileW: 50,
  tileH: 50,
  tiles: []
};

// 初始化游戏
game.init(mapData);

// 手动创建图层系统
const layerManager = new LayerManager({
  layerCount: 5,
  foregroundAlpha: 0.6,
  zIndexStep: 30,
  parallaxRange: 0.7
});

// 启动游戏
game.start();
```

### 3. 图层系统 Layer System

```typescript
// 创建 5 个图层，深度范围 0-2000
const layers = layerManager.createStandardLayers(0, 2000, 5, {
  // 前景透明度（Layer 4）
  foregroundAlpha: 0.6,
  
  // 背景透明度（Layer 0）
  backgroundAlpha: 1.0,
  
  // Z 轴间距（每层偏移像素）
  zIndexStep: 30,
  
  // 视差范围系数（0.0-1.0）
  // Layer 0 = 30%, Layer 4 = 30% + range
  parallaxRange: 0.7,
  
  // 背景基础视差（默认 30%）
  backgroundParallax: 0.3
});

// 图层属性
layers.forEach(layer => {
  console.log(`Layer ${layer.id}:`);
  console.log(`  Depth: ${layer.depthMin} - ${layer.depthMax}`);
  console.log(`  Parallax: ${(layer.parallaxFactor * 100).toFixed(0)}%`);
  console.log(`  Alpha: ${(layer.alpha * 100).toFixed(0)}%`);
  console.log(`  Z-Offset: ${layer.zIndexOffset}px`);
});
```

### 4. 实体管理 Entity Management

```typescript
import { IsoBox, IsoCharacter } from 'axial-2-5d';

// 创建 3D 建筑
const building = new IsoBox('house', 5, 5, 80, 80, 60);
building.setFaceColors([
  '#f5deb3', // top
  '#deb887', // front-right
  '#cd853f', // front-left
  '#b8860b', // back-right
  '#daa520', // back-left
  '#8b4513'  // bottom
]);
entityManager.addEntity(building);

// 创建角色
const player = new IsoCharacter('hero', 3, 3, 'hero_sprite', {
  width: 32,
  height: 48,
  anchorY: 1.0
});
entityManager.addEntity(player);
```

### 5. 相机控制 Camera Controls

```typescript
// 跟随玩家
game.centerCameraOnEntity('player');

// 手动设置位置
game.setCameraPosition(100, 200);

// 缩放
game.renderer.camera.zoom(1.1);  // 放大
game.renderer.camera.zoom(0.9);  // 缩小

// 平移
game.renderer.camera.pan(50, 30);
```

## 🎮 配置选项 Configuration

### 投影类型 Projection Types

**等距投影 Isometric:**
```typescript
{
  type: 'isometric',
  viewAngle: 45  // 标准等距
}
```

**二测投影 Dimetric:**
```typescript
{
  type: 'dimetric',
  viewAngle: 45,  // 水平旋转
  tiltAngle: 30   // 俯仰角
}
```

### 图层配置 Layer Options

```typescript
{
  // 视差范围：控制深度感强度
  // 0.0 = 所有图层同步移动（无深度感）
  // 0.7 = 中等深度感（默认）
  // 1.0 = 最大深度感
  parallaxRange: 0.7,
  
  // Z 轴间距：每层之间的垂直偏移（像素）
  // 0 = 所有图层重叠
  // 30 = 每层相差 30px
  zIndexStep: 30,
  
  // 前景透明度（Layer 4）
  foregroundAlpha: 0.6,
  
  // 背景透明度（Layer 0）
  backgroundAlpha: 1.0
}
```

## 🛠️ 开发命令 Development Commands

```bash
# 编译框架
npm run build

# 开发模式（自动打开框架示例）
npm run dev

# 监视模式（自动重新编译）
npm run dev:watch

# 运行测试
npm run test

# 启动演示服务器
npm run server

# 运行 CLI 演示
npm run demo

# 清理编译输出
npm run clean
```

## 🧪 测试 Testing

```bash
# 运行单元测试
npm test

# 输出示例：
# Tests: 29
# Passed: 29
# Failed: 0
```

## 📊 核心特性 Features

- 📐 **等距/二测投影** - 支持多种视角配置
- 🎨 **深度排序** - 自动处理遮挡关系
- 🗺️ **网格系统** - 完整的地图数据管理
- 🎭 **实体系统** - 角色、建筑等游戏对象
- 🖱️ **输入处理** - 鼠标/键盘/触摸支持
- 🎨 **UI 系统** - 对话框、按钮等 UI 组件
- 🔍 **调试工具** - FPS、网格、坐标显示
- 📦 **资源管理** - 图片、音频、图集加载
- 🎬 **场景管理** - 多场景切换支持
- ✏️ **寻路系统** - A*算法支持
- 🗂️ **图层系统** - 多图层视差滚动
- 🎨 **Z 轴偏移** - 图层垂直分层
- 🎯 **可调视差** - 动态调整深度感

## 🤝 贡献 Contributing

欢迎提交 Issue 和 Pull Request！

## 📄 许可证 License

MIT License

## 🙏 致谢 Acknowledgments

- 投影算法参考 [as3isolib](https://code.google.com/p/as3isolib/)
- 感谢 J.W.Opitz 的开源贡献