Entities

An entity is a named record for something your project needs to describe or reference. Most entities are characters and items, but an entity can represent any defined object in your setting, including a location, faction, creature, spell, historical event, or piece of lore.

Entities can take part in a quest or dialogue, or simply form a structured database for your world. A lore entry can hold article text and tags alongside references to related locations, even if it never appears directly in a graph.

Entities and entity types

Every entity is an instance of an entity type. The type defines which fields the entity has, while the entity supplies the values for one object.

Entity type	Entity	Example fields
Character	Mira Thorne	Full name, role, biography, related characters
Item	Moonstone Key	Description, value, related quest
Location	Old Harbor	Region, description, connected locations
LoreEntry	Old Harbor Founding	Article text, era, related people and places

Narratyr includes Character and Item types in a new project (which can be modified). Create your own entity types for other kinds of records, then add the fields that make sense for your game. A location doesn't need special built-in behavior to be useful. Treat it as an entity when other content needs to reference it or read its data.

Entities and variables

Entities describe what something is. Variables describe state that can change while the game runs.

An entity for Old Harbor can store its description, region, and map icon. A HasVisitedOldHarbor variable can record whether the player has been there. Keeping the place and its current state separate lets several dialogues and quests refer to the same location without repeating its details. Entity fields are read-only at runtime, so they can't be modified by the game. They should be used to store data about an entity that isn't meant to change over time.

Entity References: Refer to the same object throughout a project

Entity references connect project data without relying on a name that an author may later change. You can use them in:

• dialogue speakers
• variables and function parameters
• fields on other entities, including lists and sets of related entities
• quest objectives and other graph data whose type includes an entity-reference field

An entity-reference field can accept any entity or limit its choices to one entity type, such as Character or Location. References store the entity's stable Narratyr ID, so renaming the entity or changing its External ID doesn't break links inside the project.

This makes entities useful as shared narrative records. A quest can target a location, a dialogue can use a character as its speaker, and a lore entry can link to both. Each reference still points to the same record.

Create and organize entities

Open Characters & Items to browse entities in folders. Select Add, then choose one of the entity types available in the project. The type determines which property fields appear in the details panel.

Each entity has these common values:

Value	Purpose
Name	The label authors see in Narratyr and the source display name exported to the game
ID	A read-only, stable identifier used by Narratyr references
External ID	The identifier your game code can use to find or correlate the entity
Path	The folder used to organize the entity in the editor
Entity Type	The definition that supplies the entity's property fields
Profile image	An optional project asset used as the entity's portrait or thumbnail

Choose an External ID that will remain clear in game code. Narratyr doesn't change it when you rename the entity. If game code has started using an External ID, treat it as part of the connection between Narratyr and the game.

Folders only organize the editor. Use them to separate characters, locations, lore, or any other groups that make a large project easier to browse.

Example Use: Build a lore database

Create a LoreEntry, CodexEntry, or similar entity type when your project needs a store of setting information. Give it long-form text and an image, then use an option set to classify the topic. Entity-reference fields can connect it to related people, items, or places. Mark player-facing text as translatable when you define the field.

Lore entities don't need to be dialogue speakers or direct quest targets. They can serve as a shared source of facts for writers. You can also export them for an in-game codex or use them as structured context for other project content.

Exported entities

Exports include each entity's common values and the property values defined by its type. The runtime integration can look up an entity by its stable ID or External ID and read its typed data. Entity references in exported dialogues, quests, variables, and fields continue to use the stable ID.

See Exporting for the general workflow. To create a complete example in the editor, follow Add a character.