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
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.

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.