# FactoryForge

C++20 warehouse logistics puzzles with a desktop map editor. Windows and Linux
are the intended desktop platforms. This independent repository belongs to the
AppFabrik portfolio. Version 0.1.0 is developed in tested, chronological commits.

## Try the desktop app

```bash
bash scripts/dev.sh
```

Choose one of five puzzles. Green cells are inbound, gold cells are storage and
purple cells are outbound. Paint roads between the stations and the blue vehicle
homes. Validate, start and deliver every order before the deadline. Parallel
roads and free loading ports reduce waiting. Each puzzle includes a reference
solution. Pause, step and 1×/2×/4× speed do not change the simulation rules.

Create a custom map from **New map**, place stations and vehicles, and add orders
with cell coordinates. Wheel zooms, Ctrl+drag pans, left drag paints and right
drag erases. Ctrl+Z/Ctrl+Shift+Z undo and redo. Ctrl+S saves the starting layout,
not a running simulation. Failed imports and cancelled close keep your draft.
The DE/EN button changes language without discarding input. Puzzle results and
language are stored in the local application settings. No account or network
connection is required while playing.

![FactoryForge map editor](docs/screenshots/factoryforge-editor.png)

## Core architecture

The framework-free core models a grid, delivery orders, vehicles and budgets.
Static A* finds connected routes. A rolling 12-tick reservation window plans
vehicle movement conservatively and prevents shared-cell and opposite-edge
collisions. Waiting vehicles gain priority. This is a bounded heuristic, not an
optimal multi-agent planner. A layout can still deadlock and reports waiting
instead of allowing vehicles to pass through each other.

One simulation tick represents 100 ms. Rendering and speed never change logical
time. Orders are assigned to the nearest reachable pickup with stable tie
breaking. After delivery, vehicles return to their home cell to free the ports.
The five built-in puzzles include reproducible solution layouts and tests.

```bash
bash scripts/check.sh core
```

Requires GCC 13 or MSVC 2022, CMake 3.25+, Ninja and clang-format. GoogleTest
1.15.2 is downloaded into the ignored build directory on first configuration.
Qt is unnecessary for this core-only build.

## Application and project files

The application service runs the core in a stoppable C++20 `std::jthread` and
publishes value snapshots under a mutex. Pause and single-step preserve logical
time. The document service provides bounded undo history and compares with the
saved document to retain correct dirty state after undo, redo and branching.

The repository interface has a Qt JSON adapter. `.factoryforge` files use format
version 1 and are limited to 4 MiB, 128 × 128 cells, 50 vehicles and 10000 orders.
Drafts may be incomplete. Starting a simulation additionally checks budgets,
endpoints and connectivity. Failed imports preserve the current draft. Atomic
save never falls back to overwriting an existing file directly.

```bash
bash scripts/check.sh dev
```

This build also requires Qt 6.4+ Core, Gui, Widgets and Test. `scripts/env.sh`
recognizes the optional user-local Qt 6.8.3 toolchain.
## Console and distribution

```bash
build/release/factoryforge-cli --puzzle 4
build/release/factoryforge-cli --project assets/puzzles/puzzle-5-solution.factoryforge
build/release/factoryforge-cli --benchmark 50
```

The CLI exits with 0 for a solved scenario, 1 for a failed deadline and 2 for
invalid input. It writes JSON metrics. The ten project fixtures include all
puzzles and reference solutions. [Performance results](docs/performance.md)
explain the measured workload and limits.

Build packages with `python3 scripts/package_linux.py --qt /path/to/Qt/6.8.3/gcc_64`
after `cmake --preset release` and `cmake --build --preset release`. On Windows use
`scripts/package_windows.ps1` with Qt/MSVC tools in PATH. The GitHub workflow
contains native Linux/GCC and Windows/MSVC builds. It has not run remotely yet.

The Linux bundle targets Ubuntu 24.04 x64 and includes Qt/ICU runtime libraries,
platform plugins, puzzle files, launchers, licence texts and a SHA-256 checksum.
It has been smoke-tested locally. The Windows build and package still require
native Windows verification. Neither package is publicly released yet.

For user-local Linux tooling, run `bash scripts/setup.sh`. GCC 13 and Ninja must
be available. To use a modified Qt installation set `FACTORYFORGE_QT` before
running the scripts, or configure CMake directly with `CMAKE_PREFIX_PATH`.


## Learning and portfolio

[Nine executable lessons](assets/tutorials/README.md) begin with the first C++
program and connect to the real editor and simulation. Run them with
`python3 scripts/verify_tutorials.py` after sourcing `scripts/env.sh`.
[The German case study](docs/portfolio-case-study.md) explains the architecture,
tradeoffs and evidence to discuss in interviews.

## Licence and source availability

Application source is Apache-2.0. Qt is dynamically linked and retains its own
licence. Screenshots contain only the included sample puzzles. No GitHub remote
or public release has been configured yet.
