🛠️ Crafting — Teaching Panels¶

The Teaching folder contains a set of lightweight IMGUI panels used for learning, debugging, and hands-on testing of the Crafting System directly inside your scenes.
These panels demonstrate how preflight checks, enqueue flow, job state/progress, workbenches, routing behaviour, inventory/currency adapters, validators/modifiers, and offline persistence behave via the public Crafting APIs.

Each panel is intentionally minimal and code-first — ideal for understanding behaviour, copying patterns, and wiring your own production UI later.

Status: Sample / Teaching UI — intended for development/testing scenes only. Not for shipping.

Define Guard: REV_CRAFTING_PRESENT

⚠️ If a Teaching panel is present on a GameObject in a shipped scene, it will be visible and interactive at runtime.
Shipping with Teaching panels attached is a developer error, not a framework bug.

🧩 Panel Overview¶

Panel	Focus	Notes
CraftingQuickstartPanel	Core flow	Seed inventory/currency, `CanCraftDetailed()`, `Enqueue()`, live jobs
CraftingWorkbenchBasicsPanel	Bench-driven crafting	2D/3D workbenches, station-tag filtering, approximate trigger/range teaching, live progress
CraftingRoutingSpaceCurrencyPanel	Routing + space + currency	Output routing behaviour, chance space policy, cost vs balance, Max Now + Reason
CraftingValidatorsModifiersPanel	Validators & modifiers	Toggle MonoBehaviour validators/modifiers, observe effects on preflight and enqueue
CraftingRealAdaptersPanel	Real adapter sandbox	Mutates real inventory/currency adapters; includes teachables-only router demo
CraftingOfflineProgressPanel	Offline progress + persistence	Save/restore active job snapshots, simulate “app closed”, restore completes/resumes

Each panel is self-contained and demonstrates one clear concept.
All panels inherit from TeachablePanelBase, use pure IMGUI, anchor top-left, and toggle with the Backquote (`) key.

🎯 Learning Goals¶

Across all panels you’ll learn to:

Run preflight using CanCraftDetailed() and read Max Now + first blocking reason
Enqueue crafts safely using Enqueue() (single, many, and optional batching)
Observe job state and progress (e.g. queued/running/completed/failed)
Understand workbench gating (in-range checks + station tag filtering)
Debug routing behaviour and why outputs land where they do
Test space budgeting for chance outputs via CraftChanceSpacePolicy
Validate currency costs vs live balances through the service + currency adapter
Toggle validators/modifiers to isolate which rule is blocking or altering jobs
Save/restore job state and verify offline progress behaviour on restore

💡 Example: Preflight → Enqueue¶

Teaching panels demonstrate the same call patterns your production code will use:

var check = crafting.CanCraftDetailed(owner, recipe, count, options);

if (check.maxCrafts > 0)
{
    var job = crafting.Enqueue(new CraftRequest(owner, recipe, count, container, stationTag));
}

No mock logic.
No demo-only shortcuts.
These panels show what the runtime systems decide via public APIs — including failure reasons.

🧠 Key Concepts the Panels Teach¶

Preflight is the source of truth¶

All “why can’t I craft?” debugging starts with the service result: - Preflight evaluates inputs, currency, space, and validators
- The service reports the first blocking reason

Adapters are the integration seam¶

Inventory and currency work through adapters wired on CraftingServiceCore. - Panels never bypass adapters. - “Real Adapters” panels can mutate actual runtime state — on purpose — for sandbox validation.

Routing behaviour¶

Output routing may use an ICraftingOutputRouter when configured, with a default container fallback.
Exact routing behaviour is defined by the router implementation and is not a guaranteed execution order.

Panels may use a teachables-only demo router to visualise behaviour.
That router is not a production pattern.

Offline progress is applied on restore¶

Offline simulation works by restoring snapshots with older timestamps.
Whether anything fast-forwards depends on service offline settings.

🧰 Integration Tips¶

Teaching panels are IMGUI-based and intended for Editor/dev scenes only.
They are excluded from player builds unless explicitly enabled and left in a scene.
Safe to keep in dev scenes — they won’t affect runtime systems beyond explicit button actions.
Copy service calls, result handling, and data flow into your runtime UI.
Ignore IMGUI/layout code — it’s scaffolding only.

Panels will clearly warn if required references/adapters are missing.

⚠️ Safety Notes¶

CraftingRealAdaptersPanel mutates real inventory/currency state via your adapters.
Use it only in sandbox/testing scenes.
Some panels may attach/configure teachables-only helper components (e.g. a demo output router) to demonstrate routing.
These helpers are restored/removed on disable to avoid leaving scenes mutated.

🧱 Teaching Folder Layout¶

Crafting/
 ├─ Teaching/
 │   ├─ CraftingQuickstartPanel.cs
 │   ├─ CraftingWorkbenchBasicsPanel.cs
 │   ├─ CraftingRoutingSpaceCurrencyPanel.cs
 │   ├─ CraftingValidatorsModifiersPanel.cs
 │   ├─ CraftingRealAdaptersPanel.cs
 │   ├─ CraftingOfflineProgressPanel.cs
 │   └─ Support/
 │       ├─ CraftingRejectFeedback.cs
 │       └─ TeachingOutputRouter.cs

🧠 Quick Review¶

Attribute	Summary
Audience	Developers integrating or exploring the Crafting system
Goal	Teach preflight, enqueue, jobs, routing behaviour, benches, validators, adapters, and persistence
Style	Code-first, readable, dependency-light
Location	`Assets/RevFramework/Teaching/Crafting/`
Safety	Dev-only; must not be shipped with scenes
Theme	IMGUI — consistent with all RevFramework teaching panels

TL;DR¶

The Teaching folder is your in-engine classroom for Crafting.
Use it to debug preflight failures, routing/space/currency behaviour, workbench gating, validators/modifiers, and offline job restores — then copy the patterns into your own UI.