初始化提交

2025-10-03 16:49:53 +08:00
parent 157ca32e2d
commit bdd67a65fa
1066 changed files with 373311 additions and 261 deletions
--- a/guide/api/README.md
+++ b/guide/api/README.md
@@ -0,0 +1,600 @@
+# 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。