Tags

Learn about tags as components without data and how to use world:add() to mark entities

Tags are components without data. They are used to mark or categorize entities without storing any associated values. Think of them as boolean flags that can be added or removed from entities.

Why Use Tags?

A tag takes zero bytes of storage per entity. More importantly, tags enable a different mental model. When you see a tag on an entity, you know it’s just a marker and there’s no data to read or write.

Tags are entities that do not have the builtin jecs.Component trait, which tells the ECS that this ID cannot store any data—it is just a marker.

Creating Tags

There are two ways to create tags:

1. Using jecs.tag() (Recommended)

Preregister a tag entity that will be allocated when you create the world:

local jecs = require("@jecs")

local Dead = jecs.tag()

-- Creating the world after the tags to ensure they get allocated
local world = jecs.world()

This is the “proper” way to create tags. It ensures a stable type ID by registering the tag before creating the world. See the guide on preregistering components for more details.

2. Using world:entity()

Create a regular entity ID and use it as a tag:

local world = jecs.world()
local Dead = world:entity()

This approach is simpler but doesn’t guarantee stable IDs across sessions.

Adding Tags

Use world:add() to add a tag to an entity:

local entity = world:entity()

world:add(entity, Dead)  -- Adds the tag

print(world:has(entity, Dead))  -- true

You cannot use world:set() with tags because tags don’t store data. Use world:add() instead.

Checking for Tags

Use world:has() to check if an entity has a tag:

if world:has(entity, Dead) then
    print("Entity is dead")
end

You can also check if a component ID is a tag using jecs.is_tag():

print(jecs.is_tag(world, Dead))  -- true

local Position = world:component() :: jecs.Id<number>
print(jecs.is_tag(world, Position))  -- false

Removing Tags

Use world:remove() to remove a tag from an entity:

world:remove(entity, Dead)

print(world:has(entity, Dead))  -- false

Tags vs Components

Feature	Tags	Components
Storage	0 bytes per entity	Type-specific bytes per entity
Adding	world:add()	world:set()
Reading	world:has()	world:get()
Removing	world:remove()	world:remove()
Use case	Marking/categorizing	Storing data

Example Use Cases

Tags are perfect for:

• State flags: Dead, Alive, Stunned, Frozen
• Categories: Npc, Player, Enemy, Ally
• Capabilities: CanFly, CanSwim, CanTeleport
• Temporary markers: Dirty, Updated, Scheduled

local Enemy = jecs.tag()
local Flying = jecs.tag()
local Boss = jecs.tag()

local world = jecs.world()

local dragon = world:entity()
world:add(dragon, Enemy)
world:add(dragon, Flying)
world:add(dragon, Boss)

-- Query for flying enemies
for entity in world:query(Enemy):with(Flying) do
    print(`Flying enemy: {entity}`)
end

Tags can be used in queries just like components. Use query:with() to filter for entities that have a tag without retrieving any data.