Path to the BodyPlan singleton.
Path to the default bulk Material for a member of this species. v1 sufficient: a Tangible Stuff cloned from a species template can stamp itself with this Material at clone-time. (Tissue / per-Detail authoring is deferred.)
Path to the parent Clade singleton (kingdom or sub-clade).
ProtectedbinomialLatin binomial nomenclature (e.g. 'Homo sapiens').
Protectedcircadian'diurnal', 'nocturnal', 'crepuscular', 'cathemeral',
'aperiodic'. v1 has no consumer (sleep / circadian deferred).
ProtectedcommonVernacular synonyms (e.g. ['human', 'man']).
ProtecteddietOptional dietary tag ('carnivore', 'herbivore', 'omnivore',
'photosynthesis'). v1 has no consumer (DietApi deferred).
ProtectedillustrationProtectedinnateGated mixins this species intrinsically confers (activates) —
the innate leg of conferral, the mirror of AugmentMixin.confers().
getActiveMixins / collectAugmentConferralNames union these names
with the actor's slot-augment conferrals, so a gated mixin is active
when composed AND (an augment confers it OR the species confers it).
A born-attuned species declares ['AetherMixin'], giving attunement
with no implant — the same innate⊕acquired union the sensorium does
for bodyplan senses and defaultModeFor does for locomotion.
Scope: this activates a gated mixin already composed on the
shared Creature/Avatar class — it cannot compose a new mixin
onto an instance (the compose-everything-gated vs. per-species-
subclass question is deferred; nothing needs it yet).
Home is Species, not BodyPlan — a capability divergence among
species sharing a body plan.
ProtectedlifecycleLifecycle states this species recognizes. Animalia: typically
['alive', 'dead', 'undead']. Constructa:
['powered', 'unpowered', 'destroyed']. Plantae: ['alive', 'dead'].
Drives OrganismMixin.setLifecycleState's validity (when validation
lands; v1 accepts any string per slate).
ProtectedlifespanProtectedlifespanLifespan band (years). v1 is descriptive only.
ProtectedlongProtectednameReferences to one or more NameBank Documents by key (e.g.
['common'], ['orcish', 'common']). The name suggester resolves
these and unions the pools. NOT the name data itself — that lives
in the name_banks collection. See NameBank.
ProtectedolfactoryPer-species smell capability — minimal acuity scalar.
null for species with no notable smell (a rock, a vacuum-borne
construct). v1 has no consumer of the value beyond shape; future
smell-propagation work draws on it.
Protectedreproductive'sexual', 'parthenogenetic', 'asexual',
'hermaphroditic-self', 'manufactured', 'spawned', 'none'.
v1 has no consumer; the field is authored for completeness so
future breeding/genetics work has data to draw on.
ProtectedsavedPer-prop marshaller bindings. Maps prop name → marshaller
templatePath. Persistent and arrives alongside savedProps
during hydration. setProp / getProp consult this map to
decide whether to invoke toStored / fromStored for a
given value. Props without a binding here round-trip raw, the
way scalar props always have.
Auto-initialized to an empty object; populated by
initProp(prop, { marshaller: '/path' }).
Protected OptionalsavedPersistent properties — STORED SHAPE. Host-internal storage;
setProp applies marshaller.toStored before writing here
when a marshaller is bound for the prop, and getProp
applies marshaller.fromStored on read so external callers
see the runtime type. The hydrator's bracket-assign deposits
the raw record directly without per-key conversion — the
marshaller binding lives on savedPropMarshallers and runs
lazily at access time.
Protectedsex'xy', 'zw', 'environmental', 'haplodiploid',
'hermaphroditic-simultaneous', 'hermaphroditic-sequential',
'dioecious', 'monoecious', 'none'. SexedMixin (Item 7)
looks up the valid sex set from this field.
ProtectedshortReadonlystuffRuntime ID for this object (generated using nanoid). This is NOT the MongoDB _id - it's a runtime identifier.
ProtectedtransientTransient properties (memory only, lost on restart).
ProtectedvisionPer-species vision capability for the perception subsystem.
null falls through to VisionModality's default. Flat 3-scalar record;
default JSON serialization handles it (no marshaller needed).
ProtectedvitalPer-species vital baselines + survivable bands (Vitals substrate).
null falls back to the engine universe-default biological
profile. Flat nested record; default JSON serialization handles it
(no marshaller, like visionProfile).
Static_StaticcommandVisible is target-shape only — no verb contributions. See the
mixin docstring for why look.yaml belongs on Perceiver's
self bucket, not on Visible's target-side buckets.
StaticmarkupMarkup-augmenter contribution. senseStripAugmenter reads the
per-call filter from AugmentOpts and the viewer's sensorium
(derived from BodyPlan.getModalities()), and drops
<sense channel="X">…</sense> regions and <detail sense="X">
wrappings whose channel isn't in filter ∩ sensorium.
Lives on VisibleMixin (not DetailedMixin) because <sense>
regions can appear in any Visible-mixed long, with or without
detail authoring. Ordering: VisibleMixin sits above Detailed
in the typical composition chain, so the parent-first walker
runs senseStripAugmenter BEFORE wrapDetailKeysAugmenter —
strip-then-wrap is correct because wrapping inside a region
destined for the strip is wasted work.
StaticpersistentStaticsubscribableLive-query subscribable fields. Each descriptor's
dependsOnFields defaults to [descriptor.name] (descriptor
name = source field name), so the FieldChangedEvent fires
from setShortDescription / setLongDescription trigger
re-projection automatically. The ShadowChangedEvent entries
cover future hood / disguise shadows that override visible
appearance without firing a field change.
ProtectedpropsHost-internal accessor; external callers go through getProps().
Consent seam for the residency (self-eviction) sweep. The sweep
asks each idle object whether it may be culled; the object decides,
reading its own knowledge. Default is cull ({ ok: true }) — a
fresh backing class is reclaimable by default and only becomes
sticky when its author deliberately vetoes, the correct bias for a
leak-plugger. Return { ok: false, reason } to veto.
Vetoes layer on the mixin/class that owns the relevant
relationship, composed via super.canEvict(context) — base Stuff
stays permissive and does not reach into Container/Shadow/Avatar/
Exit knowledge. The relational vetoes derive from the R2.x
ref-cleanup rules: an object in an owned/symmetric live-ref
relationship vetoes while its anchor is alive (see
docs/subsystems/residency.md).
Distinct from canDestruct: an object that permits eviction can
still canDestruct-veto, so the sweep's enforce path tolerates a
DestructError (logs + continues). The sweep calls this on the
raw target (via RAW_TARGET) so asking never counts as a touch.
Check if property exists AND the caller is allowed to see it.
Returns the prop's options when both are true, null otherwise.
Single answer to "does this prop exist and can I read it?":
the Get access op gates visibility, so a denied caller gets
the same null as for a non-existent prop. Lets EventApi.on
disambiguate "no such event / not allowed to subscribe" from
"exists and emitted-but-no-payload-yet" without sentinels.
Change property configuration.
Default access control. Override in subclasses to provide custom access control.
Default implementation allows all operations.
Destroy this object.
Locked down by @CallSecurity(ApiOnly) — only callers under
mud/api/ (in practice, StuffApi.destruct) may invoke it.
@Unshadowable because the unregistration path must always run;
a shadow that intercepts and skips it would leak the object into
the registry forever. @Final because subclass overrides would
defeat the same invariant — the loader hook throws
FinalViolationError at import time on any subclass redefinition.
Subclass cleanup belongs on the optional onDestruct() witness
(consulted by StuffApi.destruct while the target is still live);
refusal logic belongs on canDestruct(). This terminal destroy()
is the unshadowable mark-and-unregister step only.
The body-plan template path, without resolving the BodyPlan
instance. Useful for callers that key off the path directly
(e.g. Wearable.fitsSlot looking up slotClaims[bodyPlanPath])
— saves the path-resolution round-trip when the BodyPlan
Stuff itself isn't needed.
Material template path (no resolution) — mirrors getBodyPlanPath.
Read the recency timestamp. Read by the residency sweep — which
calls it on the raw target (via RAW_TARGET) so the sweep's own
introspection never counts as a touch.
Get the long description with fallback to short, then default.
Affordance-annotated long description — see the interface
docstring for the augmenter pipeline contract. Calls
Mml.augment with the host (this), the supplied viewer,
and the per-call opts (the senses build threads
opts.filter through here for verb-specific sense filtering).
Every contributing mixin's augmenters run in
parent-first → child-last order.
Optionalopts: AugmentOptsSelf-presentation — the casual-register render string for this object, the answer to "what does this Stuff call itself?" Three- step resolution:
Named.name if present and non-empty — the object's
proper name ("Alice", "Excalibur", "Town Square").Visible.shortDescription if present and non-empty —
the object's visual identity ("a heavy oak door").For a Globbable stack (quantity !== 1) the count folds in as
an affix — "30 coins" — pluralized via GrammarApi.pluralize
(which honors host-side getPluralForm() overrides for
irregulars). Named takes precedence over Visible so a
Named-with-description renders by its proper name; code that
needs the formal register calls getFullName() when typed as
Named.
Viewer-blind by design. This is the shared baseline every
Stuff exposes; the viewer-aware naming step (recognition /
identification — see
docs/subsystems/belief.md) composes on top
of it. Left shadowable (NOT @Final) so masking / disguise
effects can override the rendered identity via a method shadow.
Build the composable Mml fragment for this object's display name —
the Mml sibling of getPresentation. Mml.ref (and so every
<item> / <name> / … identity tag) renders this, not a raw
string, so a name joins the compose chain as a fragment like
everything else. The label is the already-resolved, viewer-aware
name (recognition runs in the render layer and hands it in).
Return null for the plain default — Mml.ref then wraps the label
in Mml.text, which escapes it exactly once, so player-authored
names / status decoration are safe by construction and the fragment
is never re-escaped downstream. Override to build a richer fragment
(a TPA terminal wraps its name in <color> to tint by state). The
plain-string getPresentation stays the surface for non-prose
consumers (logs, context.note, MQL scalars).
Get property value (with masks applied).
Lazily auto-initializes prop options when savedProps carries
a hydration-delivered entry but propOptions doesn't yet —
otherwise the value would be unreachable through the public API
(getProp returns null without a config). Auto-init uses
transient: false so the prop's persistence flag matches its
storage location.
Read-only view combining saved + transient properties. Saved
props are returned in their RUNTIME form — marshalled props
pass through marshaller.fromStored on the way out so callers
see Quantity instances and friends, not the raw stored shape.
Get the short description with fallback.
Read seam. Instance method, but unwraps via ProxyApi.unwrap
before reaching the # slot — this inside an instance method
called through the proxy is the proxy, and the # slot lives
on the raw target.
Get the spatial zone. Unwraps via RAW_TARGET because the
# slot lives on the raw target only and this inside an
instance method called through the proxy is the proxy.
Initialize a new property with options. Pass marshaller:
for props that hold rich value objects — the binding persists
alongside savedProps, so the same marshaller will run on
future loads of this host.
Optionaloptions: PropOptionsInput<T>Check if this object has been destroyed.
@Unshadowable: the destroyed-state read is a framework invariant —
any shadow that lied about it would let consumers touch a torn-down
Stuff. @Final: subclasses overriding this would defeat the same
invariant; the loader hook throws FinalViolationError at import
time on any subclass that redefines it.
R2.4 cleanup on the held side of Clade.species.
Species is a concrete leaf class, not a mixin (no
_mixinName), so the framework cleanupOnDestruct dispatch
— which walks MixinApi.queryMixins — wouldn't discover a
static here. Use the onDestruct witness instead, chaining
super.onDestruct() so SingletonMixin / PropertiedMixin
layers further up the chain still run.
TODO: production wire-up is pending. Clade.addSpecies is
called only by tests today; once Species template hydration
registers itself with its parent Clade, this handler is
automatically correct. Until then it's a no-op for
production but exercised by the OPEN-4 regression test.
Re-roll a fresh suggestion with no real-name bias (the player asked for another option, or it's an additional character).
Set property value (auto-initializes if doesn't exist).
If savedProps already carries an entry for this name (e.g.
delivered by hydration from a seed template), auto-init treats
the prop as transient: false so subsequent writes route back
to savedProps rather than landing in transientProps. Without
this branch, hydrated values would be silently shadowed by the
first set call.
Stamp this Stuff's templatePath and re-key the
byTemplatePath index so future findByTemplatePath lookups
see the new path. No-op when path matches the current value.
Locked down by @CallSecurity(ApiOnly) because flipping a
Stuff's identity post-clone would break FromTemplate
policies and any caller-side caching of template-path
identity. @Final @Unshadowable because the index update has
to run for every successful set — a subclass override that
forgot the index call (or a shadow that intercepted) would
silently desync byTemplatePath.
Unwraps via ProxyApi.unwrap so the #-slot access lands on
the raw target (see comment on #templatePath above).
Set the spatial zone. Gated by FromSpatialZone — only the
SpatialZone class and its subclasses (CartesianZone,
SphericalZone) may call this through the proxy. The
addLocation / removeLocation chokepoints on the zone side
are the legitimate callers; everyone else is rejected.
Clone-time seeding from StuffApi.#cloneInner doesn't go
through this method — it uses the caller-allowlisted
_stampZone seam below.
@Final @Unshadowable because the index of substrate
invariants that consult getZone() (containment's
cross-zone gate, Mobile.traverse, MQL scope walks) trusts
the slot's value; a subclass override or shadow that lied
about it could break those invariants. No legitimate
subclass needs to extend this anyway — the only legitimate
write paths are the SpatialZone chokepoints and clone-time.
Suggest a fantasy name for a new member of this species. Resolves
the species' nameBankKeys → the referenced NameBank
pools, then phonetically riffs on the player's real given name
(when provided) by preferring a bank given-name sharing its first
letter — so the suggestion feels personally theirs while reading as
the species. Surname is drawn from the bank pool. Always returns a
given name when the bank is non-empty, so intake is never blocked.
realName is the player's real (Google) given name; pass undefined
for additional characters (draws straight from the bank).
OptionalrealName: stringGet a string representation of this idea (for debugging). Subclasses should override to provide more specific information.
Refresh the recency timestamp to now. Timestamp-fixed (no caller-supplied value). Called on the raw target by the security gate on every successful dispatch (Phase 2) and by the residency presence walk.
Constructor - calls parent Stuff constructor.