Pandona-Engine/guide/api

API参考

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

全局API

PE

PE是引擎的主要入口点。

PE.create(options)

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

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)

导航到指定路径的场景。

PE.navigateTo('/about')

参数:

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

PE.version

获取PE引擎版本。

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

生命周期钩子

onLoad(callback)

场景加载时调用的钩子。

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

onShow(callback)

场景显示时调用的钩子。

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

onHide(callback)

场景隐藏时调用的钩子。

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

onDestory(callback)

场景销毁时调用的钩子。

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

Engine实例API

元素创建

create(type, options)

创建元素。

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)

创建精灵元素。

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

createBox(x, y, width, height)

创建盒子元素。

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

createText(text, x, y)

创建文本元素。

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

createHtml(html, x, y)

创建HTML元素。

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

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

创建SVG元素。

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

场景管理

switchToPath(path)

切换到指定路径的场景。

await game.switchToPath('/about')

preloadScenes(paths)

预加载场景。

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

getCurrentPath()

获取当前场景路径。

const currentPath = game.getCurrentPath()

getCurrentScene()

获取当前场景对象。

const currentScene = game.getCurrentScene()

getSceneElement(name)

获取场景中的元素。

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

动画系统

tween(target, duration, easing)

创建补间动画。

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

createFrameAnimation(name, frames, frameRate)

创建帧动画。

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

playFrameAnimation(sprite, animationName, loop)

播放帧动画。

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

createSequence(name, animations)

创建动画序列。

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

playSequence(sequenceName, loop)

播放动画序列。

game.playSequence('moveAndFade')

资源管理

load(src)

加载资源。

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

loadSound(name, src, options)

加载音效。

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

loadMusic(name, src, options)

加载音乐。

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

playSound(name, options)

播放音效。

game.playSound('jump')

playMusic(name, options)

播放音乐。

game.playMusic('bgm')

摄像机控制

setCameraPosition(x, y)

设置摄像机位置。

game.setCameraPosition(100, 100)

moveCamera(x, y)

移动摄像机。

game.moveCamera(50, 50)

setCameraZoom(zoom)

设置摄像机缩放。

game.setCameraZoom(1.5)

follow(target, offset)

跟随目标。

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

shakeCamera(intensity, duration)

摄像机震动效果。

game.shakeCamera(10, 500)

事件系统

eventBus

获取事件总线实例。

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

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

定时器

setTimeout(callback, delay)

设置定时器。

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

clearTimeout(timer)

清除定时器。

game.clearTimeout(timer)

setInterval(callback, interval)

设置间隔执行。

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

clearInterval(intervalId)

清除间隔执行。

game.clearInterval(intervalId)

元素API

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

位置和尺寸

setPosition(x, y)

设置元素位置。

element.setPosition(100, 200)

setSize(width, height)

设置元素尺寸。

element.setSize(300, 150)

getX()

获取元素X坐标。

const x = element.getX()

getY()

获取元素Y坐标。

const y = element.getY()

getWidth()

获取元素宽度。

const width = element.getWidth()

getHeight()

获取元素高度。

const height = element.getHeight()

样式操作

setStyle(property, value)

设置单个样式属性。

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

setStyles(styles)

设置多个样式属性。

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

addClass(className)

添加CSS类。

element.addClass('my-class')

removeClass(className)

移除CSS类。

element.removeClass('my-class')

hasClass(className)

检查是否包含CSS类。

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

显示控制

show()

显示元素。

element.show()

hide()

隐藏元素。

element.hide()

toggle()

切换显示状态。

element.toggle()

文本元素特有API

setText(text)

设置文本内容。

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

HTML元素特有API

setHtml(html)

设置HTML内容。

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

插件API

use(plugin, options)

安装插件。

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

配置选项

引擎配置

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

资源加载配置

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

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

动画配置

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。