Distribution guide

The project download 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

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:

node tools/serve.mjs

Open http://127.0.0.1:8194/ or its shell/ page. See getting started 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:

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:

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 and creating objects explain this ownership contract.

Verification before redistribution

The complete project provides:

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 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, including its warranty, liability, and governing-law provisions. This guide does not replace that text.

Bundled Three.js retains its MIT license notice. 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 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.

Download the original Markdown