# 简介

你正在阅读的是 Pandona Engine (PE) 的文档！

PE 是一款用于构建 2D 游戏和动画的 JavaScript 框架。它基于标准 HTML、CSS 和 JavaScript 构建，并提供了一套声明式的、组件化的编程模型，帮助你高效地开发 2D 游戏和动画。无论是简单的互动动画还是复杂的 2D 游戏，PE 都可以胜任。

下面是一个最基本的示例：

```javascript
import PE from 'PE'

// 创建游戏实例
const game = PE.create()

// 创建一个精灵元素
const sprite = game.create('sprite', {
  x: 100,
  y: 100,
  width: 50,
  height: 50
})

// 将精灵添加到游戏中
game.addGameObject(sprite)
```

```html
<sence>
  <sprite class="my-sprite" @click="handleClick"></sprite>
  <box class="my-box">Hello PE!</box>
</sence>

<script>
function handleClick() {
  console.log('Sprite clicked!')
}
</script>
```

**结果展示**

上面的示例展示了 PE 的核心功能：

- **声明式渲染**：PE 基于标准 HTML 拓展了一套模板语法，使得我们可以声明式地描述游戏场景和元素。
- **响应性**：PE 会自动跟踪游戏状态并在其发生变化时响应式地更新渲染。
- **组件化**：PE 支持基于场景的组件化开发，每个场景可以包含多个元素。

## 什么是 PE？

PE (Pandona Engine) 是一款用于构建 2D 游戏和动画的 JavaScript 框架。它基于标准 HTML、CSS 和 JavaScript 构建，并提供了一套声明式的、组件化的编程模型，帮助你高效地开发 2D 游戏和动画。

## 渐进式框架

PE 是一个框架，也是一个生态。其功能覆盖了大部分 2D 游戏和动画开发常见的需求。但游戏开发世界是十分多样化的，不同的开发者在构建的东西可能在形式和规模上会有很大的不同。考虑到这一点，PE 的设计非常注重灵活性和"可以被逐步集成"这个特点。根据你的需求场景，你可以用不同的方式使用 PE：

- 无需构建步骤，渐进式增强静态的 HTML
- 在任何页面中作为 Web Components 嵌入
- 单场景应用 (SSA)
- 全屏 / 画布渲染 (CSR)
- 开发桌面端、移动端 2D 游戏

## 场景组件

在大多数 PE 项目中，我们可以使用一种类似 HTML 格式的文件来书写游戏场景，它被称为**场景文件** (也被称为 `*.pe` 文件)。顾名义，PE 的场景文件会将一个场景的逻辑 (JavaScript)，模板 (HTML) 和样式 (CSS) 封装在同一个文件里。下面我们将用场景文件的格式重写上面的示例：

```html
<sence>
  <sprite class="my-sprite" @click="handleClick"></sprite>
  <box class="my-box">Hello PE!</box>
</sence>

<script>
function handleClick() {
  console.log('Sprite clicked!')
}
</script>

<style>
.my-sprite {
  width: 50px;
  height: 50px;
  background-color: blue;
}
.my-box {
  color: white;
  background-color: red;
}
</style>
```

场景文件是 PE 的标志性功能。你可以使用它来编写游戏场景。你可以在后续相关章节里了解更多关于场景文件的用法及用途。

## API 风格

PE 的场景可以按两种不同的风格书写：**模板式 API** 和 **编程式 API**。

### 模板式 API (Template API)

使用模板式 API，我们可以在 `.pe` 文件中使用类似 HTML 的语法来描述场景元素，并在 `<script>` 标签中编写逻辑代码。

```html
<sence>
  <sprite class="my-sprite" @click="increment"></sprite>
  <text class="counter">Count is: {{ count }}</text>
</sence>

<script>
let count = 0

function increment() {
  count++
}
</script>
```

### 编程式 API (Programmatic API)

通过编程式 API，我们可以使用 JavaScript 代码直接创建和管理游戏元素。

```javascript
import PE from 'PE'

// 创建游戏实例
const game = PE.create()

// 创建响应式状态
let count = 0

// 创建精灵元素
const sprite = game.create('sprite', {
  x: 100,
  y: 100,
  width: 50,
  height: 50
})

// 添加点击事件
sprite.element.addEventListener('click', () => {
  count++
})

// 将精灵添加到游戏中
game.addGameObject(sprite)
```

### 该选哪一个？

两种 API 风格都能够覆盖大部分的游戏开发场景。它们只是同一个底层系统所提供的两套不同的接口。

模板式 API 以"场景"的概念为中心，对于有 Web 开发背景的用户来说，这通常与基于 HTML 的心智模型更为一致。同时，它将渲染相关的细节抽象出来，并强制按照模板和脚本的方式来组织代码，从而对初学者而言更为友好。

编程式 API 的核心思想是直接使用 JavaScript 代码来创建和管理游戏元素。这种形式更加自由，也需要你对 PE 的系统有更深的理解才能高效使用。相应的，它的灵活性也使得组织和重用游戏逻辑的模式变得更加强大。

如果你是使用 PE 的新手，这里是我们的大致建议：

- 在学习的过程中，推荐采用更易于自己理解的风格。再强调一下，大部分的核心概念在这两种风格之间都是通用的。熟悉了一种风格以后，你也能够很快地理解另一种风格。
- 在生产项目中：
  - 当你不需要使用构建工具，或者打算主要在低复杂度的场景中使用 PE，推荐采用模板式 API。
  - 当你打算用 PE 构建完整的游戏项目，推荐采用编程式 API。

在学习阶段，你不必只固守一种风格。在接下来的文档中我们会为你提供一系列两种风格的代码供你参考。

## 还有其他问题？

请查看我们的 FAQ。

## 选择你的学习路径

不同的开发者有不同的学习方式。尽管在可能的情况下，我们推荐你通读所有内容，但你还是可以自由地选择一种自己喜欢的学习路径！