jecs/docs/learn/faq/common-issues.md

Common Issues

This guide covers common issues you might encounter when using Jecs and their solutions.

Performance Issues

Query Performance

Issue: Queries are running slower than expected

Solutions:

1. Cache frequently used queries:

local movementQuery = world:query(Position, Velocity):cached()

2. Use with() for components you don't need values from:

-- Instead of
for id, pos, _ in world:query(Position, IsEnemy) do end

-- Use
for id, pos in world:query(Position):with(IsEnemy) do end

3. Minimize relationship complexity to reduce archetype fragmentation

Memory Usage

Issue: High memory usage with many entities

Solutions:

1. Use tags instead of boolean components
2. Call world:cleanup() periodically to remove empty archetypes
3. Consider component data structure size

Type Issues

Component Type Errors

Issue: Type errors with components

Solutions:

1. Always specify component types:

local Health = world:component() :: jecs.Entity<number>
local Position = world:component() :: jecs.Entity<Vector3>

2. Use correct types in set operations:

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

-- Wrong
world:set(entity, Position, {x=0, y=0, z=0})

Relationship Issues

Missing Targets

Issue: Cannot find relationship targets

Solutions:

1. Use world:target() to get relationship targets:

local parent = world:target(entity, ChildOf)

2. Check relationship existence:

if world:has(entity, pair(ChildOf, parent)) then
    -- Process relationship
end

Cleanup Issues

Issue: Entities not cleaning up properly

Solutions:

1. Configure cleanup traits:

world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete))

2. Manually clean up relationships before deleting entities:

world:clear(entity) -- Remove all components
world:delete(entity) -- Then delete entity

Best Practices

Query Organization

• Cache frequently used queries
• Use appropriate filters (with/without)
• Consider component order in queries

Component Design

• Keep components small and focused
• Use tags for boolean states
• Document component types

Memory Management

• Clean up unused entities
• Configure appropriate cleanup traits
• Monitor archetype fragmentation

Getting Help

If you encounter issues not covered here:

1. Check the API documentation
2. Join our Discord server
3. Open an issue on GitHub