API Reference

API Reference

English | 简体中文

Generator namespace: ChaosCardGenerator

ComponentProfileRequest

Identifies one generation profile with ProfileId, balance Character, and UnlockComponentRoles. Use stable ASCII profile IDs. The two-argument constructor is for built-in profiles.

ComponentGenerationProfile

Contains ShellCatalog, ComponentCatalog, NameCatalog, an occurrence-policy factory, and an IComponentValuePolicy. CreateOccurrencePolicy() must return fresh pool-scoped state. Its optional ComponentKeywordPolicy independently controls native/custom base-keyword and upgrade availability.

ComponentPackageApi

Register(ComponentPackageRegistration) atomically preflights and installs profile, stable named localization, keyword definitions/upgrades, multiplicity, and custom valuation metadata. Register before the first ComponentApi.Resolve. Duplicate package IDs are rejected without leaving partial registry state. IncludeInUltimateChaos defaults to true and contributes the complete normal source catalog to the weighted union.

ComponentApi.ComposeCatalog combines complete source catalogs without losing occurrence weighting. An external normal profile can be resolved with UnlockComponentRoles=true without registering a duplicate Ultimate profile.

ImmutableComponentCatalog

Builds all structural indexes from reviewed IroncladCardRecipe values. The historical type name is retained for binary/source compatibility; it is valid for any balance archetype.

ComponentSemanticFlags

Stable flags for cross-cutting assembly facts: Beneficial, Negative, Restricted, EnemyDamage, PowerFoundation, ScalableReward, and SelfCardMovement. Targets, zones, values, triggers, conditions, execution, and valuation stay in their dedicated RuntimeSpec/route fields.

ComponentLocalizationRegistration

Registers Chinese/English templates by component SemanticId. Named placeholders bind to RuntimeSpec value slots ([[damage]], [[hits]], [[energy:energy]], [[stars:stars]]) or registered text slots ([[token]]). Generated operations persist the small localization ID, not the compiled template. The older ComponentLocalizedText exact sentence registry remains an API v2 compatibility surface only.

ComponentKeywordApi

Registers stable ASCII custom keyword IDs and optional deterministic IComponentKeywordRule legality. Recipe and upgrade records carry those IDs without extending the game's closed enums. A custom keyword is presentation and classification metadata, not a hidden gameplay effect; its effect still needs structured runtime and valuation routes.

IComponentOccurrencePolicy

• SourcePriorWeight: native/source family prior.
• SelectionWeight: closed-loop correction after accepted cards.
• VariantWeight: choice within a family.
• Observe: receives finalized cards only, never failed attempts.

Use ComponentApi.CreateNativeOccurrencePolicy(catalog) unless the character needs a custom distribution.

IComponentValuePolicy

Controls numeric scalability, native-value preservation, sampling, clamping, value bonuses, and trigger payoff scaling. Use ComponentApi.DefaultValuePolicy unless you need a fully custom numeric model.

IComponentValuation

Returns finalized effect value in hundredths of one point of single-target damage. Exact opcode/variant routes win over opcode-wide routes.

ComponentValuationRegistration also supports one downside mode:

• NegativeLinearValuePerUnit > 0: linear compensation per unit; or
• NegativeMultiplier > 1: whole-card multiplicative downside compensation.

Do not set both.

ComponentMultiplicity

• Repeatable: ordinary component.
• SinglePerCard: at most once on one generated card.
• UniquePerPool: at most once in the generated pool.

Register with ComponentMultiplicityRegistration. Pool uniqueness is consumed only by accepted finalized cards.

Runtime namespace: AutoAnthony

ComponentRuntimeApi

• Register(opcode, variant, handler) registers one route.
• RegisterPackage(packageId, routes) validates and commits a route set.
• HasRoute and RegisteredRoutes support startup audits.
• Registration freezes when the first generated operation executes.

ComponentPresentationApi

RegisterPackage atomically registers optional IComponentHoverTipProvider routes. Registration freezes on first generated hover-tip render.

ComponentKeywordRuntimeApi

RegisterPackage maps generator keyword IDs to IComponentKeywordRuntimeAdapter instances. An adapter can expose native CardKeyword values, semantic tags, hover tips, and an upgrade callback. Registration freezes on the first generated-card keyword query.

ExternalComponentCharacterApi

• Register declares profile identity, archetype, and energy-icon prefix.
• RegisterRuntime optionally declares the fixed slot type table, run-active predicate, and generated card pool. With it, persistent Powers reconstruct external cards without patching the private executor, and vanilla cross-pool events discover the active external pool.
• An optional IExternalAncientRelicAdapter supplies Archaic Tooth and Dusty Tome behavior without a hard-coded character ID.
• InstallDefinitions replaces one profile's complete run-scoped definition list.
• GetDefinitions returns the installed immutable list.
• ClearDefinitions removes run-scoped definitions.

Character registration freezes when definitions are first installed or read.

External integration services

• ComponentRunSettingsApi returns immutable local settings or resolves the host-authored multiplayer carrier, including preserve-original and random-art options.
• ComponentGenerationProgressApi exposes the standard pool-generation/loading overlay.
• ComponentTriggerApi dispatches custom player/card triggers through normal recursion guards, X snapshots, dependency resolution, and selection cleanup. It also exposes effective operation amounts.
• ComponentSurpriseApi exposes generated-card, known-card, and concealment queries without UI reflection.
• CardNameGenerator.RegisterExternalParts atomically registers reviewed bilingual name morphology without reflecting into the built-in name dictionary.

Deliberate boundaries

Native execution still contains compatibility branches for built-in templates; custom namespaced opcodes use the generic runtime registry. The game's keyword enums remain closed, so API v3 stores custom identity as ASCII IDs and projects it through runtime adapters instead of manufacturing enum members. The owning mod still supplies its save field, host-authoritative definition synchronization, concrete card classes/art, custom token/orb/status resolution, and any novel card lifecycle hook.

ExternalChaosCardModel

Base class for concrete fixed-slot card models. Override ComponentProfileId, Slot, and Pool; generated text, upgrades, trigger dispatch, and operation execution are inherited.

Validation and failure behavior

Registration throws immediately for non-ASCII IDs, duplicate routes, missing RuntimeSpecs or named localization, unknown keyword IDs, duplicate semantic IDs, invalid trigger owners, empty catalogs, or a catalog whose character differs from its profile archetype. Package registries preflight before mutation; treat failures as initialization errors and retry only after fixing the complete registration.