Skip to content

AGENTS.md

Latest commit

 

History

History
36 lines (31 loc) · 3.57 KB

AGENTS.md

File metadata and controls

36 lines (31 loc) · 3.57 KB

TCGEngine Instructions

Read .github/copilot-instructions.md before making substantive engine changes. It is the detailed source of truth for this repository's engine workflow, generator behavior, Decision Queue patterns, and card-implementation rules.

Use this file as the compact default guidance:

  • Prefer the tcgengine-card-editor MCP workflow for card work. Standard sequence:
    • get_card_info
    • get_zone_schema
    • get_helper_functions
    • get_implemented_examples
    • save_card_abilities
  • Treat .github/copilot-instructions.md as canonical for await/codegen constraints. In particular:
    • Do not put await inside conditionals or loops.
    • Do not rely on pre-await locals after an await; recompute what you need.
    • Precompute chooser strings before await $player.MZChoose(...) / similar calls.
  • Do not manually edit generated files such as <RootName>/GeneratedCode/GeneratedMacroCode.php, GeneratedMacroCount.js, or generated GeneratedUI_*.js outputs unless the task is specifically about the generator.
  • For card implementations, prefer the MCP card editor workflow: inspect card info, inspect schema/helpers/examples, save abilities through MCP, and let the generator update derived macro code.
  • Add new non-generated helper logic under <RootName>/Custom/ in the most appropriate file instead of patching generated code.
  • Prefer built-in macro prereqs/restrictions before adding manual activation guards in GameLogic.php. If a restriction is card-local and expressible as a generated prereq, implement it in the macro/prereq layer so selection, UI, and legality checks stay aligned.
  • Prefer schema/generator-backed numerical modifier macros for scalar cost adjustments. In Grand Archive this includes MemoryCostModifier, ReserveCostModifier, PlayCostModifier, and ActivationCostModifier; use the modifier framework before adding one-off cost math to manual switchboards.
  • When working in Grand Archive, use established helpers and effective runtime wrappers such as EffectiveCardType, EffectiveCardSubtypes, EffectiveCardClasses, and EffectiveCardElement rather than raw card-dictionary lookups on field objects.
  • For per-turn single-card stat changes, use AddTurnEffect(...) plus the corresponding ObjectCurrentPower, ObjectCurrentHP, or ObjectCurrentLevel switch case in GameLogic.php.
  • For persistent field-object overrides, use ApplyPersistentOverride(...); for temporary suppression, use AddTurnEffect($mzCard, 'NO_ABILITIES').
  • Field-presence passives belong in ObjectCurrentPower, ObjectCurrentHP, or ObjectCurrentLevel, using the established passive-deduping pattern.
  • Keep Decision Queue custom handlers short, non-interactive, and tolerant of malformed parameters. Interactive flows should use the supported decision types and established await patterns described in .github/copilot-instructions.md.
  • Register game-specific custom Decision Queue handlers and additional activation costs in <RootName>/Custom/GameLogic.php, not in generated code.
  • Use the appropriate custom file for new helpers:
    • combat helpers -> CombatLogic.php
    • materialize helpers -> MaterializeLogic.php
    • general runtime/game helpers -> GameLogic.php
  • If you change schema or generator behavior, regenerate outputs and account for the timestamped GeneratedUI_*.js file behavior noted in .github/copilot-instructions.md.

Priority note:

  • If this file and .github/copilot-instructions.md ever conflict, follow the more specific rule for the files you are editing and prefer the detailed engine guidance in .github/copilot-instructions.md.