Entity.h header

#include <ew/core/Entity.h>

Namespace ew::core

Entity class

class ew::core::Entity

A codex entity: a named content object that belongs to a taxonomy category and carries values for that category's fields (its own plus inherited). This is the bridge between the content graph and the taxonomy – the category id selects the schema (via Taxonomy::effectiveFields) and values are stored by field key. Type interpretation of a value is the caller's job, guided by the field's FieldType.

Members

ew::core::Entity::Entity(ContentId id, CategoryId categoryId, QString name)

Creates an entity with identity id, in category categoryId (a null id means uncategorized), and display name name.

CategoryId ew::core::Entity::categoryId() const

The category this entity belongs to; a null id means uncategorized.

void ew::core::Entity::setCategoryId(CategoryId categoryId)

Sets the entity's category (a null id means uncategorized).

const QString & ew::core::Entity::name() const

The entity's display name (used for lists, links, and previews).

void ew::core::Entity::setName(QString name)

Sets the entity's display name.

void ew::core::Entity::setValue(QString key, QString value)

Sets the value for field key, replacing any existing value.

std::optional< QString > ew::core::Entity::value(QStringView key) const

Returns the value stored for field key, or std::nullopt if none is set.

bool ew::core::Entity::hasValue(QStringView key) const

Returns true if a value is stored for field key.

bool ew::core::Entity::clearValue(QStringView key)

Removes the value for field key. Returns true if a value was removed.

const std::map< QString, QString > & ew::core::Entity::values() const

All stored field values, keyed by field key in deterministic (sorted) order.

std::optional< qint64 > ew::core::Entity::birthInstant() const

The instant (minutes since the story epoch) this entity came into being, if known. A canon fact the timeline continuity engine uses for lifespan and age checks: an event with this entity as a participant must not occur before it.

void ew::core::Entity::setBirthInstant(std::optional< qint64 > birthInstant)

Sets the entity's birth instant (std::nullopt when unknown).

std::optional< qint64 > ew::core::Entity::deathInstant() const

The instant this entity ceased to be, if known. An event with this entity as a participant must not occur after it.

void ew::core::Entity::setDeathInstant(std::optional< qint64 > deathInstant)

Sets the entity's death instant (std::nullopt when unknown).

const std::vector< TimedFieldValue > & ew::core::Entity::timedValues() const

The entity's state-over-time: the timed changes to its field values across the story timeline (see TimedFieldValue), in no particular order. Empty when the entity has no timed values (its fields are constant).

void ew::core::Entity::setTimedValues(std::vector< TimedFieldValue > timedValues)

Sets the entity's state-over-time (its timed field-value changes).

std::optional< QString > ew::core::Entity::valueAt(QStringView key, qint64 instant) const

The effective value of field key at story instant: the value of the latest timed change for key at or before instant, or – when no timed change applies that early – the base value (Entity::value). std::nullopt when the field has neither a timed change in effect by instant nor a base value.

const std::set< QString > & ew::core::Entity::aliases() const

Alternative names/nicknames this entity is also known by (e.g. "Strider", "Elessar" for Aragorn). Used for link resolution – the prose auto-linker treats each alias like the primary name – and for spell-check (so coined names are not flagged). Deduplicated and ordered for deterministic serialization; empty when the entity has none.

void ew::core::Entity::setAliases(std::set< QString > aliases)

Sets the entity's alternative names/nicknames.

const std::vector< ContentId > & ew::core::Entity::gallery() const

The media assets shown as this entity's gallery on its codex page (portraits, reference art, a map of its domain), by Media id in display order. Each id resolves to a Media object whose assetPath points at the image file; the first is used as the entity's thumbnail in hover previews. Distinct from a Reference field (a single typed link) – a gallery is an ordered set of illustrative images. Empty when the entity has no gallery.

void ew::core::Entity::setGallery(std::vector< ContentId > gallery)

Sets the entity's gallery (Media ids in display order; the first is the thumbnail).

TimedFieldValue struct

struct ew::core::TimedFieldValue

A change to one of an entity's field values at a point in story time: from instant onward, the field key takes the value value. This is how an entity's attributes evolve over the timeline – a character's location, rank, or status; a faction's ruler – distinct from the base field value (Entity::value), which is the initial value in effect before any timed change. The instant is minutes since the project's story epoch, matching timeline events and lifespans.

Members

QString ew::core::TimedFieldValue::key

The field key whose value changes (the same key space as Entity::value).

qint64 ew::core::TimedFieldValue::instant = 0

When the change takes effect, in minutes since the project's story epoch.

QString ew::core::TimedFieldValue::value

The field's value from instant onward.

bool operator==(const TimedFieldValue &, const TimedFieldValue &)=default

Two timed values compare equal when key, instant, and value all match.