Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 41 additions & 86 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,114 +1,69 @@
# Loopset
<p align="center">
<img src="docs/media/readme-hero.png" alt="Loopset — Build a little world. Test a better plan." width="100%">
</p>

**Build a little world. Test a better plan.**
<p align="center">
<a href="https://berkebasbay.github.io/loopset/"><img src="https://img.shields.io/badge/Free%20to%20use-173a2c?style=for-the-badge" alt="Free to use"></a>
<a href="https://berkebasbay.github.io/loopset/"><img src="https://img.shields.io/badge/No%20account-173a2c?style=for-the-badge" alt="No account required"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/Code%20license-MIT-173a2c?style=for-the-badge&labelColor=294b37" alt="Code license: MIT"></a>
</p>

Loopset is a free, open-source process and capacity simulator that runs in your browser. Build a facility, change demand or staffing, and compare completed work, waiting time and resource cost before choosing a plan.
<p align="center">
<strong><a href="https://berkebasbay.github.io/loopset/">Try Loopset →</a></strong> ·
<a href="docs/QUICKSTART.md">Quickstart</a> ·
<a href="CONTRIBUTING.md">Contribute</a>
</p>

**[Try the live app →](https://berkebasbay.github.io/loopset/)** · **[Watch the 30-second tour](https://berkebasbay.github.io/loopset/watch/#short)** · **[Watch the 55-second walkthrough](https://berkebasbay.github.io/loopset/watch/#full)**
Loopset lets you build a small factory, service team or event, then see how a different plan affects queues, waiting and cost. It runs in your browser, with no installation or account.

[![Service Studio in Loopset: specialists, waiting requests and a running process](public/media/loopset-demo.jpg)](https://berkebasbay.github.io/loopset/watch/#full)
## See it in action

**12 editable templates · 24 prepared alternatives · 1,141 browser-ready 3D models**
https://github.com/user-attachments/assets/42cf61e9-e756-4939-8fbe-9a2239fef163

No account, installation, API key or simulation backend. Calculations run locally, and project files stay on your device. Start from a template or a genuinely empty site, then save your own reusable starting points.
<sub>30-second tour · <a href="https://berkebasbay.github.io/loopset/watch/">Captions & downloads</a> · <a href="docs/media/README.md">Video credits</a></sub>

## Compare the trade-off
<details>
<summary><strong>Watch the full walkthrough · 55 seconds</strong></summary>

In the included synthetic **Service Studio**, the Specialists and Resolution steps share the same team. Increasing the shared team from two to three available units produces this comparison:
https://github.com/user-attachments/assets/03fb5577-61f1-4ac8-a22f-95c133f78d10

| Recorded outcome | Original plan · 2 units | Changed plan · 3 units |
| --- | ---: | ---: |
| Completed requests | 66 | 86 |
| Average waiting time | 9.5 min | 5.2 min |
| Modeled resource cost | $85 | $115 |
</details>

The videos show the real edit, **Run & compare**, and the resulting table. Both plans use the same 106 arrivals, one-hour duration and seed 4207. Station counts and the break calendar stay unchanged. These are rounded results from one synthetic case, not a forecast or a promise of savings; resource cost is not total business cost.
## Build. Run. Compare.

| Video | Watch online | Repository file |
| --- | --- | --- |
| Quick tour · 30 seconds | [Watch](https://berkebasbay.github.io/loopset/watch/#short) | [English MP4](public/media/loopset-demo-short.mp4) |
| Full walkthrough · 55 seconds | [Watch](https://berkebasbay.github.io/loopset/watch/#full) | [English MP4](public/media/loopset-demo.mp4) |
- **Build your world.** Choose one of 12 templates or start with an empty site. Drag in equipment, shelves and work areas from 1,141 ready-to-use 3D models.
- **Try a different plan.** Change arrivals, processing time or staffing. Run it and compare completed work, waiting and resource cost.
- **Make it yours.** Save your project, keep alternatives, or turn your setup into a reusable template.

Both videos include English screen text, music and effects. The [watch page](https://berkebasbay.github.io/loopset/watch/) includes captions and a text walkthrough. See the [media notes](docs/media/README.md) for sources and recording scope.
### Pick a place to start

## Your first experiment
| Service Studio | Festival Gate | Little Factory |
| :---: | :---: | :---: |
| <img src="public/previews/templates/service.png" alt="Service Studio: a team sharing specialist capacity" width="260"> | <img src="public/previews/templates/festival.png" alt="Festival Gate: visitors moving through entrance queues" width="260"> | <img src="public/previews/templates/factory.png" alt="Little Factory: machining, inspection and packing" width="260"> |
| Teams & waiting | Arrivals & queues | Production & capacity |

1. Open **Templates → Service Studio** and review its **Project brief**.
2. In **Define process**, select **Specialists**. In **Properties**, change the shared team's **Base available units** from 2 to 3.
3. Choose **Run & compare**. Read completed work, waiting and cost together.
4. Save an alternative or use **Download project JSON** to keep an editable copy. **Save as template** makes a reusable starting point in this browser.
[Explore all templates →](docs/TEMPLATES.md)

For your own layout, choose **Blank** or **Empty site**, place objects, and use **Start a process** when you are ready to simulate. [Follow the quickstart →](docs/QUICKSTART.md)
<details>
<summary><strong>Run locally & develop</strong></summary>

## Start with a question

| Template | Explore |
| --- | --- |
| **Service Studio** | How do priority requests and multiple stages compete for shared specialists? |
| **Festival Gate** | What happens to queues when arrivals come in waves and visitors have limited patience? |
| **Little Factory** | Where does work accumulate across machining, inspection and packing? |
| **Workshop and eight more starters** | Shared work cells, machining, rework, 3D printing, packing, fulfillment, returns, parcel handling and repairs. |

Each starter has an original plan and two prepared alternatives, with editable assumptions and real scene previews. Apply an alternative, calculate it, compare it, or undo it. All examples use synthetic data and the same discrete-event engine. [Browse the template guide →](docs/TEMPLATES.md)

## Build, model and compare

- **Build the facility.** Search the 3D library and drag equipment, shelves, containers and building parts into place. Models load when used; repeated placements share geometry. Layout, elevation, rotation and scale are editable.
- **Define the process.** Connect arrivals, queues, processing steps, routes, delays and exits. Model time distributions, arrival waves, priorities, patience and finite waiting space. Copy steps and edit compatible groups with Undo/Redo.
- **Keep capacity explicit.** Parallel stations, shared resources, installed limits and shifts are separate controls. An extra workstation does not automatically add a worker.
- **Test alternatives.** Run independent replications, matched-input comparisons or a finite capacity search with separate verification runs. Inspect waiting distributions, unfinished work, cost and observed bottleneck candidates.
- **Keep and share your work.** Save projects and personal templates locally. Transfer editable project JSON; export results as JSON, CSV, PNG or HTML, or use print/PDF. Imported data is reviewed before it changes a model.

The workspace separates **Build facility**, **Define process** and **Review results**. A searchable Steps list, complete DOM model editor, keyboard controls and reduced-motion options provide alternatives to manipulating the 3D scene. [Read the workspace guide →](docs/UX_GUIDE.md)

## Run locally

Use **Node.js 24** and npm:
Use Node.js 24 and npm:

```sh
npm ci
npm run dev
```

Open the local address printed by Vite. No credentials or application-server setup are required. `npm run build` produces the static app; `npm run preview` serves that build locally.

The engine also works without the interface:

```sh
npm run build:engine
npm run simulate -- --example service --seed 4207
npm run simulate -- examples/factory.json
```
Open the local address printed by Vite. No API keys or backend setup.

Results retain their input snapshot, seed, engine/RNG identity and calculation limits. [Use the headless API →](docs/API.md)
The engine also runs without the interface. See the [Engine API](docs/API.md), [model guide](docs/MODEL_GUIDE.md), and [contribution guide](CONTRIBUTING.md).

## What the simulation represents
</details>

The miniature world illustrates a process. Walking, scenery, camera position and replay speed do not change numerical outcomes or add physical travel time. A 3D machine model does not supply measured processing times, collision physics, CAD analysis or inventory-assembly behavior.

Synthetic examples are not calibrated business forecasts. A single run does not establish statistical confidence; repeated experiments help examine uncertainty. Incomplete calculations and limited replay remain explicitly identified.

Browser storage belongs to the current site address and browser. Download project JSON backups to transfer work or protect it from cleared storage.

## Documentation

[Quickstart](docs/QUICKSTART.md) · [Templates](docs/TEMPLATES.md) · [Facility guide](docs/FACILITY_GUIDE.md) · [Workspace guide](docs/UX_GUIDE.md) · [Model contract](docs/MODEL_GUIDE.md) · [Engine API](docs/API.md) · [Examples](examples/README.md) · [Testing](docs/QUALITY.md) · [Static hosting](docs/DEPLOYMENT.md)

## Contribute

Useful contributions include a template with a clear process question, a focused bug fix, an accessible editing improvement, a clearer guide or an independently reasoned engine test.

[Open an issue](https://github.com/berkebasbay/loopset/issues/new/choose) with a small synthetic example, or propose a focused pull request. For larger changes, discuss the problem and scope first. [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, model boundaries and the required checks. Pull requests are welcome and reviewed for correctness, usability and maintainability.

```sh
npm run typecheck
npm test -- --maxWorkers=1
npm run build
npm run test:headless
```
## Help build Loopset

Report vulnerabilities through [SECURITY.md](SECURITY.md).
New templates, clearer guides, accessible interactions and focused bug fixes are welcome. [Open an issue](https://github.com/berkebasbay/loopset/issues/new/choose) or [send a pull request](CONTRIBUTING.md).

## License and credits
---

Original Loopset code is [MIT licensed](LICENSE). Third-party models, textures, fonts, music and effects retain their own terms; they are not all MIT. See [third-party notices](THIRD_PARTY_NOTICES.md), [NVIDIA asset sources and adaptations](docs/NVIDIA_ASSETS.md), and [demo media credits](docs/media/README.md).
<sub>The 3D scene illustrates your process model; walking and layout do not change the calculation. Examples use synthetic data. <a href="docs/MODEL_GUIDE.md">Modeling scope</a> · Original code: <a href="LICENSE">MIT</a>. Artwork, fonts and media retain their <a href="THIRD_PARTY_NOTICES.md">own licenses</a>.</sub>
4 changes: 4 additions & 0 deletions docs/media/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,7 @@ Stock music and effects are incorporated into the films; their standalone source
The PNG screenshots in this directory document the RC14 workspace, template gallery and recorded-result surfaces. `loopset-facility.png` uses the enhanced Little Factory layout; its source is [`examples/facility.json`](../../examples/facility.json). `loopset-compare.png` shows that Factory's separate station/team experiment, 40 → 77 completed orders; it is not the Service Studio comparison in the current films.

`public/previews/templates/` contains the twelve starter scene previews. All models and examples shown are synthetic. Original browser captures omit local-origin footers. NVIDIA CC BY 4.0 models, Quaternius/Poly Haven CC0 material and fonts retain the creator/source/license records linked above.

## Repository artwork

`readme-hero.png` and the site social card combine the Loopset cube mark, DM Sans and real Service Studio/Festival Gate starter previews. They use the same source artwork and credits listed above; the cards are editorial layouts, not additional product controls.
Binary file added docs/media/readme-hero.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified public/social-card.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading