jecs/docs/learn/overview/get-started.md

Getting Started with Jecs

This guide will help you get Jecs up and running in your project.

Installation

Choose your preferred installation method:

Using Wally (Luau)

Add to your wally.toml: ::: code-group

[dependencies]
jecs = "ukendio/jecs@0.2.3"

:::

Then run:

wally install

Using npm (roblox-ts)

Use your preferred package manager: ::: code-group

npm i https://github.com/Ukendio/jecs.git

yarn add https://github.com/Ukendio/jecs.git

pnpm add https://github.com/Ukendio/jecs.git

:::

Standalone Installation

1. Navigate to the releases page
2. Download jecs.rbxm from the assets
3. Import into your Roblox project

Basic Usage

Here's a simple example to get you started:

::: code-group

local jecs = require(path.to.jecs)

-- Create a world
local world = jecs.World.new()

-- Define components
local Position = world:component() :: jecs.Entity<Vector3>
local Velocity = world:component() :: jecs.Entity<Vector3>

-- Create an entity
local entity = world:entity()

-- Add components
world:set(entity, Position, Vector3.new(0, 0, 0))
world:set(entity, Velocity, Vector3.new(1, 0, 0))

-- Update system
local function updatePositions()
    for id, position, velocity in world:query(Position, Velocity) do
        world:set(id, Position, position + velocity)
    end
end

import { World } from "@rbxts/jecs";

// Create a world
const world = new World();

// Define components
const Position = world.component<Vector3>();
const Velocity = world.component<Vector3>();

// Create an entity
const entity = world.entity();

// Add components
world.set(entity, Position, new Vector3(0, 0, 0));
world.set(entity, Velocity, new Vector3(1, 0, 0));

// Update system
function updatePositions() {
    for (const [id, position, velocity] of world.query(Position, Velocity)) {
        world.set(id, Position, position.add(velocity));
    }
}

:::

Advanced Example: Relationships

Here's an example showing Jecs' relationship features:

::: code-group

local world = jecs.World.new()
local pair = jecs.pair
local Wildcard = jecs.Wildcard

-- Define components
local Name = world:component()
local Eats = world:component()

-- Create food types (components are entities!)
local Apples = world:component()
world:set(Apples, Name, "apples")
local Oranges = world:component()
world:set(Oranges, Name, "oranges")

-- Create entities with relationships
local bob = world:entity()
world:set(bob, Name, "bob")
world:set(bob, pair(Eats, Apples), 10)
world:set(bob, pair(Eats, Oranges), 5)

local alice = world:entity()
world:set(alice, Name, "alice")
world:set(alice, pair(Eats, Apples), 4)

-- Query relationships
for id, amount in world:query(pair(Eats, Wildcard)) do
    local food = world:target(id, Eats)
    print(string.format("%s eats %d %s", 
        world:get(id, Name),
        amount, 
        world:get(food, Name)))
end

-- Output:
--   bob eats 10 apples
--   bob eats 5 oranges
--   alice eats 4 apples

:::

Key Features

Entity Management

-- Create entities
local entity = world:entity()

-- Delete entities
world:delete(entity)

-- Clear all components
world:clear(entity)

Component Operations

-- Add component (tag)
world:add(entity, IsEnemy)

-- Set component value
world:set(entity, Health, 100)

-- Get component value
local health = world:get(entity, Health)

-- Remove component
world:remove(entity, Health)

Relationships

-- Create parent-child relationship
world:add(child, pair(jecs.ChildOf, parent))

-- Query children
for child in world:query(pair(jecs.ChildOf, parent)) do
    -- Process child entities
end

Next Steps

1. Check out the First Jecs Project tutorial
2. Learn about Entities and Components
3. Explore Queries and Relationships
4. Browse the API Reference

Getting Help

• Join our Discord server
• Check the FAQ
• Report issues on GitHub