🛠️ Crafting System — Public API¶

This page defines the supported, stable public API for the RevFramework Crafting System.

If something is not listed here, it is not supported as a public integration point — even if it appears accessible in code.

Audience: Developers integrating Crafting into gameplay, tools, or UI
Scope: Runtime public API and supported runtime components
Stability: Breaking changes to items listed on this page are avoided or clearly versioned

API Stability Policy

Items listed on this page are considered stable.
New public APIs and components may be added over time.
Internals may change without notice.

RevFramework guarantees stability only for documented public APIs and components.
Usage of internal or undocumented code is unsupported and may break without notice.

📌 Core Concepts¶

CraftingServiceCore is the orchestration root.
Crafting is adapter-driven (inventory, currency, authority).
All decisions flow through preflight → enqueue → job lifecycle.
No global singletons, no hidden state mutation.
Public APIs are intentionally small; behaviour is extended via components.

🧱 Core Service¶

`CraftingServiceCore`¶

The central runtime service that manages crafting jobs.

Supported Responsibilities¶

Preflight validation (inputs, currency, space, validators)
Job creation, scheduling, progress, completion, cancellation
Persistence and offline recovery
Event emission
Deterministic, code‑driven execution (no inspector dependency required)

This is the primary integration point for gameplay code, tools, and UI.

🔧 Service Configuration & Driving (Supported)¶

These APIs allow code‑first usage, deterministic testing, tooling, and headless/server scenarios.

`Configure(...)`¶

void Configure(
    ICraftingInventoryAdapter inventory,
    ICraftingCurrencyAdapter currency = null,
    ICraftingAuthority authority = null,
    ICraftingOutputRouter router = null,
    string defaultContainer = null,
    IRandomProvider rng = null,
    ITimeProvider time = null,
    IWallClockProvider wallClock = null
)

Binds adapters and optional seams directly via code.

Supported use cases - Code‑first projects (no inspector wiring) - Server‑authoritative or headless simulations - Tooling and batch processing - Deterministic tests

This method is a supported alternative to inspector wiring and Unity lifecycle timing.

`Tick(...)`¶

void Tick(float now)

Drives one simulation step using an explicit time value.

Supported use cases - Deterministic simulation and replay - Offline reconciliation - Headless/server execution - Tests and tools that must not rely on Update()

Runtime gameplay continues to call this automatically via Update().

`SetRefundInputsOnDeliveryFail(...)`¶

void SetRefundInputsOnDeliveryFail(bool enabled)

Configures the delivery‑failure refund policy.

When enabled, consumed inputs are best‑effort refunded if delivery fails (space/immediate). Currency refunds are handled independently.

🔍 Preflight & Queries¶

`CanCraft(...)`¶

bool CanCraft(GameObject owner, RecipeCore recipe, CraftPreflightOptions opts = default)

Returns true if at least one craft is possible right now.

`CanCraftCount(...)`¶

int CanCraftCount(GameObject owner, RecipeCore recipe, int requested, CraftPreflightOptions opts = default)

Returns the maximum number of crafts possible, clamped by requested.

`CanCraftDetailed(...)`¶

CraftCheck CanCraftDetailed(
    GameObject owner,
    RecipeCore recipe,
    int requested = 1,
    CraftPreflightOptions opts = default
)

Returns: - maxCrafts - the first blocking CraftFailReason

This is the authoritative preflight call used by tools, UI, and Teachables.

▶️ Crafting Actions¶

`Enqueue(...)`¶

CraftJob Enqueue(CraftRequest request)

Consumes inputs/currency immediately and enqueues a job.

Returns: - CraftJob on success - null on failure (reason emitted via events)

Convenience Helpers¶

CraftJob EnqueueOne(...)
CraftJob EnqueueBatch(...)
List<CraftJob> EnqueueMany(...)

All are thin wrappers around Enqueue(...).

🛡️ Strong / Escrow Crafting (Advanced)¶

`TryCraftImmediateEscrow(...)`¶

bool TryCraftImmediateEscrow(
    CraftRequest request,
    string idempotencyKey,
    out CraftFailReason fail
)

An opt‑in, strong execution path for immediate (zero‑duration) crafts.

This API: - Requires inventory adapters that support reservations - Requires currency adapters that support holds - Executes as a single atomic operation - Fails fast if required escrow seams are missing

Not suitable for queued or timed crafts.

⏱️ Job Queries & Control¶

IReadOnlyList<CraftJob> GetJobs(GameObject owner = null)
float GetJobRemainingSeconds(int jobId)
bool CancelJob(int jobId, bool refund = true)
bool PauseJob(int jobId)
bool ResumeJob(int jobId)

📣 Events (Lifecycle)¶

event Action<CraftJob> OnJobAccepted
event Action<CraftJob> OnJobStarted
event Action<CraftJob, float> OnJobProgress
event Action<CraftJob> OnJobCompleted
event Action<CraftJob, CraftFailReason> OnJobFailed
event Action<CraftJob> OnJobCancelled
event Action<GameObject, RecipeCore, CraftFailReason> OnPreflightRejected

Events are runtime‑safe and intended for UI/state updates.

🧩 Recipe Construction (Supported)¶

`RecipeCore.Create(...)`¶

static RecipeCore Create(
    IReadOnlyList<ItemRef> inputs,
    IReadOnlyList<ItemRef> outputs,
    string currencyId = null,
    long amountPerCraft = 0,
    float craftTimeSeconds = 0f,
    string stationTag = null,
    string displayName = null,
    string description = null,
    int xpPerCraft = 0
)

Creates a runtime‑safe RecipeCore instance without editor or reflection access.

Supported use cases - Procedural recipes - Runtime imports/conversion - Tooling - Deterministic tests

Returned instances are runtime objects and should be treated as immutable.

🧩 Adapters (Supported Seams)¶

Inventory¶

bool HasInventoryAdapter
bool TryGetInventoryAdapter(out ICraftingInventoryAdapter adapter)
bool TryGetInventoryContext(GameObject owner, string container, out CraftingInventoryContext ctx)

Currency¶

bool HasCurrencyAdapter
bool TryGetCurrencyAdapter(out ICraftingCurrencyAdapter adapter)

Authority¶

bool HasAuthorityGate
bool CanMutate(GameObject owner, out CraftFailReason denyReason)

🧪 Validators & Modifiers¶

Implement ICraftingValidator or ICraftingModifier
Registered via components on the owner and parents
Order is not a contract

💾 Persistence & Offline Progress¶

List<CraftJobSnapshot> SaveActiveJobs(...)
void RestoreJobs(...)

Paused jobs do not tick offline.

❌ Explicitly Not Supported¶

Reflection into Crafting internals
Inspector or SerializedObject manipulation
Calling internal hooks
Modifying job lists directly

TL;DR¶

This page defines the contract.
If it’s documented here, it’s supported.
If it’s not here, don’t depend on it.