canvas-engine
npm install @arekrado/canvas-engine
DevTools
(in progress) https://github.com/ArekRado/canvas-engine-devtools
Example
https://github.com/ArekRado/kostki https://github.com/ArekRado/canvas-engine-devtools/tree/master/example
ECS
What is entity component system?
Entity
It's just a unique string - think about it as uniq ID from SQL database.
import { entity, initialState } from '@arekrado/canvas-engine'
const newEntity = entity.generate('human-friendly-name')
const stateWithEntity = entity.set({ state: initialState, entity: newEntity })Component
Component describes game state without logic. It's something like a record in a table from SQL database.
type State = {
// {...}
component: {
animationNumber: Dictionary<AnimationNumber>
animationString: Dictionary<AnimationString>
animationVector2D: Dictionary<AnimationVector2D>
animationVector3D: Dictionary<AnimationVector3D>
collideBox: Dictionary<CollideBox>
collideCircle: Dictionary<CollideCircle>
mouseInteraction: Dictionary<MouseInteraction>
time: Dictionary<Time>
camera: Dictionary<Camera>
transform: Dictionary<Transform>
event: Dictionary<Event>
mouse: Dictionary<Mouse>
keyboard: Dictionary<Keyboard>
}
// {...}
}Here is example how to use components:
import { Component, GetDefaultComponent } from '@arekrado/canvas-engine'
export type GunMagazine = Component<{
type: 'tubular' | 'box' | 'rotary' | 'drum'
bullets: number
}>
export const getDefaultGunMagazine: GetDefaultComponent<GunMagazine> = (
data,
) => ({
name: 'gunMagazine',
bullets: 0,
type: 'rotary',
...data,
})import {
componentName,
entity,
defaultData,
setComponent,
Transform,
} from '@arekrado/canvas-engine'
import { vectorZero } from '@arekrado/vector-2d'
import { getDefaultGunMagazine, GunMagazine } from './components/gunMagazine'
import gunImg from './assets/gun.png'
export const GunBlueprint = ({ state }): State => {
// create new entity
const gunEntity = generateEntity({ name: 'gun' })
// add new entity to state
// btw can't wait for a pipeline operator
state = createEntity({ state, entity })
state = setComponent<Transform>({
name: componentName.transform,
state,
data: defaultData.transform({
position: vector(10, 50),
}),
})
// create and push gun sprite and connect it with entity
state = setComponent<Sprite>({
name: componentName.sprite,
state,
data: defaultData.sprite({
entity: gunEntity,
src: gunImg,
}),
})
// finally add our own component
newState = setComponent<GunMagazine>({
name: 'gunMagazine',
state,
data: getDefaultGunMagazine({
entity: gunEntity,
bullets: 5,
}),
})
return newState
}System
Pure logic without state. Every system receives whole state then modifies it and returns new state. Canvas-engine contains several internal systems use runOneFrame funtion to run them.
createSystem provides simple abstraction with lifecycle methods connecting components with systems by name.
import {
Component,
State,
componentName,
createSystem,
getComponent,
defaultData,
} from '@arekrado/canvas-engine'
export const playerSystem = (state: State) =>
createSystem<Player, State>({
name: 'player',
state,
create: ({ state, component }) => {
state = setComponent<Transform, State>({
entity: component.entity,
name: componentName.transform,
state,
data: defaultData.transform({
position: vector(5, 150),
}),
})
return state
},
tick: ({ state, component }) => {
const transform = getComponent<Transform, State>({
entity: component.entity,
name: componentName.transform,
state,
})
if (state.keyboard.keys['a']?.isPressed) {
return bulletBlueprint({
position: entity.position,
})
}
return state
},
})Easy start
import {
runOneFrame,
getState,
EmptyState,
} from '@arekrado/canvas-engine'
import {
Engine,
NullEngine,
Scene,
UniversalCamera,
Vector3,
Camera,
} from '@babylonjs'
import { GunMagazine, Player } from './types'
import { gunBlueprint } from './blueprints/gunBlueprint'
import gunImg from './assets/area.png'
// Setup babylonjs
const engine = new Engine(document.getElementById('game'))
const scene = new Scene(engine)
const camera = new UniversalCamera(
'UniversalCamera',
new Vector3(0, 0, -1),
scene,
)
camera.mode = Camera.ORTHOGRAPHIC_CAMERA
// Setup state
type Components = {
player: Player
gun: Gun
}
type Systems = System<Player>
type State = EmptyState<Components, Systems>
let state = getState({ scene, camera }) as State
// Setup system
state = playerSystem(state)
// Setup initial state data
state = gunBlueprint(state)
const beforeRenderCallback = () => {
state = runOneFrame(state)
}
scene.registerBeforeRender(beforeRenderCallback)Typescript
import { EmptyState, EmptyState } from '@arekrado/canvas-engine'
export type Components = {
animationNumber: Dictionary<AnimationNumber>
collideBox: Dictionary<CollideBox>
transform: Dictionary<Transform>
}
export type Systems =
| System<AnimationNumber>
| System<CollideBox>
| System<Transform>
type YourOwnState = EmptyState<Components, Systems>
type YourOwnStateWithCanvasEngine = EmptyState<Components, Systems>Event - TODO
Blueprints vs Systems
Use blueprints if you don't want to duplicate state
// Bad
state = createCar({
state,
entity,
data: {
name: 'fiat', // only this propert will be used in a Car component
color: 'red', // bad, it can be stored in a Material component
position: [0,0,0], // bad, it can be stored in a Transform component
}
})
// Good
const carBlueprint = ({ state entity }: { state:State, entity:Entity }) => {
state = createCar({ state, entity, data: { name: 'fiat' } })
state = createTransform({ state, entity, data })
}Use system:
- if you want to use component lifecycle (create, remove, tick, update, adding and removing eventHandlers)
- if you use plain component functions (createComponent, remoevComponent, updateComponent)