:alembic: alchemy engine

> 👾 Easily make 2D browser games with pixi.js

:sparkles: Features

- 100% Type-Safe
- Batteries included (get started using one CLI command)
- Reactive - Re-render view when state changes
- Object pooling
- Timer - Run logic every X ticks
- Animations
- Debug overlay
- Keyboard input
- Sounds
- Sprite sheet generation
- Scenes
- CLI - Create project and components
- CI - Workflows to build, test and deploy to itch.io
- Screen shake
- Uses vite for a super fast and modern dev server

---

Getting started

Run the init command from within a Git repo

``console
npx alchemy@latest init
`

This will:

- Copy template files
- Add alchemy-engine and pixi.js as dependencies

---

API Docs

- Module API
- create
- sprite
- animatedSprite
- text
- htmlText
- bitmapText
- container
- graphics
- rectangle
- event
- onClick
- onHover
- sync
- sync
- syncPosition
- keys
- arrowKeys
- position
- getAllChildren
- getAllLeafChildren
- debug
- logObject
- boundsToString
- contains
- intersects
- type guards
- isAnimatedSprite
- loadDataFromImage
- pool
- Scene API
- getTexture
- getTextures
- useScreenShake
- animate
- app
- music
- sound
- setScene
- global
- container
- state
- internalState
- subscribe, subscribeKey, proxy
- timer
- input
- random
- CLI
- dev
- sprite
- sound
- Local development
- See also

Module API

These are imported directly from alchemy-engine

$3

Convenience functions to create Pixi objects

#### sprite

`ts
import { sprite } from 'alchemy-engine'

sprite(container, getTexture('./square-1')])
`

#### animatedSprite

`ts
import { animatedSprite } from 'alchemy-engine'

animatedSprite(container, getTextures(['./square-1', './square-2']))
`

#### text

`ts
import { text } from 'alchemy-engine'

text(container, textStyle, 'Hello world')
`

#### htmlText

`ts
import { htmlText } from 'alchemy-engine'

htmlText(container, textStyle, 'Hello world')
`

#### bitmapText

`ts
import { bitmapText } from 'alchemy-engine'

bitmapText(container, textStyle, 'Hello world')
`

#### container

`ts
import { container } from 'alchemy-engine'

container(_container)
`

#### graphics

`ts
import { graphics } from 'alchemy-engine'

graphics(container)
`

#### rectangle

`ts
import { rectangle } from 'alchemy-engine'

rectangle(container, { x: 0, y: 0, width: 10, height: 10 })
`

$3

#### onClick

Convenience functions for mouse input

`ts
import { onClick } from 'alchemy-engine'

onClick(container, () => {
console.log('Clicked!')
})
`

#### onHover

`ts
import { onHover } from 'alchemy-engine'

onHover(container, {
onOver() {
console.log('Hovered!')
},
onOut() {
console.log('Not hovered!')
},
})
`

$3

#### sync

#### syncPosition

$3

#### arrowKeys

Constants for all arrow keys

`ts
import { arrowKeys } from 'alchemy-engine'

export const keys = ['a', 'w', 's', 'd', ...arrowKeys] as const
`

$3

TODO

$3

TODO

$3

TODO

$3

#### logObject

Nicely log a Pixi object. Set label property for best result.

`ts
import { logObject } from 'alchemy-engine'

const sprite = new Sprite()
sprite.label = 'sprite'
logObject(sprite)
`

$3

Enables easier logging of sprite bounds

`ts
import { boundsToString } from 'alchemy-engine'

console.log(boundsToString(sprite))
`

$3

Check if a point is within the bounds of an object

`ts
import { contains } from 'alchemy-engine'

if (contains(sprite, { x: 1, y: 1 })) {
// point is within bounds of sprite
}
`

$3

Check if the bounds of two objects are intersecting

`ts
import { intersects } from 'alchemy-engine'

if (intersects(sprite1, sprite2)) {
// sprites are intersecting
}
`

$3

#### isAnimatedSprite

`ts
import { isAnimatedSprite } from 'alchemy-engine'

if (isAnimatedSprite(sprite)) {
// sprite is of type AnimatedSprite
}
`

$3

This function can be used to for example load a level from image data

`ts
import { loadDataFromImage } from 'alchemy-engine'
import map from '~/public/asset/map.png?url'

const { pixels, width, height } = await loadDataFromImage(map)
console.log(pixels)
// ['255-255-255', '0-0-0']
`

$3

Docs

---

Scene API

The arguments passed to a scene

`ts
{
textures,
container,
input,
state,
timer,
sound,
app,
timer,
useScreenShake,
}: Scene
`

$3

Get a texture

`ts
function myScene(scene: Scene) {
sprite(scene.container, scene.getTexture('./texture-1'))
}
`

$3

Get multiple textures

`ts
function myScene(scene: Scene) {
animatedSprite(
scene.container,
scene.getTextures(['./texture-1', './texture-2']),
)
}
`

$3

Enable the use of screen shake

screenShake takes a number between 0 and 1

`ts
const screenShake = useScreenShake(container)

screenShake(0.5)
`

$3

These functions all require an onUpdate and duration argument

Optionally you can pass a startValue (default: 0) and endValue (default: 1)

- sine
- easeOut
- easeIn
- linear

`ts

`

$3

The Pixi Application instance

$3

`ts
Record
`

Example:

`ts
scene.music.bgm.loop(true).play()
`

$3

`ts
Record
`

Example:

`ts
scene.sound.coin.play()
`

$3

Takes sceneKey as an argument

`ts
setScene('mainMenu')
`

$3

timer

A timer that doesn't get cancelled when changing scenes

$3

A scene specific Pixi container. Will be destroyed when scene is changed.

$3

Set state to trigger sync and subscribe functions

$3

$3

Re-exported from valtio

Changes from valtio versions:

- Triggers once up front when called
- Unsubscribes when changing scene

$3

delay

Resolves a promise after X ticks

`ts
// Wait 100 updates
await scene.timer.delay(100)
`

repeatUntil

Execute a callback every update until duration is reached

`ts
await scene.timer.repeatUntil(3, (time, deltaTime) => {})
`

repeatEvery

Execute a callback indefinitely every interval updates

Returns a cancel function

`ts
const cancel = repeatEvery(3, (time, deltaTime) => {})
`

$3

debouncedKey

`ts
scene.input.debouncedKey(
'd',
() => {
s.position.x += 1
},
// Delay between key presses
10,
)
`

isKeyDown

Check if a key is currently being pressed

`ts
scene.timer.repeatEvery(1, () => {
if (scene.input.isKeyDown(['a', 'ArrowLeft'])) {
s.position.x -= 1
}
if (scene.input.isKeyDown(['d', 'ArrowRight'])) {
s.position.x += 1
}
})
`

$3

There is a built-in seedable random module.

To set the seed, pass it in to createGame

`ts
createGame({
randomSeed: 99,
})
`

The module uses the same API as park-miller, with some additions:

chance(percentage) => boolean

---

CLI

$3

Start the dev server. Listens to changes to source code, sprite, src/public/asset/sound and src/public/asset/music folders.

`console
npx alchemy dev
`

$3

Generate sprite sheet

`console
npx alchemy sprite
`

$3

Load sounds

`console
npx alchemy sound
`

---

Local development

Run ./go.sh` to test that things work

---

See also

- State machine: xstate
- Noise simplex-noise