# API参考

本章节提供了PE引擎所有公共API的详细参考文档。

## 全局API

### PE

PE是引擎的主要入口点。

#### PE.create(options)

创建一个新的PE引擎实例。

```javascript
import PE from 'pe-engine'

const game = PE.create({
  width: 800,
  height: 600,
  background: '#f0f0f0',
  fps: 60
})
```

**参数:**

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| options | Object | {} | 配置选项 |
| options.width | number | 800 | 舞台宽度 |
| options.height | number | 600 | 舞台高度 |
| options.background | string | '#f0f0f0' | 背景色 |
| options.fps | number | 60 | 帧率 |

**返回值:**

Engine实例

#### PE.navigateTo(path)

导航到指定路径的场景。

```javascript
PE.navigateTo('/about')
```

**参数:**

| 参数 | 类型 | 描述 |
|------|------|------|
| path | string | 目标场景路径 |

#### PE.version

获取PE引擎版本。

```javascript
console.log(PE.version) // '1.0.0'
```

### 生命周期钩子

#### onLoad(callback)

场景加载时调用的钩子。

```javascript
onLoad(() => {
  console.log('场景加载完成')
})
```

#### onShow(callback)

场景显示时调用的钩子。

```javascript
onShow(() => {
  console.log('场景显示')
})
```

#### onHide(callback)

场景隐藏时调用的钩子。

```javascript
onHide(() => {
  console.log('场景隐藏')
})
```

#### onDestory(callback)

场景销毁时调用的钩子。

```javascript
onDestory(() => {
  console.log('场景销毁')
})
```

## Engine实例API

### 元素创建

#### create(type, options)

创建元素。

```javascript
const sprite = game.create('sprite', { x: 100, y: 100 })
const box = game.create('box', { x: 200, y: 200, width: 100, height: 50 })
```

**参数:**

| 参数 | 类型 | 描述 |
|------|------|------|
| type | string | 元素类型 ('sprite', 'box', 'text', 'html', 'svg') |
| options | Object | 元素配置选项 |

**返回值:**

创建的元素实例

#### createSprite(image, x, y, width, height)

创建精灵元素。

```javascript
const sprite = game.createSprite('path/to/image.png', 100, 100, 50, 50)
```

#### createBox(x, y, width, height)

创建盒子元素。

```javascript
const box = game.createBox(100, 100, 200, 100)
```

#### createText(text, x, y)

创建文本元素。

```javascript
const text = game.createText('Hello PE!', 100, 100)
```

#### createHtml(html, x, y)

创建HTML元素。

```javascript
const htmlElement = game.createHtml('<div>HTML内容</div>', 100, 100)
```

#### createSvg(x, y, width, height, content)

创建SVG元素。

```javascript
const svgElement = game.createSvg(100, 100, 200, 200, '<circle cx="100" cy="100" r="50" />')
```

### 场景管理

#### switchToPath(path)

切换到指定路径的场景。

```javascript
await game.switchToPath('/about')
```

#### preloadScenes(paths)

预加载场景。

```javascript
await game.preloadScenes(['/home', '/about', '/contact'])
```

#### getCurrentPath()

获取当前场景路径。

```javascript
const currentPath = game.getCurrentPath()
```

#### getCurrentScene()

获取当前场景对象。

```javascript
const currentScene = game.getCurrentScene()
```

#### getSceneElement(name)

获取场景中的元素。

```javascript
const element = game.getSceneElement('my-button')
```

### 动画系统

#### tween(target, duration, easing)

创建补间动画。

```javascript
const tween = game.tween(element.element, 1000, 'easeInOutQuad')
  .to({ left: '500px' })
  .start()
```

#### createFrameAnimation(name, frames, frameRate)

创建帧动画。

```javascript
game.createFrameAnimation('walk', [
  'img/walk1.png',
  'img/walk2.png',
  'img/walk3.png'
], 10)
```

#### playFrameAnimation(sprite, animationName, loop)

播放帧动画。

```javascript
game.playFrameAnimation(sprite, 'walk', true)
```

#### createSequence(name, animations)

创建动画序列。

```javascript
game.createSequence('moveAndFade', [
  { target: element.element, props: { left: '500px' }, duration: 1000 },
  { target: element.element, props: { opacity: 0 }, duration: 500 }
])
```

#### playSequence(sequenceName, loop)

播放动画序列。

```javascript
game.playSequence('moveAndFade')
```

### 资源管理

#### load(src)

加载资源。

```javascript
const image = await game.load('path/to/image.png')
```

#### loadSound(name, src, options)

加载音效。

```javascript
game.loadSound('jump', 'path/to/jump.mp3')
```

#### loadMusic(name, src, options)

加载音乐。

```javascript
game.loadMusic('bgm', 'path/to/background.mp3')
```

#### playSound(name, options)

播放音效。

```javascript
game.playSound('jump')
```

#### playMusic(name, options)

播放音乐。

```javascript
game.playMusic('bgm')
```

### 摄像机控制

#### setCameraPosition(x, y)

设置摄像机位置。

```javascript
game.setCameraPosition(100, 100)
```

#### moveCamera(x, y)

移动摄像机。

```javascript
game.moveCamera(50, 50)
```

#### setCameraZoom(zoom)

设置摄像机缩放。

```javascript
game.setCameraZoom(1.5)
```

#### follow(target, offset)

跟随目标。

```javascript
game.follow(playerSprite, { x: 0, y: -50 })
```

#### shakeCamera(intensity, duration)

摄像机震动效果。

```javascript
game.shakeCamera(10, 500)
```

### 事件系统

#### eventBus

获取事件总线实例。

```javascript
// 发送事件
game.eventBus.emit('custom-event', { data: 'example' })

// 监听事件
game.eventBus.on('custom-event', (data) => {
  console.log('接收到事件:', data)
})
```

### 定时器

#### setTimeout(callback, delay)

设置定时器。

```javascript
const timer = game.setTimeout(() => {
  console.log('定时器触发')
}, 1000)
```

#### clearTimeout(timer)

清除定时器。

```javascript
game.clearTimeout(timer)
```

#### setInterval(callback, interval)

设置间隔执行。

```javascript
const intervalId = game.setInterval(() => {
  console.log('间隔执行')
}, 1000)
```

#### clearInterval(intervalId)

清除间隔执行。

```javascript
game.clearInterval(intervalId)
```

## 元素API

所有PE元素都具有以下通用API：

### 位置和尺寸

#### setPosition(x, y)

设置元素位置。

```javascript
element.setPosition(100, 200)
```

#### setSize(width, height)

设置元素尺寸。

```javascript
element.setSize(300, 150)
```

#### getX()

获取元素X坐标。

```javascript
const x = element.getX()
```

#### getY()

获取元素Y坐标。

```javascript
const y = element.getY()
```

#### getWidth()

获取元素宽度。

```javascript
const width = element.getWidth()
```

#### getHeight()

获取元素高度。

```javascript
const height = element.getHeight()
```

### 样式操作

#### setStyle(property, value)

设置单个样式属性。

```javascript
element.setStyle('backgroundColor', '#3498db')
```

#### setStyles(styles)

设置多个样式属性。

```javascript
element.setStyles({
  backgroundColor: '#3498db',
  borderRadius: '8px'
})
```

#### addClass(className)

添加CSS类。

```javascript
element.addClass('my-class')
```

#### removeClass(className)

移除CSS类。

```javascript
element.removeClass('my-class')
```

#### hasClass(className)

检查是否包含CSS类。

```javascript
if (element.hasClass('my-class')) {
  // 执行相应操作
}
```

### 显示控制

#### show()

显示元素。

```javascript
element.show()
```

#### hide()

隐藏元素。

```javascript
element.hide()
```

#### toggle()

切换显示状态。

```javascript
element.toggle()
```

### 文本元素特有API

#### setText(text)

设置文本内容。

```javascript
textElement.setText('新的文本内容')
```

### HTML元素特有API

#### setHtml(html)

设置HTML内容。

```javascript
htmlElement.setHtml('<div>新的HTML内容</div>')
```

## 插件API

### use(plugin, options)

安装插件。

```javascript
game.use(MyPlugin, { option1: 'value1' })
```

## 配置选项

### 引擎配置

```javascript
const game = PE.create({
  // 舞台尺寸
  width: 800,
  height: 600,
  
  // 背景色
  background: '#f0f0f0',
  
  // 帧率
  fps: 60
})
```

### 资源加载配置

```javascript
game.loadSound('jump', 'path/to/jump.mp3', {
  volume: 0.5,
  loop: false
})

game.loadMusic('bgm', 'path/to/background.mp3', {
  volume: 0.8,
  loop: true
})
```

### 动画配置

```javascript
const tween = game.tween(element.element, 1000, 'easeInOutQuad')
  .to({ left: '500px' }, 1000)
  .delay(500) // 延迟500ms
  .onStart(() => console.log('动画开始'))
  .onUpdate(() => console.log('动画更新'))
  .onComplete(() => console.log('动画完成'))
  .start()
```

通过以上API参考，你可以详细了解PE引擎提供的所有功能和使用方法。在实际开发中，建议结合示例代码和文档说明来更好地理解和使用这些API。