Entity Tags Reference¶

Tags are free-form string labels attached to entities via entity.add_tag("tag_name"). They provide a lightweight way to classify, filter, and query entities without requiring dedicated components. Tags are used throughout building commands (@attribute, @find, @search, @purge) and in game logic to drive behavior.

Tag API¶

entity.add_tag("hostile")       # Add a tag
entity.remove_tag("hostile")    # Remove a tag
entity.has_tag("hostile")       # Check for a tag

Tags are also managed in-game with the @attribute command:

@attribute sword add magic
@attribute sword remove cursed
@attribute sword list

Entity Type Tags¶

These tags identify what kind of entity something is:

Tag	Purpose
`player`	Marks the entity as a player character
`npc`	Marks the entity as a non-player character
`item`	Marks the entity as an item
`room`	Marks the entity as a room
`weapon`	Item subtype: a weapon
`armor`	Item subtype: armor
`consumable`	Item subtype: a consumable (potions, food)
`potion`	Item subtype: specifically a potion
`container`	Entity that can hold other items
`corpse`	A dead entity's remains
`quest_item`	An item tied to a quest objective

NPC Disposition Tags¶

Control how NPCs interact with players and the world:

Tag	Purpose
`friendly`	NPC is friendly to players
`hostile`	NPC is aggressive toward players
`enemy`	NPC is an enemy combatant
`combatant`	NPC participates in combat
`quest_giver`	NPC offers quests
`merchant` / `shopkeeper`	NPC buys and sells items
`innkeeper`	NPC runs an inn
`guard`	NPC is a guard
`healer` / `priest`	NPC provides healing

NPC Role & Rank Tags¶

Describe an NPC's role or rank:

Tag	Purpose
`boss`	A boss-level enemy
`mini_boss`	A mini-boss encounter
`elite`	An elite-tier NPC
`leader`	A group or faction leader
`captain`	A captain rank
`elder`	A village elder
`bodyguard`	A bodyguard NPC
`guardian`	A guardian of an area or artifact
`ancient`	An ancient being
`construct`	An artificial construct

NPC Personality Tags¶

Used by NPC autonomy systems for personality traits:

Tag	Purpose
`brave`	NPC is courageous
`ambitious`	NPC seeks advancement
`diligent`	NPC is hardworking
`greedy`	NPC is motivated by wealth
`stealthy`	NPC prefers stealth
`social`	NPC is socially inclined

State Tags¶

Track entity state:

Tag	Purpose
`dead`	Entity is dead
`in_combat`	Entity is currently in combat
`online`	Player is currently online
`immortal`	Entity cannot be killed
`hidden`	Entity is hidden from normal view
`persistent`	Entity survives server restarts
`transient`	Entity is temporary
`cursed`	Entity is cursed
`magical`	Entity has magical properties

Location Tags¶

Associate entities with areas:

Tag	Purpose
`village`	Located in or associated with the village
`goblin`	Associated with goblins or goblin areas

Builder / System Tags¶

Tags used by building tools and internal systems:

Tag	Purpose
`builder_created`	Entity was created via builder commands
`batch_created`	Entity was created by a batch script
`character`	Entity is a playable character

Dynamic Tags¶

Some tags are generated dynamically with prefixes:

Pattern	Example	Purpose
`goblin_{variant}`	`goblin_scout`	NPC variant identifier
`quest_{id}`	`quest_rescue`	Links item to a quest
`objective_{name}`	`objective_find_key`	Links item to a quest objective
`quality_{level}`	`quality_fine`	Item quality tier
`size_{size}`	`size_large`	Potion size
`effect_{type}`	`effect_healing`	Potion effect type
`source:{origin}`	`source:builder`	Tracks entity origin

Filtering with Tags¶

Tags are used in @find and @search commands:

@find item tag=weapon            # All weapon items
@find npc tag=hostile            # All hostile NPCs
@search type:npc AND tag:boss    # All boss NPCs
@purge type:item tag=transient   # Delete all transient items