Card Tinkering and Settings API

Card Tinkering and Settings API

English | 简体中文

This page is for companion mods that inspect or rearrange AutoAnthony cards. It documents the public bridge only; an editor remains responsible for its own UI, persistence, undo behavior, and multiplayer transport.

Requires AutoAnthony 0.3.42 or newer:

if (CardTinkeringApi.ApiVersion != 3 || AutoAnthonySettingsApi.ApiVersion != 1)
    throw new NotSupportedException("Unsupported AutoAnthony card-editing API.");

Rules

• Work with GeneratedCard, GeneratorOperation, and OperationRuntimeSpec; never parse a rendered description.
• Treat RuntimeSpec schema identity as the component identity. Template text is authoring/compatibility metadata.
• Use numeric-balanced mode unless the user explicitly edits an aggressive-mode card.
• Validate the complete proposed operation list before rebuilding or installing it.
• Synchronize the serialized result from one authority in multiplayer. Do not let peers rebuild independently.

Read the user's preference

if (!AutoAnthonySettingsApi.Enabled || !AutoAnthonySettingsApi.AnytimeCardEditing)
    return;

The settings API is read-only. It exposes only the master switch and the opt-in preference for editing outside combat; it cannot change settings or expose next-run-only choices.

Inspect value

CardTinkeringBudgetBreakdown budget = CardTinkeringApi.EvaluateBudget(card);

// This is the same production comparison used by balanced generation.
bool aboveEnvelope = budget.NetValue > budget.OrdinaryUpperBound;

The native value currency is one hundredth of one point of ordinary single-target damage. The exact terms are:

• PositiveValue: sum of positive finalized effects after trigger composition.
• LinearCompensation: additive downside value deducted from the positive side.
• DownsideMultiplier: multiplicative capacity granted by strong downside rules; never below 1.
• NetValue: (PositiveValue - LinearCompensation) / DownsideMultiplier.
• OrdinaryUpperBound: the shell's production upper bound for cost, rarity, type, fields, and mode.

Evaluate(card) is a compact display-oriented summary. EvaluateComponent(operation) deliberately prices the component without a discount inherited from its old trigger: a moved payoff must earn its discount from its new trigger chain.

Validate and rebuild

IReadOnlyList<GeneratorOperation> proposed = BuildProposedOperations();
CardTinkeringValidationResult validation = CardTinkeringApi.Validate(card, proposed);

if (!validation.IsValid)
{
    ShowErrors(validation.Errors);
    return;
}

GeneratedCard rebuilt = CardTinkeringApi.Rebuild(card, proposed, proposedUpgradeEffects);

Validation covers trigger ownership/order, target availability, X-resource compatibility, Power-only operations, self-card movement, Grand Finale/return-to-hand costs, numeric self-cost reduction, and common assembly exclusions. Do not repair an invalid result at runtime; keep the original card or ask the user to change the composition.

Rebuild retains shell-level upgrade effects, applies the supplied operation upgrades, and renders Chinese and English descriptions from structured localization. It does not mutate the input card.

Persist or synchronize an edited card

string payload = CardTinkeringApi.SerializeCard(rebuilt);

// Store or transmit payload as an opaque versioned string.
GeneratedCard restored = CardTinkeringApi.DeserializeCard(payload);

The payload preserves RuntimeSpecs, localization metadata, and upgrade value-slot IDs. Its schema is independent of the API version. Treat it as opaque: use the API to deserialize it and reject unsupported schemas instead of editing the JSON by hand.

In multiplayer, one peer must own the edit. Send that serialized payload to every client and install the same ordered result. AutoAnthony validates and reconstructs the card but does not provide the editor's network message or save field.

Trigger and atomic-component guidance

An ordinary delayed or event-driven operation should be a trigger plus the same reusable payoff used immediately. For example, targeted Poison is always T:Poison; a compatible enemy-event trigger supplies the event target.

Keep an operation atomic if it must capture a selected card, target, current value, or future choice before firing. Target-Vulnerable-to-Strength also remains atomic because the practical value of Strength diminishes at very high Vulnerable stacks. Moving only half of such an operation is invalid even if the localized sentence appears grammatically separable.

Continue with API Reference for the complete surface and API Changelog before changing an existing integration.