PFO_OS

System Documentation

Welcome to the analytical breakdown of Pioneers Factory OS (PFO_OS). This document explores the inner workings of our directed acyclic graph generation, recipe resolving logic, and Next.js / Tailwind setup.

Tech Stack Foundation

Built on React 19 and Next.js 15, styled strictly with Tailwind CSS v4. Data pipelines rely on memory-mapped JSON dictionaries, utilizing @xyflow/react for rich, interactive topological arrays.

React Flow & Visualization Strategy

The system utilizes an advanced @xyflow/react implementation to map out calculated supply chains visually. The main file is localized to /components/FlowGraph.tsx.

  • Auto-Layouting with Dagre: Instead of manual grid snapping, the factory components and edges are pipelined into dagre.js. The algorithm calculates coordinate matrices automatically, setting rank directions (rankdir: 'LR') for consistent horizontal flows and minimizing edge crossing.
  • Custom Nodes: Defined in CustomMachineNode.tsx, these interactive cards allow inline data inspection. They dynamically display inline recipe stats, over/under clock modifiers, efficiency frontiers using algorithmic boundaries, and include functional logic (e.g., swapping recipes, interacting with AI agents, and copy-pasting JSON topologies directly from clipboard natively).
  • Export Engine: It employs html-to-image coupled with XYFlow bounds to allow exporting entire production setups via exact viewport extraction to deterministic PNG images.

Recipe Resolution & Logic

The game data holds exhaustive dictionaries of Recipes and Machines. The system calculates material requirements backwards from end-targets, traversing dependencies natively.

  • Filtering: Before running recursions, the engine filters recipes via multiple variables: user base tier limits, manually disabled recipes/machines via user preferences, and explicit logic overrides.
  • Target Allocation: The platform supports specific fixed output goals (e.g. 50/min), flexible quotas against raw resource limits, or exact deterministic belt splits (mapping directly to game-native synchronization points like 780/m).
  • Real-Time Overrides: Component UI interactions dynamically alter definitions by calling onRecipeChange constraints, re-registering into the settings.recipeOverrides store and seamlessly re-triggering calculation updates.

Unit Modes & Allocation

PFO applies rigid allocation rules based on the chosen Unit Mode for an objective. Each objective uses inputs like GLOBAL ALLOCATION (desired rate) and PROPORTIONAL_PARTS (ratios).

ITEMS/M

Based on the [GLOBAL ALLOCATION] as a fixed output rate. Creates the production line specifically targeting the precise mathematical items per minute required.

MAX_CLOCK

Based on the [GLOBAL ALLOCATION] as output. Creates the production line with maximum efficiency, assuming the utilization of Power Slugs (250% clocks) and Somersloops for raw output multiplication.

FULL_QUOTA

Based on the Base Resource Extraction capacity (limits from Sector settings) as the limiting input. Creates a production line that consumes all available resources. Ignores the [GLOBAL ALLOCATION] field.

FULL_QUOTA_MAX_CLOCK

Merges FULL_QUOTA with MAX_CLOCK logic. Uses Base Resource Extraction limits as the bottleneck, while maximizing internal machine efficiency using Somersloops and fully maxed clock speeds.

BELT_SYNC

Similar to MAX_CLOCK/FULL_QUOTA bounding, but ensures all output nodes rigorously adhere to proportional ratios matching standard physical belt throughput speeds (1:2, 1:3, 1:4, 1:5, 1:6, and their reversed multiples). E.g., if max speed is 120, it syncs logic firmly to 60, 40, 30, 24, or 20.

FLEX_RATIO

Employed when multiple output items are bound together. Using [PROPORTIONAL_PARTS] as the ratio (e.g. 1:2:3 for Iron Plate : Iron Rod : Screws), it calculates shared input demands and scales them mathematically. This is evaluated against the shared Base Resource Extraction limit directly.

Recursive Calculation Process

The core computational algorithm resides in /lib/calculator.ts, utilizing a depth-first topological traversal bounded by strict guardrails to prevent cyclic overflow.

// Process Flow Pseudo-Representation

1. Identify output target constraints (Items/min, Flex quotas).

2. Preemptively assert Logistic network capacity to satiate requirements.

3. Process Node Merging: If combined routing, check global cache map.

4. Match specific alternate recipe based on Tier or User Configuration.

5. Calculate Node Rate -> Map to actual Machine outputs via Somersloops & Clock Speeds.

6. Evaluate Inputs -> Trigger calculateRecursive() on downstream components.

7. Post-process bounds mapping byproducts to Waste/Export pipelines.

Furthermore, empirical adjustments track exact power loads utilizing inverse exponential formulas native to the simulator platform (defaulting loosely around 1.321928 scaling curves), guaranteeing pixel-perfect alignment to simulated reality behavior.