https://github.com/rbxts-flamework/jecs
A jecs wrapper for Flamework. Takes advantage of Flamework macros and type ID system for increased ergonomics.
https://github.com/rbxts-flamework/jecs
ecs flamework jecs roblox
Last synced: 3 months ago
JSON representation
A jecs wrapper for Flamework. Takes advantage of Flamework macros and type ID system for increased ergonomics.
- Host: GitHub
- URL: https://github.com/rbxts-flamework/jecs
- Owner: rbxts-flamework
- License: mit
- Created: 2024-10-02T21:08:33.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-04-04T23:42:59.000Z (6 months ago)
- Last Synced: 2025-06-22T07:35:46.954Z (4 months ago)
- Topics: ecs, flamework, jecs, roblox
- Language: TypeScript
- Homepage:
- Size: 469 KB
- Stars: 40
- Watchers: 2
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Flamecs
Flamework + ECS = Flamecs 🔥
- Blazingly Stupid
- Looking for VC funding
- Use types as components
- Zero-cost topologically aware functions
- Built-in Scheduler (soon)
- Component Metadata (soon)
## Installation
This package is an extension of Flamework and it must be installed and configured. If Flamework is already installed, you can install `@rbxts/flamecs` and skip these steps.
### Install Flamework packages
You can install all the necessary packages using the following command.
```bash
npm install -D rbxts-transformer-flamework
npm install @flamework/core
# Install flamecs, if it isn't already
npm install @rbxts/flamecs
```
### Configure the transformer
The Flamework transformer must be configured in your `tsconfig.json`. The fields should be placed inside of the `compilerOptions` object.
```jsonc
{
"compilerOptions": {
// Add `node_modules/@flamework` into your `typeRoots` field.
"typeRoots": ["node_modules/@rbxts", "node_modules/@flamework"],
// Copy the following fields
"experimentalDecorators": true,
"plugins": [
{
"transform": "rbxts-transformer-flamework",
},
],
},
}
```
### Configure your Rojo project
Flamework uses a custom npm org and must be configured in your `default.project.json`.
You should find the entry for `node_modules` and modify it to include `@flamework`. It should look something like this:
```json
"node_modules": {
"@rbxts": {
"$path": "node_modules/@rbxts"
},
"@flamework": {
"$path": "node_modules/@flamework"
}
}
```
### Recompile
You may need to delete the `out` folder and recompile for Flamework's transformer to begin working. Afterwards, you are ready to use flamecs.
## Components
```typescript
interface Position {
x: number;
y: number;
}
// Tag (no data)
interface Player extends Tag {}
// Components can be wrapped to use non-table data
interface Name extends Wrap {}
interface Health extends Wrap {}
```
## Entities
### Spawning Entities
```typescript
const entity = spawn();
// When spawning with tags the bundle list can be omitted
const marcus = spawn<[Player]>();
const ketchup = spawn<[Position, Player]>([{ x: 0, y: 0 }]);
// Get the runtime entity id from a component
const positionComponent = component();
```
### Modifying Entities
```typescript
add(entity);
set(entity, { x: 10, y: 20 });
set(entity, "Alice");
// Insert can be used to add/set multiple components
insert<[Name, Health, Player]>(entity, ["Bob", 100]);
remove(entity);
if (has(entity)) {
// ...
}
const pos = get(entity);
const name = get(entity);
despawn(entity);
```
## Queries
```typescript
for (const [entity, pos, name] of query<[Position, Name]>()) {
print(`${name} at ${pos.x}, ${pos.y}`);
}
for (const [entity, pos] of query<[Position, Without]>()) {
// ...
}
for (const [entity, pos] of query<[Position, With<[Player, Health]>]>()) {
// ...
}
```
## Relationships
### Defining Relationships
```typescript
interface Likes extends Tag {}
interface Owns extends Wrap {}
// Alice likes Bob
add>(alice, bob);
// Alice owns 5 items
set>(alice, 5);
```
### Querying Relationships
```typescript
// Query all entities that like something Pair
for (const [entity] of query<[Pair]>()) {
const target = target(entity);
print(`${entity} likes ${target}`);
}
// Query specific relationships where the object is a runtime id
for (const [entity] of query().pair(bob)) {
// ...
}
```
## Signals
```typescript
added().connect((entity) => {
print(`Position added to ${entity}`);
});
removed().connect((entity) => {
print(`Position removed from ${entity}`);
});
changed().connect((entity, newValue) => {
print(`Position of ${entity} changed to ${newValue}`);
});
```
## Hooks and Systems
```typescript
// Hooks must be used within a `start()` function.
start({}, () => {
if (useThrottle(0.5)) {
// ...
}
for (const [player] of useEvent(Players.PlayerAdded)) {
const entity = spawn<[Name, Player]>([player.Name]);
// ...
}
});
```