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.