2nd/10_Wiki/Topics/Frontend/Equipment-Crafting-and-Synthesis-Engine.md

---
id: wiki-2026-0508-equipment-crafting-and-synthesis
title: Equipment Crafting and Synthesis Engine
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Crafting System, Item Synthesis, Forge System]
duplicate_of: none
source_trust_level: A
confidence_score: 0.85
verification_status: applied
tags: [game-dev, frontend, ui, crafting, gameplay]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: React
---

# Equipment Crafting and Synthesis Engine

## 매 한 줄
> **"매 input item 의 set 의 의 output item 의 deterministic/stochastic 의 transformation 의 system"**. Diablo, Path of Exile, Genshin Impact 의 의 matter 의 core loop. 2026 의 frontend 의 의 reactive preview + server-authoritative resolution 의 standard pattern.

## 매 핵심

### 매 architecture layer
- **Recipe 의 catalog**: input pattern → output spec (data-driven JSON).
- **Resolver**: input 의 match 의 recipe 의 find 의 — pattern matching engine.
- **Roller**: stochastic 의 modifier roll (affix, stat range).
- **Preview UI**: reactive 의 — input 의 change 의 의 result 의 의 live recompute.
- **Server commit**: 의 authoritative 의 final roll — 매 client 의 prediction 의 의 validate.

### 매 stochastic 의 vs 의 deterministic
- **Deterministic**: 의 fixed output (e.g. base item + recipe → fixed legendary).
- **Stochastic**: 의 random affix (rarity tier, stat range, modifier pool).
- **Hybrid**: deterministic base + stochastic affix.

### 매 응용
1. RPG forge (sword + 의 gem → enchanted sword).
2. Gacha synthesis (3-star × 3 → 4-star upgrade).
3. Crafting MMORPG (pattern + 의 material → gear).
4. Auto-battler item merge (3 의 의 same → upgraded).

## 💻 패턴

### Recipe 의 schema
```ts
type Recipe = {
  id: string;
  inputs: ItemPattern[];          // ordered or set
  ordered: boolean;
  output: OutputSpec;
  cost?: { gold?: number; energy?: number };
  unlockLevel?: number;
};

type ItemPattern =
  | { kind: "exact"; itemId: string; qty: number }
  | { kind: "tag"; tag: string; rarity?: Rarity; qty: number };

type OutputSpec =
  | { kind: "fixed"; itemId: string }
  | { kind: "rolled"; baseItemId: string; affixPools: AffixPool[] };
```

### Resolver (pattern match)
```ts
function findRecipe(inputs: Item[], catalog: Recipe[]): Recipe | null {
  return catalog.find((r) => matches(r, inputs)) ?? null;
}

function matches(recipe: Recipe, inputs: Item[]): boolean {
  const remaining = [...inputs];
  for (const pat of recipe.inputs) {
    const idx = remaining.findIndex((it) => itemMatchesPattern(it, pat));
    if (idx === -1) return false;
    remaining.splice(idx, 1);
  }
  return remaining.length === 0;
}

function itemMatchesPattern(item: Item, pat: ItemPattern): boolean {
  if (pat.kind === "exact") return item.itemId === pat.itemId;
  return item.tags.includes(pat.tag) && (!pat.rarity || item.rarity === pat.rarity);
}
```

### Affix roller (seeded)
```ts
import { xoshiro256ss } from "./prng";

type AffixPool = { tag: string; weight: number; statRange: [number, number] };

function rollAffixes(pools: AffixPool[], count: number, seed: bigint): Affix[] {
  const rng = xoshiro256ss(seed);
  const result: Affix[] = [];
  const available = [...pools];
  for (let i = 0; i < count && available.length > 0; i++) {
    const total = available.reduce((s, p) => s + p.weight, 0);
    let r = rng() * total;
    const idx = available.findIndex((p) => (r -= p.weight) < 0);
    const pool = available[idx];
    available.splice(idx, 1);
    const [lo, hi] = pool.statRange;
    result.push({ tag: pool.tag, value: lo + rng() * (hi - lo) });
  }
  return result;
}
```

### React 의 craft preview UI
```tsx
function CraftBench({ inventory }: { inventory: Item[] }) {
  const [slots, setSlots] = useState<Item[]>([]);

  const recipe = useMemo(() => findRecipe(slots, RECIPE_CATALOG), [slots]);
  const preview = useMemo(() => {
    if (!recipe) return null;
    if (recipe.output.kind === "fixed") return { kind: "fixed", item: ITEM_DB[recipe.output.baseItemId] };
    return { kind: "rolled", base: recipe.output.baseItemId, affixCount: recipe.output.affixPools.length };
  }, [recipe]);

  return (
    <div className="grid grid-cols-2 gap-4">
      <SlotGrid slots={slots} setSlots={setSlots} inventory={inventory} />
      <PreviewPanel recipe={recipe} preview={preview} onCraft={() => craft(slots)} />
    </div>
  );
}
```

### Server-authoritative commit
```ts
// Client
async function craft(inputs: Item[]) {
  const r = await fetch("/api/craft", {
    method: "POST",
    body: JSON.stringify({ inputIds: inputs.map((i) => i.instanceId) }),
  });
  if (!r.ok) throw new Error("craft failed");
  return r.json() as Promise<CraftResult>;
}

// Server (authoritative seed)
function handleCraft(req) {
  const inputs = loadInventory(req.userId, req.inputIds);
  const recipe = findRecipe(inputs, CATALOG);
  if (!recipe) return { ok: false, reason: "no_match" };

  const seed = BigInt(`0x${randomBytes(8).toString("hex")}`);
  const result = applyOutput(recipe.output, seed);
  consumeInputs(req.userId, inputs);
  grantItem(req.userId, result);
  return { ok: true, item: result, seed: seed.toString() };
}
```

### Drag-drop 의 slot
```tsx
function Slot({ item, onDrop }: { item?: Item; onDrop: (it: Item) => void }) {
  return (
    <div
      onDragOver={(e) => e.preventDefault()}
      onDrop={(e) => {
        const id = e.dataTransfer.getData("text/plain");
        const it = INVENTORY.get(id);
        if (it) onDrop(it);
      }}
      className="border-2 border-dashed h-24 w-24 grid place-items-center"
    >
      {item ? <ItemIcon item={item} /> : <span>+</span>}
    </div>
  );
}
```

### Probability 의 display
```tsx
function ProbabilityBar({ pools }: { pools: AffixPool[] }) {
  const total = pools.reduce((s, p) => s + p.weight, 0);
  return (
    <ul>
      {pools.map((p) => (
        <li key={p.tag}>
          {p.tag} — {((p.weight / total) * 100).toFixed(1)}%
        </li>
      ))}
    </ul>
  );
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Casual game / mobile | Deterministic recipe — 매 predictability |
| ARPG / Diablo-like | Stochastic affix + 의 base 의 deterministic |
| Gacha / loot | Stochastic 의 의 server seed 의 authoritative |
| Single-player offline | Client RNG 의 OK |
| Multiplayer competitive | 매 server 의 의 seed 의 — anti-cheat |

**기본값**: data-driven recipe + server-rolled affix + reactive preview UI.

## 🔗 Graph

## 🤖 LLM 활용
**언제**: crafting recipe schema 설계, affix pool weighting, preview reactive UI.
**언제 X**: 매 simple 의 single-purpose game (puzzle, runner) — 매 over-engineering.

## ❌ 안티패턴
- **Client-only roll**: 매 trivially exploitable (replay, save-scum).
- **Hard-coded recipe**: data-driven 의 X 의 — designer iteration 의 dev rebuild 의 require.
- **Hidden probability**: regulator 의 (China, Korea, Japan) 의 force disclose.
- **Synchronous animate-then-commit**: 매 latency 의 bad UX — optimistic preview 의 즉시 + server 의 confirm.

## 🧪 검증 / 중복
- Verified (Diablo IV crafting docs, Path of Exile wiki, Genshin gacha rates, GDC talks 의 crafting design).
- 신뢰도 B+ — game-specific 의 variance.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — recipe schema + affix roller + server authority 추가 |