#luna-three

#Installation

moon add mizchi/luna_three@0.1.0
moon add mizchi/three@0.1.3
moon add mizchi/luna@0.24.1
moon add mizchi/signals@0.6.5
pnpm add three@0.185.1 @mizchi/three-mbt@link:./.mooncakes/mizchi/three/js

#Usage

// moon.pkg
import {
  "mizchi/three",
  "mizchi/luna_three" @lt,
  "mizchi/luna/core" @luna,
  "mizchi/luna/js/resource" @reactivity,
  "mizchi/signals",
}

supported_targets = "js"

let x = @reactivity.signal(0.0)
let scene = @three.Scene()
let root = @lt.mount(scene.as_object3d(), @luna.component(fn() {
  @lt.group([
    @lt.mesh(
      geometry=Box(1, 1, 1),
      material=Standard(0x49c6bb, 0.4, 0.2),
      props=[
        @lt.prop(Name("box")),
        @lt.dynamic(fn() { Position(x.get(), 0, 0) }),
      ],
    ),
    @lt.ambient_light(intensity=2),
    @lt.directional_light(props=[@lt.prop(Position(3, 5, 4))]),
  ])
}))

x.set(2.0) // Updates the existing mesh synchronously.
// Render/export scene with mizchi/three, then release this tree:
root.unmount()

#Modeling and reactivity

• group, mesh, primitive, ambient_light, directional_light, and perspective_camera produce native Luna virtual nodes, without allocating three.js resources until mounted.
• Geometry: Box(width, height, depth), Sphere(radius, widthSegments,heightSegments), Plane(width, height), Cylinder(topRadius, bottomRadius,height, radialSegments), Cone(radius, height, radialSegments), Torus(radius, tube, radialSegments, tubularSegments), or Borrowed(geometry).
• Material: Basic(color), Standard(color, roughness, metalness), Normal, or Borrowed(material). Colors are RGB integers, rotations are radians.
• prop(Property) is static; dynamic(() -> Property) tracks signals. Properties include transforms, name, visibility, shadow flags, geometry, material, light color/intensity, and perspective camera parameters. Later properties override earlier properties in the same slot. This allows a dynamic Geometry(...) or Material(...) to override a mesh's initial spec.
• Components run once per mount. Put reactive values inside dynamic getters or Luna control nodes. Updating a property preserves its Object3D; material values update in place when the material kind is unchanged. Geometry changes construct a replacement. Removed properties restore their original values.
• Luna fragment, component, show, for_each, and switch_ are supported. Fragments and control nodes do not insert extra Object3D groups. show retains its child while true and cleans its scope when false. switch_ retains the selected branch until the selected case changes.
• Use key="stable-id" on elements returned by for_each. Keys are scoped to siblings. Reordering retains matching element objects and resources; unkeyed elements match by position and kind. Cached virtual nodes retain their scopes; newly returned component/control nodes mount new scopes. Key and a primitive's Object must be static: change them by returning a new node from a list.
• A property update reapplies only changed values. Host animation may mutate other properties without unrelated signal updates resetting the animation.

@luna.for_each(fn() {
  items.get().map(fn(id) {
    @lt.mesh(
      key=id,
      geometry=Sphere(0.5, 24, 16),
      material=Basic(0xffb86b),
      props=[@lt.prop(Name(id))],
    )
  })
})

#Ownership and diagnostics

#Development

just test-luna-three
just test-luna-three-browser
just mouse
# http://127.0.0.1:4173/luna-three.html
just build-mouse
# _build/mouse-site/luna-three.html

#Packaging