This commit is contained in:
2026-10-29 15:21:05 +01:00
parent bb85881cac
commit bc05b63083
36 changed files with 4654 additions and 5080 deletions

View File

@@ -0,0 +1,227 @@
<template>
<section class="source-guide">
<header class="guide-head">
<h2>Card source guide</h2>
<p class="muted">
Implementations are a small, literal JavaScript expression that the backend evaluates with
its own safe interpreter. It is never run as JavaScript: only the names below exist. The
editor and the compiler use the same two-way format. Use <strong>Draft with AI</strong> for
a first pass, then review and save.
</p>
</header>
<article>
<h3>Shape</h3>
<p>
Export the card's type line and an array of abilities with
<code>card(typeLine, [...])</code>. A leading <code>// Card [status]</code> comment is
optional and ignored. Multi-face cards export
<code>faces(face('Name', 'Type line', [...]), ...)</code> in card order.
</p>
<pre>export default card('Creature — Human Cleric', [
keywords('Flying', 'Ward {2}'),
triggered(when.enters(each(permanents.other().withType('creature'))), [
gainLife(you, 1),
]),
activated([tapCost()], [
addMana(you, mana('{G}')),
]),
])
export default faces(
face('Front', 'Instant', [spell([draw(you, 2)])]),
face('Back', 'Creature — Human', [keyword('Flying')]),
)</pre>
<p class="muted">
Plain <code>export default [...]</code> is still accepted and uses the Scryfall type line.
Effect lists also accept callbacks: <code>() =&gt; draw(you, 1)</code> for one effect,
or <code>() =&gt; { draw(you, 1); gainLife(you, 1) }</code> for several. Arrays remain
valid; the formatter emits callbacks.
</p>
</article>
<article>
<h3>Abilities</h3>
<table>
<thead>
<tr><th>Call</th><th>Example</th></tr>
</thead>
<tbody>
<tr><td><code>triggered(event, [effects], options)</code></td><td><code>triggered(when.dies(self), [draw(you, 1)])</code></td></tr>
<tr><td><code>activated([costs], [effects], options)</code></td><td><code>activated([manaCost('{2}'), tapCost()], [...])</code></td></tr>
<tr><td><code>staticAbility([effects], options)</code></td><td><code>staticAbility([staticPump(each(creatures.youControl()), 1, 1)])</code></td></tr>
<tr><td><code>spell([effects], options)</code></td><td>An instant or sorcery.</td></tr>
<tr><td><code>keyword(name, value)</code></td><td><code>keyword('Ward', '{2}')</code></td></tr>
<tr><td><code>keywords(...names)</code></td><td><code>keywords('Flying', 'Trample')</code></td></tr>
<tr><td><code>additionalCost([costs])</code></td><td><code>additionalCost([payLife(2)])</code></td></tr>
<tr><td><code>chapter(['I', 'II'], [effects])</code></td><td>Saga chapters.</td></tr>
<tr><td><code>unsupported(reason, text)</code></td><td>Preserve the oracle text when it cannot be expressed.</td></tr>
</tbody>
</table>
<p class="muted">
Options include <code>{ condition, optional }</code>; activated abilities also accept
<code>timing: 'sorcery'</code> and <code>activationsPerTurn</code>.
</p>
</article>
<article>
<h3>Selectors and targets</h3>
<p>
Start from <code>permanents</code>, <code>cards</code> or <code>creatures</code> and chain
filters: <code>withType</code>, <code>withSubtype</code>, <code>withSupertype</code>,
<code>withColor</code>, <code>withKeyword</code>, <code>youControl</code>,
<code>other</code>, <code>tapped</code>, <code>token</code>, <code>powerAtLeast</code>,
<code>manaValueAtMost</code>, <code>named</code>, <code>inZone</code>.
</p>
<pre>target(permanents.withType('creature').other().youControl())
each(creatures.withColor('red').withKeyword('flying'))
pick(cards.withType('land'), { upTo: 2 })
targetSpell(permanents.withType('instant'))
divided(3, creatures.attacking())
self, triggerSubject, previousTarget, anyTarget, targetPlayerOrPlaneswalker</pre>
<p class="muted">
Values: numbers, <code>X</code>, <code>itsPower</code>, <code>itsToughness</code>,
<code>count(selector)</code>, <code>cardsInHand(you)</code>,
<code>totalPower(selector)</code>, <code>eventAmount()</code>.
</p>
</article>
<article>
<h3>Effects and costs</h3>
<pre>damage(target(creature), 3)
draw(you, 2)
gainLife(you, 1)
createToken(you, 1, token({ types: ['creature'], subtypes: ['goblin'], colors: ['red'], power: 1, toughness: 1 }))
putCounters(target(creature), '+1/+1', 2)
destroy(target(creature))
addMana(you, mana('{G}{G}'))
search(you, cards.withType('creature'), 1, { destination: 'battlefield', shuffle: true })
pump(each(creatures.youControl()), 1, 1, untilEndOfTurn)
ifThen(youControl(permanents.withType('artifact'), 3), [draw(you, 1)])
modal(1, 1, [[draw(you, 2)], [gainLife(you, 3)]])</pre>
<p>
Costs are separate: <code>manaCost('{2}{U}')</code>, <code>tapCost()</code>,
<code>sacrificeSelf()</code>, <code>payLife(3)</code>,
<code>discardCost(1)</code>, <code>removeCountersCost('+1/+1', 1)</code>.
</p>
<p class="muted">
Durations: <code>permanent</code>, <code>untilEndOfTurn</code>,
<code>untilYourNextTurn</code>, <code>untilEndOfYourNextTurn</code>,
<code>untilEndOfCombat</code>, <code>whileSourceOnBattlefield</code>.
</p>
</article>
<article>
<h3>Triggers, statics and conditions</h3>
<pre>triggered(when.attacks(self), [
createToken(you, 1, token({ types: ['creature'], subtypes: ['goblin'], colors: ['red'], power: 1, toughness: 1, tapped: true })),
])
triggered(when.upkeep(you), [
ifThen(youControl(permanents.withType('artifact'), 3), [draw(you, 1)]),
])
staticAbility([
staticGrant(each(creatures.youControl()), 'Flying'),
])</pre>
<p class="muted">
Common triggers: <code>when.enters</code>, <code>when.dies</code>,
<code>when.attacks</code>, <code>when.upkeep</code>, <code>when.endStep</code>,
<code>when.cast</code>, <code>when.dealsDamage</code>. Common conditions:
<code>yourTurn()</code>, <code>youControl(selector, n)</code>, <code>wasKicked()</code>,
<code>ifYouDo()</code>, <code>otherwise()</code>. Always check the compiled result after
saving.
</p>
</article>
<article>
<h3>When the syntax cannot express it</h3>
<p>Never guess a wrong effect. Preserve the oracle text and leave it unsupported:</p>
<pre>unsupported('modal bullet outside a modal block', 'Choose one — ...')</pre>
<p class="muted">
The full reference lives in <code>backend/docs/card-effects.md</code>.
</p>
</article>
</section>
</template>
<style scoped>
.source-guide {
flex: 1;
min-height: 0;
overflow-y: auto;
background: var(--panel);
border: 1px solid var(--line);
border-radius: 8px;
padding: 1rem 1.25rem;
display: flex;
flex-direction: column;
gap: 1.25rem;
}
.guide-head {
display: flex;
flex-direction: column;
gap: 0.25rem;
}
h3 {
margin-bottom: 0.4rem;
}
p {
line-height: 1.5;
font-size: 0.9rem;
}
code {
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
font-size: 0.85em;
background: #11151d;
border: 1px solid var(--line);
border-radius: 4px;
padding: 0.05rem 0.3rem;
}
pre {
margin: 0.5rem 0 0;
padding: 0.65rem 0.8rem;
background: #11151d;
border: 1px solid var(--line);
border-radius: 6px;
overflow-x: auto;
font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
font-size: 0.82rem;
line-height: 1.5;
}
table {
border-collapse: collapse;
width: 100%;
font-size: 0.85rem;
}
th,
td {
border-bottom: 1px solid var(--line);
padding: 0.35rem 0.5rem;
text-align: left;
vertical-align: top;
}
th {
white-space: nowrap;
color: var(--muted);
font-weight: 600;
}
tbody th {
width: 7rem;
}
@media (max-width: 800px) {
tbody th {
width: auto;
}
}
</style>