# Distribution guide

The [project download](../3d-engine.zip) supplies browser code, local assets, documentation, and supporting examples. Run the workshop to inspect the supplied objects; copy the runtime and selected object folders when building an independent application. The download is a static application distribution, not an npm installation or a hosted runtime service.

## Folder and download roles

| Item | Purpose | Required by a custom application's runtime? |
| --- | --- | --- |
| `engine/` | Public API, generic services, and bundled Three.js | Yes; copy the complete folder. |
| `objects/<package>/` | A model package, its behavior, manifest, helpers, and local assets | Only for packages that the application uses. |
| `shell/` | The supplied workshop, Model Studio, and scene composition | Only when running or adapting the workshop. |
| `docs/` | HTML reading pages, original Markdown guides, licenses, and verification records | Guides are independent of execution; retain applicable license notices when redistributing. |
| `tests/` | Numerical checks and browser fixtures | For verification and development, not ordinary application execution. |
| `tools/` | Local serving, import-boundary checks, standalone-app creation, and public packaging | Development/serving support; the graphics runtime does not import these tools. |
| `templates/starter/`, `templates/object-demo/` | Runnable examples sharing the project's engine and selected objects | Starting points; use `create-app.mjs` to make independent copies. |
| Release manifest | Package identity, entry points, and file hashes where supplied | An integrity/reference record, not a scene dependency. |

The public HTML pages are for reading and navigation. The ZIP is for obtaining the files. Markdown originals remain in the package for editing and reference. Public output retains useful source, operational guides, tests, and tools; old release copies, `.work` scratch folders, and one-time asset harvesting are excluded. Older versioned releases may organize the workshop differently; follow their own entry points.

## Run and relocate

In the extracted full-project folder, run:

```sh
node tools/serve.mjs
```

Open `http://127.0.0.1:8194/` or its `shell/` page. See [getting started](getting-started.html) for prerequisites and an alternate port. The local server serves files from its own project folder; it does not require the original development machine or path.

For an independent application, generate a starter copy:

```sh
node tools/create-app.mjs --template=starter --out=apps/my-app
```

Use `--template=object-demo` to include the people and beach packages. The tool copies the engine and required object folders and corrects the template's imports to the new local layout. The original templates share `../../engine/` and `../../objects/`; copying only those template files would leave that dependency on the surrounding project.

A generated object-demo consumer has this layout:

```text
my-application/
  index.html
  app.js
  engine/
    index.js
    src/
    vendor/
  objects/
    people/
    beach/
```

Import `./engine/index.js` from the consumer and pass that namespace to object constructors. Keep package-internal imports and asset URLs relative. Renaming the outer application folder requires no absolute-path edits. Renaming an object folder requires updating the consumer's imports or Studio package path, while its local imports remain valid.

A copied consumer without `tools/` can run under any suitable static HTTP server. The full project's local server can also serve a consumer nested within it using `--root=relative-folder`. That server option deliberately stays within the server's own project tree. A public static host needs to serve JavaScript modules and asset files with appropriate MIME types; deployment itself is separate from preparing the files.

## Ownership and compatibility

Use the bundled `api.THREE` namespace with the copied engine. Keep `index.js`, `src/`, and `vendor/` together. Copy an object package completely, including optional authored data; copying a single class file can omit its dependencies.

Check the engine version, object protocol, required injected services, and package manifest when upgrading. An object protocol number alone does not establish that every optional feature is available. Keep a restorable copy, replace complete compatible folders, and rerun the consumer's relevant checks. Application-specific input and scene behavior should remain in the application rather than being embedded in every object.

Snapshots restore supported object state and transforms. Shared services and decoded asset data must be supplied again during reconstruction. The [object package reference](object_packages.html) and [creating objects](creating-objects.html) explain this ownership contract.

## Verification before redistribution

The complete project provides:

```sh
npm test
npm run verify
```

The first command runs numerical/API checks; the second audits local references and independent package boundaries. Browser fixtures under `tests/` verify actual rendering and interactions. Use checks appropriate to your changes, including replacement/disposal when resources are rebuilt. Test the actual packaged consumer at its new URL, not only the development source.

`npm run build` invokes `tools/distribute.mjs` to prepare the public folder and ZIP. For a clean public folder that is already prepared, `node tools/package.mjs` recreates its ZIP with every file in that folder except the ZIP itself. Run the build command to prepare a fresh clean output when development tests have created working files. The packaging tool's checks must pass; it is not a way to bypass a failed verification.

A generated distribution still needs its relevant integration and visual checks. A successful archive build does not prove rendering, physical controller compatibility, or simulation accuracy. The [verification guide](verification.html) describes the scope of the supplied checks. These tools prepare local files; publishing them to an external host is a separate action.

## Licenses and commercial use

The project license permits use, modification, and redistribution, including commercial use, subject to its terms and retained notices. Read the actual [project license](licenses/license.txt), including its warranty, liability, and governing-law provisions. This guide does not replace that text.

Bundled Three.js retains its [MIT license notice](licenses/THREE.txt). Included authored human source data is identified as CC0 in its provenance records; keep those records and applicable notices with redistributed assets. Added third-party content may have different terms. See [source provenance](source_provenance.html) for the supplied dependencies and assets.

The engine runs locally without runtime AI, but its finite-world and approximate-physics limits still apply. Public availability and commercial permission are not claims of photographic realism, certified simulation accuracy, or suitability for every use.