Objective

MMO\rpg\entities · 1 symbol · generated 5 Oct 2026

class

Objective

A personal-development objective: a unit of progress, a level curve (pluggable, see MMO\rpg\xp\CurveFactory), and the running total of XP logged against it.

#[MMO\core\attributes\ArrayProperty('progress', getter: 'getProgress', setter: false, schema: 'object', store: false)] #[MMO\core\attributes\ArrayProperty('pendingDecay', getter: 'getPendingDecay', setter: false, schema: 'number', store: false)] #[MMO\core\attributes\ArrayProperty('inactiveDays', getter: 'getInactiveDays', setter: false, schema: 'integer', store: false)] #[MMO\core\attributes\ArrayProperty('default', getter: false, setter: 'setDefault', schema: ['type' => 'bool', 'order' => 100], store: false)] class MMO\rpg\entities\Objective extends MMO\core\entities\Entity

Namespace: MMO\rpg\entities
Extends: Entity
See: docs/XP system.md

Index

	action	the per-action reward: {xpBase, difficultyMultiplier}
	curveParams	curve-specific parameters, see CurveFactory::catalog()
	curveType	one of MMO\rpg\xp\CurveFactory::types()
	lastLogDate
	lMax	total number of levels the curve is defined over
	name
	regression	inactivity decay config: {enabled, graceDays, halfLifeDays}
	sameDayCount
	skillScore	0 (total beginner) - 1 (expert), used to compute the starting level
	streakDays
	tiers	tier labels (list of {name, maxRatio}), defaults to XPCalculator::defaultTiers() when null
	totalXp	Cumulative XP earned so far.
	unit
	calculator()
	getInactiveDays()
	getPendingDecay()
	getProgress()	Current level/tier/progress, previewing (not persisting) any pending inactivity decay.
	logAction($quantity, $difficultyOverride)	Logs one instance of the objective's activity: applies any inactivity decay accrued before today (persisted — a lapse costs XP even if you're about to log progress again right now), then grants XP …
	previewDecay($calc, $today)	Computes what `totalXp` would be after applying inactivity decay through today, WITHOUT persisting anything — used both to preview regression (getProgress/getPendingDecay/getInactiveDays) and, righ…
	regressionConfig()
	setDefault()	Seeds `totalXp` at the cumulative cost of the starting level derived from `skillScore`/`lMax` — so a competent starter doesn't have to grind through levels already earned.

Properties13

action

the per-action reward: {xpBase, difficultyMultiplier}

#[MMO\core\attributes\ArrayProperty(schema: 'object')] protected array $action = ['xpBase' => 10.0, 'difficultyMultiplier' => 1.0]

Type: array

curveParams

curve-specific parameters, see CurveFactory::catalog()

#[MMO\core\attributes\ArrayProperty(schema: 'object')] protected array $curveParams = []

Type: array

curveType

one of MMO\rpg\xp\CurveFactory::types()

#[MMO\core\attributes\ArrayProperty()] protected string $curveType = 'linear'

Type: string

lastLogDate

#[MMO\core\attributes\ArrayProperty()] protected ?string $lastLogDate = null

Type: null | string

lMax

total number of levels the curve is defined over

#[MMO\core\attributes\ArrayProperty()] protected int $lMax = 40

Type: int

name

#[MMO\core\attributes\ArrayProperty()] protected string $name = ''

Type: string

regression

inactivity decay config: {enabled, graceDays, halfLifeDays}

#[MMO\core\attributes\ArrayProperty(schema: 'object')] protected array $regression = ['enabled' => false, 'graceDays' => 3, 'halfLifeDays' => 14.0]

Type: array

sameDayCount

#[MMO\core\attributes\ArrayProperty()] protected int $sameDayCount = 0

Type: int

skillScore

0 (total beginner) - 1 (expert), used to compute the starting level

#[MMO\core\attributes\ArrayProperty()] protected float $skillScore = 0.0

Type: float

streakDays

#[MMO\core\attributes\ArrayProperty()] protected int $streakDays = 0

Type: int

tiers

tier labels (list of {name, maxRatio}), defaults to XPCalculator::defaultTiers() when null

#[MMO\core\attributes\ArrayProperty(schema: ['type' => '?object'])] protected ?array $tiers = null

Type: null | array

totalXp

Cumulative XP earned so far. Left uninitialized until setDefault() seeds it from the starting level's cumulative cost — mirrors DailyEvent::setDefault()'s isset() gating pattern.

#[MMO\core\attributes\ArrayProperty()] protected float $totalXp

Type: float

unit

#[MMO\core\attributes\ArrayProperty()] protected string $unit = ''

Type: string

Methods8

calculator()

Objective.php:72

protected function calculator(): MMO\rpg\xp\XPCalculator

returns

XPCalculator

getInactiveDays()

Objective.php:141

function getInactiveDays(): int

returns

int

getPendingDecay()

Objective.php:136

function getPendingDecay(): float

returns

float

getProgress()

Objective.php:129

Current level/tier/progress, previewing (not persisting) any pending inactivity decay.

function getProgress(): ?array

returns

null | array

logAction($quantity, $difficultyOverride)

Objective.php:154

Logs one instance of the objective's activity: applies any inactivity decay accrued before today (persisted — a lapse costs XP even if you're about to log progress again right now), then grants XP via XPCalculator::actionXp() with streak/diminishing-returns handling.

function logAction(float $quantity, ?float $difficultyOverride = null): array

$quantity	float
$difficultyOverride = null	null \| float
returns	array	float, xpDecayed: float, inactiveDays: int}

previewDecay($calc, $today)

Objective.php:108

Computes what totalXp would be after applying inactivity decay through today, WITHOUT persisting anything — used both to preview regression (getProgress/getPendingDecay/getInactiveDays) and, right before logAction() persists, to fold it in for real.

protected function previewDecay(MMO\rpg\xp\XPCalculator $calc, string $today): array

$calc	XPCalculator
$today	string
returns	array

regressionConfig()

Objective.php:98

protected function regressionConfig(): array

returns

array

setDefault()

Objective.php:88

Seeds totalXp at the cumulative cost of the starting level derived from skillScore/lMax — so a competent starter doesn't have to grind through levels already earned. Only runs once, at creation (the client sends default: true alongside the initial curve/skill config, same convention as DailyEvent::setDefault()); a later save that changes the curve never resets progress already logged.

function setDefault(): bool

returns

bool

Inherited members (111)

	Constants	Declared by	Description
	`FLAG_CHANGED`	iEntity
	`FLAG_CREATED`	iEntity
	`FLAG_IGNORE_CHANGE`	iEntity
	`FLAG_IGNORE_ENTITY`	iEntity
	`FLAG_OPACIFY`	iEntity
	`FLAG_REMOVED`	iEntity

Properties	Declared by	Description
`ArrayProperties`	aEntity
`changes`	aEntity
`collection`	Entity
`ctime`	Entity
`errors`	aEntity
`flags`	aEntity
`id`	Entity	identifier in collection
`label`	Entity	short name
`links`	aEntity
`mtime`	Entity
`SearchProperties`	aEntity
`status`	aEntity
`title`	Entity	long name

Methods	Declared by	Description
`addFlags($flags)`	aEntity
`addLink($link)`	aEntity	Append a link.
`archive()`	aEntity	This function is called to 'delete' the entity.
`ArrayProperties()`	aEntity	Build (once per class, then cached in the static `$ArrayProperties` array) the list of every #[ArrayProperty] declared on this class, its parent classes, and the traits they use -- by reflection…
`ArrayProperty($name)`	aEntity
`CheckData($data, $errors)`	aEntity	Check data before it touches any entity: would an entity made from $data be valid?
`clearChanges()`	aEntity	Reset change tracking: clears `iEntity::FLAG_CHANGED` and forgets every recorded change.
`compareTo($value)`	aEntity	Compare value
`conversionError($key, $e)`	aEntity	The error recorded for a value that could not be set at all (usually: it could not be converted to its property's type), in the same form as a validation error.
`Copy($entity, $properties)`	Entity	Build a new entity from $entity's own stored data (a duplicate, minus its id -- so saving it creates a genuinely new record -- in the same collection).
`debugName()`	aEntity
`get($path, $default)`	aEntity	Read a (possibly nested) value by json-path, e.g.
`getArrayProperty($key, $isRef, $store)`	aEntity	Read a single array property's current value, through its getter (a direct property, a path alias, or a method).
`getChanges($asArray, $store)`	aEntity
`getCollection()`	Entity
`getCtime()`	Entity
`getErrors()`	aEntity
`getFlags()`	aEntity
`getId()`	Entity
`getLabel()`	Entity
`getLinks()`	aEntity
`getLinksByRel($rels, $all)`	aEntity	Get a list of Reference that have a specific relationship.
`getMetadata()`	aEntity
`getMtime()`	Entity
`getRepository()`	Entity
`getStatus()`	aEntity
`getTitle()`	Entity
`getView()`	aEntity
`hasChanged($keys)`	aEntity
`hasFlags($flags, $strict)`	aEntity
`hasStatusChanged()`	aEntity
`HiddenPath($path)`	aEntity	The hidden property (`ArrayProperty::isHidden`) a json-path goes through, known from the declared types alone: of this class, or of a class a property on the way may hold -- every class of its t…
`ignore()`	Entity	Ignore everything about this entity: discard its pending changes and flag it so it's skipped by future commits (`aRepository::onCommit`).
`ignoreChanges($value)`	aEntity	Temporarily suppress `markChanged` (used e.g.
`isActive()`	aEntity
`isArchive()`	aEntity
`isArrayPropertySet($key, $store)`	Entity	Same as `aEntity::isArrayPropertySet`, but 'ctime'/'mtime' are never reported as "set" (they're always present, so listing them adds no information), and neither is 'id' once the entity is alrea…
`isChanged()`	aEntity
`isCreated()`	aEntity
`isDraft()`	aEntity
`isEmpty()`	aEntity
`isFinal()`	aEntity
`isHiddenPath($path)`	aEntity
`isIgnored()`	Entity
`isOpacified()`	aEntity
`isPending()`	aEntity
`isRemoved()`	aEntity
`isSimilar($value)`	Entity
`isUnique()`	aEntity	Tells if an entity has enough information to be unique (at least one unique group has no null)
`isValid()`	aEntity
`isValidated()`	aEntity
`ListClassReferences($onlyStorable)`	aEntity	Get a list of all the classes and their properties that are using references to this class.
`loadArray($data, $coerceOptions, $fromStore)`	Entity	Same as `aEntity::loadArray`, but 'ctime'/'mtime' are never taken from $data: they belong to the server (set when the entity is created, bumped by `markChanged`), and a client sending back th…
`loadFromStore($data)`	Entity	Restore from stored data, setting 'ctime'/'mtime' directly (bypassing their normal setters -- see `setCtime`/`setMtime`, which are read-only via #[ArrayProperty]).
`localName()`	Entity
`loopReferences()`	Entity	Yield all the entities in the repository that have a reference on this one.
`markChanged($keys)`	Entity	Same as `aEntity::markChanged`, also bumping `$mtime` to now -- unless the change itself was to 'ctime'/'mtime' (avoiding infinite recursion via `setMtime`'s own markChanged call).
`mutate($type, $path, $value, $oldValue)`	aEntity	\MMO\core\interfaces\iMutationObserver::mutate -- besides the normal `tArrayProperties::mutate` behavior, walks up $path to find the nearest enclosing aEntity (the mutation may have happened dee…
`offsetExists($key)`	aEntity	\ArrayAccess::offsetExists -- tells whether $key is a declared #[ArrayProperty], not whether it currently holds a non-default value (use `isArrayPropertySet` for that).
`offsetGet($key)`	aEntity	\ArrayAccess::offsetGet
`offsetSet($key, $value)`	aEntity	\ArrayAccess::offsetSet
`offsetUnset($key)`	aEntity	\ArrayAccess::offsetUnset -- equivalent to setting the property to null (its coerced value depends on the property's schema: e.g.
`opacify($value)`	aEntity	Hide this entity's properties from `toArray` output (typically used to redact an entity the current viewer isn't allowed to see the details of, while still letting it be referenced by uid/metadata).
`push($path, $value)`	aEntity	Append a value to a (possibly nested) list property by json-path.
`reload()`	Entity	Reload entity from its repository
`removeFlags($flags)`	aEntity
`removeLink($link)`	aEntity	Remove a link (by identity).
`removePermanently($force)`	Entity	Remove entity from database
`replaceBy($replace, $mergeData)`	Entity	Replace this entity by another one, trying to change all references to this entity to the new one.
`Schema()`	aEntity	The JSON-Schema describing every #[ArrayProperty] of this class (built once and cached by `ArrayProperties`).
`SearchProperty($name)`	aEntity
`set($path, $value)`	aEntity	Write a (possibly nested) value by json-path, creating intermediate structure as needed.
`setArrayProperty($key, $value, $coerceOptions, $ignoreReadonly)`	aEntity	Same as `tArrayProperties::setArrayProperty`, plus: any coercion/validation failure is caught and recorded in `getErrors` (making the entity `isValid()-false`) instead of propagating as an…
`setArrayPropertyOffset($key, $offset, $value, $coerceOptions)`	aEntity	Same as `tArrayProperties::setArrayPropertyOffset`, plus: when pushing (offset === null) a new entity onto a list property, if an existing item is `isSimilar` to the new value, that item's of…
`setCollection($collection, $removeFromCollection)`	Entity	Move this entity to (or out of, if null) a collection.
`setCtime($date, $force)`	Entity	Set creation time
`setId($id)`	Entity	Set the id, re-registering this entity in its `$collection` under the new id (`Collection`'s entities are keyed by id).
`setLinks($links)`	aEntity	Replace every link with $links.
`setMtime($date, $force)`	Entity	Set modification time
`setStatus($status)`	aEntity
`store()`	aEntity	Export all array properties with `store` set to true.
`test($filter)`	aEntity
`toArray($fields, $flatten, $recursive)`	aEntity	Same as `tArrayProperties::toArray`, except an `isOpacified` entity always exports only its 'uid' and 'metadata' (its other properties are hidden from output).
`toLink($attributes)`	aEntity
`traitMutate($type, $path, $value, $oldValue)`	aEntity	\MMO\core\interfaces\iMutationObserver::mutate -- reacts to a mutation that happened deep inside one of this object's array properties (e.g.
`traitSetArrayProperty($key, $value, $coerceOptions, $fromStore)`	aEntity	Set array property
`traitSetArrayPropertyOffset($key, $offset, $value, $coerceOptions)`	aEntity	Set/push a value into an array property
`traitToArray($fields, $flatten, $recursive)`	aEntity	Export fields to an array.
`uid()`	Entity
`validate($errors)`	aEntity	Validate this entity: its current values against its own `tArrayProperties::Schema`, plus every value that could not even be set -- one that could not be converted to its property's type never r…
`View()`	aEntity
`__construct($data, $collection)`	Entity