Component API Overview

Component API Overview

English | 简体中文

Component API v3 separates the responsibilities that were previously coupled inside card generation:

Layer	Main types	Owner
Generation	ComponentGenerationProfile, IComponentCatalog	Describes card shells, component inventory, names, and policies
Balance	IComponentOccurrencePolicy, IComponentValuePolicy, IComponentValuation	Selects effects, samples values, and prices finalized effects
Runtime	ComponentRuntimeApi, IComponentRuntimeHandler	Executes custom structured opcodes
Presentation	ComponentPresentationApi, IComponentHoverTipProvider	Adds tips for custom references and named mechanics
Keywords	ComponentKeywordRuntimeApi, IComponentKeywordRuntimeAdapter	Projects stable custom keyword IDs into game cards and tips
Character host	ExternalComponentCharacterApi, ExternalChaosCardModel	Connects fixed card models to run-scoped generated definitions
Host services	ComponentRunSettingsApi, ComponentGenerationProgressApi, ComponentTriggerApi, ComponentSurpriseApi	Reuses settings, progress, trigger, and concealment behavior without reflection
Card editing	CardTinkeringApi, AutoAnthonySettingsApi	Evaluates/rebuilds structured cards and exposes opt-in editor settings
Naming	CardNameGenerator.RegisterExternalParts	Registers reviewed same-character bilingual name morphology

Design rules

• Runtime semantics use lowercase ASCII IDs and OperationRuntimeSpec; localized prose is output only.
• Named localization templates bind directly to RuntimeSpec value/text slots instead of matching rendered numbers or words.
• Occurrence probability and numeric/effect value are independent.
• Registration happens during mod initialization and freezes before generation or execution begins.
• A profile ID is the external identity. Its GeneratedCharacter is only the closest built-in balance and legality archetype.
• The character mod continues to own its CharacterModel, CardPoolModel, card classes, run lifecycle, portraits, rarity counts, and authoritative save/multiplayer synchronization.

Assemblies and namespaces

Reference AutoAnthony.dll plus the normal STS2/Godot assemblies.

• Generator contracts live in ChaosCardGenerator.
• Runtime, presentation, and external-card contracts live in AutoAnthony.

Check the versions before registering:

if (ComponentApi.ApiVersion != 3 || ComponentPackageApi.ApiVersion != 3
    || ComponentRuntimeApi.ApiVersion != 1 || ExternalComponentCharacterApi.ApiVersion != 3)
    throw new NotSupportedException("Unsupported AutoAnthony Component API version.");

This is the minimum guard for the core integration path. Check every additional surface your adapter calls and see the complete API Changelog version matrix. The services introduced in 0.3.32 also require that mod version even though the top-level ComponentApi was already v3.

Card editors should additionally require CardTinkeringApi.ApiVersion == 3; integrations using the read-only editor preference should require AutoAnthonySettingsApi.ApiVersion == 1 and AutoAnthony 0.3.42 or newer.

Lifecycle

Register in this order during your mod initializer:

1. ComponentPackageApi.Register(...)
2. Optional: CardNameGenerator.RegisterExternalParts(...)
3. ComponentRuntimeApi.RegisterPackage(...) for custom opcodes
4. ComponentPresentationApi.RegisterPackage(...) for optional hover tips
5. ComponentKeywordRuntimeApi.RegisterPackage(...) for custom keyword projection
6. ExternalComponentCharacterApi.Register(...)
7. Optional: ExternalComponentCharacterApi.RegisterRuntime(...)

At new-run or restore time, create complete ChaosCardDefinition records and call ExternalComponentCharacterApi.InstallDefinitions(profileId, definitions). On run cleanup, call ClearDefinitions(profileId).

Continue with Authoring a Component Package.

Composition identity

RuntimeSpec schema identity—not localized text—is authoritative. Semantically identical immediate effects use one shared component even when their native sources belong to different characters. Ordinary delayed clauses compose a trigger such as C:NextTurnStart or C:NextTurnsStart with the same payoff used immediately; only trigger cadence changes valuation.

Keep an operation atomic when it must capture a selected card, target, current value, or future choice before the delayed event. Target-Vulnerable-to-Strength is also intentionally atomic because high Vulnerable stacks give diminishing practical Strength value. Targeted Poison uses the same T:Poison component on a selected target or below a compatible enemy-event trigger.

Character-prefixed legacy aliases remain readable for supported snapshots but are not valid IDs for new reviewed catalogs. See Authoring a Component Package for trigger ownership rules.