Skip to content
DarkBladeDev Docs

Diagnostics, FAQ, and Flight Recorder

This guide covers common administration and player issues, validation errors, and runtime diagnosis using the Process Flight Recorder introduced in v2.5.0.

1. Frequently Encountered Issues

Issue 1: “Workstation not recognized” or clicks open Vanilla Anvil

  • Cause: The station block material does not match blocks: in stations/*.yml, or fallback_to_vanilla: true is letting the vanilla GUI take precedence.
  • Fix: Check /cfe station list to ensure the station loaded. Verify that your block matches the exact Bukkit material. If using custom tags, ensure the block PDC tag matches pdc_key:.

Issue 2: “Process does not start when clicking”

  • Cause: Missing tools in hand, insufficient input quantities, or unmet capability requirements (e.g. temperature too low).
  • Fix: Run /cfe recipe info <recipe_id> to view required materials and capabilities. Run /cfe status to inspect current station capabilities.

Issue 3: “Ghost blocks not appearing on multiblocks”

  • Cause: PacketEvents is missing or disabled.
  • Fix: Ensure PacketEvents v2.14.0+ is running in /plugins. Check server startup logs for PacketEvents initialization.

Issue 4: “Process aborts with ‘Station capability exhausted’ or jumps to salvage”

  • Cause: The workstation’s consumable capability (e.g. high_temperature, steam_pressure) depleted below its min_threshold during stage ticking (governed by CapabilityDrainPolicy).
  • Fix: Replenish the station resource (e.g. refuel, pump fluid) or adjust drain_per_second, drain_per_use, or min_threshold in stations/*.yml.

Issue 5: “Are reserved ingredients lost on server reload or crash?”

  • Cause: In recipes using mode: RESERVE (v2.8.0+), ingredients are isolated in memory during crafting.
  • Fix: Zero item loss is guaranteed. ItemReservationManager listens to server shutdown, plugin reload (onDisable), and player disconnect events to immediately release all active reserved items back into player inventories or drop them naturally at the workstation (world.dropItemNaturally).

2. Process Flight Recorder (v2.5.0 - v2.9.0)

CraftingEngine includes a high-performance in-memory black box telemetry flight recorder (ProcessFlightRecorder) that captures the microsecond-accurate timeline of active and terminated crafting processes.

Inspecting Traces via Commands

Ventana de terminal
/cfe process list                        # View active and recently completed process UUIDs
/cfe process trace <uuid> [limit]        # Renders interactive MiniMessage chronological timeline
/cfe process trace export <uuid>         # Dumps structured JSON log to plugins/CraftingEngine/traces/
/cfe process info <uuid>                 # Summary info with clickable [Trace Timeline] and [Export Trace] buttons

Telemetry Details & Event Types:

  • Process Lifecycle: PROCESS_START, PROCESS_COMPLETE, PROCESS_CANCEL, PROCESS_FAIL.
  • Transitions & Branching: Renders color-coded badges:
    • [BRANCH 20/100]: Weighted probabilistic branch selection.
    • [JUMP]: Explicit Action DSL stage jump (transition: "<stageId>").
    • [RECOVERY]: Stage failure diverted to failure_transition.
    • [TIMEOUT]: Sequential transition after duration elapsed.
  • Station Capabilities (v2.7.0):
    • CAPABILITY_DRAINED: Quantity drained, remaining balance, and variable key.
    • CAPABILITY_EXHAUSTED: Triggered when variable drops below min_threshold.
  • Transactional Input Reservation (v2.8.0):
    • INPUT_RESERVED: Items moved to isolated reservation buffer on craft start.
    • INPUT_RELEASED: Items safely refunded upon cancellation/failure.
    • INPUT_COMMITTED: Items permanently consumed upon completion.
  • Ingredient Property Inheritance (v2.9.0):
    • Captures input PDC tags and logs evaluated target attributes and mathematical expressions.

3. Diagnostic Commands Summary

CommandPurpose
/cfe statusOverall plugin health, memory buffers, loaded registries, and tick scheduler state.
/cfe recipe validate-allBatch test all blueprints for schema typos, missing resources, and topological errors.
/cfe multiblock checkScans target blocks to diagnose multiblock structure errors and cardinal alignment.
/cfe item inspectPrints exact namespaced identifiers, CustomModelData, and PDC keys of held items.
/cfe process trace <uuid>Inspects live or historical flight recorder execution timeline.
/cfe process trace export <uuid>Dumps complete process trace JSON to disk asynchronously.

4. Getting Support

If you encounter bugs, performance issues, or edge cases: