CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新文档

Browse Source
This commit is contained in:
YHH
2025-08-11 08:18:18 +08:00
parent 3b9ae4f384
commit d539bb3dd9
2 changed files with 78 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@@ -49,7 +49,7 @@ npm install @esengine/ecs-framework
### 1. 基础使用
```typescript
import { Core, Scene, Entity, Component, EntitySystem } from '@esengine/ecs-framework';
import { Core, Scene, Entity, Component, EntitySystem, Matcher, Time } from '@esengine/ecs-framework';
// 创建核心实例
const core = Core.create({ debug: true });
@@ -58,14 +58,26 @@ Core.scene = scene;
// 定义组件
class PositionComponent extends Component {
constructor(public x: number = 0, public y: number = 0) {
public x: number = 0;
public y: number = 0;
constructor(...args: unknown[]) {
super();
const [x = 0, y = 0] = args as [number?, number?];
this.x = x;
this.y = y;
}
}
class VelocityComponent extends Component {
constructor(public dx: number = 0, public dy: number = 0) {
public x: number = 0;
public y: number = 0;
constructor(...args: unknown[]) {
super();
const [x = 0, y = 0] = args as [number?, number?];
this.x = x;
this.y = y;
}
}
@@ -76,15 +88,17 @@ entity.addComponent(new VelocityComponent(5, 0));
// 创建系统
class MovementSystem extends EntitySystem {
public process(entities: Entity[]) {
for (const entity of entities) {
const position = entity.getComponent(PositionComponent);
const velocity = entity.getComponent(VelocityComponent);
if (position && velocity) {
position.x += velocity.dx;
position.y += velocity.dy;
constructor() {
super(Matcher.all(PositionComponent, VelocityComponent));
}
protected override process(entities: Entity[]) {
for (const entity of entities) {
const position = entity.getComponent(PositionComponent)!;
const velocity = entity.getComponent(VelocityComponent)!;
position.x += velocity.x * Time.deltaTime;
position.y += velocity.y * Time.deltaTime;
}
}
}
@@ -100,16 +114,26 @@ Core.update(deltaTime);
### 查询系统
```typescript
import { EntityManager } from '@esengine/ecs-framework';
import { Matcher } from '@esengine/ecs-framework';
const entityManager = new EntityManager();
// 方式1：使用Matcher和EntitySystem
class QuerySystem extends EntitySystem {
constructor() {
super(Matcher.all(PositionComponent, VelocityComponent).none(HealthComponent));
}
// 流式查询 API
const results = entityManager
.query()
.withAll(PositionComponent, VelocityComponent)
.withNone(HealthComponent)
.execute();
protected override process(entities: Entity[]) {
// 处理匹配的实体
console.log(`Found ${entities.length} entities`);
}
}
// 方式2：手动过滤场景中的实体
const results = scene.entities.buffer.filter(entity =>
entity.hasComponent(PositionComponent) &&
entity.hasComponent(VelocityComponent) &&
!entity.hasComponent(HealthComponent)
);
```
### 事件系统
@@ -119,7 +143,7 @@ import { EventHandler, ECSEventType } from '@esengine/ecs-framework';
class GameSystem {
@EventHandler(ECSEventType.ENTITY_DESTROYED)
onEntityDestroyed(data: EntityDestroyedEventData) {
onEntityDestroyed(data: any) {
console.log('实体销毁:', data.entityName);
}
}
@@ -198,12 +222,16 @@ function gameLoop(currentTime: number) {
### 查询 API
```typescript
entityManager.query()
.withAll(...components) // 包含所有组件
.withAny(...components) // 包含任意组件
.withNone(...components) // 不包含组件
.withTag(tag) // 包含标签
.execute() // 执行查询
// Matcher API - 用于EntitySystem
Matcher.all(...components) // 包含所有组件
Matcher.any(...components) // 包含任意组件
Matcher.none(...components) // 不包含组件
// 手动查询 - 用于场景实体过滤
scene.entities.buffer.filter(entity =>
entity.hasComponent(ComponentA) &&
entity.tag === someTag
);
```
## 文档

85
docs/getting-started.md
View File

@@ -221,31 +221,18 @@ class LayaECSGame extends LayaScene {
// Laya渲染系统
class LayaRenderSystem extends EntitySystem {
private layaScene: LayaScene;
private renderMatcher: Matcher;
constructor(layaScene: LayaScene) {
super();
super(Matcher.all(PositionComponent, SpriteComponent));
this.layaScene = layaScene;
}
public initialize(): void {
super.initialize();
// 创建Matcher来查询需要渲染的实体
if (this.scene) {
this.renderMatcher = Matcher.create(this.scene.querySystem)
.all(PositionComponent, SpriteComponent);
}
}
protected process(entities: Entity[]): void {
// 获取需要渲染的实体
const renderableEntities = this.renderMatcher.query();
renderableEntities.forEach(entity => {
protected override process(entities: Entity[]): void {
entities.forEach(entity => {
const pos = entity.getComponent(PositionComponent)!;
const sprite = entity.getComponent(SpriteComponent)!;
if (pos && sprite && sprite.layaSprite) {
if (sprite.layaSprite) {
sprite.layaSprite.x = pos.x;
sprite.layaSprite.y = pos.y;
}
@@ -260,7 +247,7 @@ Laya.Scene.open("GameScene.scene", false, null, null, LayaECSGame);
### Cocos Creator
```typescript
import { Component as CocosComponent, _decorator } from 'cc';
import { Component as CocosComponent, _decorator, Node } from 'cc';
import { Core, Scene as ECSScene, EntityManager, EntitySystem } from '@esengine/ecs-framework';
const { ccclass, property } = _decorator;
@@ -307,25 +294,14 @@ export class ECSGameManager extends CocosComponent {
// Cocos渲染系统
class CocosRenderSystem extends EntitySystem {
private rootNode: Node;
private renderMatcher: Matcher;
constructor(rootNode: Node) {
super();
super(Matcher.all(PositionComponent, SpriteComponent));
this.rootNode = rootNode;
}
public initialize(): void {
super.initialize();
if (this.scene) {
this.renderMatcher = Matcher.create(this.scene.querySystem)
.all(PositionComponent, SpriteComponent);
}
}
protected process(entities: Entity[]): void {
const renderableEntities = this.renderMatcher.query();
renderableEntities.forEach(entity => {
protected override process(entities: Entity[]): void {
entities.forEach(entity => {
const pos = entity.getComponent(PositionComponent)!;
const sprite = entity.getComponent(SpriteComponent)!;
@@ -507,8 +483,9 @@ class PositionComponent extends Component {
public x: number = 0;
public y: number = 0;
constructor(x: number = 0, y: number = 0) {
constructor(...args: unknown[]) {
super();
const [x = 0, y = 0] = args as [number?, number?];
this.x = x;
this.y = y;
}
@@ -524,8 +501,9 @@ class VelocityComponent extends Component {
public x: number = 0;
public y: number = 0;
constructor(x: number = 0, y: number = 0) {
constructor(...args: unknown[]) {
super();
const [x = 0, y = 0] = args as [number?, number?];
this.x = x;
this.y = y;
}
@@ -541,8 +519,9 @@ class HealthComponent extends Component {
public maxHealth: number = 100;
public currentHealth: number = 100;
constructor(maxHealth: number = 100) {
constructor(...args: unknown[]) {
super();
const [maxHealth = 100] = args as [number?];
this.maxHealth = maxHealth;
this.currentHealth = maxHealth;
}
@@ -576,44 +555,26 @@ class MovementSystem extends EntitySystem {
super(Matcher.all(PositionComponent, VelocityComponent));
}
protected process(entities: Entity[]): void {
const movingEntities = entities;
protected override process(entities: Entity[]): void {
entities.forEach(entity => {
const position = entity.getComponent(PositionComponent)!;
const velocity = entity.getComponent(VelocityComponent)!;
movingEntities.forEach(entity => {
const position = entity.getComponent(PositionComponent);
const velocity = entity.getComponent(VelocityComponent);
if (position && velocity) {
position.x += velocity.x * Time.deltaTime;
position.y += velocity.y * Time.deltaTime;
}
});
}
}
class HealthSystem extends EntitySystem {
private healthMatcher: Matcher;
constructor() {
super();
super(Matcher.all(HealthComponent));
}
public initialize(): void {
super.initialize();
if (this.scene) {
this.healthMatcher = Matcher.create(this.scene.querySystem)
.all(HealthComponent);
}
}
protected process(entities: Entity[]): void {
if (!this.healthMatcher) return;
const healthEntities = this.healthMatcher.query();
healthEntities.forEach(entity => {
const health = entity.getComponent(HealthComponent);
if (health && health.currentHealth <= 0) {
protected override process(entities: Entity[]): void {
entities.forEach(entity => {
const health = entity.getComponent(HealthComponent)!;
if (health.currentHealth <= 0) {
entity.destroy();
}
});