A lightweight 2.5D isometric view engine based on CSS 3D Transform
npm install iso-engine一个轻量级的 2.5D 等距视图引擎,基于 CSS 3D Transform 和 Lit Web Components 构建。
- 🎨 纯 CSS 3D 渲染 - 基于 CSS 3D Transform,无需 Canvas/WebGL,性能优异
- 🧩 声明式组件 - 提供 Web Components,支持 HTML 声明式使用
- 📦 命令式 API - 同时支持 JavaScript 命令式创建和管理
- 🔗 智能连线 - 支持实体间连线,多种路由算法,流动动画
- 💡 光影系统 - 内置光照效果和阴影
- 🎭 特效系统 - 可扩展的特效管理器
- 📐 灵活布局 - 支持等距坐标和网格坐标两种定位方式
``bash`
pnpm install iso-engine
`html
x="0" y="0" z="0"
width="100" height="100" depth="50"
top-color="#667eea"
front-color="#5a67d8"
right-color="#4c51bf">
顶面内容
前面内容
右面内容
x="200" y="100" z="0"
width="80" height="80" depth="60">
from="box1@bottom:mr"
to="box2@bottom:ml"
color="#00d4ff" width="2"
route="x-y"
animation="flow">
`
`javascript
import { IsometricEngine } from 'iso-engine'
// 创建引擎实例
const engine = new IsometricEngine()
// 创建场景
const scene = engine.createScene(document.getElementById('container'), {
width: 800,
height: 600,
centerOrigin: true
})
// 创建实体
const entity1 = engine.createEntity({
x: 0, y: 0, z: 0,
width: 100, height: 100, depth: 50,
colors: {
top: '#667eea',
front: '#5a67d8',
right: '#4c51bf'
}
})
const entity2 = engine.createEntity({
x: 200, y: 100, z: 0,
width: 80, height: 80, depth: 60
})
// 添加到场景
scene.addEntity(entity1)
scene.addEntity(entity2)
// 创建连线
const connector = engine.createConnector(entity1, entity2, {
color: '#00d4ff',
width: 2,
animated: true
})
engine.addConnectorToScene(connector, scene)
`
场景是所有等距元素的容器,负责 3D 变换和坐标系统。
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| width | number | 800 | 场景宽度(px) |height
| | number | 500 | 场景高度(px) |center-origin
| | boolean | false | 是否将原点居中 |origin-x
| | number | 0 | 原点 X 偏移 |origin-y
| | number | 0 | 原点 Y 偏移 |perspective
| | number | 0 | 透视距离(0 为正交投影) |
基础的 3D 立方体实体,支持自定义各面内容。
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| entity-id | string | '' | 实体唯一标识 |x
| | number | 0 | 等距 X 坐标 |y
| | number | 0 | 等距 Y 坐标 |z
| | number | 0 | 等距 Z 坐标(高度) |width
| | number | 100 | 宽度 |height
| | number | 100 | 高度(深度方向) |depth
| | number | 50 | 深度(垂直方向) |top-color
| | string | '#ccc' | 顶面颜色 |front-color
| | string | '#aaa' | 前面颜色 |right-color
| | string | '#888' | 右面颜色 |no-pointer
| | boolean | false | 禁用鼠标事件 |row
| | number | null | 网格行(可选) |col
| | number | null | 网格列(可选) |grid-size
| | number | 30 | 网格单元大小 |
插槽(Slots):
- top - 顶面内容front
- - 前面内容right
- - 右面内容
带倾斜面板的控制台组件,适合展示仪表盘、控制面板等。
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| tilt | number | 30 | 面板倾斜角度 |facing
| | 'front' \| 'right' | 'front' | 面板朝向 |
单一平面组件,可用于地板、墙面等。
连接两个实体的连线组件,支持多种路由和动画效果。
| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| from | string | - | 起始连接点,格式:entityId 或 entityId@face:position |to
| | string | - | 目标连接点,格式同上 |color
| | string | '#00d4ff' | 连线颜色 |width
| | number | 2 | 连线宽度 |line-style
| | string | 'solid' | 线条样式:solid / dashed / dotted |route
| | string | 'auto' | 路由类型 |perpendicular-length
| | number | 0 | 垂直延伸距离 |animation
| | string | 'none' | 动画配置,格式:type 或 type speed 或 type speed color |particles
| | string | '' | 粒子配置,格式:color size rate speed effect direction trail |
连接点格式: entityId@face:positiontop
- entityId:目标实体的 ID
- face: | bottom | front | back | left | righttl
- position:
- (top-left) | tc (top-center) | tr (top-right)ml
- (middle-left) | mc (middle-center) | mr (middle-right)bl
- (bottom-left) | bc (bottom-center) | br (bottom-right)
示例: from="box1@bottom:mr" 表示从 box1 实体底面的右中位置连接
动画格式: type speed coloranimation="flow"
- - 默认速度的流动动画animation="flow 1.5"
- - 1.5 倍速流动动画animation="glow 1 #ff0000"
- - 红色发光动画
粒子格式: 空格分隔的参数,支持带单位(顺序无关)
- particles="#fff 8px 2hz 500ms glow forward 3trail" - 带单位的完整配置particles="500ms 8px 2hz"
- - 顺序无关,通过单位识别particles="8 2 0.5"
- - 无单位按顺序解析(size, rate, speed)particles="rainbow bidirectional"
- - 彩虹双向粒子px
- 单位说明:=尺寸, hz=频率, ms=毫秒速度, s=秒速度, trail=拖尾长度
路由类型: auto | direct | x-y | y-x | x-z | z-x 等轴组合
引擎使用等距坐标系统:
- X 轴:向右下方延伸
- Y 轴:向左下方延伸
- Z 轴:垂直向上
``
Z
|
|
+------ X
/
/
Y
可以通过全局事件动态调整等距视角:
`javascript`
window.dispatchEvent(new CustomEvent('iso-angles-changed', {
detail: {
rotateX: 60, // 俯视角度
rotateZ: 45, // 旋转角度
perspective: 0 // 透视距离(0 为正交)
}
}))
`bash安装依赖
pnpm install
项目结构
`
src/
├── components/ # 组件
│ ├── IsoScene.ts # 场景组件
│ ├── IsoEntity.ts # 实体基类
│ ├── IsoCube.ts # 立方体组件
│ ├── IsoConsole.ts # 控制台组件
│ ├── IsoPlane.ts # 平面组件
│ ├── IsoConnector.ts # 连线组件
│ ├── Entity.ts # 命令式实体
│ ├── Connector.ts # 命令式连线
│ └── ...
├── core/ # 核心模块
│ ├── IsometricEngine.ts # 引擎主类
│ ├── Scene.ts # 场景类
│ ├── Transform.ts # 变换工具
│ └── BaseComponent.ts # 组件基类
├── effects/ # 特效系统
│ ├── EffectManager.ts # 特效管理器
│ └── LightingSystem.ts # 光影系统
├── events/ # 事件系统
├── utils/ # 工具函数
├── constants/ # 常量定义
├── types/ # 类型定义
└── index.ts # 入口文件
``MIT