Skip to content

Crafting / Core / Contracts

Purpose

This folder contains the public data contracts used to interact with the Crafting system.

Types in Contracts are: - stable - serializable where appropriate - safe for hostile consumers - free of mutation, side effects, and service logic

They define what callers can ask, what the service reports, and how results are described — without exposing how the Crafting service works internally.

If a type crosses a system boundary, gets serialized, or is consumed by UI or Teachables, it belongs here.

What lives here

Requests

  • CraftRequest
  • Input parameters for enqueueing crafts.
  • Supports single or batched execution.
  • Captures owner, recipe, count, container override, station tag, and user data.

This is the only supported way to ask the service to create jobs.

Preflight results

  • CraftCheck
  • Result of a detailed preflight evaluation.

  • Reports the maximum number of crafts allowed and the first blocking reason.

  • CraftProbe

  • UI-friendly breakdown of preflight limits.
  • Separates bounds imposed by items, currency, and space.

These types describe capability, not execution.

Jobs & persistence

  • CraftJob
  • Runtime record of an accepted craft or batch.

  • Read-only to consumers; owned and mutated exclusively by the service.

  • CraftJobSnapshot

  • Serializable snapshot used for save/load and offline progress.

  • CraftJobState

  • Discrete job states (Queued, Running, Paused, Completed, Cancelled, Failed).

Callers may observe jobs but must never mutate them.

Enums & configuration

  • CraftFailReason
  • Explicit reasons a craft cannot proceed.
  • Used consistently across preflight, runtime failure, and events.

  • Ordering guarantees apply only to preflight evaluation.

  • CraftTimeMode

  • Declares which Unity time source the service uses.

  • CraftPreflightOptions

  • Optional overrides for container and station context during preflight.

These enums are intentionally explicit and user-facing.

What does NOT belong here

  • Service logic
  • Adapter interfaces
  • Inventory or currency APIs
  • Validation or modifier behaviour
  • Any type that performs side effects

If a type does work, it does not belong in Contracts.

Usage rules

For callers

  • Treat all contract types as descriptive, not authoritative.
  • Never assume internal ordering, timing, or side effects.
  • Use CraftFailReason to drive UI and feedback — not heuristics.

For persistence

  • CraftJobSnapshot is the only supported persistence shape.
  • Consumers must provide their own ID mapping for owners and recipes.
  • Snapshots assume inputs and currency were already consumed.

Public API guarantee

All types in this folder are part of the supported public API.

Changes follow these rules: - fields may be added (non-breaking) - semantics will not silently change - removed fields or behavioural changes require a major version bump

Teachables compile against these contracts to prove API stability.

Design notes

  • Contracts are boring on purpose.
  • They carry data, not service behaviour.
  • They survive serialization, save/load, and hostile inspection.

If you need to do something, look elsewhere. If you need to describe something, it probably belongs here.