Luma District / 栖光街区

An open experiment for an immersive commerce district: real-world routes become claimable 3D storefronts, merchants configure buildings and campaigns, shoppers walk the street, enter stores, add products to cart, and complete a checkout flow.

栖光街区不是一个普通 3D Demo，而是一个开放的 Commerce World Protocol + 3D ecommerce renderer 实验。目标是让真实商家、真实商品、真实营销位和真实地图路线可以组合成一个可扩展的沉浸式商业街区。

Why Open Source

High-quality 3D commerce is not only a frontend problem. It needs protocol design, SaaS architecture, WebGL/WebXR engineering, Blender/DCC pipelines, PBR materials, city assets, interaction design, and retail merchandising taste.

This repository is opened so designers, 3D artists, WebGL engineers, ecommerce builders, and SaaS architects can improve the idea together.

Current MVP

• First-person 3D street rendered with React Three Fiber.
• Merchant and shopper entries in the same app.
• Claimable building positions generated from a route projection model.
• Building templates for flagship towers, boutiques, and corner showrooms.
• Store interior with shelves, product objects, cashier, guide, cart, and checkout flow.
• Commerce World Protocol types for platform bindings, store manifests, modules, commands, events, and marketing campaigns.
• Configurable marketing slots: roof sign, street window, entrance screen, and corner billboard.
• Theme packages separated from the renderer.
• Basic WebXR button mount for future VR entry.

This is still an early prototype. The current art direction is not production quality yet.

Architecture

The project separates commerce logic from 3D rendering:

• src/domain/commerce.ts: stores, products, routes, plots, building templates, merchant onboarding drafts.
• src/domain/protocol.ts: commerce-world protocol, platform capabilities, store modules, commands, events, marketing campaigns.
• src/services/routeProjection.ts: projects map routes into street paths and claimable plots.
• src/services/storeManifest.ts: creates a data-driven store manifest.
• src/services/marketingCampaigns.ts: maps merchant marketing data to renderable campaign slots.
• src/services/buildingMarketingSlots.ts: converts campaign slots into deterministic 3D surfaces.
• src/world/WorldStage.tsx: 3D renderer over domain data.
• src/components/MerchantWorkspace.tsx: merchant onboarding and publishing workflow.

More detail: docs/architecture/luma-district-architecture.md

Roadmap

1. Asset pipeline

   • Replace prototype geometry with high-quality CC0/commercial-safe city, retail, and human assets.
   • Add Blender/glTF validation and optimization pipeline.
   • Add PBR texture packs for glass, asphalt, concrete, metal, wood, fabric, and retail lighting.

2. Commerce World Protocol

   • Promote StoreWorldManifest into a district-level document.
   • Add campaign scheduling, placement pricing, audience rules, and A/B test metadata.
   • Add collision, occlusion, and level-of-detail constraints.

3. Merchant SaaS

   • Building claim workflow.
   • Template marketplace for buildings, storefronts, shelves, staff, counters, and campaign surfaces.
   • Store decoration editor that exports protocol manifests.

4. Renderer quality

   • Real city-block composition.
   • Continuous route meshes and collision boundaries.
   • Better camera navigation, minimap, and accessibility.
   • WebXR controller interaction.

5. Platform integration

   • Product, SKU, inventory, price, cart, checkout, order, logistics, and refund adapters.
   • Start with mock adapters, then add real commerce-platform connector examples.

Getting Started

npm install
npm run dev

Open http://127.0.0.1:5173/.

Useful commands:

npm test
npm run build
npm run lint

Contributing

The most valuable contributions right now:

• Better city/street/building/store assets with clear license metadata.
• PBR material packs and glTF optimization.
• Three.js/R3F renderer improvements: depth, occlusion, collisions, camera movement, LOD.
• Commerce protocol feedback from ecommerce platform, marketplace, or SaaS experience.
• Merchant decoration editor ideas.
• UX critique from retail, brand, or spatial design perspectives.

Read CONTRIBUTING.md before opening a PR.

License

Code is licensed under MIT. See LICENSE.

Third-party and generated assets may have separate terms. See NOTICE.md.