diff --git a/README.md b/README.md index dc4712c..5cdcff3 100644 --- a/README.md +++ b/README.md @@ -10,17 +10,21 @@

Try Loopset → · - Quickstart · + Documentation · Contribute

-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. +**A simulation playground for process ideas.** Build a factory, a service team or an event. Change how work arrives, how long it takes or who is available, then see what happens to queues, waiting and cost. + +Loopset is free and runs in your browser. Your projects stay on your device, with no account or installation required. ## See it in action +From a working template to a real comparison: explore the world, change the shared team and run the next plan. + https://github.com/user-attachments/assets/42cf61e9-e756-4939-8fbe-9a2239fef163 -30-second tour · Captions & downloads · Video credits +30-second tour · Captions & downloads · Media credits
Watch the full walkthrough · 55 seconds @@ -29,23 +33,64 @@ https://github.com/user-attachments/assets/03fb5577-61f1-4ac8-a22f-95c133f78d10
-## Build. Run. Compare. +## A tour of the workspace + +### 01 · Start with a world you can change + +Choose from **12 editable templates**, each with a starting plan and two prepared alternatives, or start with an empty site. Arrange your facility with **1,141 ready-to-use 3D models**, then define the process that makes it work. + +

+ The real Service Studio workspace with the process scene, specialist properties, replay controls and recorded results +

+ +Service Studio: reception, specialists and resolution in one editable workspace. Build your own facility → + +### 02 · Turn a question into an experiment + +Select a step and adjust processing time, parallel stations or the team it needs. Stations, people and shifts are separate decisions. In this example, the shared specialist team changes from **2 available units to 3**, while the station count and break plan stay the same. + +

+ Actual Shared specialists control changed from two to three available units, with the unchanged installed limit and shift controls +

+ +The real editor, enlarged in the walkthrough. Try this experiment → + +### 03 · See the result and the trade-off + +Run the changed plan and compare it with the original. Here, completed requests rise from **66 to 86** and average waiting falls from **9.5 to 5.2 minutes**. The extra capacity also raises modeled resource cost from **$85 to $115**. + +

+ Actual Service Studio comparison: completed requests 66 to 86, average wait 9.5 to 5.2 minutes, and resource cost 85 to 115 dollars +

+ +One synthetic example: 106 arrivals, one hour, seed 4207. Results depend on the model's assumptions; resource cost is not total business cost. How to read a result → -- **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. +Save the plan, keep it as a reusable template, or download an editable project file. Repeated experiments and matched-input comparisons are available when you want to investigate uncertainty beyond a single run. -### Pick a place to start +## Find your starting point | Service Studio | Festival Gate | Little Factory | | :---: | :---: | :---: | -| Service Studio: a team sharing specialist capacity | Festival Gate: visitors moving through entrance queues | Little Factory: machining, inspection and packing | +| Service Studio: shared specialists and waiting requests | Festival Gate: arrival waves and entrance queues | Little Factory: machining, inspection and packing | | Teams & waiting | Arrivals & queues | Production & capacity | -[Explore all templates →](docs/TEMPLATES.md) +The collection also includes workshops, machining, rework, 3D printing, packing, fulfillment, returns, parcel handling and repairs. [Explore the templates and their experiments →](docs/TEMPLATES.md) + +## Documentation + +**[Browse all guides →](docs/README.md)** + +| I want to… | Start here | +| --- | --- | +| Run my first experiment | [Quickstart](docs/QUICKSTART.md) · [Starter templates](docs/TEMPLATES.md) | +| Build a facility and edit its process | [Facility guide](docs/FACILITY_GUIDE.md) · [Workspace guide](docs/UX_GUIDE.md) | +| Understand assumptions and results | [Model guide](docs/MODEL_GUIDE.md) · [Export and sharing](docs/SHARING.md) | +| Use the engine in my own project | [Headless API](docs/API.md) · [Architecture](docs/ARCHITECTURE.md) | +| Develop, test or host Loopset | [Contributing](CONTRIBUTING.md) · [Testing](docs/QUALITY.md) · [Static hosting](docs/DEPLOYMENT.md) | +| Find artwork sources and licenses | [Asset catalogue](docs/CATALOGUE.md) · [Asset attribution](docs/NVIDIA_ASSETS.md) · [Media credits](docs/media/README.md) |
-Run locally & develop +Run locally Use Node.js 24 and npm: @@ -54,15 +99,13 @@ npm ci npm run dev ``` -Open the local address printed by Vite. No API keys or backend setup. - -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). +Open the local address printed by Vite. No API keys or backend setup are required. The [contribution guide](CONTRIBUTING.md) covers checks and development conventions.
## Help build Loopset -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). +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). For a larger change, discuss the problem and scope first. --- diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index bccf949..98b76cd 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -11,7 +11,7 @@ npm ci npm run dev ``` -Open the address printed by Vite. Choose **Little Factory**, **Festival Gate** or **Service Studio**; examples calculate on opening. **New model** starts a valid arrival → waiting → processing → completion flow. +Open the address printed by Vite. Use **Templates** to choose **Service Studio**, **Festival Gate**, **Little Factory** or another starter; examples calculate on opening. **Blank** starts an empty site, and **Start a process** adds a valid arrival → waiting → processing → completion flow when you are ready. The working surface has a world, a searchable **Steps** list, contextual **Properties**, and **Run simulation**. **Tools → Model editor** keeps the complete professional model available when you need it. @@ -27,6 +27,23 @@ For a custom facility, choose **Build facility → Empty site**. This starts wit Use Undo/Redo or **Action history** to reverse model edits. Restoring a saved scenario changes the draft; calculate it to get a new result. +## Reproduce the Service Studio demo + +1. Open **Templates → Service Studio** and let the original plan finish calculating. +2. In **Define process**, select **Specialists** in the world or Steps list, then open **Properties**. +3. Under **Team or equipment → Shared specialists**, change **Base available units** from **2** to **3** and apply the field with Enter. Leave **Parallel stations**, the installed limit and the shift/break plan unchanged. +4. Choose **Run & compare**. The original remains the baseline for the comparison. + +With the starter's one-hour duration and seed 4207, the same 106 realized arrivals produce these rounded results: + +| Outcome | Original · 2 shared units | Changed · 3 shared units | +| --- | ---: | ---: | +| Completed requests | 66 | 86 | +| Average waiting time | 9.5 min | 5.2 min | +| Modeled resource cost | $85 | $115 | + +This is one synthetic example. The arrival estimate in Scenario settings is an expectation; the actual count comes from the recorded run. Cost is a modeled resource charge, not total business cost. The [model guide](MODEL_GUIDE.md#measurement-and-interpretation) explains which work contributes to each metric and how repeated experiments help examine uncertainty. + ## Change duration or demand **Scenario settings**, beside Run, offers 30-minute, 1-hour, 8-hour and custom durations. Choose seconds, minutes, hours or days for display. Changing the unit alone leaves the model unchanged. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..eb17744 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,60 @@ +# Loopset documentation + +Build a process, test a plan and understand the result. These guides cover the browser workspace, modeling rules, experiments and the standalone engine. + +**[Open Loopset →](https://berkebasbay.github.io/loopset/)** · [Watch the demos](https://berkebasbay.github.io/loopset/watch/) · [Project overview](../README.md) + +## Choose a starting point + +| Your goal | Follow this path | +| --- | --- | +| Try Loopset for the first time | [Quickstart](QUICKSTART.md) → [Service Studio video experiment](QUICKSTART.md#reproduce-the-service-studio-demo) | +| Build a layout from scratch | [Facility guide](FACILITY_GUIDE.md) → [Workspace controls](UX_GUIDE.md) | +| Explore a ready-made process | [Starter templates](TEMPLATES.md) → [Read a result carefully](TEMPLATES.md#read-a-result-carefully) | +| Understand results and uncertainty | [Read results in the workspace](UX_GUIDE.md#read-results-and-keep-alternatives) → [Measurement and interpretation](MODEL_GUIDE.md#measurement-and-interpretation) | +| Integrate or extend the engine | [Headless API](API.md) → [Architecture](ARCHITECTURE.md) → [Contributing](../CONTRIBUTING.md) | + +## Use the application + +| Guide | What you will find | +| --- | --- | +| [Quickstart](QUICKSTART.md) | Open a template, try a capacity decision, reproduce the demo, calculate, save and reopen a project. | +| [Workspace guide](UX_GUIDE.md) | Properties, demand and duration, teams and shifts, process editing, comparisons, replay, keyboard controls and smaller screens. | +| [Build a facility](FACILITY_GUIDE.md) | Start empty, place and arrange objects, connect process cells, save templates and transfer the complete facility. | +| [Starter templates](TEMPLATES.md) | All twelve starters, their process questions, two alternatives each, assumptions and personal templates. | +| [Export and share](SHARING.md) | Choose project JSON, run JSON, CSV, PNG, HTML or print/PDF and keep the calculation context with the result. | + +## Understand the simulation + +The visual world and the numerical model have different roles. Artwork and walking make a process easier to follow; arrivals, durations, routing, queues and capacity determine its results. + +- [Model guide](MODEL_GUIDE.md): process steps, distributions, priorities, patience, resources, calendars, event ordering, measurement, reproducibility and CSV inputs. +- [Measurement and interpretation](MODEL_GUIDE.md#measurement-and-interpretation): completed versus unfinished work, waiting samples, percentiles, warm-up, replay limits and uncertainty. +- [Replications and paired comparisons](API.md#replications-and-paired-comparisons): run repeated experiments and compare compatible plans through the headless API. +- [Bounded capacity search](API.md#bounded-capacity-search): search a finite set of shared-resource capacities and retain separate verification runs. +- [Portable examples](../examples/README.md): synthetic reference projects and reproducible command-line runs. + +The supplied examples are learning models. Real decisions need appropriate inputs, validation and an understanding of uncertainty. A single run is not a general improvement guarantee. + +## Develop and deploy + +| Guide | What you will find | +| --- | --- | +| [Headless API](API.md) | Build/import commands, public exports, project validation, one run, replay statistics, experiments and the CLI contract. | +| [Architecture](ARCHITECTURE.md) | Model, calculation, rendering and storage boundaries; immutable results; templates and empty layouts. | +| [Contributing](../CONTRIBUTING.md) | Where to make a change, what evidence to include, template/demo exports and publication checks. | +| [Testing](QUALITY.md) | Automated coverage and browser smoke-check commands. | +| [Static hosting](DEPLOYMENT.md) | Build a static deployment, configure a subpath, serve media and verify the deployed source revision. | +| [Security](../SECURITY.md) | Supported reporting and handling of vulnerabilities. | + +## Assets, media and licenses + +- [Prepared asset catalogue](CATALOGUE.md): the browser-ready inventory, source preparation and verification. +- [World assets and attribution](NVIDIA_ASSETS.md): model, people, surroundings and lighting sources, plus browser adaptations. +- [Demo media](media/README.md): videos, screenshots, repository artwork, recording scope and credits. +- [Third-party notices](../THIRD_PARTY_NOTICES.md): the separate licenses for dependencies, artwork, fonts, music and effects. +- [Code license](../LICENSE): MIT terms for original Loopset code. + +## Get help + +[Open an issue](https://github.com/berkebasbay/loopset/issues/new/choose) with a small synthetic example, the actions you took and the result you expected. Keep personal or customer data out of public examples. diff --git a/docs/media/README.md b/docs/media/README.md index bc7bcff..1bf87da 100644 --- a/docs/media/README.md +++ b/docs/media/README.md @@ -20,6 +20,10 @@ Stock music and effects are incorporated into the films; their standalone source ## Interface screenshots +`loopset-service-workspace.png` shows the actual Service Studio workspace before the recorded team change. It is taken from the same high-resolution native capture used in the current films. The full-run metrics and the replay's momentary scene counters describe different scopes. + +`loopset-service-edit.png` and `loopset-service-compare.png` are stills from the published English walkthrough, at 34.4 and 39.5 seconds. They retain the real editor/table and the film's larger editorial annotations. The field has been applied before the edit still; the comparison shows the same synthetic case described above. No interface control or numerical value was reconstructed for these images. + 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. diff --git a/docs/media/loopset-service-compare.png b/docs/media/loopset-service-compare.png new file mode 100644 index 0000000..148ab4a Binary files /dev/null and b/docs/media/loopset-service-compare.png differ diff --git a/docs/media/loopset-service-edit.png b/docs/media/loopset-service-edit.png new file mode 100644 index 0000000..43e2ff1 Binary files /dev/null and b/docs/media/loopset-service-edit.png differ diff --git a/docs/media/loopset-service-workspace.png b/docs/media/loopset-service-workspace.png new file mode 100644 index 0000000..7d89ba9 Binary files /dev/null and b/docs/media/loopset-service-workspace.png differ