Skip to content

🍳 Crafting — Unity / RecipeDefinition

This folder contains the Unity-facing recipe asset (RecipeDefinition). It exists to support designer-friendly authoring in the Unity Inspector and is not part of the supported Crafting Core runtime API.

RecipeDefinition is a framework-internal authoring helper that compiles only when the relevant optional systems are present.

At runtime, Unity-facing recipe assets are resolved into RecipeCore data before being used by the Crafting service.

Truth-pass note: This README describes behaviour implemented by the current runtime and conversion helpers. Where behaviour depends on compile-time defines or internal helpers, that dependency is stated explicitly.

🎯 Purpose

RecipeDefinition allows designers to author recipes using ItemDefinition assets instead of typing GUID strings manually.

Key points:

  • The Crafting service operates on RecipeCore (GUIDs + quantities + optional currency cost).
  • RecipeDefinition is an authoring helper that can be converted to RecipeCore when the relevant optional systems are present (compile-time define).
  • Conversion and caching details are intentionally hidden behind the public RecipeResolve API.
  • Projects may ship with no RecipeDefinition assets at all and rely solely on RecipeCore.

📦 RecipeDefinition structure (overview)

RecipeDefinition stores item references (ItemDefinition) plus authoring metadata (display name, description, station tag, currency fields, craft time).

Authoring notes (Editor-time):

  • Ingredient.item / Output.item may be temporarily null during editing.
  • OnValidate() trims obvious strings and clamps obvious numeric fields.
  • IsValid is a basic sanity check intended for tooling/debug, not a full runtime guarantee.

🔁 Conversion to RecipeCore

RecipeDefinition.ToCore() produces a new RecipeCore instance containing only runtime data:

  • Inputs/outputs are converted to ItemRef entries using ItemDefinition.guid
  • Quantities are clamped to at least 1
  • Currency ID is trimmed/null-normalised; currency amount is clamped to non-negative
  • Craft time is clamped to non-negative
  • Station tag and strings are trimmed/null-normalised
  • The created RecipeCore is marked HideFlags.DontSave

ToCore() always allocates a new RecipeCore instance and performs no caching.

🚀 Supported runtime resolution (public API)

External runtime code should not call ToCore() or internal caches directly.

Use the supported seam:

bool ok = RecipeResolve.TryResolve(asset, out RecipeCore core);

Runtime behaviour:

  • If asset is a RecipeCore, it is returned directly.
  • If asset is a convertible wrapper (e.g., RecipeDefinition), conversion is attempted only when the relevant optional systems are present in the build (compile-time define).
  • If conversion is unavailable, resolution fails gracefully (false / null) without throwing.

This keeps callers insulated from: - optional compile-time defines, - internal caching details, and - allocation mechanics.

🧠 Internal caching (framework only)

When conversion is available, the framework may cache converted RecipeCore instances to avoid repeated allocations.

Current implementation notes: - Cached cores are keyed by the source Unity asset. - Cached cores are marked HideFlags.DontSave. - Cache lifetime is an internal detail (e.g., cleared on domain reload).

This mechanism is not a supported extension point. Treat it as an implementation detail.

✔️ Validity & guardrails

RecipeDefinition.IsValid performs a basic sanity check for tooling/debug:

  • At least one input and one output entry
  • Non-null items have quantities >= 1
  • Currency cost is non-negative

Editor-time guardrails in OnValidate(): - clamps negative cost/time - fixes quantities < 1 - trims station tags, names, descriptions, and currency IDs - allows placeholder null items during authoring

🧭 Typical workflow

  1. Create a RecipeDefinition via: Assets → Create → RevFramework → Crafting → Recipe (Unity)
  2. Add inputs and outputs using ItemDefinition assets
  3. Optionally configure:
  4. currency ID and cost
  5. craft time
  6. station tag
  7. display name and description
  8. At runtime, resolve with: 
    RecipeResolve.TryResolve(asset, out var core);
  9. Pass the resulting RecipeCore into Crafting APIs.

📝 Notes

  • RecipeDefinition compiles only when REV_INVENTORY_PRESENT is defined.
  • Without that define, only RecipeCore assets are supported by RecipeResolve.
  • Converted recipes are runtime-created objects (not saved) and contain no ItemDefinition references.

RecipeDefinition exists purely to support Unity authoring. The Crafting runtime consumes RecipeCore data.