giers10/webeditor3d
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2b599b8f49f85d1160290e8f6d6631121df26840
webeditor3d/README.md

4.4 KiB
Raw Blame History

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.

npm install
npm run dev

Vite will print a local URL, typically http://localhost:5173/.

Common Scripts

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:

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.