Migrating from Matter

This guide helps you migrate your code from Matter ECS to Jecs.

Key Differences

World Creation

-- Matter
local world = Matter.World.new()

-- Jecs
local world = jecs.World.new()

Component Definition

-- Matter
local Position = { name = "Position" }
local Velocity = { name = "Velocity" }

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

Entity Creation

-- Matter
local entity = world:spawn()

-- Jecs
local entity = world:entity()

Adding Components

-- Matter
world:insert(entity, Position, { x = 0, y = 0, z = 0 })

-- Jecs
world:set(entity, Position, Vector3.new(0, 0, 0))

Querying

-- Matter
for id, pos, vel in world:query(Position, Velocity) do
    -- Process entities
end

-- Jecs
for id, pos, vel in world:query(Position, Velocity) do
    -- Process entities
end

Major Feature Differences

Relationships

Jecs provides built-in support for entity relationships:

-- Jecs only
world:add(child, pair(ChildOf, parent))

Component Traits

Jecs allows adding traits to components:

-- Jecs only
world:add(Position, Networked)

Query Caching

Jecs provides explicit query caching:

-- Jecs only
local cachedQuery = world:query(Position, Velocity):cached()

Migration Steps

Update Component Definitions
- Replace Matter component tables with Jecs components
- Add type annotations for better type safety
Update Entity Management
- Replace spawn() with entity()
- Update component insertion syntax
Update Queries
- Review and update query usage
- Consider using query caching for performance
Add Relationships
- Replace custom parent-child implementations with Jecs relationships
- Use built-in relationship features
Update Systems
- Review system implementation patterns
- Consider using component traits for better organization

Performance Considerations

Query Performance
- Cache frequently used queries
- Use appropriate filters
Component Storage
- Use tags for boolean states
- Consider component data structure size
Relationship Usage
- Be mindful of relationship complexity
- Use built-in relationships when possible

Getting Help

Need help migrating?

Join our Discord server
Check the API documentation
Open an issue on GitHub

2.5 KiB Raw Blame History