Back to Details

miniplex

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Miniplex ECS

Miniplex ECS

Use Miniplex for minimalistic Entity Component System with TypeScript support.
When setting up or undertaking important changes with Miniplex, fetch the documentations:
Core: https://raw.githubusercontent.com/hmans/miniplex/refs/heads/main/packages/core/README.md React bindings: https://raw.githubusercontent.com/hmans/miniplex/refs/heads/main/packages/react/README.md
使用Miniplex构建支持TypeScript的极简式实体组件系统（ECS）。
在设置Miniplex或对其进行重要更改时，请查阅以下文档：
核心库：https://raw.githubusercontent.com/hmans/miniplex/refs/heads/main/packages/core/README.md React绑定：https://raw.githubusercontent.com/hmans/miniplex/refs/heads/main/packages/react/README.md

Technique

技术实现

Define an entity type with optional properties, create a world, and query entities based on their properties. Use 
miniplex-react
for React bindings with the 
Entities
component.
定义包含可选属性的实体类型，创建world，并根据实体属性查询实体。使用
miniplex-react
提供的
Entities
组件实现React绑定。

Key Concepts

核心概念

  • Entity type defines all possible components as optional properties
  • world.with('prop1', 'prop2')
    creates typed queries
  • world.add()
    and 
    world.remove()
    for entity lifecycle
  • world.addComponent()
    and 
    world.removeComponent()
    for component lifecycle
  • <Entities in={query}>{Component}</Entities>
    renders entities reactively
  • Entity props are passed directly to child components
  • 实体类型将所有可能的组件定义为可选属性
  • world.with('prop1', 'prop2')
    用于创建类型化查询
  • 使用
    world.add()
    和
    world.remove()
    管理实体生命周期
  • 使用
    world.addComponent()
    和
    world.removeComponent()
    管理组件生命周期
  • <Entities in={query}>{Component}</Entities>
    可响应式渲染实体
  • 实体属性会直接传递给子组件

What NOT to Use

不推荐使用的功能

  • onEntityAdded
    / 
    onEntityRemoved
    - Prefer using data and systems to trigger things (e.g., timers, flags)
  • .where()
    - Don't use predicate-based filtering
  • onEntityAdded
    / 
    onEntityRemoved
    - 建议使用数据和系统来触发操作（例如计时器、标记）
  • .where()
    - 不要使用基于谓词的过滤

Preferred Methods

推荐使用的方法

Only use these world methods:
  • world.add(entity)
    - Add a new entity
  • world.remove(entity)
    - Remove an entity
  • world.addComponent(entity, 'component', value)
    - Add component to existing entity
  • world.removeComponent(entity, 'component')
    - Remove component from entity
  • world.with('prop1', 'prop2')
    - Create queries
仅使用以下world方法：
  • world.add(entity)
    - 添加新实体
  • world.remove(entity)
    - 删除实体
  • world.addComponent(entity, 'component', value)
    - 为现有实体添加组件
  • world.removeComponent(entity, 'component')
    - 从实体中移除组件
  • world.with('prop1', 'prop2')
    - 创建查询

Queries

查询

Declare queries at module level and import them where needed:
tsx
// ecs/queries.ts
export const characterQuery = world.with('position', 'isCharacter')
export const enemyQuery = world.with('position', 'isEnemy')
export const movingEntities = world.with('position', 'velocity')

// In a system file
import { movingEntities } from './ecs/queries'
在模块级别声明查询，并在需要的地方导入：
tsx
// ecs/queries.ts
export const characterQuery = world.with('position', 'isCharacter')
export const enemyQuery = world.with('position', 'isEnemy')
export const movingEntities = world.with('position', 'velocity')

// 在系统文件中
import { movingEntities } from './ecs/queries'

Usage

使用示例

tsx
type Entity = {
  position?: { x: number; y: number }
  isCharacter?: true
}

const world = new World<Entity>()
const characters = world.with('position', 'isCharacter')

// Add entity
world.add({ position: { x: 0, y: 0 }, isCharacter: true })

// Render
<Entities in={characters}>{Character}</Entities>
Note: Miniplex is feature-complete but no longer maintained.
This skill is part of verekia's r3f-gamedev.
tsx
type Entity = {
  position?: { x: number; y: number }
  isCharacter?: true
}

const world = new World<Entity>()
const characters = world.with('position', 'isCharacter')

// 添加实体
world.add({ position: { x: 0, y: 0 }, isCharacter: true })

// 渲染
<Entities in={characters}>{Character}</Entities>
注意：Miniplex功能已完善，但不再维护。
本技能属于verekia的r3f-gamedev项目。