Toucan is an opinionated Entity Component System framework for Roblox-TS inspired by Rust's Bevy, favoring developer experience over raw performance.

Currently, it is in alpha stage and is not yet ready for production. The documentation is still being worked on.

Features

• Fluent API: chain methods directly on entity handles to spawn, add, remove, or modify components in a single expression, without the verbosity of step-by-step imperative manipulation;

• Expressive Queries: easily query over all entities, entities that have changed, or entities that relate to each other. Then, chain query results to filter, map, or reduce them further;

• Plugins: components and systems are better organized when grouped together within a plugin, which in turn also allows for third-party plugins that are easy to integrate;

• Standard Schedules: systems are assigned to predefined schedules that are based on Roblox's standard update loop, allowing you to easily decide when and how often to run each system;

• System Sets: systems can be grouped together into sets, allowing them to share a single configuration and run together as a unit. This also allows you to define your game's own custom pipeline, such as Setup -> Physics -> Rendering;

• Everything is an Entity: components, systems, plugins, resources, schedules, you name it — everything is an entity, meaning they can all be inspected and edited at runtime.

Example

import { component, entity, pair, query, scheduler, Scheduler, Builtin } from '@rbxts/toucan'

const Age = component<number>()
const Likes = component()

function spawnPeople() {
	const bob = entity('Bob').set(Age, 22)
	const charlie = entity('Charlie').set(Age, 42)

	entity('Alice')
		.set(Age, 25)
		.set(pair(Likes, bob))
		.set(pair(Likes, charlie))
}

const greetInterests = query(Age)
	.with(pair(Likes, Builtin.Wildcard))
	.bind((subject, age) => {
		subject.targetsOf(Likes).forEach((interest) => {
			print(`Hey ${interest}, nice to meet you! I'm ${subject} and my age is ${age}!1!`)
		})
	})

function greetingPlugin(scheduler: Scheduler) {
    scheduler
        .useSystem('startup', spawnPeople)
        .useSystem('update', greetInterests)
}

scheduler()
    .usePlugin(greetingPlugin)
    .run()

Installation

npm install @rbxts/toucan
yarn add @rbxts/toucan
pnpm add @rbxts/toucan
bun add @rbxts/toucan

Development

1. First, make sure you have bun and rokit installed in your system;

2. Then, run bun run setup to install dependencies across the entire project;

3. Finally, run bun run dev to start development.