120 lines
4.4 KiB
Markdown
120 lines
4.4 KiB
Markdown
# WebEditor3D
|
|
|
|
WebEditor3D is a browser-based engine/editor for authoring interactive 3D
|
|
environments and running them immediately in the browser.
|
|
|
|
The core loop is:
|
|
|
|
1. author a scene
|
|
2. save or load the project
|
|
3. enter run mode without leaving the editor
|
|
|
|
The project is focused on fast whiteboxing, imported assets, typed entities,
|
|
simple interactions, and web-native delivery. It is not intended to replace
|
|
Blender, CAD tools, or a general-purpose engine platform.
|
|
|
|
## Current Capabilities
|
|
|
|
- Whitebox authoring with box, wedge, cylinder, cone, and torus primitives.
|
|
- Object transforms plus face, edge, and vertex selection foundations.
|
|
- Per-face materials, UV controls, climbable faces, water volumes, and light
|
|
volume settings for whitebox solids.
|
|
- Authored terrain with sculpt and paint tools.
|
|
- GLB/GLTF model import, including multi-file GLTF packages and Draco assets.
|
|
- Imported image and audio assets stored in the project asset registry.
|
|
- Placed `modelInstances` with explicit collision modes.
|
|
- Typed entities such as `PlayerStart`, `SceneEntry`, `NPC`, `CameraRig`,
|
|
`TriggerVolume`, `TeleportTarget`, `Interactable`, local lights, and sound
|
|
emitters.
|
|
- Interaction links for runtime behavior such as teleport, visibility, audio,
|
|
animation, control effects, and sequences.
|
|
- Multi-scene project state with scene loading screen settings.
|
|
- Project-wide time, day/night lighting, scheduler routines, sequence authoring,
|
|
and dialogue foundations.
|
|
- Built-in runner with first-person and third-person navigation, Rapier
|
|
collision, scene transitions, dialogue overlay, spatial audio, and animation
|
|
playback.
|
|
- Multi-viewport editor layout with perspective, top, front, and side views.
|
|
|
|
## Getting Started
|
|
|
|
Use a current Node.js LTS release.
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Vite will print a local URL, typically `http://localhost:5173/`.
|
|
|
|
## Common Scripts
|
|
|
|
```bash
|
|
npm run dev # start the Vite dev server
|
|
npm run build # typecheck and build the app
|
|
npm run typecheck # run TypeScript without emitting files
|
|
npm run lint # run ESLint
|
|
npm test # run Vitest tests
|
|
npm run test:watch # run Vitest in watch mode
|
|
npm run test:browser # run Playwright browser tests
|
|
npm run test:e2e # alias for Playwright browser tests
|
|
```
|
|
|
|
## Project Files
|
|
|
|
User-facing save/load uses portable `.we3d` project packages. A package is a zip
|
|
archive containing canonical project JSON plus referenced assets.
|
|
|
|
Important format boundaries:
|
|
|
|
- The editable project format is the `.we3d` project package.
|
|
- The canonical document is versioned and migrated through serialization code.
|
|
- Runtime output is separate from editable save/load.
|
|
- Blob URLs are transient loading details, not persisted asset references.
|
|
|
|
## Architecture Map
|
|
|
|
- `src/document`: canonical project and scene document state.
|
|
- `src/commands`: undoable editor mutations.
|
|
- `src/geometry`: derived whitebox, terrain, mesh, and collider generation.
|
|
- `src/viewport-three`: editor viewport rendering and interaction helpers.
|
|
- `src/runtime-three`: play-mode runtime, scene build, collision, scheduling,
|
|
audio, navigation, interactions, and scene transitions.
|
|
- `src/assets`: imported model, image, audio, and asset storage adapters.
|
|
- `src/entities`: typed scene objects with editor/runtime semantics.
|
|
- `src/interactions`: authored trigger/action links.
|
|
- `src/controls`, `src/scheduler`, `src/sequencer`, `src/dialogues`: shared
|
|
control surface, time-based orchestration, sequence steps, and dialogue data.
|
|
- `src/serialization`: JSON serialization, migrations, autosave, and `.we3d`
|
|
package import/export.
|
|
- `src/app`: React editor shell and panels.
|
|
- `src/runner-web`: React wrapper for the built-in runner canvas.
|
|
|
|
## Development Notes
|
|
|
|
- `ProjectDocument` / `SceneDocument` is the source of truth.
|
|
- Editor-authored mutations should go through commands.
|
|
- Three.js scenes, meshes, materials, and runtime objects are derived state.
|
|
- Imported assets live in the asset registry.
|
|
- Placed imported assets live in `modelInstances`.
|
|
- Typed runtime/editor objects live in `entities`.
|
|
- Global ambient, sun, background, fog, and project time live in project/world
|
|
settings.
|
|
|
|
## Verification
|
|
|
|
For a normal code change, run the narrowest relevant checks. Useful defaults are:
|
|
|
|
```bash
|
|
npm run typecheck
|
|
npm test
|
|
npm run test:browser
|
|
```
|
|
|
|
Use Playwright tests when browser behavior, rendering, input, or the built-in
|
|
runner is part of the change.
|
|
|
|
## License
|
|
|
|
No license file is currently included in this repository.
|