Skip to content
hoanghaingPublic

About

Hybrid 3D XML Editor - Based on Three.js

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

57 Commits

Folders and files

Repository files navigation

h3xEditor

An embeddable 3D home editor built on h3x.js. Start from a 2D floor layout, see it as a 3D house, and furnish it by dragging and dropping presets. No 3D skills needed.

Status: in active redesign. The engine core (h3x/core) is done in the h3x.js repo. This repo currently holds the legacy prototype (Express + EJS + three.js r128). The prototype will be replaced by a TypeScript + Vue 3 editor library. After that, the legacy-ejs tag keeps the old prototype available.

What it is

h3xEditor is a library, not a website. It ships a complete editor that any app can embed:

<H3xEditor :catalog="catalog" :storage="storage" locale="vi" @change="onChange" />

Apps that don't use Vue will be able to call mountH3xEditor(element, options) instead.

Everything specific to a product comes in through options:

  • the preset catalog (URL or object)
  • the storage adapter
  • the locale
  • the theme
  • extension hooks

The editor itself contains no hosting, accounts or payment logic.

Planned for phase 1 (one floor)

  • Pick a sample layout. Common Vietnamese floor plans: tube houses 4×16 / 5×20, studio, 1–3 bedroom apartments, L-shaped single-storey house, single room.
  • Reshape it in 2D. Drag wall nodes, drag walls, or type wall lengths. Live dimensions are shown while dragging. Shapes that break the layout are rejected.
  • See it in 3D. Walls with door and window cut-outs, and floors per room. Change wall and floor finishes.
  • Furnish it. Drag presets onto the floor, a wall or the ceiling. Physical rules are enforced: nothing clips through walls, floats, or overlaps.
  • Room areas are computed automatically.
  • Saving. Projects autosave in the browser (IndexedDB), and you can import/export .h3x files (XML).
  • Language. Vietnamese UI by default, with English available.

Out of scope for now: drawing walls freely, multiple floors, roofs and stairs, accounts, and cloud sync.

Architecture

Layer Repo Role
h3x.js hoanghaing/h3x.js The engine. h3x/core holds the data model, XML, undo/redo, validation and collision checks. h3x/three (3D), h3x/plan (2D SVG) and h3x/vue are coming.
h3xEditor this repo The embeddable editor UI built on h3x.js: panels, preset library, layouts, storage, i18n.
Product website separate, later The branded app that uses h3xEditor: hosted preset catalog (Cloudflare R2), accounts (Cloudflare Workers).

2D and 3D are two views of one model. An edit in either view goes through an h3x command, so it can be undone, and both views update from the same change events.

Planned screen layout

  • Top bar: new / open / save / export, undo / redo, and a 2D | 3D | Split view switch.
  • Left: the Layouts and Objects tabs, with search and drag & drop.
  • Center: the viewport.
  • Right: properties of the selection (wall length, thickness and finishes; opening size and position; room name and floor; item variant and rotation).
  • Bottom: total area, room count, and placement warnings.

Catalog (provided by the host app)

{
  "version": 1,
  "baseUrl": "https://assets.example.com/",
  "categories": [{ "id": "living", "name": { "vi": "Phòng khách", "en": "Living room" } }],
  "finishes": [{ "id": "paint-white", "kind": "wall", "name": { "vi": "Sơn trắng" }, "color": "#f5f5f0" }],
  "presets": [{
    "id": "sofa-3s-01", "name": { "vi": "Sofa 3 chỗ", "en": "3-seat sofa" },
    "category": "living", "mount": "floor",
    "footprint": { "w": 2.1, "d": 0.9, "h": 0.85 },
    "model": "models/sofa-3s-01.v1.glb", "thumbnail": "thumbs/sofa-3s-01.webp",
    "tier": "free"
  }],
  "layouts": [{ "id": "nha-ong-4x16", "name": { "vi": "Nhà ống 4×16m" }, "file": "layouts/nha-ong-4x16.h3x" }]
}

mount is one of floor, wall, ceiling or opening. Models are glTF/GLB files: origin at the bottom center of the footprint, front facing +Z. Keep each model light, about 5–20k triangles with textures of 1K or less.

Roadmap

  1. ✅ h3x/core: model, XML, undo/redo, room detection, layout and placement validation (in h3x.js)
  2. h3x/three: render walls (with openings), floors and presets, plus camera and axis gizmo
  3. h3x/plan: 2D SVG plan view and layout editing
  4. Constrained drag & drop of catalog presets in 2D and 3D
  5. h3xEditor: full editor UI, IndexedDB storage, import/export, i18n, sample layouts, playground
  6. UMD build / mountH3xEditor, the Vue wrapper, API docs

Running the legacy prototype

npm install
npm start          # http://localhost:8888

License

MIT

About

Hybrid 3D XML Editor - Based on Three.js

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages