🛠️ 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¶

CraftingService is the orchestration root.
Crafting is adapter‑driven (inventory, currency, authority).
All decisions flow through preflight → enqueue → job lifecycle.
Public APIs are intentionally small; behaviour is extended through adapters, validators, modifiers, and routing rather than subclassing the service.
Crafting avoids global state and does not require singletons.

🧱 Core Runtime Service¶

`CraftingService`¶

The central runtime service responsible for all crafting execution.

Responsibilities¶

Preflight validation (inputs, currency, space, validators)
Job creation and scheduling
Progress updates and completion
Cancellation and pause/resume
Persistence APIs and offline reconciliation
Event emission for UI / gameplay systems
Deterministic execution when driven explicitly

Gameplay systems typically interact with Crafting only through this service.

🔧 Service Configuration & Driving¶

These APIs allow code‑first configuration, deterministic tests, and headless/server simulation.

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
)

Configures adapters and runtime seams directly.

Supported scenarios:

code‑first projects
deterministic testing
server/headless execution
tool‑driven simulation

This is a supported alternative to Inspector wiring.

Tick¶

void Tick(float now)

Runs a single simulation step using an explicit time value.

Typical uses:

deterministic replay
server simulation
automated tests
tooling

Normal gameplay continues to drive this via Update().

Runtime Policy Controls¶

void SetRefundInputsOnDeliveryFail(bool enabled)
void SetChanceSpacePolicy(CraftChanceSpacePolicy policy)
void SetMaxParallelJobs(int maxParallel)
void SetDefaultStationCap(int maxParallel)
void SetStationCap(string stationTag, int maxParallel)
bool RemoveStationCap(string stationTag)
void ClearStationCaps()

These methods modify runtime scheduling and failure‑handling behaviour.

🔍 Preflight Queries¶

CanCraft¶

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

Returns true if at least one craft can currently be accepted.

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 evaluation used by tools, UI, and Teachables.

Probe¶

CraftProbe Probe(
    GameObject owner,
    RecipeCore recipe,
    int requested = 1,
    CraftPreflightOptions opts = default
)

Returns a structured breakdown of:

item limits
currency limits
space limits
final craft count
blocking reason

Used primarily for UI and diagnostics.

▶️ Crafting Actions¶

Enqueue¶

CraftJob Enqueue(in CraftRequest request)

Consumes inputs/currency immediately and creates one or more crafting jobs.

Returns:

CraftJob on success
null if the request was rejected (a failure reason will be emitted via rejection events)

Convenience Helpers¶

CraftJob EnqueueOne(...)
CraftJob EnqueueBatch(...)
List<CraftJob> EnqueueMany(
    GameObject owner,
    RecipeCore recipe,
    int count,
    string container = null,
    object userData = null
)

These are thin helpers built on top of Enqueue.

🛡️ Strong / Escrow Crafting¶

TryCraftImmediateEscrow¶

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

Optional strong execution path for zero‑duration crafts.

Requirements:

inventory adapter supporting reservations
currency adapter supporting holds

Behaviour:

performs a reserve → commit flow intended to behave atomically when adapter contracts are honoured
no job is created
executes immediately

This path is intended for atomic, instant crafts only.

⏱️ 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)

bool MoveQueuedFirst(int jobId)
IReadOnlyList<CraftJob> GetJobsByState(...)
int FillJobsByState(List<CraftJob> results, ...)

These methods allow runtime job inspection and control.

📣 Lifecycle Events¶

event Action<CraftJob> OnJobAccepted
event Action<CraftJob> OnJobEnqueued
event Action<CraftJob> OnJobStarted
event Action<CraftJob, float> OnJobProgress
event Action<CraftJob> OnJobCompleted
event Action<CraftJob, CraftFailReason> OnJobFailed
event Action<CraftJob> OnJobCancelled

event Action<CraftJob, JobLifecyclePhase, CraftFailReason> OnJobLifecycle

event Action<GameObject, RecipeCore, CraftFailReason> OnPreflightRejected
event Action<GameObject, RecipeCore, CraftFailReason> OnJobRejected

event Action<GameObject, RecipeCore, int> OnCraftXp

These events allow gameplay systems and UI to observe crafting behaviour.

🧩 Recipe Construction¶

Runtime Recipe Creation¶

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 RecipeCore instance without editor dependencies.

Typical uses:

procedural crafting systems
importing data from external sources
deterministic tests
runtime recipe generation

Returned recipes should be treated as immutable.

🔌 Adapter Seams¶

Crafting integrates with other systems exclusively through adapter interfaces.

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)
bool TryGetAuthority(out ICraftingAuthority authority)

Allows callers to check whether crafting mutations are currently permitted under the configured authority gate.

When no ICraftingAuthority implementation is configured, CanMutate returns true and crafting behaves permissively.

Routing¶

bool SetOutputRouter(ICraftingOutputRouter router)

🧩 Validators & Modifiers¶

Custom behaviour is implemented via components:

ICraftingValidator
ICraftingModifier
ICraftingOutputRouter

Discovery behaviour:

Components are searched on the owner and parent chain
Order should not be relied upon as a stable contract

💾 Persistence & Offline Progress¶

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

Paused jobs do not tick offline.

Offline completion re-applies modifiers and attempts delivery when the target container can be resolved.

⚠️ Persistence Responsibility¶

The Crafting system exposes APIs for saving and restoring active jobs.
It does not provide a save system or storage layer.

No file handling
No cloud sync
No automatic save/load triggers

👉 Integrating these APIs into your save system is entirely the developer’s responsibility.

This mirrors other system boundaries in RevFramework:

Authority → you define and enforce
Networking → you implement
Persistence → you define and control

The framework provides the data and execution model — you decide how and when it is stored.

Crafting defines what the data means — your game defines how it lives.

❌ Explicitly Not Supported¶

The following are intentionally not supported integration points:

Reflection into Crafting internals
Manipulating job lists directly
Inspector/SerializedObject mutation of runtime state
Calling internal hooks or helpers

TL;DR¶

This page defines the contract.
If something appears here, it is a supported public API.
If it does not appear here, it should be treated as internal implementation detail.