Process & Registry

Shared Ameleons Companion contract

This document records the parts of the Ameleons/Companion model that are genuinely cross-product Family rules. Product-specific gameplay, UI and persistence still belong in the owning repo.

Canonical ownership

Amoleo Ameleons owns:

• stable identity for each owned Ameleon;
• species/form/variant taxonomy;
• collection ownership and acquisition provenance;
• user-visible naming where supported;
• appearance/customisation state;
• cosmetic entitlements and equipped cosmetics;
• the user's currently selected Companion;
• visibility/public-sharing state;
• canonical render/runtime metadata and generated renditions.

A consuming product must not copy these fields into its own database as a second authority.

A game or consuming product owns only its own domain state. Leomaly, for example, may own world/story/progression/encounter/quest/battle/currency state, but an Ameleon acquired there remains the same canonical individual owned by the Ameleons platform.

Companion semantics

A Companion is a role held by an Ameleon: the user's currently selected canonical creature. It is not a separate mascot entity owned by Todo, Health or another consumer.

Consumers read Companion state through a versioned Ameleons contract. They may cache only what is necessary for presentation/performance and must treat Ameleons as authoritative when the two disagree.

Rendering contract

Canonical Ameleons start from extremely low-poly, silhouette-first 3D assets. The same canonical appearance may be projected into lighter renditions for consumers that cannot or should not render the original asset directly, including:

• deliberate low-resolution/pixel treatments;
• tiny 2D sprites;
• Game Boy-like renditions;
• simplified rider/follower views such as Amoleo Health.

Generated renditions are presentations of the same Ameleon, not new independently editable creature records.

Availability and coupling

Consuming products must degrade gracefully when Ameleons is unavailable. A failure to fetch Companion/collection data must not make an otherwise unrelated product unusable.

Contracts between Ameleons and consumers must be versioned. Consumers depend on deliberate API/render-manifest capabilities, never direct database access.

Milestones boundary

Amoleo Milestones owns accomplishment definitions/history and the fact that a Milestone was unlocked. Ameleons owns any creature or cosmetic entitlement granted as a result.

A source product may report a Milestone unlock; the corresponding reward flow may then grant an entitlement through Ameleons. Neither service should duplicate the other's canonical ledger.

Known consumers

• Leomaly — the first Ameleons game; acquires/uses canonical Ameleons while keeping Leomaly-specific game state.
• Todo — restrained Companion presence and selected Todo-Milestone cosmetic rewards.
• Health — renders the active Ameleon as a rider/follower using an appropriate generated rendition and may consume body-archetype capabilities.
• Pets — may provide a future read-only public catalogue/profile presentation at ameleons.pets.amoleo.com; Pets owns presentation, not the taxonomy or collection data.

Product-listing boundary

Registration in Family tooling does not itself promote Ameleons or Leomaly into the enforced footer. tools/lockup.json.pendingApps records future/public candidates without making them a hard requirement. Promotion remains a separate editorial decision.

Leomaly is an Amoleo Games title, so its eventual treatment on family-wide product lists may differ from a conventional utility product even though its repo participates in shared Family rules.

Generated from docs/family-companion.md. Edit there and re-run npm run build in docs-site-src/ — never hand-edit a page.