name	ptcg-limitless-importer
description	Use when importing or validating English Limitless TCG cards or deck URLs in this Godot PTCG repo, including mixed Chinese/English deck mapping, LEN_* generated cards, bundled deck data, card effect implementation, AI strategy wiring, and headless duel regression tests.

PTCG Limitless Importer

Workflow

Identify the source.
- Limitless deck URLs look like https://limitlesstcg.com/decks/list/<id>.
- Limitless card URLs look like https://limitlesstcg.com/cards/<SET>/<number>.
- Local deck IDs use 800000000 + limitless_id. Example: deck 18921 becomes 800018921.
Parse through the repo adapter.
- Use scripts/network/LimitlessCardParser.gd for HTML parsing.
- Use scripts/network/LimitlessCardResolver.gd for local mapping.
- Use scripts/network/LimitlessCardTranslation.gd for generated-card Chinese detail text. Keep rule-facing name / text values in abilities and attacks as the original English strings, and add display-only name_zh / text_zh fields so effect registration and AI strategy matching keep working.
- Preserve source_provider, source_url, source_set_code, source_card_index, source_language, source_prints, source_imported_at, and source_parser_version.
- Image URLs should use CardData.build_limitless_image_url() and local cache paths under user://cards/images/<set_code>/<card_index>.png.
Resolve cards conservatively.
- Prefer exact English print metadata and same-print-group local implementations.
- Map Basic Energy to canonical local energy cards.
- Generate missing English cards as LEN_<SET>_<number> only when no unambiguous implemented local card exists.
- Fail closed on ambiguous non-energy prints instead of guessing.
Bundle data.
- Card JSON files go in data/bundled_user/cards/.
- Generated Limitless card images go in data/bundled_user/cards/images/<set_code>/<card_index>.png.bin.
- Deck JSON files go in data/bundled_user/decks/.
- Add every new card JSON, bundled image, and deck JSON to data/bundled_user/_manifest.txt.
- Built-in AI decks do not necessarily run the import-time image downloader, so bundled LEN_* cards must ship with images or they will render blank for fresh installs.
- For translated generated cards, bundled card JSON should store the English rule-facing name, Chinese display-only name_zh, Chinese description, and name_en as the Limitless English identity. Preserve English attack/ability name fields plus display-only Chinese name_zh / text_zh.
- If the deck should appear as a built-in AI opponent, add the deck ID to CardDatabase.SUPPORTED_AI_DECK_IDS.
Implement effects before declaring a card supported.
- Register trainer, stadium, tool, and special energy effects in scripts/engine/EffectRegistry.gd.
- Pokemon abilities and attacks may be routed by English names in _get_ability_effect() / _get_attack_effects() when the generated card has a stable Limitless effect_id.
- Add new effect scripts under scripts/effects/....
- Verify with CardImplementationStatus.is_unimplemented(card) == false for every generated non-vanilla key card.
Wire AI decks when needed.
- Add a strategy under scripts/ai/DeckStrategy*.gd when the deck has a distinct plan.
- Register it in scripts/ai/DeckStrategyRegistry.gd by strategy ID and deck ID.
- Score Dictionary interaction options explicitly; many headless prompts pass assignment or copied-attack dictionaries instead of raw cards or slots.

Tests

Run focused tests first:

D:\ai\godot\Godot_v4.6.1-stable_win64_console.exe --headless --path . -s tests/FocusedSuiteRunner.gd -- --suite-script=res://tests/test_limitless_importer.gd
D:\ai\godot\Godot_v4.6.1-stable_win64_console.exe --headless --path . -s tests/FocusedSuiteRunner.gd -- --suite-script=res://tests/test_limitless_ns_zoroark_effects.gd
D:\ai\godot\Godot_v4.6.1-stable_win64_console.exe --headless --path . -s tests/FocusedSuiteRunner.gd -- --suite-script=res://tests/test_limitless_ns_zoroark_deck.gd

For bundled generated cards, tests should prove the image path is in _manifest.txt, the .png.bin file is a valid image, Godot can decode it, and CardData.resolve_existing_image_path() falls back to the bundled image when user:// cache is missing.

For translated generated cards, tests should prove:

resolver-generated cards receive Chinese name_zh / description while preserving English name and name_en;
attack and ability English name / text fields remain unchanged for rule logic;
UI helpers such as CardData.dictionary_display_name() and CardData.dictionary_display_text() prefer name_zh / text_zh;
deck entries display the translated generated card names while retaining source_name for Limitless audit metadata.

For headless stall reports, add or run an action-cap probe against the reported matchup and seed when available. A useful baseline is Limitless deck 800018921 versus rule Charizard 575716.

Run full validation before finishing user-facing work:

D:\ai\godot\Godot_v4.6.1-stable_win64_console.exe --headless --path . -s tests/FunctionalTestRunner.gd

Failure Checklist

Deck imports 60 cards but build_deck_instances() returns fewer: missing card JSON, bad manifest entry, or stale user cache.
Built-in Limitless cards render blank: missing bundled data/bundled_user/cards/images/<set_code>/<card_index>.png.bin, missing image manifest entry, invalid image bytes, or a stale card JSON image path.
Card is visible but marked unimplemented: missing effect_id, registry entry, Pokemon ability route, or attack effect route.
Headless duel hits unsupported_interaction_step: the effect exposes an interaction shape not handled by AILegalActionBuilder, AIStepResolver, or the deck strategy.
Headless duel hits action_cap_reached: inspect decision trace tail for repeated no-progress actions, repeated prompts, dead active Pokemon, or strategy scores that prefer non-terminal loops.
Limitless English names render incorrectly: keep generated JSON and GDScript source UTF-8, normalize curly apostrophes with char(0x2019) / char(0x2018) instead of embedding mojibake.
Translated Limitless card stops matching an effect or AI rule: verify only display fields were translated. effect_id, attack name, ability name, evolves_from, and name_en should keep the rule-facing English identity unless the local rule explicitly supports Chinese aliases.

PTCG Limitless Importer

Workflow

Identify the source.

Limitless deck URLs look like https://limitlesstcg.com/decks/list/<id>.
Limitless card URLs look like https://limitlesstcg.com/cards/<SET>/<number>.
Local deck IDs use 800000000 + limitless_id. Example: deck 18921 becomes 800018921.

Parse through the repo adapter.

Use scripts/network/LimitlessCardParser.gd for HTML parsing.
Use scripts/network/LimitlessCardResolver.gd for local mapping.
Use scripts/network/LimitlessCardTranslation.gd for generated-card Chinese detail text. Keep rule-facing name / text values in abilities and attacks as the original English strings, and add display-only name_zh / text_zh fields so effect registration and AI strategy matching keep working.
Preserve source_provider, source_url, source_set_code, source_card_index, source_language, source_prints, source_imported_at, and source_parser_version.
Image URLs should use CardData.build_limitless_image_url() and local cache paths under user://cards/images/<set_code>/<card_index>.png.

Resolve cards conservatively.

Prefer exact English print metadata and same-print-group local implementations.
Map Basic Energy to canonical local energy cards.
Generate missing English cards as LEN_<SET>_<number> only when no unambiguous implemented local card exists.
Fail closed on ambiguous non-energy prints instead of guessing.

Bundle data.

Card JSON files go in data/bundled_user/cards/.
Generated Limitless card images go in data/bundled_user/cards/images/<set_code>/<card_index>.png.bin.
Deck JSON files go in data/bundled_user/decks/.
Add every new card JSON, bundled image, and deck JSON to data/bundled_user/_manifest.txt.
Built-in AI decks do not necessarily run the import-time image downloader, so bundled LEN_* cards must ship with images or they will render blank for fresh installs.
For translated generated cards, bundled card JSON should store the English rule-facing name, Chinese display-only name_zh, Chinese description, and name_en as the Limitless English identity. Preserve English attack/ability name fields plus display-only Chinese name_zh / text_zh.
If the deck should appear as a built-in AI opponent, add the deck ID to CardDatabase.SUPPORTED_AI_DECK_IDS.

Implement effects before declaring a card supported.

Register trainer, stadium, tool, and special energy effects in scripts/engine/EffectRegistry.gd.
Pokemon abilities and attacks may be routed by English names in _get_ability_effect() / _get_attack_effects() when the generated card has a stable Limitless effect_id.
Add new effect scripts under scripts/effects/....
Verify with CardImplementationStatus.is_unimplemented(card) == false for every generated non-vanilla key card.

Wire AI decks when needed.

Add a strategy under scripts/ai/DeckStrategy*.gd when the deck has a distinct plan.
Register it in scripts/ai/DeckStrategyRegistry.gd by strategy ID and deck ID.
Score Dictionary interaction options explicitly; many headless prompts pass assignment or copied-attack dictionaries instead of raw cards or slots.

Tests

Run focused tests first:

D:\ai\godot\Godot_v4.6.1-stable_win64_console.exe --headless --path . -s tests/FocusedSuiteRunner.gd -- --suite-script=res://tests/test_limitless_importer.gd D:\ai\godot\Godot_v4.6.1-stable_win64_console.exe --headless --path . -s tests/FocusedSuiteRunner.gd -- --suite-script=res://tests/test_limitless_ns_zoroark_effects.gd D:\ai\godot\Godot_v4.6.1-stable_win64_console.exe --headless --path . -s tests/FocusedSuiteRunner.gd -- --suite-script=res://tests/test_limitless_ns_zoroark_deck.gd

For translated generated cards, tests should prove:

resolver-generated cards receive Chinese name_zh / description while preserving English name and name_en;

attack and ability English name / text fields remain unchanged for rule logic;

UI helpers such as CardData.dictionary_display_name() and CardData.dictionary_display_text() prefer name_zh / text_zh;

deck entries display the translated generated card names while retaining source_name for Limitless audit metadata.

For headless stall reports, add or run an action-cap probe against the reported matchup and seed when available. A useful baseline is Limitless deck 800018921 versus rule Charizard 575716.

Run full validation before finishing user-facing work:

D:\ai\godot\Godot_v4.6.1-stable_win64_console.exe --headless --path . -s tests/FunctionalTestRunner.gd

Failure Checklist

Deck imports 60 cards but build_deck_instances() returns fewer: missing card JSON, bad manifest entry, or stale user cache.

Built-in Limitless cards render blank: missing bundled data/bundled_user/cards/images/<set_code>/<card_index>.png.bin, missing image manifest entry, invalid image bytes, or a stale card JSON image path.

Card is visible but marked unimplemented: missing effect_id, registry entry, Pokemon ability route, or attack effect route.

Headless duel hits unsupported_interaction_step: the effect exposes an interaction shape not handled by AILegalActionBuilder, AIStepResolver, or the deck strategy.

Headless duel hits action_cap_reached: inspect decision trace tail for repeated no-progress actions, repeated prompts, dead active Pokemon, or strategy scores that prefer non-terminal loops.

Limitless English names render incorrectly: keep generated JSON and GDScript source UTF-8, normalize curly apostrophes with char(0x2019) / char(0x2018) instead of embedding mojibake.

Translated Limitless card stops matching an effect or AI rule: verify only display fields were translated. effect_id, attack name, ability name, evolves_from, and name_en should keep the rule-facing English identity unless the local rule explicitly supports Chinese aliases.

ptcg-limitless-importer