ASTRA 3DENGINE & WORKSHOP

Getting started

Astra 3D Engine runs in a browser and includes a workshop for inspecting objects, terrain, motion, lighting, and flight. Its runtime and supplied assets are local files. It does not call an AI service, require user photographs, or depend on an external asset host.

Run the download locally

  1. Download the project and extract it. Keep the extracted folder structure together.
  2. Install Node.js 24 or later if it is not already available. Use a browser with WebGL2 and hardware graphics support.
  3. Open a terminal in the extracted project folder and run:

``sh node tools/serve.mjs ``

  1. Open http://127.0.0.1:8194/ for the project pages, or http://127.0.0.1:8194/shell/ for the workshop. Leave the terminal running while using the application. Press Ctrl+C in that terminal to stop the server.

No dependency installation or build step is needed to run the supplied project. Node runs the local file server; the browser runs the graphics. The server binds to the local computer. If port 8194 is occupied, run node tools/serve.mjs --port=8195 and use port 8195 in the browser address.

Do not open index.html through a file:// address. Browser module imports and asset loading need HTTP. An existing static HTTP server can also serve the folder; open the project's shell/ path beneath that server's URL.

Inspect the workshop

Start in Model Studio. Choose an available model, then Add or Replace selected. The inspector exposes the selected object's properties and actions. Frame selected centres the camera. The side panel scrolls to additional controls.

Left drag orbits by default. The Camera panel also offers pan and free look. Click the viewport before using W/A/S/D, Q/E, or arrow-key camera controls. Pausing animation does not prevent camera navigation. See Model Studio and camera and controller controls for the complete controls.

The other scenes exercise different uses of the engine. Flight includes guided and manual views; its Location menu opens landscape inspection points. The beach scene demonstrates shared object behavior and environment services. These are sample applications, not features that an independent consumer must load.

Start your own application

Open http://127.0.0.1:8194/templates/starter/ to see engine-only scene setup and simple 3D contacts, or http://127.0.0.1:8194/templates/object-demo/ for a person and umbrella with working controls. These in-project templates share the project's engine and object folders.

To create a standalone application with its own dependency copies, run one of these from the full project's root:

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

Or select --template=object-demo to include the people and beach packages. Open http://127.0.0.1:8194/apps/my-app/ while the local server is running. You can later move or rename that complete generated application folder and serve it from another location; its imports are local to the copy. Copying a shared-runtime template folder by itself is not the standalone creation procedure.

In an application that you assemble yourself, the public import is relative to that application's files:

import * as api from './engine/index.js';
import {BeachUmbrella} from './objects/beach/index.js';

const umbrella = new BeachUmbrella(api, {radius: 1.2});
scene.add(umbrella.root); // scene is provided by your Engine.mount factory
umbrella.setOpen(true);

Copy the entire engine folder, including src/ and vendor/, and use its exported THREE namespace. Copy each object folder as a unit. Objects receive the engine API through their constructor; they do not contain a fixed path to your engine.

Your application supplies the canvas, scene, camera, input, update loop, and resource ownership. Register object disposal in the scene scope, for example scope.own(umbrella). The API reference includes the complete mount/update pattern and documents the engine services.

Check or build a distribution

From the complete project, npm test runs the Node checks, npm run verify audits the local dependency boundaries, and npm run build runs the public distribution builder. These commands do not deploy to an external host. See the distribution guide for what each output contains.

Know the boundaries

The engine supports three-dimensional positions, orientations, meshes, and collision queries. The generated landscape is finite, and its terrain is a heightfield. Motion, flight, water, and weather are approximations intended for interactive applications; this is not a general rigid-body, aerodynamic, or fluid simulation. Supplied scenes do not guarantee photographic realism.

For reusable models, continue with creating objects and the object package reference. For folder roles, copying, public distribution, and licenses, read the distribution guide. The FAQ covers common setup and usage questions.

Download the original Markdown