jecs/docs/learn/overview/first-jecs-project.md

Your First Jecs Project

This tutorial will walk you through creating your first project with Jecs, demonstrating core concepts and best practices.

Setting Up

First, make sure you have Jecs installed. If not, check the Getting Started guide.

::: code-group

local jecs = require(path.to.jecs)
local world = jecs.World.new()

import { World } from "@rbxts/jecs";
const world = new World();

:::

Creating Components

Let's create some basic components for a simple game:

::: code-group

-- Position in 3D space
local Position = world:component() :: jecs.Entity<Vector3>

-- Velocity for movement
local Velocity = world:component() :: jecs.Entity<Vector3>

-- Health for gameplay
local Health = world:component() :: jecs.Entity<number>

-- Tag for marking enemies
local IsEnemy = world:component()

// Position in 3D space
const Position = world.component<Vector3>();

// Velocity for movement
const Velocity = world.component<Vector3>();

// Health for gameplay
const Health = world.component<number>();

// Tag for marking enemies
const IsEnemy = world.component();

:::

Creating Game Systems

Let's create some basic systems to handle movement and gameplay:

Movement System

::: code-group

-- Cache the query for better performance
local movementQuery = world:query(Position, Velocity):cached()

local function updateMovement(deltaTime)
    for id, position, velocity in movementQuery:iter() do
        -- Update position based on velocity and time
        world:set(id, Position, position + velocity * deltaTime)
    end
end

// Cache the query for better performance
const movementQuery = world.query(Position, Velocity).cached();

function updateMovement(deltaTime: number) {
    for (const [id, position, velocity] of movementQuery) {
        // Update position based on velocity and time
        world.set(id, Position, position.add(velocity.mul(deltaTime)));
    }
}

:::

Damage System

::: code-group

local function applyDamage(entity, amount)
    local currentHealth = world:get(entity, Health)
    if currentHealth then
        local newHealth = currentHealth - amount
        if newHealth <= 0 then
            world:delete(entity)
        else
            world:set(entity, Health, newHealth)
        end
    end
end

function applyDamage(entity: Entity, amount: number) {
    const currentHealth = world.get(entity, Health);
    if (currentHealth) {
        const newHealth = currentHealth - amount;
        if (newHealth <= 0) {
            world.delete(entity);
        } else {
            world.set(entity, Health, newHealth);
        }
    }
}

:::

Creating Game Entities

Now let's create some game entities:

::: code-group

-- Create a player
local player = world:entity()
world:set(player, Position, Vector3.new(0, 0, 0))
world:set(player, Velocity, Vector3.new(0, 0, 0))
world:set(player, Health, 100)

-- Create an enemy
local enemy = world:entity()
world:set(enemy, Position, Vector3.new(10, 0, 10))
world:set(enemy, Health, 50)
world:add(enemy, IsEnemy)

// Create a player
const player = world.entity();
world.set(player, Position, new Vector3(0, 0, 0));
world.set(player, Velocity, new Vector3(0, 0, 0));
world.set(player, Health, 100);

// Create an enemy
const enemy = world.entity();
world.set(enemy, Position, new Vector3(10, 0, 10));
world.set(enemy, Health, 50);
world.add(enemy, IsEnemy);

:::

Adding Relationships

Let's add some parent-child relationships:

::: code-group

-- Create weapon entity
local weapon = world:entity()
world:add(weapon, pair(jecs.ChildOf, player))

-- Query for player's children
for child in world:query(pair(jecs.ChildOf, player)) do
    print("Found player's child:", child)
end

// Create weapon entity
const weapon = world.entity();
world.add(weapon, pair(jecs.ChildOf, player));

// Query for player's children
for (const [child] of world.query(pair(jecs.ChildOf, player))) {
    print("Found player's child:", child);
}

:::

Running the Game Loop

Here's how to put it all together:

::: code-group

local RunService = game:GetService("RunService")

RunService.Heartbeat:Connect(function(deltaTime)
    -- Update movement
    updateMovement(deltaTime)
    
    -- Other game systems...
end)

const RunService = game.GetService("RunService");

RunService.Heartbeat.Connect((deltaTime) => {
    // Update movement
    updateMovement(deltaTime);
    
    // Other game systems...
});

:::

Next Steps

1. Learn more about Entities and Components
2. Explore Queries in depth
3. Understand Relationships
4. Check out Component Traits
5. Browse the API Reference

Where To Get Help

If you are encountering problems, there are resources for you to get help:

• Roblox OSS Discord server has a #jecs thread under the #projects channel
• Open an issue if you run into bugs or have feature requests
• Dive into the nitty gritty in the thesis paper