---
# System prepended metadata

title: vang

---

# vang

## ✅ TODO

### updated plan
* ComponentFlags impl.
* Initial query implementation. no filter (check perf)
* Impl filters
* Check comments
* Simple example
* Publish initally to npm with very simple doc pages

* Move onto std/3d lib.
    * rapier.js physics
    * three.js visuals
    * geckos.io netcode

### Plan
* redo packages
    - imp
    - @imp/shared
    - @imp/collections
* create simple core ecs (no query with filter etc) & testing (gotta be faster than ts-jest)
* core should be a mix of uecs + bevyecs
* publish to github
* create other features
#### Rework
* use bevy-ecs as reference
* redo entity allocation https://github.com/bevyengine/bevy/blob/main/crates/bevy_ecs/src/entity/mod.rs
* redo world https://github.com/bevyengine/bevy/blob/main/crates/bevy_ecs/src/world/mod.rs


### Storage/World
* optimize create/delete/destroy operations
* disable/enable components
* added/changed/removed filter impl.
* disabled filter impl.
* create plugin define
* dont allow "new Component" (ruins pooling)
* ComponentSparseSet grow/shrink
* better storage types (@see below)


```typescript=

type Storage = {
    slice(id: ComponentId): ComponentSlice;
    sliceOrInsert(id: ComponentId): ComponentSlice;
    
    /**
     * 
     */
    entitySliceOfSmallest(components: Entity): EntitySlice;
}

type Sliceable = {
    slice(from: number, to: number): Slice
}

type Slice<I = number, T = unknown> = {
    at(index: I): T;
    length: number;
}

type ArraySlice<T> = Slice<number, T>

type ComponentSlice<T extends Component = Component> = Slice<Entity, T>

type EntitySlice = Slice<number, T>

```
* use name 'trait' where needed ("FilterTrait", "ComponentTrait")
* rename ComponentFlags -> ComponentSet
* use name 'ComponentFlags' for states like "ADDED", "REMOVED", "CHANGED", "DISABLED"

### Scheduler
* add systems at runtime
* enable/disable systems at runtime

### World Builder
* use arbitary order when defining groups
* create `group` util function for defining groups 
* add `groups` method to add several groups
* be able to use objets created by `groups` when selecting order
* plugin support
* throw if multiple groups with same name has been registered
* go over naming (systems, components etc.)

### Collections
* move to seperate package
* simplify Vec.

## 📜 Example
```typescript
import { World, query, group } from "vang";
import { added, not, changed } from "vang/filters"

function box_system(world: World) {
    for (const [box, tr] of query(Box, not(Transform2D)) {
        tr.y -= box.weight;
    }
}

const PostUpdateGroup = group("post-update", { after: "update"});
const PreUpdateGroup  = group("pre-update", { before: "update"});
const RenderingGroup  = group("rendering", { rel: "update" order: -10000 });

const world = World.build()
    .with({ capacity: 1000 })
    .groups(PostUpdateGroup, PreUpdateGroup, RenderingGroup)
    .group("debug-update", { before: PreUpdateGroup })
    .systems(PostUpdateGroup, box_system):

```

### Plugins
```typescript=
// 3dplugin.ts
import { plugin } from "vang";

type Options = {
    rendering: boolean;
}

export default plugin<Options>({
    name: `${package.name}`,
    version: `${package.version}`,
    register: (builder, opts) => {
        builder.group("transforms-update", { after: "update" })
        if (opts.rendering) {
            // add rendering components/ctx
        }
    }
})

// game.ts
import Std3DPlugin from "@imp/std/3d"

const world = World.build()
    .plugin(Std3DPlugin({ rendering: false }))

```


## 📦 Packages

### `vang`

Contains the core _ECS_ project.

```typescript
export type { Component, ComponentType }
export type { Resource, ResourceType }
export type { Plugin }
export type { System }

export { World, query, ComponentFlags, ComponentSet }
```
### `vang/filter`
Query filters.
```typescript
export { added, removed, changed, disabled, observe, not, filter }
```

### `@vang/std/3d`

Default 3D plugin for creating 3D games
* 3D position, scale, rotation etc.
* threejs rendering
* parent hierarchy


### `@vang/shared`

Shared utility & common types/classes.

### `@vang/collections`
Collections such as:
* Vec
* SparseSet
* SlotMap

### `@vang/app`
More "generic" engine version

### `@vang/net`
Netcode implementation. Will probly use geckos.io & their TypedSchema packages
as a start & expand/create my own if I feel thats needed or if I want to 😅

### `@vang/devtools`
inspector devtools.
@see flecs, ecsy for examples