https://github.com/blackglory/extra-ecs
🌲 A maintainable and readable entity component system implementation
https://github.com/blackglory/extra-ecs
browser esm library nodejs npm-package typescript
Last synced: 6 months ago
JSON representation
🌲 A maintainable and readable entity component system implementation
- Host: GitHub
- URL: https://github.com/blackglory/extra-ecs
- Owner: BlackGlory
- License: mit
- Created: 2022-08-15T14:36:20.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-09-04T13:46:47.000Z (almost 2 years ago)
- Last Synced: 2024-12-27T19:47:44.004Z (over 1 year ago)
- Topics: browser, esm, library, nodejs, npm-package, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/extra-ecs
- Size: 2.44 MB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# extra-ecs
## Install
```sh
npm install --save extra-ecs
# or
yarn add extra-ecs
```
## Usage
```ts
import { StructureOfArrays, float64 } from 'structure-of-arrays'
import { World, Query, allOf } from 'extra-ecs'
const Enabled = Symbol()
const Position = new StructureOfArrays({
x: float64
, y: float64
})
const Velocity = new StructureOfArrays({
x: float64
, y: float64
})
const world = new World()
const player = world.createEntityId()
const enemy = world.createEntityId()
world.addComponents(
player
, [Position] // equivalent to [Position, { x: 0, y: 0 }]
, [Velocity, { x: 10, y: 0 }]
, [Enabled]
)
world.addComponents(
enemy
, [Position, { x: 100, y: 0 }]
, [Velocitiy, { x: -10, y: 0 }]
, [Enabled]
)
const movableQuery = new Query(world, allOf(Position, Velocity, Enabled))
function movementSystem(deltaTime: number): void {
for (const entityId of movableQuery.findAllEntityId()) {
Position.arrays.x[entityId] += Velocity.arrays.x[entityId] * deltaTime
Position.arrays.y[entityId] += Velocity.arrays.y[entityId] * deltaTime
}
}
movementSystem(deltaTime)
```
## API
```ts
type Component =
| StructureOfArrays
| StructureOfSparseMaps
| symbol
```
### World
```ts
type MapComponentsToComponentValuePairs> = {
[Index in keyof T]:
[Exclude] extends [infer U]
? (
U extends Structure
? (
Equals extends true
? Falsy | [component: Component]
: Falsy | [component: Component, value?: MapTypesOfStructureToPrimitives]
)
: never
)
: never
}
class World {
getAllEntityIds(): Iterable
createEntityId(): number
hasEntityId(entityId: number): boolean
removeEntityId(entityId: number): void
componentsExist>(
entityId: number
, ...components: T
): MapProps
getComponents(entityId: number): Iterable
addComponents>(
entityId: number
, ...componentValuePairs: MapComponentsToComponentValuePairs
): void
removeComponents(
entityId: number
, ...components: NonEmptyArray | Falsy>
): void
}
```
### Query
```ts
class Query {
constructor(world: World, pattern: Pattern)
hasEntityId(entityId: number): boolean
findAllEntityIds(): Iterable
destroy(): void
}
```
#### Patterns
```ts
type Pattern =
| Component
| Expression
type Expression =
| Not
| AllOf
| AnyOf
| OneOf
```
##### and
```ts
function and(left: Pattern, right: Pattern): AllOf
```
##### or
```ts
function or(left: Pattern, right: Pattern): AnyOf
```
##### xor
```ts
function xor(left: Pattern, right: Pattern): OneOf
```
##### not
```ts
function not(...patterns: NonEmptyArray): Not
```
`not(pattern1, pattern2) = not(anyOf(pattern1, pattern2))`
##### allOf
```ts
function allOf(...patterns: NonEmptyArray): AllOf
```
`allOf(pattern1, pattern2, pattern3) = and(and(pattern1, pattern2), pattern3)`
##### anyOf
```ts
function anyOf(...patterns: NonEmptyArray): AnyOf
```
`anyOf(pattern1, pattern2, pattern3) = or(or(pattern1, pattern2), pattern3)`
##### oneOf
```ts
function oneOf(...patterns: NonEmptyArray): OneOf
```
`oneOf(pattern1, pattern2, pattern3) = xor(xor(pattern1, pattern2), pattern3)`