Skip to content

🧱 Crafting — Core

📦 Folder Overview

This folder contains the core runtime implementation of the Crafting system.

It defines the actual crafting behaviour, including:

  • preflight evaluation
  • input and currency consumption
  • job scheduling and execution
  • output delivery
  • failure handling
  • persistence and offline progress (job-based)

If something changes how crafting behaves at runtime, it belongs here.

This folder is not UI, not adapters, and not optional gameplay extensions.

🧩 What Lives Here

CraftingService

The orchestration engine for all crafting operations.

  • manages the job lifecycle (accept → run → deliver → complete/fail)
  • integrates with inventory, currency, authority, routing, RNG, time, and persistence
  • exposes the supported public API used by gameplay, UI, and teaching tools

Escrow Path (optional)

An opt-in, immediate-only path for atomic crafting using reservation semantics.

  • implemented as part of CraftingService
  • uses reservation/hold adapters when available
  • executes immediately (no job lifecycle)

This path:

  • does not replace the job system
  • does not support long-running or queued crafting
  • does not provide multi-container atomic guarantees

If reservation-capable adapters are not available, this path is not used.

Supporting Domains

  • Context/ Immutable context (CraftContext) and mutable adjustments (CraftAdjustments)

  • Contracts/ Public data contracts (jobs, requests, results, probes, enums)

  • Lifecycle/ Job lifecycle phase definitions and events

  • Recipe/ Runtime recipe data (RecipeCore) and resolution (RecipeResolve)

  • Internal/ Framework-only helpers and implementation details

🎯 Purpose

This folder defines the authoritative runtime behaviour of the Crafting system.

It provides:

  • a service-driven execution model
  • deterministic evaluation (subject to RNG configuration)
  • explicit failure handling and result reporting
  • persistence and offline progress support

🧠 Usage Guidance

  • Use CraftingService as the entry point for all crafting operations
  • Interact with the system through public contracts and abstractions
  • Extend behaviour using adapters, validators, modifiers, and routing

Do not modify or subclass core runtime types to extend behaviour.

⚠️ Important Notes

  • Crafting is service-driven, not recipe-driven
  • Recipes are treated as immutable runtime data
  • Mutation is gated and observable
  • Failure reasons are explicit and surfaced
  • Determinism depends on RNG configuration and call order

🚫 Not for Production Use

This folder does not include:

  • UI or editor tooling
  • concrete inventory or currency implementations
  • game-specific logic (levels, perks, tech trees)

These belong in adapters, modifiers, validators, or higher-level systems.

  • Crafting Abstractions (integration contracts)
  • Crafting Adapters (system integrations)
  • Integrations (module-specific implementations)

🧱 Public vs Internal

Public API

  • CraftingService
  • RecipeCore
  • RecipeResolve
  • Context types
  • Contract types
  • Lifecycle types

Internal

  • Internal/ contents
  • internal delegates and helpers

Teachables compile against the public surface only.

🧩 Supported Extension Points

Crafting is extensible without subclassing through:

  • adapters (ICraftingInventoryAdapter, ICraftingCurrencyAdapter, etc.)
  • modifiers (ICraftingModifier)
  • validators (ICraftingValidator)
  • routing (ICraftingOutputRouter)
  • authority (ICraftingAuthority)

Behaviour outside these seams is not part of the supported extension surface.

🧠 Design Notes

  • service-driven architecture
  • explicit and observable state transitions
  • failure-first design (no hidden partial success)
  • offline progress based on wall-clock time

This layer is designed to operate consistently across save/load cycles and different authority models, depending on integration setup.